Difference between pages "Global Command: getWindowBrightness" and "Global Command: registerEventHandler"

From The Official Visionaire Studio: Adventure Game Engine Wiki
(Difference between pages)
 
 
Line 1: Line 1:
−
Returns the brightness (gamma) of the window. A value of 0 is completely dark, 100 is normal brightness.
+
Registering an event handler allows you to run custom functions on specific engine events.
  
 
{| class="ts"
 
{| class="ts"
 
|-
 
|-
 
| style="width:15%" | Related functions
 
| style="width:15%" | Related functions
−
| [[Global Command: setWindowBrightness|setWindowBrightness]]
+
| [[Global Command: unregisterEventHandler|unregisterEventHandler]]
 
|}
 
|}
  
Line 10: Line 10:
 
== Syntax ==
 
== Syntax ==
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
−
getWindowBrightness()
+
registerEventHandler(eventType, handler [, flags])
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 16: Line 16:
 
== Parameters ==
 
== Parameters ==
  
−
none
+
{| class="ts"
 +
|-
 +
! style="width:15%" | Parameter
 +
! style="width:15%" | Type
 +
! style="width:15%" | Supported values
 +
! colspan="2" | Description
 +
|-
 +
| rowspan="9" | eventType
 +
| rowspan="9" | string
 +
| "actionArea"
 +
| Event fires when a character enters or leaves an action area.
 +
| rowspan="9" style="width:15%" | The type of event which triggers the event handler to be called.
 +
|-
 +
| "animationStarted"
 +
| Event fires when an animation gets started.
 +
|-
 +
| "animationStopped"
 +
| Event fires when an animation gets stopped.
 +
|-
 +
| "engineEvent"
 +
| Event fires on certain engine events.
 +
|-
 +
| "keyEvent"
 +
| Event fires when the user presses a key on the keyboard or gamepad.
 +
|-
 +
| "mainLoop"
 +
| Event fires continuously about 60 times per second.
 +
|-
 +
| "mouseEvent"
 +
| Event fires when the user uses the mouse or fingers/gestures on touch devices.
 +
|-
 +
| "textStarted"
 +
| Event fires when a text gets displayed.
 +
|-
 +
| "textStopped"
 +
| Event fires when a text display ends.
 +
|-
 +
| handler
 +
| string
 +
|
 +
| colspan="2" | The name of the function which is called when the event occurs. See the table below for the arguments the function takes.
 +
|-
 +
| flags
 +
| table of integers
 +
| ''see the list of mouse events in the table below''
 +
| colspan="2" | A list of mouse events upon which the event handler is called. Only applicable if eventType = "mouseEvent". If no mouse event is specified, the event handler is registered for all mouse events.
 +
|}
 +
 
 +
 
 +
=== Event handler function ===
  
 +
Depending on the event type, the event handler function takes different arguments.
  
−
== Return values ==
 
 
{| class="ts"
 
{| class="ts"
 
|-
 
|-
−
! style="width:15%" | Type
+
! style="width:15%" | Event type
−
! Description
+
! style="width:15%" | Arguments
 +
! colspan="2" | Description
 +
|-
 +
| rowspan="3" | "actionArea"
 +
| movement (str)
 +
| colspan="2" | The event which triggered the function. Supported values:
 +
* "ENTER"
 +
* "LEAVE"
 +
|-
 +
| actionArea (TVisObj)
 +
| colspan="2" | The action area that triggered the event.
 +
|-
 +
| character (TVisObj)
 +
| colspan="2" | The character that triggered the event.
 +
|-
 +
| "animationStarted"
 +
| animation (TVisObj)
 +
| colspan="2" | The animation which gets started.
 +
|-
 +
| "animationStopped"
 +
| animation (TVisObj)
 +
| colspan="2" | The animation which gets stopped.
 +
|-
 +
| rowspan="2" | "engineEvent"
 +
| event (str)
 +
| colspan="2" | The engine event which triggered the function. Supported values:
 +
* "LoadingSavegameSuccess"
 +
|-
 +
| path (str)
 +
| colspan="2" | The full path to the loaded savegame file.
 +
''Example (Windows): "C:\Users\USERNAME\AppData\Local/DEVELOPER/GAME/Savegames/savegame00.dat"''
 +
|-
 +
| rowspan="4" | "keyEvent"
 +
| eventType (int)
 +
| The key event which triggered the function. Supported values:
 +
* eEvtKeyDown (1): This event can be fired multiple times when pressing a key.
 +
* eEvtKeyUp (2): This event will only fire once when pressing a key.
 +
* eEvtKeyTextInput (3): This event can be fired multiple times when pressing a key. Use it to keep track of the user entering more complex unicode characters, where multiple keys have to be pressed to generate a single character (e.&nbsp;g. Chinese characters).
 +
* eEvtControllerKeyDown (4)
 +
* eEvtControllerKeyUp (5)
 +
* eEvtControllerAxis (6)
 +
| rowspan="4" style="width:15%" | The function must return a boolean. If true the key event will not be handled by the engine.
 +
|-
 +
| character (str)
 +
| The text input of the pressed key. This parameter only contains printable characters.
 +
|-
 +
| keycode (int)
 +
| Unicode/ASCII keycode of the pressed key (only valid for "eEvtKeyDown" and "eEvtKeyUp" events). Use it to query special keys like the following:
 +
* eKeyBackspace (8)
 +
* eKeyTab (9)
 +
* eKeyReturn (13)
 +
* eKeyEscape (27)
 +
* eKeySpace (32)
 +
|-
 +
| modifiers (int)
 +
| The currently active key modifiers (only valid for "eEvtKeyDown" and "eEvtKeyUp" events):
 +
* eKeyModLShift (1)
 +
* eKeyModRShift (2)
 +
* eKeyModShift (3)
 +
* eKeyModLCtrl (64)
 +
* eKeyModCtrl (192)
 +
* eKeyModRCtrl (128)
 +
* eKeyModLAlt (256)
 +
* eKeyModRAlt (512)
 +
* eKeyModAlt (768)
 +
* eKeyModLGui (1024)
 +
* eKeyModRGui (2048)
 +
* eKeyModGui (3072)
 +
* eKeyModNum (4096)
 +
* eKeyModCaps (8192)
 +
* eKeyModMode (16384)
 +
|-
 +
| "mainLoop"
 +
| none
 +
| colspan="2" |
 +
|-
 +
| rowspan="5" | "mouseEvent"
 +
| eventType (int)
 +
| colspan="2" | The mouse event which triggered the function. Supported values:
 +
* 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)
 +
* eEvtMultiGesture (14)
 +
* eEvtDollarGesture (15)
 +
* eEvtTouchDown (16)
 +
* eEvtTouchUp (17)
 +
* eEvtTouchMove (18)
 +
|-
 +
| position (t_point)
 +
| colspan="2" | The mouse position or the normalized center of the gesture (for "eEvtMultiGesture" and "eEvtDollarGesture" events), respectively. A table (associative array) containing the elements '''x (int)''' and '''y (int)'''.
 +
|-
 +
| fingers1 (int)
 +
| colspan="2" | Only valid for "eEvtMultiGesture" and "eEvtDollarGesture" events:
 +
* for "eEvtMultiGesture": the amount that the fingers pinched during the motion
 +
* for "eEvtDollarGesture": the difference between the gesture template and the actual performed gesture (the lower the number, the better the match)
 +
|-
 +
| fingers2 (int)
 +
| colspan="2" | Only valid for "eEvtMultiGesture" and "eEvtDollarGesture" events:
 +
* for "eEvtMultiGesture": the amount that the fingers rotated during the motion, in radians
 +
* for "eEvtDollarGesture": the number of fingers used in the gesture
 +
|-
 +
| fingers3 (int)
 +
| colspan="2" | Only valid for "eEvtMultiGesture" and "eEvtDollarGesture" events:
 +
* for "eEvtMultiGesture": the number of fingers used in the gesture
 +
* for "eEvtDollarGesture": the unique id of the closest gesture to the performed stroke
 +
|-
 +
| "textStarted"
 +
| text (TVisObj)
 +
| colspan="2" | The text object which gets displayed.
 +
|-
 +
| "textStopped"
 +
| text (TVisObj)
 +
| colspan="2" | The text object which gets stopped displaying.
 
|-
 
|-
−
| integer
 
−
| The current gamma/brightness value.
 
 
|}
 
