Difference between revisions of "Lua API:Event"
(Remove vague reference to ascii) |
(Mention keyboard layouts for extra confusion) |
||
Line 35: | Line 35: | ||
: This event can be canceled | : This event can be canceled | ||
: Arguments: key, scan, rep, shift, ctrl, alt | : Arguments: key, scan, rep, shift, ctrl, alt | ||
− | :: '''key''' is the key code. The interface API provides constants you can use to compare this with: 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) | + | :: '''key''' is the key code. This is a number that represents the symbol that may be printed on a key on a keyboard. The relation of these numbers to physical keys varies wildly across systems and keyboard layouts. The interface API provides constants you can use to compare this with: 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. 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) | :: '''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) | ||
:: '''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. | :: '''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. |
Latest revision as of 13:55, 30 August 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. This is a number that represents the symbol that may be printed on a key on a keyboard. The relation of these numbers to physical keys varies wildly across systems and keyboard layouts. The interface API provides constants you can use to compare this with: 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.