Difference between revisions of "Lua API:Event"

From The Powder Toy
Jump to: navigation, search
m (mark the events that can be canceled)
(Add beforesimdraw and aftersimdraw)
 
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
The Elements API contains methods and constants for listening to events. This is the api you should use if you want to handle mouse and keyboard input. Shorthand: you can use evt. instead of event.
+
The Elements API contains methods and constants for listening to events. This is the API you should use if you want to handle mouse and keyboard input. Shorthand: you can use evt. instead of event.
  
 
== Methods ==
 
== Methods ==
  
 
=== event.register ===
 
=== event.register ===
  function event.register(number eventType, function eventHandler)
+
  <function> event.register(eventType, eventHandler)
Registers an event handler for a certain type of event. See the list of constants at the bottom of the page for possible events you can listen to. Returns eventHandler, in case it's a lambda function and you want to unregister it later.
+
Registers an event handler for a specific type of event. See the list of constants at the bottom of the page for possible events you can listen to. The constants exist under the event namespace, not as strings. Returns eventHandler, this could be useful in case eventHandler is a lambda function and you want to unregister it later.
  
The event handler will be called with a varying number of arguments, depending on which type of event is being handled. Certain events can also be canceled by returning false from the event.
+
The event handler will be called with a varying number of arguments, depending on which type of event is being handled.<br/>
 +
Some events can also be ignored by TPT if the event handler returns false.
 +
 
 +
Example:<br/>
 +
-- Declare function
 +
F = function(x, y)
 +
  print("mouse clicked at " .. x .. "," .. y)
 +
  if (y < 300) return true end -- Should TPT also handle the event?
 +
  return false -- No, TPT should not receive the event
 +
end
 +
event.register(event.mousedown, F) -- Hook function
 +
event.unregister(event.mousedown, F) -- Unhook function
  
 
=== event.unregister ===
 
=== event.unregister ===
  event.unregister(number eventType, function eventHandler)
+
  <nil> event.unregister(eventType, eventHandler)
Unregister a previously registered event handler. Has no effect of this function wasn't registered or wasn't registered under this event type.
+
Unregister a previously registered event handler. Has no effect if this function wasn't registered or wasn't registered under this event type.
  
 
=== event.getmodifiers ===
 
=== event.getmodifiers ===
  number event.getmodifiers()
+
  <number> event.getmodifiers()