|}
 +
 +
 +
== Return values ==
 +
 +
none
  
  
 
== Examples ==
 
== Examples ==
  
−
'''Example 1:''' Do something, if the brightness value is less than 50%.
+
'''Example 1:''' Register an event handler function for the main loop, printing a text to the log file continuously.
−
<syntaxhighlight lang ="lua">
+
<syntaxhighlight lang="lua">
−
if getWindowBrightness() < 50 then
+
function onMainLoop()
−
   -- do something
+
  print("I am still alive!")
 +
end
 +
 
 +
registerEventHandler("mainLoop", "onMainLoop")
 +
</syntaxhighlight>
 +
 
 +
 
 +
'''Example 2:''' Register an event handler function for mouse events which is called when the user uses the scroll wheel.
 +
<syntaxhighlight lang="lua">
 +
function onMouseEvent(eventType, position)
 +
  if eventType == eEvtMouseWheelUp then
 +
    print("User scrolled up.")
 +
  elseif eventType == eEvtMouseWheelDown then
 +
    print("User scrolled down.")
 +
   end
 
end
 
end
 +
 +
registerEventHandler("mouseEvent", "onMouseEvent", {eEvtMouseWheelUp, eEvtMouseWheelDown})
 +
</syntaxhighlight>
 +
 +
 +
'''Example 3:''' Register an event handler function for key events.
 +
<syntaxhighlight lang="lua">
 +
