Difference between revisions of "RegisterEventHandler"

From The Official Visionaire Studio: Adventure Game Engine Wiki
(10 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<div class="toccolours mw-collapsible mw-collapsed" style="background: #f0f0f0; border: 1px dashed darkgrey" width="100%">
+
==registerEventHandler==
<b>Command History</b>
 
<div class="mw-collapsible-content">
 
<div style="background:#ebebeb" width="100%">Available since <span style="color:orange">v3.6</span></div>
 
<div>animationStarted, animationStopped, textStarted & textStopped event listener LUA commands added to <span style="color:orange">v3.6</span></div>
 
<div style="background:#ebebeb" width="100%">mouseEvent listener added to <span style="color:orange">v3.7</span></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>
{| class="mw-collapsible mw-collapsed" style="background: #f0f0f0; border: 1px dashed darkgrey" width="100%"
 
! Additional Info
 
|-
 
|
 
Current events available: <br/>
 
mainLoop, mouseEvent, animationStarted, animationStopped, textStarted & textStopped
 
|}
 
  
 
+
Lua Syntax:
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>
registerEventHandler("eventName", "functionName", {integerValue or eventFlagName})
 
</syntaxhighlight>
 
 
 
<span style="font-size:15px"><b><u>mainLoop</u></b></span>
 
 
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!
 
 
 
Example 1: mainLoop (code inside of the loop event - not recommended!)
 
<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 onMouseEvent(eventType, mousePosition)
function checkValue()
+
  if eventType == eEvtMouseWheelUp or eventType == eEvtMouseWheelDown then
-- if x equals less than 100 then + 1 should be added to value of x on each loop until x equals 100!
+
    -- mouse wheel was activated, do something
if x < 100 then
+
   end
   x = x + 1
 
end
 
 
end
 
end
  
-- let's create the mainLoop event, where we will include functions for looping!
+
registerEventHandler("mouseEvent", "onMouseEvent", {eEvtMouseMove, eEvtMouseLeftButtonDoubleClick, eEvtMouseLeftButtonDown, eEvtMouseLeftButtonUp, eEvtMouseLeftButtonHold, eEvtMouseLeftButtonHolding, eEvtMouseRightButtonDoubleClick, eEvtMouseRightButtonDown, eEvtMouseRightButtonUp, eEvtMouseMiddleButtonDown, eEvtMouseMiddleButtonUp, eEvtMouseWheelUp, eEvtMouseWheelDown})
function onMainLoop()
 
checkValue() -- calls checkVal function on each loop!
 
end
 
 
 
-- let's create the loop handler!
 
registerEventHandler("mainLoop", "onMainLoop")
 
end
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 
+
Example 3: keyEvent
 
+
<syntaxhighlight>
 
+
function keyboardHandler(eventType, character, keycode, modifiers)
<span style="font-size:15px"><b><u>mouseEvent</u></b></span>
+
  if eventType==eEvtKeyUp then
 
+
    print('key up: ' .. keycode)
you should only include one instance of the "mouseEvent" listener per game/project!
+
    -- test for '0' with character parameter
{| class="mw-collapsible mw-collapsed" style="background: #f0f0f0; border: 1px dashed darkgrey" width="100%"
+
    if character == '0' then print('0 released') end
! Additional Info
+
    -- another option to test '0' key
|-
+
    if keycode == 48 then print('0 released') end
|
+
  elseif eventType==eEvtKeyDown then
Current mouseEvent eventFlags available: (if no mouseEvent flags are included then all mouse events will be registered!)
+
    print('key down: ' .. keycode)
<syntaxhighlight enclose="div">
+
  elseif eventType==eEvtKeyTextInput then
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)
+
    -- this will also show more 'complex' unicode characters when multiple keys are used to generate a single character (e.g. Chinese characters)
</syntaxhighlight> <br/>
+
    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
Example: mouseEvent
+
    return true
<syntaxhighlight enclose="div">
+
  end
--[[
+
  return false -- key event will also be handled by engine
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)
 
-- bleh!
 
 
end
 
end
  
-- let's create the mouseEvent listener!
+
registerEventHandler("keyEvent", "keyboardHandler")
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 of the mouseEvents; only add the ones you need for your game!
 
--]]
 
 
</syntaxhighlight>
 
</syntaxhighlight>
 
 
 
<b><u>Arguments</u></b>
 
 
will add later!
 
 
Flags: n/a (will add later)
 
 
Return: 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")