Difference between revisions of "RegisterEventHandler"

From The Official Visionaire Studio: Adventure Game Engine Wiki
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<div class="toccolours mw-collapsible mw-collapsed tbl-ds">
+
==registerEventHandler==
<span>Command History</span>
 
<div class="mw-collapsible-content">
 
<div class="alt-bg">Available since v3.6</div>
 
<div>animationStarted, animationStopped, textStarted & textStopped event listener LUA commands added to v3.6</div>
 
<div class="alt-bg">mouseEvent listener added to v3.7</div>
 
</div></div>
 
  
 +
<div class="command-min-version-info">Available since: <span class="command-min-version">v3.6</span></div>
  
registerEventHandler is an event listener which lets you declare what should happen when specific events are registered!
+
<div class="command-doc">Registers an event handler function for a specific event.</div>
<div class="toccolours mw-collapsible mw-collapsed tbl-ds">
 
<span class="bold">Additional Info</span>
 
<div class="mw-collapsible-content">
 
<div>Current events available:
 
<pre>mainLoop, mouseEvent, animationStarted, animationStopped, textStarted & textStopped</pre></div>
 
</div></div>
 
  
 
+
Lua Syntax:
Syntax:
+
<pre class="command-syntax">registerEventHandler(event, eventHandler [, eventFlags])</pre>
<syntaxhighlight>
+
===Arguments===
registerEventHandler("eventName", "functionName", {integerValue or eventFlagName})
+
====event====
</syntaxhighlight>
+
:'''"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.
<span class="medium bold underline">mainLoop</span>
+
:
 
+
:The function for the events "animationStarted", "animationStopped", "textStarted" and "textStopped" should take exactly one argument which is the affected visionaire object.
you should only include one instance of the "mainLoop" event per game/project! <br/>
+
:
currently there is no delay/pause method to control the speed of the loop!
+
: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).
Example 1: mainLoop (code inside of the loop event - not recommended!)
+
:
 +
: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>
-- let's create the function for the mainLoop event!
 
 
function onMainLoop()
 
function onMainLoop()
-- if x equals less than 100 then + 1 should be added to value of x on each loop until x equals 100!
+
-- do something
if x < 100 then
 
  x = x + 1
 
end
 
 
end
 
end
  
-- let's create the loop handler!
 
 
registerEventHandler("mainLoop", "onMainLoop")
 
registerEventHandler("mainLoop", "onMainLoop")
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
Example 2: mouseEvent
Example 2: mainLoop (including functions inside of the loop event - recommended!)
 
 
<syntaxhighlight>
 
<syntaxhighlight>
-- let's create a function that we will include inside of the mainLoop event!
 
function checkValue()
 
-- if x equals less than 100 then + 1 should be added to value of x on each loop until x equals 100!
 
if x < 100 then
 
  x = x + 1
 
end
 
end
 
 
-- let's create the mainLoop event, where we will include functions for looping!
 
function onMainLoop()
 
checkValue() -- calls checkVal function on each loop!
 
end
 
 
-- let's create the loop handler!
 
registerEventHandler("mainLoop", "onMainLoop")
 
end
 
</syntaxhighlight>
 
 
 
<span class="medium bold underline">mouseEvent</span>
 
 
you should only include one instance of the "mouseEvent" listener per game/project!
 
<div class="toccolours mw-collapsible mw-collapsed tbl-ds">
 
<span class="bold">Additional Info</span>
 
<div class="mw-collapsible-content">
 
<div>Current mouseEvent eventFlags available: (if no mouseEvent flags are included then all mouse events will be registered!)
 
<syntaxhighlight>eEvtMouseMove(1), eEvtMouseLeftButtonDoubleClick(2), eEvtMouseLeftButtonDown(3), eEvtMouseLeftButtonUp(4), eEvtMouseLeftButtonHold(5), eEvtMouseLeftButtonHolding(6), eEvtMouseRightButtonDoubleClick(7), eEvtMouseRightButtonDown(8), eEvtMouseRightButtonUp(9), eEvtMouseMiddleButtonDown(10), eEvtMouseMiddleButtonUp(11), eEvtMouseWheelUp(12) & eEvtMouseWheelDown(13)</syntaxhighlight></div>
 
</div></div>
 
 
 
Example: mouseEvent
 
<syntaxhighlight enclose="div">
 
--[[
 
Like the mainLoop event you can create what each registered event should do inside of the mouseEvent function or you can add functions which could be called based on certain conditions or not!
 
--]]
 
 
-- let's create the function for the mouseEvent listener!
 
 
function onMouseEvent(eventType, mousePosition)
 
function onMouseEvent(eventType, mousePosition)
-- bleh!
+
  if eventType == eEvtMouseWheelUp or eventType == eEvtMouseWheelDown then
 +
    -- mouse wheel was activated, do something
 +
  end
 
end
 
end
  
-- let's create the mouseEvent listener!
 
 
registerEventHandler("mouseEvent", "onMouseEvent", {eEvtMouseMove, eEvtMouseLeftButtonDoubleClick, eEvtMouseLeftButtonDown, eEvtMouseLeftButtonUp, eEvtMouseLeftButtonHold, eEvtMouseLeftButtonHolding, eEvtMouseRightButtonDoubleClick, eEvtMouseRightButtonDown, eEvtMouseRightButtonUp, eEvtMouseMiddleButtonDown, eEvtMouseMiddleButtonUp, eEvtMouseWheelUp, eEvtMouseWheelDown})
 
registerEventHandler("mouseEvent", "onMouseEvent", {eEvtMouseMove, eEvtMouseLeftButtonDoubleClick, eEvtMouseLeftButtonDown, eEvtMouseLeftButtonUp, eEvtMouseLeftButtonHold, eEvtMouseLeftButtonHolding, eEvtMouseRightButtonDoubleClick, eEvtMouseRightButtonDown, eEvtMouseRightButtonUp, eEvtMouseMiddleButtonDown, eEvtMouseMiddleButtonUp, eEvtMouseWheelUp, eEvtMouseWheelDown})
 
--[[
 
registerEventHandler("mouseEvent", "onMouseEvent", {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13})
 
would also work & saves time on having to type out all the string versions of the mouseEvents!
 
note: you don't need to add all of the mouseEvents; only add the ones you need for your game!
 
--]]
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
Example 3: keyEvent
 
 
<span class="medium bold underline">animationStarted & animationStopped</span>
 
 
 
you should only include one instance of the "animationStarted" & "animationStopped" listener per game/project!
 
 
 
 
 
Example: animationStarted & animationStopped
 
 
<syntaxhighlight>
 
<syntaxhighlight>
-- let's create the function which will perform the included functions or code provided; when an animation has been started!
+
function keyboardHandler(eventType, character, keycode, modifiers)
function onAnimStarted()
+
  if eventType==eEvtKeyUp then
print("an animation has been started!")
+
    print('key up: ' .. keycode)
end
+
    -- test for '0' with character parameter
 
+
    if character == '0' then print('0 released') end
-- let's create the function which will perform the included functions or code provided; when an animation has been stopped!
+
    -- another option to test '0' key
function onAnimStopped()
+
    if keycode == 48 then print('0 released') end
print("an animation has finished playing!")
+
  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
  
-- let's create the event listener for checking when an animation has been started!
+
registerEventHandler("keyEvent", "keyboardHandler")
registerEventHandler("animationStarted", "onAnimStarted")
 
 
 
-- let's create the event listener for checking when an animation has finished!
 
registerEventHandler("animationStopped","onAnimStopped")
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 
 
<span class="medium bold underline">textStarted & textStopped</span>
 
 
 
you should only include one instance of the "textStarted" & "textStopped" listener per game/project!
 
 
 
Example: textStarted & textStopped
 
<syntaxhighlight>
 
-- let's create the function which performs the provided functions or code when text is being displayed!
 
function onTextStarted()
 
-- add a function to call or provide some code ...
 
end
 
 
-- let's create the function which performs the provided functions or code when text has finished being displayed!
 
function onTextStopped()
 
-- add a function to call or provide some code ...
 
end
 
 
-- let's create the event listeners to determine when a text is being displayed or has finished displaying!
 
registerEventHandler("textStarted", "onTextStarted")
 
registerEventHandler("textStopped", "onTextStopped")
 
</syntaxhighlight>
 
 
 
 
<span class="bold underline">Arguments</span>
 
 
<span class="bold">eventName</span>: "string" <br/>
 
Current available events:
 
* mainLoop: allows you to create a loop which executes functions & code provided inside of the "functionName"
 
* mouseEvent: allows you to control what various mouse actions will do
 
* animationStarted: allows you to execute functions & code provided inside of the "functionName" when an animation is started
 
* animationStopped: allows you to execute functions & code provided inside of the "functionName" when an animation has ended
 
* textStarted: allows you to execute functions & code provided inside of the "functionName" when text is being displayed
 
* textStopped: allows you to execute functions & code provided inside of the "functionName" when text has finished being displayed
 
 
<span class="bold">functionName</span>: "string" <br/>
 
This is the name of the function that will be called/used for the event handlers/listeners.
 
 
 
<span class="bold underline">Flags</span>
 
 
<span class="bold">eventFlags</span>: integer (number) <br/>
 
This is only for the mouseEvent listener; the available mouse events are:
 
* eEvtMouseMove(1)
 
* eEvtMouseLeftButtonDoubleClick(2)
 
* eEvtMouseLeftButtonDown(3)
 
* eEvtMouseLeftButtonUp(4)
 
* eEvtMouseLeftButtonHold(5)
 
* eEvtMouseLeftButtonHolding(6)
 
* eEvtMouseRightButtonDoubleClick(7)
 
* eEvtMouseRightButtonDown(8)
 
* eEvtMouseRightButtonUp(9)
 
* eEvtMouseMiddleButtonDown(10)
 
* eEvtMouseMiddleButtonUp(11)
 
* eEvtMouseWheelUp(12)
 
* eEvtMouseWheelDown(13)
 
 
 
<span class="bold underline">Return</span>
 
 
none
 
{{i18n|RegisterEventHandler}}
 

Revision as of 21:27, 30 September 2014

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")