GUI Events

From HEWIKI
Jump to: navigation, search

Contents

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 args.handled 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.

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

See also

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox