GUI Events

From HEWIKI
(Difference between revisions)
Jump to: navigation, search
(Fixed references to XML page)
(removed the old precudral GUI Event sections)
Line 1: Line 1:
{{tocright}}
+
{{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.
'''GUI Events''' may refer to:
+
* An older "Procedural Function" system
+
* The newer "Class Method" system
+
  
The lower "Procedural Functions" part of this page is what was used, prior to the system of using [[Class methods]].
+
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 described below.  
  
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.
+
== Class Method 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 described below.
+
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.  
  
== Class Method System==
+
The [[Class Method]] system for handling GUI events works as follows:
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 <tt>_onButtonMouseClick()</tt> or <tt>_onTextInputBoxKeyPress()</tt>.
  
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 <tt>_onButtonMouseClick()</tt> or <tt>_onTextInputBoxKeyPress()</tt>.
+
A list of most of these can be found via the [[Script Editor]], in the <tt>_GUIMethodCallbacksClassMethods</tt> script.  
  
A list of most of these can be found via the [[Script Editor]], in the <tt>_GUIMethodCallbacksClassMethods</tt> 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 <tt>args.handled</tt> to TRUE, signifying that the GUI Event has been taken care of, and no further controls should do anything.  
  
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 <tt>args.handled</tt> 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.  
  
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 ===
  
===Methods===
+
[[GUI]] Events work hand in hand with [[Technical:Graphical Controls|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.  
Most methods share a name with their procedural function counterpart, i.e. the method <tt>onMouseClick</tt> correlates to the procedural function <tt>onMouseClick</tt> described lower on this page.  The methods also accept the same parameters.
+
  
Additional methods are:
+
=== Mouse Events  ===
  
====onControlBuild====
+
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.
<hsl>
+
method onControlBuild()
+
</hsl>
+
  
 +
{| border="1" width="100%" cellpadding="5" cellspacing="2"
 +
|-
 +
| '''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)
 +
|}
  
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.
+
<br>  
 
+
 
+
====OnNodeDestroy====
+
<hsl>
+
method OnNodeDestroy(args references Class GUINodeDestroyEvent)
+
</hsl>
+
 
+
 
+
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.
+
 
+
== Procedural Function System ==
+
'''Some of this information is out of date!  Though accurate, there is a new object-oriented way of handling GUI events that should be used instead (see above sections). However, there are some circumstances in which it still may be used.'''
+
 
+
===Function system overview===
+
[[GUI]] Events work hand in hand with [[Technical:Graphical Controls | 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.
+
 
+
In order to be triggered, the script on a [[Technical:GUI|GUI]] Control must contain a function which is named for the control's prototype, along with the type of event that is being expected.
+
 
+
=== How Events Pass Data to a Script ===
+
 
+
==== Single Control, Single Function ====
+
 
+
Suppose a window has an OK button, which is a node of the prototype <code>OK_button</code>, and it is desired that the <code>merchant.hsl</code> script be called whenever the button is clicked with a mouse.  On the <code>OK_button</code> node, the <code>script</code> field would be set to <code>merchant</code>.
+
 
+
In the merchant.hsl script would be a function called <code>OK_button_onMouseClick()</code>.  When the user clicked on the button, that function wouuld be called, with data contained in the function's arguments, specifying what kind of a click it was (left-click, right-click, etc).
+
 
+
So, to check if the button was clicked, the following code could be used:
+
<hsl>
+
function OK_button_onMouseClick(args references class GUIMouseEvent)  // This would catch any kind of mouse click
+
  if (args.rightButton = TRUE)                      //  And this would specifically check for a right-click
+
    println("The right mouse button was pressed.")
+
    set args.handled to TRUE
+
  .
+
.
+
</hsl>
+
 
+
==== Many Controls, One Function ====
+
 
+
It is also possible to make a more global function that can be accessed from multiple controls on a window.  For example, if a window has several different buttons for choosing a type of creature, it is not necessary to make a different function for each button.  In this case, several buttons could be made from the same control prototype, such as base_button, and then the calling node could be checked with the "me" address:
+
 
+
<hsl>
+
function base_button_OnMouseClick(args references Class GUIMouseEvent)
+
  if (me.name = "cat_button")
+
    call println("You chose a cat.")
+
  .
+
  if (me.name = "jackal_button")
+
    call println("You chose a jackal.")
+
  .
+
.
+
</hsl>
+
 
+
==== Grouped Controls, Many Scripts ====
+
   
+
Another technique for calling a script, has to do with whether the event is referring to the individual control, or to the entire window, or some other subset of controls.  There could be scripts on all [[Technical:GUI|GUI]] Controls in a window: The individual buttons, the panel that the buttons are on, and the window that the panel is located in.  Each of these scripts will be called in turn (starting with the button), unless the <code>handled</code> field is set to TRUE (its default is FALSE).
+
 
+
 
+
In the following example, there is a window [[Technical:GUI|GUI]] Control, which has as one of its children a large "parent" panel, with smaller children panels.  On one of the children panels, <code>button_panel</code> has a series of buttons.
+
 
+
When one of those buttons is clicked, the system first calls the script on the button.  If <code>handled</code> is not set to TRUE by that script, then the system would go on to call the script on the button's parent <code>button_panel</code>, and then its parent panel, and finally the root window's script (if it had one).
+
 
+
So on the lowest level button, ther might be a function as follows:
+
 
+
<hsl>
+
function OK_button_onMouseDblClick(args references Class GUIMouseEvent)  // This would catch a left-double-click
+
  if (args.leftButton = TRUE)
+
    println("The left mouse button was doubleclicked.")
+
    set args.handled to TRUE
+
  .
+
.
+
</hsl>
+
 
+
Since <code>args.handled</code> was set to TRUE, execution would stop at that point.  If, however, it was *not* set, then the system would go on to check the script on <code>button_panel</code>:
+
 
+
<hsl>
+
function button_panel_OnMouseClick(args references Class GUIMouseEvent)
+
  println("We know that a mouse click occurred somewhere")
+
  println(" on this panel, but we don't know exactly which")
+
  println(" object.  We could check the mouse x,y though")
+
 
+
  // Since args.handled is not set to TRUE, the system would go on calling
+
  //  other scripts at this point, working up the level of parents
+
.
+
</hsl>
+
 
+
=== 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.
+
  
 +
There are also two properties on the GUI Control itself which apply:
  
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
| '''Event Function'''||'''Data Class'''||'''Description'''
+
|-
|-  
+
| '''Property'''  
| OnMouseDown() ||GUIMouseEvent||Called when mouse button is pressed down
+
| '''Type'''
|-
+
| '''Default'''  
| OnMouseUp() ||GUIMouseEvent|| Called when mouse button is released
+
| '''Description'''
|-
+
|-
|  OnMouseClick() ||GUIMouseEvent|| Called when user clicks on control
+
| selected
|-
+
| boolean
|  OnMouseDblClick()||GUIMouseEvent|| Called when user double-clicks on control
+
| FALSE
|-
+
| Changes depending whether or not the current GUI Control is selected by the user
|  OnMouseEnter() ||GUIMouseEvent|| Called at the moment that the mouse cursor enters boundaries of control
+
|-
|-  
+
| ignoreDragDropEvents
| OnMouseLeave() ||GUIMouseEvent|| Called at the moment that the mouse cursor moves out of a control's boundaries
+
| boolean
|-
+
| TRUE
| OnMouseDrag() ||GUIMouseEvent|| Called when user holds down mouse button on control and moves cursor
+
| If true, causes all Drag/Drop events to be ignored
|-
+
|  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)
+
 
|}
 
|}
  
<br clear="all">
+
<br>  
  
There are also two properties on the GUI Control itself which apply:
+
Each of Mouse Event Functions receives its argument data in a node of class <code>GUIMouseEvent</code>. Its fields are as follows:  
  
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
| '''Property'''||'''Type'''||'''Default'''||'''Description'''
+
|-
|-  
+
| '''Field'''  
| selected||boolean||FALSE||Changes depending whether or not the current GUI Control is selected by the user
+
| '''Datatype'''  
|-  
+
| '''Default Value'''  
| ignoreDragDropEvents||boolean||TRUE||If true, causes all Drag/Drop events to be ignored
+
| '''Description'''
 +
|-
 +
| x
 +
| float
 +
| &nbsp;
 +
| The X position of the Mouse, with 0,0 being the top left corner of the screen
 +
|-
 +
| y
 +
| float
 +
| &nbsp;
 +
| 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
 +
| &nbsp;
 +
| The control where the event originated from
 +
|-
 +
| lastPopup
 +
| noderef of class GUIControl
 +
| &nbsp;
 +
| 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.
 
|}
 
|}
  
 +
<br> 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.
  
<br clear="all">
+
=== Keyboard Events  ===
  
Each of Mouse Event Functions receives its argument data in a node of class <code>GUIMouseEvent</code>.  Its fields are as follows:
 
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
| '''Field'''||'''Datatype'''||'''Default Value'''||'''Description'''
+
|-
|-  
+
| '''Event Function'''  
| x || float ||&nbsp;|| The X position of the Mouse, with 0,0 being the top left corner of the screen
+
| '''Data Class'''  
|-
+
| '''Description'''
| y || float ||&nbsp;|| The Y position of the Mouse, with 0,0 being the top left corner of the screen
+
|-
|-  
+
| OnKeyUp
| leftButton || boolean ||FALSE|| True if the left mouse button is being pressed.
+
| GUIKeyboardEvent
|-
+
| Called when user releases a key while the Control has focus
| midButton || boolean ||FALSE|| True if the middle button or mouse wheel is being pressed
+
|-
|-
+
| OnKeyPress
|  rightButton || boolean ||FALSE|| True if the right mouse button is being pressed.
+
| GUIKeypressEvent
|-
+
| Called after a user presses and releases (down then up) a key while the Ccontrol has focus
| button4|| boolean ||FALSE|| True if button 4 on a mouse (if it has one) is being pressed
+
|-
|-
+
| OnKeyDown
| button5|| boolean ||FALSE|| True if button 5 on a mouse (if it has one) is being pressed
+
| GUIKeyboardEvent
|-
+
| Called when user pushes down a key while control has focus
| 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|| &nbsp; ||The control where the event originated from
+
|-
+
| lastPopup|| noderef of class GUIControl || &nbsp; || 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.
+
 
|}
 
|}
  
<br clear="all">
+
<br> '''GUIKeyBoardEvent args'''
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 ===
 
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
| '''Event Function'''||'''Data Class'''||'''Description'''
+
|-
|-  
+
| '''Field'''  
| OnKeyUp ||GUIKeyboardEvent|| Called when user releases a key while the Control has focus
+
| '''Datatype'''
|-  
+
| '''Default Value'''  
| OnKeyPress ||GUIKeypressEvent|| Called after a user presses and releases (down then up) a key while the Ccontrol has focus
+
| '''Description'''
|-  
+
|-
| OnKeyDown ||GUIKeyboardEvent|| Called when user pushes down a key while control has focus
+
| 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
 
|}
 
|}
  
 +
<br>
 +
 +
'''GUIKeyPressEvent args'''
  
<br clear="all">
 
'''GUIKeyBoardEvent args'''
 
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
| '''Field'''||'''Datatype'''||'''Default Value'''||'''Description'''
+
|-
|-  
+
| '''Field'''  
| alt || boolean ||FALSE|| True if the alt key is being held down
+
| '''Datatype'''  
|-
+
| '''Default Value'''  
|  ctrl || boolean ||FALSE|| True if the ctrl key is being held down
+
| '''Description'''
|-
+
|-
|  shift || boolean ||FALSE|| True if the shift key is being held down
+
| keyCode
|-
+
| string
|  keyCode || integer ||(key that was pressed)||The key code of the key that triggered the event  
+
| (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.  
+
|-
|-  
+
| handled  
| source||node of class GUIControl||(see description)||The GUI Control that the event originated on
+
| 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  
 +
|
 
|}
 
|}
  
 +
<br>
  
<br clear="all">
+
=== GUI Focus Change Events  ===
  
'''GUIKeyPressEvent args'''
 
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
| '''Field'''||'''Datatype'''||'''Default Value'''||'''Description'''
+
|-
|-  
+
| '''Event Function'''  
| keyCode || string ||(see description)|| The key that triggered the event in string form
+
| '''Data Class'''  
|-  
+
| '''Description'''
| 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.
+
|-
|-
+
| OnGotFocus
| source||node of class GUIControl||The GUI Control that the event originated on||
+
| GUIFocusChangeEvent
 +
| Called when a control gets keyboard focus
 +
|-
 +
| OnLostFocus
 +
| GUIFocusChangeEvent
 +
| Called when a control loses keyboard focus
 
|}
 
|}
  
<br clear="all">
+
<br>  
 +
 
 +
'''GUIFocusChangeEvent fields'''
  
=== GUI Focus Change Events ===
 
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
| '''Event Function'''||'''Data Class'''||'''Description'''
+
|-
|-  
+
| '''Field'''  
| OnGotFocus ||GUIFocusChangeEvent|| Called when a control gets keyboard focus
+
| '''Datatype'''
|-  
+
| '''Default Value'''  
| OnLostFocus ||GUIFocusChangeEvent|| Called when a control loses keyboard focus
+
| '''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
 
|}
 
|}
  
<br clear="all">
+
<br>  
  
'''GUIFocusChangeEvent fields'''
+
=== GUI Value Change Events  ===
  
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
| '''Field'''||'''Datatype'''||'''Default Value'''||'''Description'''
+
|-
|-  
+
| '''Event Function'''  
| 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.  
+
| '''Data Class'''  
|-
+
| '''Description'''
| source||node of class GUIControl
+
|-
 +
| 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.
 
|}
 
|}
  
<br clear="all">
+
<br>  
===GUI Value Change Events ===
+
{| border="1" width="100%" cellpadding="5" cellspacing="2"
+
| '''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.
+
|}
+
  
<br clear="all">
+
'''GUIValueChangeEvent Fields'''  
 
+
 
+
'''GUIValueChangeEvent Fields'''
+
  
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
| '''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.  
+
| '''Field'''
|-  
+
| '''Datatype'''
| source||node of class GUIControl|| (see description)||The GUI Control on which the event was originated
+
| '''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
 
|}
 
|}
  
 +
<br>
  
<br clear="all">
+
=== GUI Layout Events  ===
  
=== GUI Layout Events ===
 
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
| '''Event Function'''||'''Data Class'''||'''Description'''
+
|-
|-  
+
| '''Event Function'''  
| 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
+
| '''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
 
|}
 
|}
  
 +
