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.

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.