Core Function GUILink

From Sputnik Wiki
Jump to: navigation, search 
GUILink( <gui object>, <linktype>, <action>, <param var> )

Contents

Description

Add a link on a Click event to a GUI object.

Parameters

gui object

The GUI object to link with.

linktype

The link type to create.

See remarks.

action

The action to perform on when the link happens this is basically same as Eval() and it will execute as string as if it was actual Sputnik code.

param var

Optional; A variable to pass inside the link this variable will become $Param inside the link this is most useful for attaching a class to the link so you can access its variables, functions natively.

Return Value

Success: Returns 1.

Failure: Returns 0.

Remarks

As a matter of note the following variables are used by Links and should not be assigned to : 

$me // Holds the GUI Object that the link is attached to
$mkeys // Holds the status of modifier keys
$arg // Some links contain special information in this such as position of mouse on a Mouse event
$param // Some links fill this variable with the forth param given at the GUILink creation

All links spawn a variable called $mkeys which can be used to check if any Modifier Keys were pressed down at the time the link event happened.

Also all links spawn a variable called $me which contains the GUI Object that the link is caused by (It is called $me since $this is already in use hehe).

Heres an example: 

// Create the GUI
$GUI = GUICreate("Window", "Hello", 200, 200);
// Show the GUI
GUILoad( $GUI );
// Create a button -- This button will simply display a message
$Button = GUICreate("Button", $GUI, "Press Me!", 8, 8);
// Add a link to the button
GUILink($Button, "Click", 'Moo();'); // Call function
// Keep the GUI running as long as long as the window is open
While ( GUIStatus( $GUI ) ) DoEvents( );
 
Function Moo()
{
	$Shift = 0;
	$Control = 0;
	$Alt = 0;
	if($mkeys & @KeyControl) $Control++;
	if($mkeys & @KeyAlt) $Alt++;
	if($mkeys & @KeyShift) $Shift++;
	// At this point $Shift, $Control and $Alt will either be TRUE or FALSE
	MsgBox(
			"When button was pressed: " .
			($Alt ? "[ALT+]" : "[ALT-]") . " ".
			($Shift ? "[SHIFT+]" : "[SHIFT-]") . " ".
			($Control ? "[CONTROL+]" : "[CONTROL-]") . " "
			);
}


Link Type 'Activated'

Description

This link will when a window activated by the user.

Special Variables

None.

Notes

None.

Link Type 'Deactivate'

Description

This link will when a window has been deactivated.

Special Variables

None.

Notes

None.

Link Type 'Load'

Description

This link will trigger before a window displayed for the first time.

Special Variables

None.

Notes

None.

Link Type 'Shown'

Description

This link will trigger when a window is first displayed.

Special Variables

None.

Notes

None.


Link Type 'FormClosing'

Description

This link will trigger when a window is closing.

Special Variables

None.

Notes

return 1; // Cancels

Link Type 'FormClosed'

Description

This link will trigger when a window is fully closed.

Special Variables

None.

Notes

None.

Link Type 'KeyPress'

Description

This link will trigger when a key is pressed on a control.

Special Variables

$arg; Details: 

$arg // The char that was pressed
Notes

return 1; // Cancels

Link Type 'Paint'

Description

This link will trigger a control is redrawn.

Special Variables

None.

Notes

None.


Link Type 'KeyDown'

Description

This link will trigger when a key is pressed down on a control.

Special Variables

$arg; Details: 

$arg[0] // String representation of the key
$arg[1] // KeyCode (Same as ones found in @Key macros)
$arg[2] // KeyData
$arg[3] // KeyValue
$arg[4] // Modifiers like mkeys
$arg[5] // Is Alt Pressed? (true/false)
$arg[6] // Is Shift Pressed? (true/false)
$arg[7] // Is Control Pressed? (true/false)
Notes

return 1; // Cancels

Link Type 'KeUp'

Description