<br>
  
<br clear="all">
+
The OnLayout event happens automatically for [[Technical:GUI|GUI]] Controls when they are created, removed, resized, or have an anchoring/docking change. The SuppressLayout() function prevents this from happening, and <code>ResumeLayout()</code> 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 <code>ForceLayout()</code> 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.
  
The OnLayout event happens automatically for [[Technical:GUI|GUI]] Controls when they are created, removed, resized, or have an anchoring/docking change.  The SuppressLayout() function prevents this from happening, and <code>ResumeLayout()</code> 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 <code>ForceLayout()</code> function which does the same thing.
+
'''GUILayoutEvent fields'''
 
+
Note that recursive calls to parent Controls may be disabled in some of these situations, as a code optimization technique.
+
 
+
<code>GUILayoutEvent</code> fields:
+
  
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
 
{| border="1" width="100%" cellpadding="5" cellspacing="2"
| '''Field'''||'''Datatype'''||'''Default Value'''||'''Description'''
+
|-
|-  
+
| '''Field'''  
| 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.  
+
| '''Datatype'''  
|-  
+
| '''Default Value'''  
| source||node of class GUIControl|The node of the GUI Control on which the event was originated
+
| '''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  
 +
| class="class" | The node of the GUI Control on which the event was originated
 
|}
 
|}
  
<br clear="all">
+
<br>  
 +
 
 +
==== GUI Layout Functions  ====
  
==== GUI Layout Functions ====
 
 
<hsl>
 
<hsl>
 
SuppressLayout(guiNode as noderef)
 
SuppressLayout(guiNode as noderef)
Line 320: Line 379:
  
 
ForceLayout(GUInode as noderef)
 
ForceLayout(GUInode as noderef)
</hsl>
+
</hsl>  
  
=== Other Event-Related Functions ===
+
=== Other Event-Related Functions ===
==== 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()
+
==== onControlBuild  ====
- Called on the GUIMovePanel when it's no longer being dragged.
+
  
OnDragEnter(draggable as noderef)
+
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. <hsl>
- Called on a target control (i.e. ignoreDragDropEvents=false) when a GUIMovePanel is dragged into its space.
+
method onControlBuild()
 +
</hsl>
  
OnDragOver(draggable as noderef)
+
==== OnNodeDestroy  ====
- Called on a target control when a GUIMovePanel is dragged within its space.
+
  
OnDragDrop(draggable as noderef) as boolean
+
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. <hsl>
- Called on a target control when a GUIMovePanel is dropped onto it; return TRUE if the drop was successful (which prevents the OnDragStop() call).
+
method OnNodeDestroy(args references Class GUINodeDestroyEvent)
 +
</hsl>
  
OnDragLeave(draggable as noderef)
+
==== GUI Drag and Drop  ====
- Called on a target control when a GUIMovePanel is dragged out of its space.
+
  
==== OnSliceCross ====
+
OnDragStart() as boolean - Called on the GUIMovePanel when it's first dragged; return TRUE if you want to prevent dragging.
  
OnSliceCross(oldSlice as integer, newSlice as integer) as Boolean
+
OnDragStop() - Called on the GUIMovePanel when it's no longer being dragged.  
- Called whenever the mouse moves from one section of a GUI9Slice to another.  (This happens just before the '''onMouseMove''' event, and will interrupt it if you return FALSE.)
+
  
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.
+
OnDragEnter(draggable as noderef) - Called on a target control (i.e. ignoreDragDropEvents=false) when a GUIMovePanel is dragged into its space.  
  
==== Set Keyboard Focus ====
+
OnDragOver(draggable as noderef) - Called on a target control when a GUIMovePanel is dragged within its space.
<hsl>
+
SetKeyboardFocus(control as noderef of class GUIControl)
+
</hsl>
+
  
Client function which gives keyboard focus to the given control; only works for controls that accept keyboard input (GUITextInputBox and GUINumericField)
+
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.
  
==== Get GUI Control Owner ====
+
==== GetSliceFromPosition  ====
<hsl>
+
GetGUIControlOwner(whichControl as noderef of class GUIControl) as noderef of class GUIControl
+
</hsl>
+
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.
+
  
== GUIXML examples ==
+
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) <hsl>
 +
SetKeyboardFocus(control as noderef of class GUIControl)
 +
</hsl>
 +
 
 +
==== 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. <hsl>
 +
GetGUIControlOwner(whichControl as noderef of class GUIControl) as noderef of class GUIControl
 +
</hsl>
  
* [[Technical:XMLInterface Examples|GUIXMLInterface Examples]]
+
== See also  ==
  
== See also==
+
*[[Technical:Graphical Editor|GUIEditor]]  
* [[Technical:Graphical Editor | GUIEditor]]
+
*[[GUIXML]]
* [[GUIXML]]
+
*[[Technical:XMLInterface Examples|GUIXMLInterface Examples]]
* [[Technical:Graphical Controls | GUIControls]]
+
*[[Technical:Graphical Controls|GUIControls]]  
* [[Technical:GUIAnimations|GUIAnimations]]
+
*[[Technical:GUIAnimations|GUIAnimations]]  
* [[Technical:Graphical Functions | GUIFunctions]]
+
*[[Technical:Graphical Functions|GUIFunctions]]  
* [[Events]]
+
*[[Events]]
  
[[Category:GUI]]
+
[[Category:GUI]] [[Category:GUI_functions|GUI events]] [[Category:Events]] [[Category:Script_entry_points]]
[[Category:GUI functions|GUI events]]
+
[[Category:Events]]
+
[[Category:Script entry points]]
+

Revision as of 22:44, 10 November 2011

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 described below.

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