Gets the current keyboard modifier state. Includes bits describing whether shift, ctrl, alt, caps lock, num lock, and other modifiers are pressed / set.
+
Gets the current keyboard modifier state. Includes bits describing whether shift, ctrl, alt, caps lock, num lock, and other modifiers are pressed / set. Constants for modifiers are present in the interface API and can be found [https://github.com/The-Powder-Toy/The-Powder-Toy/blob/master/src/lua/LuaSDLKeys.h here] (the ones starting with KMOD, for example, interface.KMOD_LCTRL)
  
 
== Event Types ==
 
== Event Types ==
 +
These event types are all constants under the event API, you should use these constants as arguments to the event.register and event.unregister functions
 +
 
; keypress
 
; keypress
: This event is sent every time a key is pressed, and continuously re-sent if they key is held down. This event should be used if you want to have a key shortcut; The textinput event should be used instead if you want to handle text input / Unicode.
+
: This event is sent every time a key is pressed, and continuously re-sent if the key is held down. This event should be used if you want to have a key shortcut; The textinput event should be used instead if you want to handle text input / Unicode.
 
: This event can be canceled
 
: This event can be canceled
: Arguments: key, scan, repeat, shift, ctrl, alt
+
: Arguments: key, scan, rep, shift, ctrl, alt
:: key is the key code, a number that is usually the ascii value for the key, but for non-printable characters it may be a high number. You can find a list of key codes here: https://wiki.libsdl.org/SDLKeycodeLookup
+
:: '''key''' is the key code, a number that is usually the ASCII value for the key, but for non-printable characters, it may be a high number. The interface API provides constants you can use, you can find a list of key codes [https://github.com/The-Powder-Toy/The-Powder-Toy/blob/master/src/lua/LuaSDLKeys.h here] (the ones starting with SDLK, for example, interface.SDLK_a)
:: scan is the scan code. This is a number that represents the physical location of a key on a keyboard. You can find a list of scan codes here: https://wiki.libsdl.org/SDLScancodeLookup
+
:: '''scan''' is the scan code. This is a number that represents the physical location of a key on a keyboard. The interface API provides constants you can use, you can find a list of scan codes [https://github.com/The-Powder-Toy/The-Powder-Toy/blob/master/src/lua/LuaSDLKeys.h here] (the ones starting with SDL_SCANCODE, for example, interface.SDL_SCANCODE_COMMA)
:: repeat is a boolean that tells whether this is a key repeat event (sent every so often when the key is held down). You may want to ignore this event when it is just a key repeat event
+
:: '''rep''' is a boolean that tells whether this is a key repeat event (sent every so often when the key is held down). You may want to ignore this event when it is just a key repeat event. Note that 'repeat' is a reserved keyword in Lua, so name your function argument rep instead.
:: shift / ctrl / alt are booleans that will tell you whether those modifiers are currently held
+
:: '''shift''' / '''ctrl''' / '''alt''' are booleans that will tell you whether those modifiers are currently held
 
; keyrelease
 
; keyrelease
 
: This event is sent every time a key is released
 
: This event is sent every time a key is released
 
: This event can be canceled
 
: This event can be canceled
: Arguments: key, scan, repeat, shift, ctrl, alt
+
: Arguments: key, scan, rep, shift, ctrl, alt
:: These arguments mean exactly the same thing as for keypress events. Repeat will always be false.
+
:: These arguments mean exactly the same thing as for keypress events. rep will always be false.
 
; textinput
 
; textinput
: This event is sent every time text is input. The text will be sent as a string, and may be more than one character or contain Unicode.  
+
: This event is sent every time text is input. The text will be sent as a string and may contain more than one character or Unicode.  
 
: Arguments: text
 
: Arguments: text
 
; mousedown
 
; mousedown
Line 38: Line 51:
 
: This event can be canceled
 
: This event can be canceled
 
: Arguments: x, y, button
 
: Arguments: x, y, button
:: x and y will not be adjusted for the zoom window. See sim.adjustCoords for that. Coordinates may be outside of the simulation bounds (clicks outside the simulation area are still sent)
+
:: '''x''' and '''y''' will not be adjusted for the zoom window. See sim.adjustCoords for that. Coordinates may be outside of the simulation bounds (clicks outside the simulation area are still sent)
:: button is the mouse button pressed. 1 is left click, 2 is middle click, 3 is right click. There may also be higher mouse buttons like 4 and 5.
+
:: '''button''' is the mouse button pressed. 1 is left click, 2 is middle click, and 3 is right click. There may also be higher mouse buttons like 4 and 5.
 
; mouseup
 
; mouseup
 
: This event is sent whenever the mouse is released. There are also other some special cases this event may be sent,
 
: This event is sent whenever the mouse is released. There are also other some special cases this event may be sent,
 
: This event can be canceled (only when reason = 0)
 
: This event can be canceled (only when reason = 0)
 
: Arguments: x, y, button, reason
 
: Arguments: x, y, button, reason
:: x, y, and button function the same as the mousedown event
+
:: '''x''', '''y''', and '''button''' function the same as the mousedown event
:: reason is a number that describes what type of mouseup event this is (basically, hacks we sent mouseup events on anyway). reason 0 is for normal mouseup events. reason 1 is used when another interface is opened and a blur event is sent. This is how tpt ensures that the mouse isn't "stuck" down forever if you release the mouse after opening another interface. reason 2 is used when the mouse moves inside or outside of the zoom window. This is how tpt cancels mouse drawing with zoom windows to ensure a big line isn't drawn across the screen. The normal reason = 0 event will still be sent later.
+
:: '''reason''' is a number that describes what type of mouseup event this is (basically, hacks we sent mouseup events on anyway). reason 0 is for normal mouseup events. reason 1 is used when another interface is opened and a blur event is sent. This is how tpt ensures that the mouse isn't "stuck" down forever if you release the mouse after opening another interface. reason 2 is used when the mouse moves inside or outside the zoom window. This is how tpt cancels mouse drawing with zoom windows to ensure a big line isn't drawn across the screen. The normal reason = 0 event will still be sent later.
 
; mousemove
 
; mousemove
 
: This event is sent every time the mouse is moved. It is only sent when the mouse is inside the tpt window, unless the mouse is held, in which case it can also be sent outside of the tpt window until the mouse is released. Coordinates from outside the tpt window bounds (including negative coordinates) can be sent in that case.
 
: This event is sent every time the mouse is moved. It is only sent when the mouse is inside the tpt window, unless the mouse is held, in which case it can also be sent outside of the tpt window until the mouse is released. Coordinates from outside the tpt window bounds (including negative coordinates) can be sent in that case.
 
: This event can be canceled
 
: This event can be canceled
 
: Arguments: x, y, dx, dy
 
: Arguments: x, y, dx, dy
:: x and y are the mouse coordinates. dx and dy are the diff from the previous coordinates to the current ones.
+
:: '''x''' and '''y''' are the mouse coordinates. '''dx''' and '''dy''' are the diff from the previous coordinates to the current ones.
 
; mousewheel
 
; mousewheel
 
: This event is sent whenever the mousewheel is scrolled.
 
: This event is sent whenever the mousewheel is scrolled.
 
: This event can be canceled
 
: This event can be canceled
 
: Arguments: x, y, d
 
: Arguments: x, y, d
:: x and y are the mouse position where the wheel was scrolled
+
:: '''x''' and '''y''' are the mouse position where the wheel was scrolled
:: d is the distance the mouse was scrolled (always -1 or 1 for me). Horizontal scrolling is not supported at the moment, in the meantime d will be 0 for horizontal scrolling.
+
:: '''d''' is the distance the mouse was scrolled. On nearly all mice this will be 1 or -1, but in certain situations, it may be higher.  You most likely want to treat higher values as 1 or -1 anyway. Horizontal scrolling is not supported at the moment, in the meantime d will be 0 for horizontal scrolling.
 
; tick
 
; tick
 
: This event is sent once per frame. It is sent after the simulation frame finishes and everything is drawn to the screen.
 
: This event is sent once per frame. It is sent after the simulation frame finishes and everything is drawn to the screen.
 +
; beforesim
 +
: This event is sent once per frame, but only if the sim is unpaused or being stepped through using framestep or subframe particle debugging. It is sent before any particle simulation or air updates have been done.
 +
; aftersim
 +
: This event is sent once per frame, but only if the sim is unpaused or being stepped through using framestep or subframe particle debugging. It is sent after all particles have been simulated.
 +
; beforesimdraw
 +
: This event is sent once per frame, before the simulation is drawn. It is sent after pressure / velocity mode graphics are drawn (if enabled), but before all other particles or simulation graphics are drawn.
 +
; aftersimdraw
 +
: This event is sent once per frame, after the simulation is drawn. All particles and graphics, such as the cursor, are already drawn. The only thing not yet rendered is the zoom window.
 
; blur
 
; blur
 
: This event is sent whenever a blocking interface (such as the save browser or the console) is opened. Lua scripts don't function in those interfaces, so this event can be used to detect when the lua script is about to stop receiving any events during that time.
 
: This event is sent whenever a blocking interface (such as the save browser or the console) is opened. Lua scripts don't function in those interfaces, so this event can be used to detect when the lua script is about to stop receiving any events during that time.
 
; close
 
; close
 
: This event is sent whenever the tpt window is about to close.
 
: This event is sent whenever the tpt window is about to close.

Latest revision as of 20:36, 10 March 2024

The Elements API contains methods and constants for listening to events. This is the API you should use if you want to handle mouse and keyboard input. Shorthand: you can use evt. instead of event.

Methods

event.register

<function> event.register(eventType, eventHandler)

Registers an event handler for a specific type of event. See the list of constants at the bottom of the page for possible events you can listen to. The constants exist under the event namespace, not as strings. Returns eventHandler, this could be useful in case eventHandler is a lambda function and you want to unregister it later.

The event handler will be called with a varying number of arguments, depending on which type of event is being handled.
Some events can also be ignored by TPT if the event handler returns false.

Example:

-- Declare function
F = function(x, y)
 print("mouse clicked at " .. x .. "," .. y)
 if (y < 300) return true end -- Should TPT also handle the event?
 return false -- No, TPT should not receive the event
end
event.register(event.mousedown, F) -- Hook function
event.unregister(event.mousedown, F) -- Unhook function

event.unregister

<nil> event.unregister(eventType, eventHandler)

Unregister a previously registered event handler. Has no effect if this function wasn't registered or wasn't registered under this event type.

event.getmodifiers

<number> event.getmodifiers()

Gets the current keyboard modifier state. Includes bits describing whether shift, ctrl, alt, caps lock, num lock, and other modifiers are pressed / set. Constants for modifiers are present in the interface API and can be found here (the ones starting with KMOD, for example, interface.KMOD_LCTRL)

Event Types

These event types are all constants under the event API, you should use these constants as arguments to the event.register and event.unregister functions

keypress
This event is sent every time a key is pressed, and continuously re-sent if the key is held down. This event should be used if you want to have a key shortcut; The textinput event should be used instead if you want to handle text input / Unicode.
This event can be canceled
Arguments: key, scan, rep, shift, ctrl, alt
key is the key code, a number that is usually the ASCII value for the key, but for non-printable characters, it may be a high number. The interface API provides constants you can use, you can find a list of key codes here (the ones starting with SDLK, for example, interface.SDLK_a)
scan is the scan code. This is a number that represents the physical location of a key on a keyboard. The interface API provides constants you can use, you can find a list of scan codes here (the ones starting with SDL_SCANCODE, for example, interface.SDL_SCANCODE_COMMA)
rep is a boolean that tells whether this is a key repeat event (sent every so often when the key is held down). You may want to ignore this event when it is just a key repeat event. Note that 'repeat' is a reserved keyword in Lua, so name your function argument rep instead.
shift / ctrl / alt are booleans that will tell you whether those modifiers are currently held
keyrelease
This event is sent every time a key is released
This event can be canceled
Arguments: key, scan, rep, shift, ctrl, alt
These arguments mean exactly the same thing as for keypress events. rep will always be false.
textinput
This event is sent every time text is input. The text will be sent as a string and may contain more than one character or Unicode.
Arguments: text
mousedown
This event is sent whenever the mouse is clicked.
This event can be canceled
Arguments: x, y, button
x and y will not be adjusted for the zoom window. See sim.adjustCoords for that. Coordinates may be outside of the simulation bounds (clicks outside the simulation area are still sent)
button is the mouse button pressed. 1 is left click, 2 is middle click, and 3 is right click. There may also be higher mouse buttons like 4 and 5.
mouseup
This event is sent whenever the mouse is released. There are also other some special cases this event may be sent,
This event can be canceled (only when reason = 0)
Arguments: x, y, button, reason
x, y, and button function the same as the mousedown event
reason is a number that describes what type of mouseup event this is (basically, hacks we sent mouseup events on anyway). reason 0 is for normal mouseup events. reason 1 is used when another interface is opened and a blur event is sent. This is how tpt ensures that the mouse isn't "stuck" down forever if you release the mouse after opening another interface. reason 2 is used when the mouse moves inside or outside the zoom window. This is how tpt cancels mouse drawing with zoom windows to ensure a big line isn't drawn across the screen. The normal reason = 0 event will still be sent later.
mousemove
This event is sent every time the mouse is moved. It is only sent when the mouse is inside the tpt window, unless the mouse is held, in which case it can also be sent outside of the tpt window until the mouse is released. Coordinates from outside the tpt window bounds (including negative coordinates) can be sent in that case.
This event can be canceled
Arguments: x, y, dx, dy
x and y are the mouse coordinates. dx and dy are the diff from the previous coordinates to the current ones.
mousewheel
This event is sent whenever the mousewheel is scrolled.
This event can be canceled
Arguments: x, y, d
x and y are the mouse position where the wheel was scrolled
d is the distance the mouse was scrolled. On nearly all mice this will be 1 or -1, but in certain situations, it may be higher. You most likely want to treat higher values as 1 or -1 anyway. Horizontal scrolling is not supported at the moment, in the meantime d will be 0 for horizontal scrolling.
tick
This event is sent once per frame. It is sent after the simulation frame finishes and everything is drawn to the screen.
beforesim
This event is sent once per frame, but only if the sim is unpaused or being stepped through using framestep or subframe particle debugging. It is sent before any particle simulation or air updates have been done.
aftersim
This event is sent once per frame, but only if the sim is unpaused or being stepped through using framestep or subframe particle debugging. It is sent after all particles have been simulated.
beforesimdraw
This event is sent once per frame, before the simulation is drawn. It is sent after pressure / velocity mode graphics are drawn (if enabled), but before all other particles or simulation graphics are drawn.
aftersimdraw
This event is sent once per frame, after the simulation is drawn. All particles and graphics, such as the cursor, are already drawn. The only thing not yet rendered is the zoom window.
blur
This event is sent whenever a blocking interface (such as the save browser or the console) is opened. Lua scripts don't function in those interfaces, so this event can be used to detect when the lua script is about to stop receiving any events during that time.
close
This event is sent whenever the tpt window is about to close.