Handling events
The sprite, window and widget objects can receive the following cursor events:
- EventCursorDown: A cursor touch state changed from up to down.
- EventCursorHit: The object has been clicked on (or hit).
- EventCursorUp: A cursor state changed from down to up.
- EventCursorEnter: A cursor entered the object region.
- EventCursorLeave: A cursor leaved the object region.
- EventCursorMove: A cursor is moving directly above the object.
Writing an event handler.
The handler function must have the following signature: function name(event, table). A handler receives two parameters from the engine, the event code and the event table.
The event table contains detailed informations on the event accessible through the following members:
- sprite: The sprite the event occurred on.
- window: The window the event occurred on.
- widget: The widget the event occurred on.
- cursor_id: Identifier of the cursor.
- x: Cursor X coordinate.
- y: Cursor Y coordinate.
- dx: Cursor X coordinate delta from the previous update to the current.
- dy: Cursor Y coordinate delta from the previous update to the current.
- down: Cursor down state.
Note: Due to the internal engine data structure, a window and a sprite are the same object, both the sprite and window members can be accessed in the same manner with no consequence.
If the event occurs on a widget, the following members will be available:
- id: The widget id.
In the case of events occurring in the context of a sprite or window, the following members expressed in the sprite or window local coordinate system, will be available:
- local_x: Cursor X coordinate.
- local_y: Cursor Y coordinate.
- local_dx: Cursor delta X coordinate.
- local_dy: Cursor delta Y coordinate.
Handling events from script.
In order to receive events a script must specify an event handler for the object it handles events for. Sprite and window event handlers are set using the WindowSetEventHandler and SpriteSetEventHandler functions.
-
// Declare a global event handler.
-
function onCursorEnterSpriteArea(event, table)
-
{
-
print("Cursor entered sprite area")
-
}
-
-
// Create a new sprite.
-
local sprite = UIAddSprite(ui, -1, EngineLoadTexture(g_engine, "button.png"), 400, 200, 128, 64)
-
-
// Set EventCursorEnter handler.
-
SpriteSetEventHandler(sprite, EventCursorEnter, onCursorEnterSpriteArea)
The widget handler can be set using the similar function WidgetSetEventHandler.
Handling events from a specific instance.
In order to receive an event from a specific instance you must use following functions to declare the handler, SpriteSetEventHandlerWithContext, WindowSetEventHandlerWithContext and WidgetSetEventHandlerWithContext.
These functions let you specify the context in which the handler is called when an event occurs.
-
class ClickableSprite
-
{
-
identifier = 0
-
sprite = 0
-
-
function hitHandler(event, table)
-
{
-
print("ClickableSprite " + identifier + " hit!")
-
}
-
-
constructor(ui, id)
-
{
-
// Store this instance identifier.
-
identifier = id
-
-
// Create the support sprite (offset by the identifier index).
-
sprite = UIAddSprite(ui, -1, EngineLoadTexture("gfx/boing.png"), 64 * identifier, 0, 64, 64)
-
-
/*
-
Set the ClickableSprite::hitHandler function as the cursor hit
-
event handler and make the callback occur from this instance context
-
by passing 'this' as the context.
-
*/
-
SpriteSetEventHandlerWithContext(sprite, EventCursorHit, this, hitHandler)
-
}
-
}
-
-
// Each ClickableSprite instantiated will receive the cursor hit event in the context of its own instance.
-
g_sprite_a <- ClickableSprite(ui, 0)
-
g_sprite_b <- ClickableSprite(ui, 1)