Lua API:Event

From The Powder Toy
Revision as of 04:32, 14 February 2019 by jacob1 (talk | contribs) (document the keyboard handling events)
Jump to: navigation, search

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(number eventType, function 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.

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.

event.unregister

event.unregister(number eventType, function eventHandler)

Unregister a previously registered event handler. Has no effect of 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.

Event Types

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.
Arguments: key, scan, repeat, 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
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
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
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
Arguments: key, scan, repeat, shift, ctrl, alt
These arguments mean exactly the same thing as for keypress events. Repeat will always be false.
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.
Arguments: text
mousedown
mouseup
mousemove
mousewheel
tick
blur
close