Class rtk.Event

Holds the state of events such as mouse or keyboard action. These don't generally need to be explicitly created but are passed along in event handlers (e.g. rtk.Widget:onclick())

Event type constants

The type field will be set to one of these values.

rtk.Event.MOUSEDOWN

A mouse button was pressed (button indicates which)

rtk.Event.MOUSEUP

A mouse button was released (button indicates which)

rtk.Event.MOUSEMOVE

The mouse cursor was moved. Note that in certain situations this event can fire even when the mouse hasn't moved, for example to trigger an rtk.Viewport to scroll when dragging a widget beyond the viewport edge. In such situations, simulated will be true.

rtk.Event.MOUSEWHEEL

The mouse wheel was moved (wheel and hwheel indicate direction and distance)

rtk.Event.KEY

A key was pressed on the keyboard (keycode and possibly char indicate which key)

rtk.Event.DROPFILE

One or more files were dragged and dropped over the widget (files indicates which). To handle dropped files globally, add the ondropfile callback to the rtk.Window itself.

rtk.Event.WINDOWCLOSE

The main window is just about to close. This is a notification-only event as currently there is no way to abort closure of the main window.

Class API

Attributes
type typeconst

read-only

Type of event which is set to one of the type constants

handled rtk.Widget or nil

read-only

The rtk.Widget of the widget that handled the event, or nil if not handled

button number

read-only

The mouse button that was the cause of the event, whether pressed or released, according to the mouse button constants. For MOUSEMOVE events, this will be the last pressed button (or 0 if no button is currently pressed).

buttons number

read-only

A bitmap of all mouse buttons currently pressed. Note that for MOUSEUP events this may be 0, if there are no more buttons pressed. To determine which button was released, use the button field.

wheel number

read-only

The vertical scroll wheel distance for MOUSEWHEEL events, negative for wheel up and positive for wheel down. A distance of 1 is roughly one "click" of a scrollwheel, and greater values indicate kinetic scrolling.

hwheel number

read-only

Like wheel but for horizontal scroll wheels.

keycode number

read-only

The raw numeric keycode of the KEY event that can be compared against rtk.keycodes

char string

read-only

A single-character string containing the printable character of the key, if available. Is nil if not translatable into a printable character.

ctrl boolean

read-only

True if the control key was held during the KEY event

shift boolean

read-only

True if the shift key was held during the KEY event

alt boolean

read-only

True if the alt key was held during the KEY event

meta boolean

read-only

True if the meta key (Windows key, for example) was held during the KEY event

modifiers number

read-only

A low-level bitmap of key event modifiers. 4=ctrl, 8=shift, 16=alt, 32=meta

files table

read-only

Set for DROPFILE events and is a table of file paths that were dropped onto the window

x number

read-only

The x client coordinate of the mouse cursor relative to the left edge of the rtk.Window

y number

read-only

The y client coordinate of the mouse cursor relative to the top edge of the rtk.Window

time number

read-only

Timestamp when the event occurred according to reaper.time_precise(). Because reaper.time_precise() is used, this is not wall time, and can only be used for purposes of calculating deltas with future calls to reaper.time_precise().

simulated boolean

read-only

If true, this is a simulated MOUSEMOVE event used to trigger some time-based behavior (such as viewport edge-scrolling or rtk.Widget:onlongpress())

debug boolean

read-only

If not nil, is the rtk.Widget that is being examined for debugging when rtk.debug is true

Methods
rtk.Event()

Creates a new event

reset()

Resets all fields in the event and sets to the given type

is_mouse_event()

Checks if the event is related to the mouse

get_button_duration()

Determine how long a mouse button has been pressed and held

set_widget_mouseover()

Marks the given widget as having the mouse over it for this event

set_modifiers()

Set the various modifier attributes according to the mouse/keyboard modifier state (per REAPER's gfx.mouse_cap)

set_handled()

Marks the event as having been handled

clone()

Clone the event

Methods

rtk.Event(attrs)

Creates a new event.

Parameters
attrs (table or nil)

optional table of attributes to initialize the event with

Return Values
(rtk.Event)

the newly constructed event

rtk.Event:reset(type)

Resets all fields in the event and sets to the given type

Parameters
type (typeconst)

the type of event

rtk.Event:is_mouse_event()

Checks if the event is related to the mouse.

Return Values
(boolean)

true if the event is a mouse-related event, false otherwise.

rtk.Event:get_button_duration(button)

Determine how long a mouse button has been pressed and held.

Parameters
button (rtk.mouse or nil)

mouse button constant, or nil to use the current value of the event's button.

Return Values
(number or nil)

the amount of time in seconds the mouse button was held for, or nil if the mouse button is not current pressed

rtk.Event:set_widget_mouseover(widget)

Marks the given widget as having the mouse over it for this event.

The main purpose of this method is tracking which widgets should be debugged but may have other purposes in future.

rtk.Event:set_modifiers(cap, button)

Set the various modifier attributes according to the mouse/keyboard modifier state (per REAPER's gfx.mouse_cap).

This is called by rtk.Window when a new event is generated.

Parameters
cap (number)

the bitmap containing mouse/keyboard state

button (number)

the specific mouse button that triggered the event per mouse button constants

rtk.Event:set_handled(widget)

Marks the event as having been handled.

Once an event is handled, it won't be actioned by any other widget. So event handlers can prevent handlers for other widgets with lower z-indexes from responding to an event by calling this method.

Parameters
widget (rtk.Widget or nil)

the widget that handled the event

rtk.Event:clone(overrides)

Clone the event.

Parameters
overrides (table)

replaces the attributes in the cloned event with the given table.

Return Values
(rtk.Widget)

a new event object