|
|
| Line 1: |
Line 1: |
| − | ==registerEventHandler==
| + | #REDIRECT [[Global Command: 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>
| |
| − | | |
| − | 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>
| |
| − | function onMainLoop()
| |
| − | -- do something
| |
| − | end
| |
| − | | |
| − | registerEventHandler("mainLoop", "onMainLoop")
| |
| − | </syntaxhighlight>
| |
| − | Example 2: mouseEvent
| |
| − | <syntaxhighlight>
| |
| − | 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})
| |
| − | </syntaxhighlight>
| |
| − | Example 3: keyEvent
| |
| − | <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
| |
| − | | |
| − | registerEventHandler("keyEvent", "keyboardHandler")
| |
| − | </syntaxhighlight>
| |