This link will trigger when a key is pressed up on a control.

Special Variables

$arg; Details: 

$arg[0] // String representation of the key
$arg[1] // KeyCode (Same as ones found in @Key macros)
$arg[2] // KeyData
$arg[3] // KeyValue
$arg[4] // Modifiers like mkeys
$arg[5] // Is Alt Pressed? (true/false)
$arg[6] // Is Shift Pressed? (true/false)
$arg[7] // Is Control Pressed? (true/false)
Notes

return 1; // Cancels

Link Type 'Click'

Description

This link will trigger when an object gets a clicked.

Special Variables

None.

Notes

None.

Link Type 'DoubleClick'

Description

This link will trigger when an object gets a double clicked.

Special Variables

None.

Notes

None.

Link Type 'MouseClick'

Description

This link will trigger when a user clicks the mouse button on a control.

Special Variables

$arg; Details: 

$arg[0] // X location of the Mouse
$arg[1] // Y location of the Mouse
$arg[2] // Number of clicks
$arg[3] // Which Mouse button was pressed
$arg[4] // Number of detents the mouse wheel has rotatet (A detent is one notch of the mouse wheel)
// [3] can be either:
// @MouseNone
// @MouseLeft
// @MouseMiddle
// @MouseRight
// @MouseXButton1
// @MouseXButton2
Notes

Some controls will accept a Right click too but not all.

Link Type 'MouseDoubleClick'

Description

This link will trigger when a user double clicks the mouse button on a control.

Special Variables

$arg; Details: 

$arg[0] // X location of the Mouse
$arg[1] // Y location of the Mouse
$arg[2] // Number of clicks
$arg[3] // Which Mouse button was pressed
$arg[4] // Number of detents the mouse wheel has rotatet (A detent is one notch of the mouse wheel)
// [3] can be either:
// @MouseNone
// @MouseLeft
// @MouseMiddle
// @MouseRight
// @MouseXButton1
// @MouseXButton2
Notes

Some controls will accept a Right click too but not all.

Link Type 'MouseDown'

Description

This link will trigger when a user presses the primary mouse button down on a control.

Special Variables

$arg; Details: 

$arg[0] // X location of the Mouse
$arg[1] // Y location of the Mouse
$arg[2] // Number of clicks
$arg[3] // Which Mouse button was pressed
$arg[4] // Number of detents the mouse wheel has rotatet (A detent is one notch of the mouse wheel)
// [3] can be either:
// @MouseNone
// @MouseLeft
// @MouseMiddle
// @MouseRight
// @MouseXButton1
// @MouseXButton2
Notes

None.

Link Type 'MouseUp'

Description

This link will trigger when a user presses the primary mouse button up on a control.

Special Variables

$arg; Details: 

$arg[0] // X location of the Mouse
$arg[1] // Y location of the Mouse
$arg[2] // Number of clicks
$arg[3] // Which Mouse button was pressed
$arg[4] // Number of detents the mouse wheel has rotatet (A detent is one notch of the mouse wheel)
// [3] can be either:
// @MouseNone
// @MouseLeft
// @MouseMiddle
// @MouseRight
// @MouseXButton1
// @MouseXButton2
Notes

None.

Link Type 'MouseWheel'

Description

This link will trigger when a user uses the mouse wheel on a control.

Special Variables

$arg; Details: 

$arg[0] // X location of the Mouse
$arg[1] // Y location of the Mouse
$arg[2] // Number of clicks
$arg[3] // Which Mouse button was pressed
$arg[4] // Number of detents the mouse wheel has rotatet (A detent is one notch of the mouse wheel)
// [3] can be either:
// @MouseNone
// @MouseLeft
// @MouseMiddle
// @MouseRight
// @MouseXButton1
// @MouseXButton2
Notes

None.

Link Type 'MouseMove'

Description

This link will trigger when a user moves a mouse over a control.

Special Variables

$arg; Details: 

