Difference between revisions of "RegisterEventHandler"
From The Official Visionaire Studio: Adventure Game Engine Wiki
(22 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | + | ==registerEventHandler== | |
− | + | <div class="command-min-version-info">Available since: <span class="command-min-version">v3.6</span></div> | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
+ | <div class="command-doc">Registers an event handler function for a specific event.</div> | ||
− | Syntax: | + | Lua Syntax: |
+ | <pre class="command-syntax">registerEventHandler(event, eventHandler [, eventFlags])</pre> | ||
+ | ===Arguments=== | ||
+ | ====event==== | ||
+ | :'''"string"''' - The event which triggers the event handler to be called. Currently supported events: "mainLoop", "mouseEvent", "keyEvent", "animationStarted", "animationStopped", "textStarted", "textStopped". | ||
+ | ====eventHandler==== | ||
+ | :'''"string"''' - The name of the lua function which is called when the event occurs. | ||
+ | : | ||
+ | :The function for the events "animationStarted", "animationStopped", "textStarted" and "textStopped" should take exactly one argument which is the affected visionaire object. | ||
+ | : | ||
+ | :There are no arguments for the "mainLoop" event handler. | ||
+ | : | ||
+ | :The function for "mouseEvent" takes two arguments, the first one is the mouse event (see "eventFlags" parameter) and the second argument is the current mouse position (a table containing x- and y-position). | ||
+ | : | ||
+ | :The function for "keyEvent" takes four arguments: eventType, character, keycode and modifiers. Return value must be true or false. If the function returns true, the key event will not be handled by the engine. | ||
+ | :eventType: eEvtKeyDown (key pressed, can be fired multiple times for pressed key), eEvtKeyTextInput (text input, can be fired multiple times for pressed key) and eEvtKeyUp (key released, only fired once). | ||
+ | :character: current text input of pressed key(s). This parameter only contains printable characters. | ||
+ | :keycode: virtual keycode, only valid for eEvtKeyDown and eEvtKeyUp events. Can be used to query special keys like Esc or Shift. | ||
+ | :modifiers: currently active key modifiers (e.g. Ctrl, Shift). | ||
+ | ====eventFlags==== | ||
+ | :'''{int,...}''' - Can only be specified for "mouseEvent": a list of mouse events where the event handler is called. | ||
+ | :Currently the following mouse events are supported: eEvtMouseMove, eEvtMouseLeftButtonDoubleClick, eEvtMouseLeftButtonDown, eEvtMouseLeftButtonUp, eEvtMouseLeftButtonHold, eEvtMouseLeftButtonHolding, eEvtMouseRightButtonDoubleClick, eEvtMouseRightButtonDown, eEvtMouseRightButtonUp, eEvtMouseMiddleButtonDown, eEvtMouseMiddleButtonUp, eEvtMouseWheelUp and eEvtMouseWheelDown. If no mouse event is specified then the event handler is registered for all mouse events. | ||
+ | ===Flags=== | ||
+ | ===Return Values=== | ||
+ | None. | ||
+ | ===Examples=== | ||
+ | Example 1: mainLoop | ||
<syntaxhighlight> | <syntaxhighlight> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
function onMainLoop() | function onMainLoop() | ||
− | + | -- do something | |
− | |||
− | |||
− | |||
end | end | ||
− | |||
registerEventHandler("mainLoop", "onMainLoop") | registerEventHandler("mainLoop", "onMainLoop") | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | + | Example 2: mouseEvent | |
− | Example 2: | ||
<syntaxhighlight> | <syntaxhighlight> | ||
− | + | function onMouseEvent(eventType, mousePosition) | |
− | + | if eventType == eEvtMouseWheelUp or eventType == eEvtMouseWheelDown then | |
− | + | -- mouse wheel was activated, do something | |
− | + | end | |
− | |||
− | |||
end | end | ||
− | + | registerEventHandler("mouseEvent", "onMouseEvent", {eEvtMouseMove, eEvtMouseLeftButtonDoubleClick, eEvtMouseLeftButtonDown, eEvtMouseLeftButtonUp, eEvtMouseLeftButtonHold, eEvtMouseLeftButtonHolding, eEvtMouseRightButtonDoubleClick, eEvtMouseRightButtonDown, eEvtMouseRightButtonUp, eEvtMouseMiddleButtonDown, eEvtMouseMiddleButtonUp, eEvtMouseWheelUp, eEvtMouseWheelDown}) | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | registerEventHandler(" | ||
− | |||
</syntaxhighlight> | </syntaxhighlight> | ||
− | + | Example 3: keyEvent | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
<syntaxhighlight> | <syntaxhighlight> | ||
− | -- | + | function keyboardHandler(eventType, character, keycode, modifiers) |
− | + | if eventType==eEvtKeyUp then | |
− | -- | + | print('key up: ' .. keycode) |
− | + | -- test for '0' with character parameter | |
− | -- | + | if character == '0' then print('0 released') end |
− | + | -- another option to test '0' key | |
− | + | if keycode == 48 then print('0 released') end | |
+ | elseif eventType==eEvtKeyDown then | ||
+ | print('key down: ' .. keycode) | ||
+ | elseif eventType==eEvtKeyTextInput then | ||
+ | -- this will also show more 'complex' unicode characters when multiple keys are used to generate a single character (e.g. Chinese characters) | ||
+ | print('input: ' .. character) | ||
+ | end | ||
+ | if keycode == eKeyEscape then | ||
+ | -- event will not be handled by engine. this means that also cutscenes can't be skipped with Escape key | ||
+ | return true | ||
+ | end | ||
+ | return false -- key event will also be handled by engine | ||
end | end | ||
− | + | registerEventHandler("keyEvent", "keyboardHandler") | |
− | registerEventHandler(" | ||
− | |||
− | |||
− | |||
− | |||
− | |||
</syntaxhighlight> | </syntaxhighlight> | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− |
Revision as of 22:27, 30 September 2014
Contents
registerEventHandler
Available since: v3.6
Registers an event handler function for a specific event.
Lua Syntax:
registerEventHandler(event, eventHandler [, eventFlags])
Arguments
event
- "string" - The event which triggers the event handler to be called. Currently supported events: "mainLoop", "mouseEvent", "keyEvent", "animationStarted", "animationStopped", "textStarted", "textStopped".
eventHandler
- "string" - The name of the lua function which is called when the event occurs.
- The function for the events "animationStarted", "animationStopped", "textStarted" and "textStopped" should take exactly one argument which is the affected visionaire object.
- There are no arguments for the "mainLoop" event handler.
- The function for "mouseEvent" takes two arguments, the first one is the mouse event (see "eventFlags" parameter) and the second argument is the current mouse position (a table containing x- and y-position).
- The function for "keyEvent" takes four arguments: eventType, character, keycode and modifiers. Return value must be true or false. If the function returns true, the key event will not be handled by the engine.
- eventType: eEvtKeyDown (key pressed, can be fired multiple times for pressed key), eEvtKeyTextInput (text input, can be fired multiple times for pressed key) and eEvtKeyUp (key released, only fired once).
- character: current text input of pressed key(s). This parameter only contains printable characters.
- keycode: virtual keycode, only valid for eEvtKeyDown and eEvtKeyUp events. Can be used to query special keys like Esc or Shift.
- modifiers: currently active key modifiers (e.g. Ctrl, Shift).
eventFlags
- {int,...} - Can only be specified for "mouseEvent": a list of mouse events where the event handler is called.
- Currently the following mouse events are supported: eEvtMouseMove, eEvtMouseLeftButtonDoubleClick, eEvtMouseLeftButtonDown, eEvtMouseLeftButtonUp, eEvtMouseLeftButtonHold, eEvtMouseLeftButtonHolding, eEvtMouseRightButtonDoubleClick, eEvtMouseRightButtonDown, eEvtMouseRightButtonUp, eEvtMouseMiddleButtonDown, eEvtMouseMiddleButtonUp, eEvtMouseWheelUp and eEvtMouseWheelDown. If no mouse event is specified then the event handler is registered for all mouse events.
Flags
Return Values
None.
Examples
Example 1: mainLoop
function onMainLoop()
-- do something
end
registerEventHandler("mainLoop", "onMainLoop")
Example 2: mouseEvent
function onMouseEvent(eventType, mousePosition)
if eventType == eEvtMouseWheelUp or eventType == eEvtMouseWheelDown then
-- mouse wheel was activated, do something
end
end
registerEventHandler("mouseEvent", "onMouseEvent", {eEvtMouseMove, eEvtMouseLeftButtonDoubleClick, eEvtMouseLeftButtonDown, eEvtMouseLeftButtonUp, eEvtMouseLeftButtonHold, eEvtMouseLeftButtonHolding, eEvtMouseRightButtonDoubleClick, eEvtMouseRightButtonDown, eEvtMouseRightButtonUp, eEvtMouseMiddleButtonDown, eEvtMouseMiddleButtonUp, eEvtMouseWheelUp, eEvtMouseWheelDown})
Example 3: keyEvent
function keyboardHandler(eventType, character, keycode, modifiers)
if eventType==eEvtKeyUp then
print('key up: ' .. keycode)
-- test for '0' with character parameter
if character == '0' then print('0 released') end
-- another option to test '0' key
if keycode == 48 then print('0 released') end
elseif eventType==eEvtKeyDown then
print('key down: ' .. keycode)
elseif eventType==eEvtKeyTextInput then
-- this will also show more 'complex' unicode characters when multiple keys are used to generate a single character (e.g. Chinese characters)
print('input: ' .. character)
end
if keycode == eKeyEscape then
-- event will not be handled by engine. this means that also cutscenes can't be skipped with Escape key
return true
end
return false -- key event will also be handled by engine
end
registerEventHandler("keyEvent", "keyboardHandler")