We want certain changes to occur when certain events happen. The player clicks a button, and this runs some script that makes a change to the game state. We do this using the action tag.
<!-- When the player clicks the object, the JS function DoSomething() is called. -->
<object name="whatever">
<action on="Press"><![CDATA[
DoSomething();
]]></action>
</object>
This next example is an "evil hack" which can be used to set the function call for an object's action from JS. For example, to call the function DoSomething(), passing the parameters SomeParam1, SomeParam2, and SomeParam3, when the player clicks a control called SomeObject:
SomeObject.onPress = function (m, n, o)
{
return function()
{
DoSomething (m, n, o);
}
} (SomeParam1, SomeParam2, SomeParam3);
Key: Italicised title means property is mandatory.
on
The most important property of is the on="" property. Here we specify a string reference to the kind of action that must occur in order to run the encapsulated script.
Just like with object properties, there are the base ones, and the extended ones.
Base Actions
The base actions are generic and can be used by any object regardless of type.
Load
Executed when the control object is first initialised at startup. Often used to perform special configuration or initialisation of an object.
MouseEnter
Only called once when entering an object.
MouseLeave
Opposite to MouseEnter.
MouseLeftPress
Called the instance the left mouse button is pressed.
MouseLeftRelease
Opposite to MouseLeftPress.
MouseMove
Called when the cursor is moving while hovering the object.
Progress
This is a special action fired when g_Progress and/or g_LoadDescription are updated during the loading of a game session.
Tick
Event occurs each game 'tick'. Use for objects that need to be constantly refreshed. It's best to find any possible alternative to a tick event, as it will cause slowdown of game processing.
Update
Called when a property has been updated.
Extended Actions
These actions are type specific. Check an object's documentation to see which extended actions are available.
Press
Executed when the object is triggered (such as when the user clicks a button, presses enter in a text field, or presses a button's hotkey). Properties like sprite_pressed and text_pressed are used during this action.
SelectionChange
Used for objects like List and Drop-down when the selection is changed. As of now, setting the selection to what it already is, will still trigger the action.
Tab
Executed when the "Tab" key is pressed on an input field (for things like autocomplete).
file
An optional "file" property can be used to run a script from a separate file, rather than using inline script or a function call.
<action on="Press" file="scriptfile1.js" />
Using both the file property and an inline script will concatenate the inline script to the file script.