$arg[0] // X location of the Mouse
$arg[1] // Y location of the Mouse
Notes

None.

Link Type 'CellBeginEdit'

Description

This link will trigger when a user begins editing a cell in DataGrid.

Special Variables

$arg; Details: 

$arg[0] // ColumnIndex
$arg[1] // RowIndex
Notes

return 1; // Cancels the edit

Link Type 'CellEndEdit'

Description

This link will trigger when a user ends editing a cell in a DataGrid.

Special Variables

$arg; Details: 

$arg[0] // ColumnIndex
$arg[1] // RowIndex
Notes

None.

Link Type 'DeletingRow'

Description

This link will trigger when a user begins deleting a row in a DataGrid.

Special Variables

$arg; Details: 

$arg[0] // RowIndex
Notes

return 1; // Cancels the delete

Link Type 'DeletedRow'

Description

This link will trigger when a user ends deleting a row in a DataGrid.

Special Variables

None.

Notes

None.

Link Type 'SelectedIndexChanged'

Description

This link will trigger when a user changes the selected item in a ComboBox, ListBox.

Special Variables

$arg; Stores the selected index value and string of the item at that index 

$arg[0] // The index
$arg[1] // The string of the item at that index
Notes

None.

Link Type 'TextChanged'

Description

This link will trigger when a user changes the text in a TextBox/Hotkeybox/CheckBox.

Special Variables

None.

Notes

None.

Link Type 'SelectionChanged'

Description

This link will trigger when a user changes the text in a CodeBox/RichTextBox.

Special Variables

None.

Notes

None.

Link Type 'CheckedChanged'

Description

This link will trigger when a user changes the state of a CheckBox or RadioButton.

Special Variables

None.

Notes

None.

Link Type 'CheckStateChanged'

Description

This link will trigger when a user changes the check state of a CheckBox.

Special Variables

None.

Notes

None.

Example

Heres a very simple example of using links this shows direct code execution links and links that call functions 

// Create the GUI
$GUI = GUICreate("Window", "Hello", 200, 200);
// Show the GUI
GUILoad( $GUI );
// Create a button -- This button will simply display a message
$Button1 = GUICreate("Button", $GUI, "Press Me!", 8, 8);
// Create a button -- This button will call a function
$Button2 = GUICreate("Button", $GUI, "Press Me!", 8, 35);
// Add a link to the buttons
GUILink($Button1, "Click", 'MsgBox("Hello World!");'); // Display message
GUILink($Button2, "Click", 'Moo();'); // Call function
// Keep the GUI running as long as long as the window is open
While ( GUIStatus( $GUI ) ) DoEvents( );
 
Function Moo()
{
	MsgBox("Moo moo farm");
}

Heres an example of usnig the "param var" with the link "click" 

// Use our custom made Inputbox class
$value = InputBox2::Show(); // Show the window
if($value) // Capture input
{
	MsgBox( "Value is $value" ); // Show what user typed
}
else
{
	MsgBox( "User did not enter a value" ); // Inform user did not type
}
 
