GUI Events
(removed the old precudral GUI Event sections) |
(edit overview for consistency) |
||
| Line 1: | Line 1: | ||
{{tocright}} Under the current Class Methods system, GUI Controls are handled via a data node of a class, which contains information on the event. The associated method script is called, and if it has a relevant method within it, the logic is handled there, and the variable <tt>args.handled</tt> can be set to TRUE, signifying that the GUI Event has been taken care of, and no further controls should do anything. | {{tocright}} Under the current Class Methods system, GUI Controls are handled via a data node of a class, which contains information on the event. The associated method script is called, and if it has a relevant method within it, the logic is handled there, and the variable <tt>args.handled</tt> can be set to TRUE, signifying that the GUI Event has been taken care of, and no further controls should do anything. | ||
| − | If no exception method is found, or none choose to mark the event as handled, HeroEngine will first attempt to call the original method on the GUI Control's parents. If none of those handle the Event, HeroEngine will move on to the older Procedural Function system | + | If no exception method is found, or none choose to mark the event as handled, HeroEngine will first attempt to call the original method on the GUI Control's parents. If none of those handle the Event, HeroEngine will move on to the older Procedural Function system. |
== Class Method System == | == Class Method System == | ||
Latest revision as of 21:14, 11 November 2011
|
If no exception method is found, or none choose to mark the event as handled, HeroEngine will first attempt to call the original method on the GUI Control's parents. If none of those handle the Event, HeroEngine will move on to the older Procedural Function system.
Class Method System
One of the benefits to the methodization system is the ability to handle all of the interactions for a given window in its own class methods script, removing the need for extraneous scripts and improving workflow. Further, it makes it simple and efficient to copy an entire window's functionality and override the behavior of one or two controls.
The Class Method system for handling GUI events works as follows:
All common base control types (e.g. radio buttons, dropdown boxes, buttons, popup menus, text input fields, etc) have a Class methods script associated with them, which traps all major GUI methods. The Control then searches its parents for a more specialized method corresponding to the Control type and event, such as _onButtonMouseClick() or _onTextInputBoxKeyPress().
A list of most of these can be found via the Script Editor, in the _GUIMethodCallbacksClassMethods script.
The parameters passed in are typically the same as the original method, a single data node of a class containing information on the event. Any such method found is then called and has the opportunity (where applicable) to set args.handled to TRUE, signifying that the GUI Event has been taken care of, and no further controls should do anything.
If no exception method is found, or none choose to mark the event as handled, HeroEngine will first attempt to call the original method on the Control's parents, and if none of those handle the Event, it will move on to the older procedural function system described lower on this page.
GUI Events
GUI Events work hand in hand with GUIControls. Once a control, such as a window or button, is created, a mechanism is then necessary which allows that window or button to be activated by something that the user does, such as clicking on it with the mouse. That "click" event can then trigger a function in a client-side script.
Mouse Events
Mouse events fall into two categories. Functions that are called when the mouse interacts with a particular control, and functions that are called when the mouse does something with one control, that passes into the zone of a different control. For example, if the mouse button was pressed on panel1 and then dragged it over to panel2, the applicable events would be OnMouseDown and OnMouseDrag on panel1, and then OnMouseEnter for panel2.
| Event Function | Data Class | Description |
| OnMouseDown | GUIMouseEvent | Called when mouse button is pressed down |
| OnMouseUp | GUIMouseEvent | Called when mouse button is released |
| OnMouseClick | GUIMouseEvent | Called when user clicks on control |
| OnMouseDblClick | GUIMouseEvent | Called when user double-clicks on control |
| OnMouseEnter | GUIMouseEvent | Called at the moment that the mouse cursor enters boundaries of control |
| OnMouseLeave | GUIMouseEvent | Called at the moment that the mouse cursor moves out of a control's boundaries |
| OnMouseDrag | GUIMouseEvent | Called when user holds down mouse button on control and moves cursor |
| OnMouseMove | GUIMouseEvent | Called when user moves the mouse cursor while over a control |
| OnClickedAway | GUIMouseEvent | Called when user clicks away from the control (property popup must be set true for this event to occur) OnClickedAway is triggered if your click happens on no control, or on a control that is *not* a popup (or a child of a popup). By design, it does not trigger if you click on a control that *is* a popup (or a child of one). |
| OnMouseWheel | GUIMouseEvent | Called when user moves the mouse wheel while over a control (see wheelDelta below) |
There are also two properties on the GUI Control itself which apply:
| Property | Type | Default | Description |
| selected | boolean | FALSE | Changes depending whether or not the current GUI Control is selected by the user |
| ignoreDragDropEvents | boolean | TRUE | If true, causes all Drag/Drop events to be ignored |
Each of Mouse Event Functions receives its argument data in a node of class GUIMouseEvent. Its fields are as follows:
| Field | Datatype | Default Value | Description |
| x | float | The X position of the Mouse, with 0,0 being the top left corner of the screen | |
| y | float | The Y position of the Mouse, with 0,0 being the top left corner of the screen | |
| leftButton | boolean | FALSE | True if the left mouse button is being pressed. |
| midButton | boolean | FALSE | True if the middle button or mouse wheel is being pressed |
| rightButton | boolean | FALSE | True if the right mouse button is being pressed. |
| button4 | boolean | FALSE | True if button 4 on a mouse (if it has one) is being pressed |
| button5 | boolean | FALSE | True if button 5 on a mouse (if it has one) is being pressed |
| wheelDelta | integer | 0 | Value representing the speed and direction that the mouse wheel (if the mouse has one) is being moved. Positive increments of 120 for moving wheel up (or away from you), negative 120's for down (or towards you) Note that you should use OnMouseWheel to catch this |
| source | noderef of class GUIControl | The control where the event originated from | |
| lastPopup | noderef of class GUIControl | On a MouseDown event, this field is set to the noderef of the control | |
| handled | boolean | FALSE | Set this to TRUE if the script handled the event, otherwise it will keep falling though to the parents until it finds one that handles the event. |
Note that if multiple buttons (such as left and right) are pushed simultaneously, they will both register as TRUE at the same time. If it is essential to check for a single click of one button and *only* that button, then it should be checked for TRUE, and the others simultaneously checked for FALSE.
Keyboard Events
| Event Function | Data Class | Description |
| OnKeyUp | GUIKeyboardEvent | Called when user releases a key while the Control has focus |
| OnKeyPress | GUIKeypressEvent | Called after a user presses and releases (down then up) a key while the Ccontrol has focus |
| OnKeyDown | GUIKeyboardEvent | Called when user pushes down a key while control has focus |
GUIKeyBoardEvent args
| Field | Datatype | Default Value | Description |
| alt | boolean | FALSE | True if the alt key is being held down |
| ctrl | boolean | FALSE | True if the ctrl key is being held down |
| shift | boolean | FALSE | True if the shift key is being held down |
| keyCode | integer | (key that was pressed) | The key code of the key that triggered the event |
| handled | boolean | FALSE | Set this to true if you've handled the event, otherwise it will keep falling though to the parents until it finds one that handles the event. |
| source | node of class GUIControl | (see description) | The GUI Control that the event originated on |
GUIKeyPressEvent args
| Field | Datatype | Default Value | Description |
| keyCode | string | (see description) | The key that triggered the event in string form |
| handled | boolean | FALSE | Set this to true if you've handled the event, otherwise it will keep falling though to the parents until it finds one that handles the event. |
| source | node of class GUIControl | The GUI Control that the event originated on |
GUI Focus Change Events
| Event Function | Data Class | Description |
| OnGotFocus | GUIFocusChangeEvent | Called when a control gets keyboard focus |
| OnLostFocus | GUIFocusChangeEvent | Called when a control loses keyboard focus |
GUIFocusChangeEvent fields
| Field | Datatype | Default Value | Description |
| handled | boolean | FALSE | Set this to true if the function has handled the event, otherwise it will keep falling though to the parents until it finds one that handles the event. |
| source | node of class GUIControl |
GUI Value Change Events
| Event Function | Data Class | Description |
| onValueChange | GUIValueChangeEvent | This event is called when a value is changed on a slider control. onMouseClick will also be called when the mouse is released. |
GUIValueChangeEvent Fields
| Field | Datatype | Default Value | Description |
| value | string | ||
| handled | boolean | FALSE | Set this to true if the function has handled the event, otherwise it will keep falling though to the parents until it finds one that handles the event. |
| source | node of class GUIControl | (see description) | The GUI Control on which the event was originated |
GUI Layout Events
| Event Function | Data Class | Description |
| onLayout | GUILayoutEvent | This notifies you that the Control is being laid out, which does things such as repositioning children controls that are docked, or notifying the parent if this control is resized or something of that nature |
The OnLayout event happens automatically for GUI Controls when they are created, removed, resized, or have an anchoring/docking change. The SuppressLayout() function prevents this from happening, and ResumeLayout() allows it to happen again. If ~forceLayout is TRUE, this immediately performs a layout, which may be necessary if significant changes have been made. There is also a ForceLayout() function which does the same thing.
Note that recursive calls to parent Controls may be disabled in some of these situations, as a code optimization technique.
GUILayoutEvent fields
| Field | Datatype | Default Value | Description |
| handled | boolean | FALSE | Set this to true if the function has handled the event, otherwise it will keep falling though to the parents until it finds one that handles the event. |
| source | The node of the GUI Control on which the event was originated |
GUI Layout Functions
SuppressLayout(guiNode as noderef) ResumeLayout(guiNode as noderef, forceLayout as bool) ForceLayout(GUInode as noderef)
Other Event-Related Functions
onControlBuild
This is called immediately after the control and all of its children have been constructed, but before the end of the control's build cycle. It's most commonly used to do any dynamic setup.
method onControlBuild()
OnNodeDestroy
Not technically a GUIControl specific method, but sees a lot of use with them. Called before the node is actually destroyed, but cannot interrupt the process. Most commonly used for cleanup.
method OnNodeDestroy(args references Class GUINodeDestroyEvent)
GUI Drag and Drop
OnDragStart() as boolean - Called on the GUIMovePanel when it's first dragged; return TRUE if you want to prevent dragging.
OnDragStop() - Called on the GUIMovePanel when it's no longer being dragged.
OnDragEnter(draggable as noderef) - Called on a target control (i.e. ignoreDragDropEvents=false) when a GUIMovePanel is dragged into its space.
OnDragOver(draggable as noderef) - Called on a target control when a GUIMovePanel is dragged within its space.
OnDragDrop(draggable as noderef) as boolean - Called on a target control when a GUIMovePanel is dropped onto it; return TRUE if the drop was successful (which prevents the OnDragStop() call).
OnDragLeave(draggable as noderef) - Called on a target control when a GUIMovePanel is dragged out of its space.
GetSliceFromPosition
At any time you can determine which section the mouse is over (or any other point of interest) by callling the function getSliceFromPosition(control as noderef of class GUIControl, screenSpacePosition as vector3) as integer. It will return either the slice number (1-9), or 0 if the position is not over the specified 9slice control at all.
Set Keyboard Focus
Client function which gives keyboard focus to the given control; only works for controls that accept keyboard input (GUITextInputBox and GUINumericField)
SetKeyboardFocus(control as noderef of class GUIControl)
Get GUI Control Owner
Returns the control referenced by the "owner" property of the given control. If given an invalid noderef, or a noderef to a control that does not have the "owner" property, a script error will result.
GetGUIControlOwner(whichControl as noderef of class GUIControl) as noderef of class GUIControl