function keyboardHandler(eventType, character, keycode, modifiers)
 +
  -- Two different ways of checking for the 0 key (by "character" or by "keycode" argument)
 +
  if eventType == eEvtKeyDown then
 +
    if character == "0" then
 +
      print("0 pressed")
 +
    end
 +
  elseif eventType == eEvtKeyUp then
 +
    if keycode == 48 then
 +
      print("0 released")
 +
    end
 +
  end
 +
 +
  -- disable the "Esc" key (cutscenes can't be skipped)
 +
  if keycode == eKeyEscape then
 +
    -- return true to prevent the engine from handling the key event
 +
    return true
 +
  end
 +
 +
  -- return false to let the engine handle the key event, too
 +
  return false
 +
end
 +
 +
registerEventHandler("keyEvent", "keyboardHandler")
 +
</syntaxhighlight>
 +
 +
 +
'''Example 4:''' Register an event handler function which gets executed after loading a savegame (be aware that this is only an example; the "read_ini()" function doesn't exist unless you created it).
 +
<syntaxhighlight lang="lua">
 +
function onEngineEvent(event, path)
 +
  if event == "LoadingSavegameSuccess" then
 +
    read_ini()
 +
  end
 +
end
 +
 +
registerEventHandler("engineEvent", "onEngineEvent")
 +
</syntaxhighlight>
 +
 +
 +
'''Example 5:''' Register an event handler function for the "textStarted" event. It keeps the user from skipping texts accidentally.
 +
<syntaxhighlight lang="lua">
 +
function delaySkipText(text)
 +
  if not text.Background then
 +
    -- Prevent text skipping
 +
    game.AlwaysAllowSkipText = false
 +
 
 +
    -- Allow skipping again after 300ms have passed; create a non-skippable cutscene for
 +
    -- that period of time by hiding the cursor, if no cutscene is currently active
 +
    if game.HideCursor == false and game.CutsceneAction:isEmpty() then
 +
      game.HideCursor = true
 +
   
 +
      setDelay(300, function() game.AlwaysAllowSkipText = true; game.HideCursor = false end)
 +
    else
 +
      setDelay(300, function() game.AlwaysAllowSkipText = true end)
 +
    end
 +
  end
 +
end
 +
 +
registerEventHandler("textStarted", "delaySkipText")
 
</syntaxhighlight>
 
</syntaxhighlight>
 
{{toc}}
 
{{toc}}

Revision as of 10:18, 11 August 2023

Registering an event handler allows you to run custom functions on specific engine events.

Related functions unregisterEventHandler


Syntax

registerEventHandler(eventType, handler [, flags])


Parameters

Parameter Type Supported values Description
eventType string "actionArea" Event fires when a character enters or leaves an action area. The type of event which triggers the event handler to be called.
"animationStarted" Event fires when an animation gets started.
"animationStopped" Event fires when an animation gets stopped.
"engineEvent" Event fires on certain engine events.
"keyEvent" Event fires when the user presses a key on the keyboard or gamepad.
"mainLoop" Event fires continuously about 60 times per second.
"mouseEvent" Event fires when the user uses the mouse or fingers/gestures on touch devices.
"textStarted" Event fires when a text gets displayed.
"textStopped" Event fires when a text display ends.
handler string The name of the function which is called when the event occurs. See the table below for the arguments the function takes.
flags table of integers see the list of mouse events in the table below A list of mouse events upon which the event handler is called. Only applicable if eventType = "mouseEvent". If no mouse event is specified, the event handler is registered for all mouse events.


Event handler function

Depending on the event type, the event handler function takes different arguments.

Event type Arguments Description
"actionArea" movement (str) The event which triggered the function. Supported values:
  • "ENTER"
  • "LEAVE"
actionArea (TVisObj) The action area that triggered the event.
character (TVisObj) The character that triggered the event.
"animationStarted" animation (TVisObj) The animation which gets started.
"animationStopped" animation (TVisObj) The animation which gets stopped.
"engineEvent" event (str) The engine event which triggered the function. Supported values:
  • "LoadingSavegameSuccess"
path (str) The full path to the loaded savegame file.

Example (Windows): "C:\Users\USERNAME\AppData\Local/DEVELOPER/GAME/Savegames/savegame00.dat"

"keyEvent" eventType (int) The key event which triggered the function. Supported values:
  • eEvtKeyDown (1): This event can be fired multiple times when pressing a key.
  • eEvtKeyUp (2): This event will only fire once when pressing a key.
  • eEvtKeyTextInput (3): This event can be fired multiple times when pressing a key. Use it to keep track of the user entering more complex unicode characters, where multiple keys have to be pressed to generate a single character (e. g. Chinese characters).
  • eEvtControllerKeyDown (4)
  • eEvtControllerKeyUp (5)
  • eEvtControllerAxis (6)
 The function must return a boolean. If true the key event will not be handled by the engine.
character (str) The text input of the pressed key. This parameter only contains printable characters.
keycode (int) Unicode/ASCII keycode of the pressed key (only valid for "eEvtKeyDown" and "eEvtKeyUp" events). Use it to query special keys like the following:
  • eKeyBackspace (8)
  • eKeyTab (9)
  • eKeyReturn (13)
  • eKeyEscape (27)
  • eKeySpace (32)
modifiers (int) The currently active key modifiers (only valid for "eEvtKeyDown" and "eEvtKeyUp" events):
  • eKeyModLShift (1)
  • eKeyModRShift (2)
  • eKeyModShift (3)
  • eKeyModLCtrl (64)
  • eKeyModCtrl (192)
  • eKeyModRCtrl (128)
  • eKeyModLAlt (256)
  • eKeyModRAlt (512)
  • eKeyModAlt (768)
  • eKeyModLGui (1024)
  • eKeyModRGui (2048)
  • eKeyModGui (3072)
  • eKeyModNum (4096)
  • eKeyModCaps (8192)
  • eKeyModMode (16384)
"mainLoop" none
"mouseEvent" eventType (int) The mouse event which triggered the function. Supported values:
  • 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)
  • eEvtMultiGesture (14)
  • eEvtDollarGesture (15)
  • eEvtTouchDown (16)
  • eEvtTouchUp (17)
  • eEvtTouchMove (18)
position (t_point) The mouse position or the normalized center of the gesture (for "eEvtMultiGesture" and "eEvtDollarGesture" events), respectively. A table (associative array) containing the elements x (int) and y (int).
fingers1 (int) Only valid for "eEvtMultiGesture" and "eEvtDollarGesture" events:
  • for "eEvtMultiGesture": the amount that the fingers pinched during the motion
  • for "eEvtDollarGesture": the difference between the gesture template and the actual performed gesture (the lower the number, the better the match)
fingers2 (int) Only valid for "eEvtMultiGesture" and "eEvtDollarGesture" events:
  • for "eEvtMultiGesture": the amount that the fingers rotated during the motion, in radians
  • for "eEvtDollarGesture": the number of fingers used in the gesture
fingers3 (int) Only valid for "eEvtMultiGesture" and "eEvtDollarGesture" events:
  • for "eEvtMultiGesture": the number of fingers used in the gesture
  • for "eEvtDollarGesture": the unique id of the closest gesture to the performed stroke
"textStarted" text (TVisObj) The text object which gets displayed.
"textStopped" text (TVisObj) The text object which gets stopped displaying.


Return values

none


Examples

Example 1: Register an event handler function for the main loop, printing a text to the log file continuously. 

function onMainLoop()
  print("I am still alive!")
end

registerEventHandler("mainLoop", "onMainLoop")


Example 2: Register an event handler function for mouse events which is called when the user uses the scroll wheel. 

function onMouseEvent(eventType, position)
  if eventType == eEvtMouseWheelUp then
    print("User scrolled up.")
  elseif eventType == eEvtMouseWheelDown then
    print("User scrolled down.")
  end
end

registerEventHandler("mouseEvent", "onMouseEvent", {eEvtMouseWheelUp, eEvtMouseWheelDown})


Example 3: Register an event handler function for key events. 

function keyboardHandler(eventType, character, keycode, modifiers)
  -- Two different ways of checking for the 0 key (by "character" or by "keycode" argument)
  if eventType == eEvtKeyDown then
    if character == "0" then
      print("0 pressed")
    end
  elseif eventType == eEvtKeyUp then
    if keycode == 48 then
      print("0 released")
    end
  end

  -- disable the "Esc" key (cutscenes can't be skipped)
  if keycode == eKeyEscape then
    -- return true to prevent the engine from handling the key event
    return true
  end

  -- return false to let the engine handle the key event, too
  return false
end

registerEventHandler("keyEvent", "keyboardHandler")


Example 4: Register an event handler function which gets executed after loading a savegame (be aware that this is only an example; the "read_ini()" function doesn't exist unless you created it). 

function onEngineEvent(event, path)
  if event == "LoadingSavegameSuccess" then
    read_ini()
  end
end

registerEventHandler("engineEvent", "onEngineEvent")


Example 5: Register an event handler function for the "textStarted" event. It keeps the user from skipping texts accidentally. 

function delaySkipText(text)
  if not text.Background then
    -- Prevent text skipping
    game.AlwaysAllowSkipText = false
  
    -- Allow skipping again after 300ms have passed; create a non-skippable cutscene for
    -- that period of time by hiding the cursor, if no cutscene is currently active
    if game.HideCursor == false and game.CutsceneAction:isEmpty() then
      game.HideCursor = true
    
      setDelay(300, function() game.AlwaysAllowSkipText = true; game.HideCursor = false end)
    else
      setDelay(300, function() game.AlwaysAllowSkipText = true end)
    end
  end
end 

registerEventHandler("textStarted", "delaySkipText")


Retrieved from "https://wiki.visionaire-tracker.net/index.php?title=Global_Command:_getWindowBrightness&oldid=12137"
  • Powered by MediaWiki