// Our inputbox class here we will create an inputbox that works just like
// the Inputbox() actual core command.
Class InputBox2
{
	// Define some variables
	my $Input;
	my $Accept;
	my $Cancel;
	my $GUI;
	my $returnValue;
	my $hWnd;
	// Make a static function that will handle the showing of the window and return values
	// This allows 0, 1, 2 or 3 params
	Static Function Show($Title = "Inputbox 2", $Prompt = "Enter a value", $Default = "")
	{
		// Spawn a new class
		$myClass = new InputBox2();
		$myClass->$returnValue = ""; // Nothing to return yet
 
		// Create the GUI
		$myClass->$GUI = GUICreate("Window", $Title, 345, 140, -1, -1, 1);
		$myClass->$hWnd = GUIGetProp($myClass->$GUI, "Handle"); // GUIs hWnd for use with Win__() functions
		GUILoad( $myClass->$GUI ); // Show the GUI
 
		// Create the prompt
		GUICreate("Label", $myClass->$GUI, $Prompt, 20, 20, 300);
		// Create input control
		$myClass->$Input = GUICreate("TextBox", $myClass->$GUI, $Default, 20, 45, 300);		
		// Focus the input control
		GUIPropInvoke($myClass->$Input, "Focus");
		// Create the accept button
		$myClass->$Accept = GUICreate("Button", $myClass->$GUI, "&Accept", 20, 70, 110);
		// Create the cancel button
		$myClass->$Cancel = GUICreate("Button", $myClass->$GUI, "&Cancel", 209, 70);
 
		// Create links
		// Heres the important bit we are going to include the $myClass inside the GUILink
		// so that we can use it inside the link as if the link was really part of this
		// function/class
 
		// This button gets the text and closes the GUI
		// Here im using @"" instead of "" since @"" lets us make a multiline string
		// much easier and it doesnt resolve $variables inside it which is what we need
		// for a link
		GUILink($myClass->$Accept, "Click",
				@"
				$param->$returnValue = GUIGetProp($param->$Input, 'Text');
				GUIUnload($param->$GUI);
				",
				$myClass); 	// The link to the class goes here without this we will be unable
						// to call functions within the class
 
		// This button closes the GUI				
		GUILink($myClass->$Cancel, "Click", 'GUIUnload($param->$GUI);', $myClass);
 
		// Use WinActivate to force the window to be activated and focus
		// This is a good example of using Win__() functions on Sputnik GUI stuff
		// instead of other windows
		WinActivate($myClass->$hWnd);
 
		// Keep the GUI running as long as long as the window is open
		While ( GUIStatus( $myClass->$GUI ) ) DoEvents( );
 
		// Get return value
		$returnValue = $myClass->$returnValue;
 
		// Clean up the GUI ie delete it
		unset($myClass->$GUI); // This will clean up all controls attached to the GUI as well
 
		// Clean up the Class ie delete it
		unset($myClass);
 
		// Return
		return $returnValue;
	}
};

Example of using KeyUp and KeyDown links 

// Create the GUI
$GUI = GUICreate("Window", "Hello", 200, 200);
// Show the GUI
GUILoad( $GUI );
// Create a button -- This button will simply display a message
$Button = GUICreate("Button", $GUI, "Close", 8, 8);
// Add a link to the button
GUILink($Button, "KeyUp", 'onKeyUp();'); // Call function
GUILink($Button, "KeyDown", 'onKeyDown();'); // Call function
// Keep the GUI running as long as long as the window is open
While ( GUIStatus( $GUI ) ) DoEvents( );
 
Function onKeyUp()
{
	my List($Key, $KeyCode, $KeyData, $KeyValue, $Modifiers, $Alt, $Shift, $Control) = $arg;
	println("### Key UP Stuff Below ###");
	println("Key '$Key'");
	println("Code '$KeyCode'");
	println("Data '$KeyData'");
	println("Value '$KeyValue'");
	println("Mods '$Modifiers'");
	println("Alt '$Alt'");
	println("Shift '$Shift'");
	println("Control '$Control'");
	println("### Key UP Stuff Above ###\n");
}
 
Function onKeyDown()
{
	my List($Key, $KeyCode, $KeyData, $KeyValue, $Modifiers, $Alt, $Shift, $Control) = $arg;
	println("### Key DOWN Stuff Below ###");
	println("Key '$Key'");
	println("Code '$KeyCode'");
	println("Data '$KeyData'");
	println("Value '$KeyValue'");
	println("Mods '$Modifiers'");
	println("Alt '$Alt'");
	println("Shift '$Shift'");
	println("Control '$Control'");
	println("### Key DOWN Stuff Above ###\n");
}
Retrieved from "http://ubersoft.org/Sputnik/wiki/index.php/Core_Function_GUILink"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox