Module rtk

Main rtk module. All functions and submodules across rtk are anchored under this namespace, however this page covers rtk's core functions.

Fields not marked as read-only are user-settable values that control rtk's global behavior and appearance. Read-only fields are automatically updated by rtk throughout program execution (as appropriate).

Synopsis

Fields
touchscroll boolean

read/write

Set to true to enable touch scrolling, where scrolling rtk.Viewport is possible by click-dragging within them, which is suitable for touchscreen displays (default false)

smoothscroll boolean

read/write

If true, scrolling viewports with the mouse wheel or programmatically will animate (default true)

touch_activate_delay number

read/write

When touchscroll is enabled, this is the default amount of time in seconds that widgets will wait before responding to a "mouse down" event (which equates to a touch event for touchscreen displays) (default 0.1 seconds)

long_press_delay number

read/write

Number of seconds the mouse is pressed over a widget before rtk.Widget:onlongpress() fires (default 0.5)

double_click_delay number

read/write

Interval between successive clicks before rtk.Widget:ondoubleclick() fires (default 0.5)

tooltip_delay number

read/write

Number of seconds where the mouse remains stationary over a widget before its tooltip pops up (default 0.5)

light_luma_threshold number

read/write

When the luminance of a color (as returned by rtk.color.luma()) is above this value then the color is considered "light" for purposes of picking appropriately contrasting text and icon colors (default 0.6)

debug boolean

read/write

Enables visual inspection of widget geometry by mousing over them (default false)

window rtk.Window or nil

read-only

The last rtk.Window object that was instantiated, or nil if none was instantiated

has_js_reascript_api boolean

read-only

true if the JS_ReaScriptAPI extension is installed, false otherwise

has_sws_extension boolean

read-only

true if the SWS extension is installed

script_path string

read-only

The full path to the directory containing the script that the REAPER action invoked

reaper_hwnd userdata

read-only

hwnd of Reaper's main window

tick number

read-only

Monotonically increasing counter that is incremented each gfx update cycle

fps number

read-only

Frame rate (measured on each update cycle of the main window)

focused_hwnd userdata

read-only

The hwnd of the currently focused window, or nil if js_ReaScriptAPI is not installed

focused boolean

read-only

The currently focused rtk.Widget (or nil if no widget is focused)

theme table

read-only

A table holding the current theme colors which is initialized via rtk.set_theme()

Functions
rtk.class()

Creates a new class

rtk.isa()

Determine if a value is an instance or sublcass of a particular class

rtk.add_image_search_path()

Registers an image search path where images and icons can be found by rtk.Image.icon() or rtk.Image:load()

rtk.set_theme()

Initializes the UI theme

rtk.set_theme_by_bgcolor()

Initializes the UI theme appropriate for the given background color

rtk.set_theme_overrides()

Applies custom overrides to the in-the-box theme settings

rtk.new_theme()

Creates a custom rtk color theme

rtk.add_modal()

Registers one or more widgets to be treated as modal

rtk.is_modal()

Check if the given widget (or any widget at all) has been registered as modal via rtk.add_modal()

rtk.reset_modal()

Removes all modal widget registrations, returning event routing to normal

rtk.pushdest()

Push a destination image id onto the stack for off-screen drawing

rtk.popdest()

Pops the last image destination off the stack

rtk.onerror()

Callback invoked when any function called via rtk.defer() or rtk.call() raises an error

rtk.call()

Immediately call a function with the given arguments with error handling

rtk.defer()

Registers a function (with arguments) to be called back by REAPER

rtk.callsoon()

Registers a function (with arguments) to be invoked within the next rtk.Window update

rtk.callafter()

Calls a function (with arguments) after the specified duration

rtk.quit()

Terminates the script, closing any open rtk.Window

Fields

rtk.touchscroll boolean read/write

Set to true to enable touch scrolling, where scrolling rtk.Viewport is possible by click-dragging within them, which is suitable for touchscreen displays (default false).

When this is enabled, certain interactions that normally occur immediately upon mouse-down (such as opening the popup menu of an rtk.OptionMenu) will be deferred until touch_activate_delay elapses, or in some cases until mouse up, giving the user the opportunity to touch scroll.

Touch scrolling in rtk also supports kinetic scrolling.

rtk.smoothscroll boolean read/write

If true, scrolling viewports with the mouse wheel or programmatically will animate (default true). This affects the default for all viewports, but individual viewports can override this with the rtk.Viewport.smoothscroll attribute.

REAPER limits scripts to 25-30fps (Windows being around 30 while Linux and OS X are closer to 25), so it can only ever really get so "smooth" but it's a useful enough effect that it's enabled by default.

rtk.touch_activate_delay number read/write

When touchscroll is enabled, this is the default amount of time in seconds that widgets will wait before responding to a "mouse down" event (which equates to a touch event for touchscreen displays) (default 0.1 seconds). This can be overridden per widget: see rtk.Widget.touch_activate_delay for more.

rtk.long_press_delay number read/write

Number of seconds the mouse is pressed over a widget before rtk.Widget:onlongpress() fires (default 0.5)

rtk.double_click_delay number read/write

Interval between successive clicks before rtk.Widget:ondoubleclick() fires (default 0.5)

rtk.tooltip_delay number read/write

Number of seconds where the mouse remains stationary over a widget before its tooltip pops up (default 0.5).

rtk.light_luma_threshold number read/write

When the luminance of a color (as returned by rtk.color.luma()) is above this value then the color is considered "light" for purposes of picking appropriately contrasting text and icon colors (default 0.6)

rtk.debug boolean read/write

Enables visual inspection of widget geometry by mousing over them (default false).

When enabled, mousing over a widget will paint boxes indicating its calculated geometry and padding boundaries, and will display a tooltip showing those values. When multiple widgets are stacked atop each other, the widget with the highest z-index will win.

When log.level is set to log.DEBUG or lower, pressing F12 will toggle this value if the rtk.Event.KEY event is unhandled.

rtk.window rtk.Window or nil read-only

The last rtk.Window object that was instantiated, or nil if none was instantiated. If you need to access global refs but don't have a reference to a widget available, you can use this field.

rtk.has_js_reascript_api boolean read-only

true if the JS_ReaScriptAPI extension is installed, false otherwise

rtk.has_sws_extension boolean read-only

true if the SWS extension is installed

rtk.script_path string read-only

The full path to the directory containing the script that the REAPER action invoked. The trailing path separator is always included.

rtk.reaper_hwnd userdata read-only

hwnd of Reaper's main window

rtk.tick number read-only

Monotonically increasing counter that is incremented each gfx update cycle

rtk.fps number read-only

Frame rate (measured on each update cycle of the main window)

rtk.focused_hwnd userdata read-only

The hwnd of the currently focused window, or nil if js_ReaScriptAPI is not installed

rtk.focused boolean read-only

The currently focused rtk.Widget (or nil if no widget is focused)

rtk.theme table read-only

A table holding the current theme colors which is initialized via rtk.set_theme(). See rtk.themes for field details.

Functions

rtk.class(name, super, attributes)

Creates a new class.

This function wraps middleclass and includes a static class method register() on the returned class for registering attributes. The register() function takes a table that describes the class's attributes, where each field in the table is an instance of rtk.Attribute.

All classes in rtk use this function, and therefore provide all the same capabilities as middleclass itself. Middleclass is bundled with rtk, but also includes some minor tweaks (e.g. to support finalizers for garbage collection).

For simple attributes that don't need any special behavior or treatment, the value can be the attribute's default value, rather than an rtk.Attribute.

See also rtk.Attribute
rtk.isa(v, cls)

Determine if a value is an instance or sublcass of a particular class.

Usage
assert(rtk.isa(obj, rtk.Image), 'must pass an rtk.Image to this function')
Parameters
v (any)

the value to test

cls (rtk.class)

a class object as returned by rtk.class()

Return Values
(boolean)

true if the value is an instance of cls (or a subclass thereof)

rtk.add_image_search_path(path, iconstyle)

Registers an image search path where images and icons can be found by rtk.Image.icon() or rtk.Image:load().

This should be called early in program execution, at least before any rtk objects are created that would depend on this path.

If a non-nil iconstyle is provided, this indicates that the given path contains either light icons (suitable for dark themes) or dark icons (suitable for light themes). When loading an icon image via rtk.Image.icon() (which is often done automatically when passing icon names to widget icon attributes, for example with rtk.Button.icon), paths registered for the appropriate iconstyle are searched first.

If an icon has been requested that's not found in any path for the required icon style but is found in a path for opposite icon style, then rtk will automatically recolor the icon monochromatically (to either white or black) to match the required icon style. This recoloring is only ever done for icons found in paths that were registered here with a non-nil icon style. Images found in paths with nil iconstyle will not be recolored.

If a non-absolute path is specified, then it will be relative to rtk.script_path.

Parameters
path (string)

the fully qualified path within which to search for images

iconstyle (string or nil)

if specified, it's either light or dark to indicate which luminance the icons within the path are, and in which case path is searched by rtk.Image.icon(). If nil, the path is searched by rtk.Image:load()

rtk.set_theme(name, overrides)

Initializes the UI theme.

If this function isn't called, then either the light or the dark theme will automatically be selected based on the window's background color (which default to a color based on REAPER's current theme).

Not dynamic

The theme cannot currently be changed dynamically after widgets have been instantiated. A restart of the script is necessary for theme changes to take effect.

Parameters
name (string)

The name of a theme added to rtk.themes. light and dark exist by default.

overrides (table or nil)

a table of fields that overrides those from the requested theme

rtk.set_theme_by_bgcolor(color, overrides)

Initializes the UI theme appropriate for the given background color.

Similar to rtk.set_theme but decides whether the dark or light theme should be used given the background color, in combination with rtk.light_luma_threshold. It also overrides the theme's built-in background color to the given color.

Parameters
color (string or table)

the background color (format per rtk.color.set())

overrides (table or nil)

if specified, passed to rtk.set_theme()

rtk.set_theme_overrides(overrides)

Applies custom overrides to the in-the-box theme settings.

This function takes a table which can optionally contain light or dark fields which in turn contain a table of overrides specific to that theme. Any other fields in the table be applied to both themes.

Some widgets in rtk are luma-adaptive, meaning they automatically adjust certain colors based on the user-defined background. As a result, it may be desirable to customize both themes, even though your primary theme is one or the other.

Example
rtk.set_theme_overrides({
    -- Use solid-color button surfaces regardless of the theme.
    button_gradient_mul = 0,
    -- Apply lower contrast default text colors, which differ by theme
    dark = {
        text = '#bbbbbb'
    },
    light = {
        text = '#666666'
    }
})
Parameters
overrides (table)

a table of overrides that apply to all or specific themes

rtk.new_theme(name, base, overrides)

Creates a custom rtk color theme.

After the theme has been created, you can set it via rtk.set_theme().

Parameters
name (string)

the name of the custom theme, where light and dark are reserved built-in themes and cannot be used

base (string or nil)

the base theme from which to inherit default values (if set)

overrides (table)

the table of theme overrides according to the theme fields

rtk.add_modal(...)

Registers one or more widgets to be treated as modal.

When at least one widget is registered as modal, the modal widgets will exclusively receive events to the exclusion of all others. Non-modal widgets will be rendered inert until rtk.reset_modal() is called. If a container is registered as modal then all its child descendants will also receive events.

This is used by rtk.Popup, for example.

Parameters
... (rtk.Widget)

one or more widgets to mark as modal

rtk.is_modal(widget)

Check if the given widget (or any widget at all) has been registered as modal via rtk.add_modal().

If the given widget is a child of a modal container, then this function will return.

Parameters
widget (rtk.Widget or nil)

a widget to check if modal, or nil to check if any widget is modal.

Return Values
(bool)

true if the widget is considered modal, false otherwise

rtk.reset_modal()

Removes all modal widget registrations, returning event routing to normal.

rtk.pushdest(dest)

Push a destination image id onto the stack for off-screen drawing.

The target for graphics operations will be the supplied image id until a new image is pushed or rtk.popdest() is called.

This is a low level function and generally doesn't need to be called directly by library users. And even then, if using an rtk.Image, rtk.Image:pushdest() is recommended instead.

local img = rtk.Image()
rtk.pushdest(img.id)
Parameters
dest (int)

the buffer id to target for drawing

rtk.popdest(expect)

Pops the last image destination off the stack.

When the stack is empty, the rtk.Window will be the target for drawing.

rtk.onerror(err, traceback)

Callback invoked when any function called via rtk.defer() or rtk.call() raises an error.

The default behavior logs the error (with stack trace) to the console and aborts program execution, but it can be replaced by user-custom error handling.

Parameters
err (string)

the error message

traceback (string)

a multiline stack trace capturing where the error occurred

rtk.call(func, ...)

Immediately call a function with the given arguments with error handling.

Errors generated by the invoked function will cause rtk.onerror() to be called.

It is a good idea to invoke your script's entrypoint via rtk.call() as early as possible to ensure you get useful error messages during any initial script setup.

Example
local rtk = require('rtk')
function main()
    local window = rtk.Window()
    window:add(rtk.Text{'Hello World'})
    window:open()
end
rtk.call(main)
Parameters
func (function)

the function to invoke

... (any)

one or more arguments to pass to func

Return Values
(any)

the value(s) returned by func

rtk.defer(func, ...)

Registers a function (with arguments) to be called back by REAPER.

This wraps reaper.defer() with the ability to pass arguments to the function (a minor convenience to avoid an anonymous function in common cases) and, more importantly, error handling by means of using rtk.call().

Parameters
func (function)

the function to invoke

... (any)

one or more arguments to pass to func

rtk.callsoon(func, ...)

Registers a function (with arguments) to be invoked within the next rtk.Window update.

This is similar to but subtly different than rtk.defer(). rtk.defer() asks REAPER itself to schedule the function, which happens at the start of the next tick of the REAPER script, and so there may be a slight delay (usually around 30ms). Meanwhile, rtk.callsoon() functions are invoked at select points witihn the rtk.Window update loop.

One such point is just after event handlers have executed, but before any pending reflow or draw. This allows event handlers to schedule a function to be invoked after all other handlers have completed but can still update the UI without any delay.

If there is no rtk.Window currently running then rtk.defer() will be used as a fallback.

See also rtk.defer()
Parameters
func (function)

the function to invoke

... (any)

one or more arguments to pass to func

rtk.callafter(duration, func, ...)

Calls a function (with arguments) after the specified duration.

Parameters
duration (number)

number of seconds to delay execution (can be fractional)

func (function)

the function to invoke

... (any)

one or more arguments to pass to func

rtk.quit()

Terminates the script, closing any open rtk.Window.

Unlike rtk.Window:close() which can keep the a script running provided there are pending deferred calls (e.g. scheduled with rtk.callafter()), this function abandons any deferred calls and exits immediately.

If rtk.Window:open() is called subsequently, it will act as a no-op.

rtk.scale

Controls the overall scale of the interface.

The fields in the rtk.scale table reflect the current scale values. The rtk.scale.user field is how you can adjust the overall scale of the rtk.Window.

rtk.scale.user number

read-write

User-defined scale factor (default 1.0). When this value is set, the window is automatically rescaled on the next update cycle.

rtk.scale.system number

read-only

Scale factor determined by the system. On Apple Retina displays, this value will be 2.0. On Windows, with variable scale, this can be an arbitrary factor and updates in real time as the system global scale is modified.

rtk.scale.reaper number

read-only

REAPER's custom scale modifier that is set via the "Advanced UI/system tweaks" button on the General settings page. This value is only read once on startup, so the script will need to be restarted if this preference is changed.

rtk.scale.framebuffer number

read-only

The scale factor of the internal graphics frame buffer relative to the OS window geometry. On Windows and Linux this is always 1.0, but on MacOS with retina displays it's 2.0, indicating that rtk.Window.w and rtk.Window.h (which represent the OS window size) will result in an internal graphics buffer that's rtk.scale.framebuffer times bigger. See rtk.Window.w for more information.

This is distinct from rtk.scale.system, which indicates the OS-defined scale factor independent of the internal graphics buffer. For example, on Windows with a 200% scale (so-called High DPI), rtk.scale.system will be 2.0 while rtk.scale.framebuffer remains 1.0, indicating the OS window size is the same as the internal framebuffer size. Meanwhile, on MacOS Retina displays, both the values will be 2.0. In other words, when converting between OS window geometry and the calculated size of rtk widgets, you must adjust by rtk.scale.framebuffer, not rtk.scale.system.

rtk.scale.value number

read-only

The final calculated scale factor to which all UI elements scale themselves. This is calculated as user * system * reaper.

Note

If you are implementing widgets or manually drawing, rtk.scale.value is the value all coordinates and dimensions should be multiplied by.

rtk.dnd

Holds the state of the current drag-and-drop operation (if any).

Synopsis

Fields
rtk.dnd.dragging rtk.Widget or nil

read-only

The currently dragging rtk.Widget (or nil if none), which is set when the user drags a widget and that widget's rtk.Widget:ondragstart() handler returns a value that approves the drag operation

rtk.dnd.droppable boolean

read-only

true if the currently dragging widget is eligible to be dropped and false otherwise

rtk.dnd.arg any

read-only

The user argument as returned by rtk.Widget:ondragstart() for the currently dragging widget

rtk.dnd.buttons rtk.mouse

read-only

A bitmap of mouse button constants (BUTTON_LEFT, BUTTON_MIDDLE, or BUTTON_RIGHT) that were pressed when the drag operation began

rtk.dnd.dragging rtk.Widget or nil read-only

The currently dragging rtk.Widget (or nil if none), which is set when the user drags a widget and that widget's rtk.Widget:ondragstart() handler returns a value that approves the drag operation.

rtk.dnd.droppable boolean read-only

true if the currently dragging widget is eligible to be dropped and false otherwise. When false, it means ondrop*() handlers will never be called. This is implicitly set based on the return value of the widget's rtk.Widget:ondragstart() handler. This is useful for drag-only widgets such scrollbars that want to leverage the global drag-handling logic without any need for droppability.

rtk.dnd.arg any read-only

The user argument as returned by rtk.Widget:ondragstart() for the currently dragging widget

rtk.dnd.buttons rtk.mouse read-only

A bitmap of mouse button constants (BUTTON_LEFT, BUTTON_MIDDLE, or BUTTON_RIGHT) that were pressed when the drag operation began. This mouse button(s) needs to be released in order for rtk.Widget:ondragend() to fire.

rtk.os

These fields are available immediately upon loading the rtk module.

rtk.os.mac

true if running on Mac OS X, false otherwise

rtk.os.windows

true if running on Windows, false otherwise

rtk.os.linux

true if running on Linux, false otherwise

rtk.os.bits

Size of pointers in bits on the current system and REAPER version. Either 32 or 64.

rtk.mouse

Although this table will include the current mouse coordinates and buttons pressed, you're strongly encouraged to use the fields from rtk.Event instead. You can use these fields only when an event isn't available (although it almost always is).

BUTTON_LEFT

Left mouse button (used in down and rtk.Event.button)

BUTTON_MIDDLE

Middle mouse button (used in down and rtk.Event.button)

BUTTON_RIGHT

Right mouse button (used in down and rtk.Event.button)

x

x coordinate of last mouse position, relative to gfx window. See also rtk.Event.x, which is preferred if an event instance is available.

y

y coordinate of last mouse position, relative to gfx window. See also rtk.Event.y, which is preferred if an event instance is available.

down

Bitmap of BUTTON_* constants indicating mouse buttons currently pressed. See also rtk.Event.buttons.

rtk.mouse.cursors

Constants that can be assigned to rtk.Widget.cursor or passed to rtk.Window:request_mouse_cursor().

Cursors marked as Windows only will fall back to the standard POINTER on Mac and Linux.

Example
-- Creates a button that shows the "invalid" mouse cursor when the mouse hovers over it.
local button = rtk.Button{label='Click at your peril', cursor=rtk.mouse.cursors.INVALID}
button.onclick = function(self, event)
    button:attr('label', "I see you're a gambler")
    button:attr('cursor', rtk.mouse.cursors.REAPER_TREBLE_CLEF)
end
container:add(button)
Note

Versions of REAPER prior to 6.24rc3 had a bug where the cursor would not change until the mouse moves, and wouldn't change at all when the mouse button was pressed. If js_ReaScriptAPI is available, rtk will avoid this bug even on older versions of REAPER.

UNDEFINED

Cursor is not defined, in which case the window will default to POINTER

POINTER

POINTER

Standard pointer

BEAM

BEAM

I-beam used for text fields

LOADING

LOADING

Indicates the window is currently no responsive (Windows only)

CROSSHAIR

CROSSHAIR

Used for precision pointing (Windows only)

UP_ARROW

UP_ARROW

An up arrow

SIZE_NW_SE

SIZE_NW_SE

Resize cursor from north-west to south-east (width/height resize)

SIZE_SW_NE

SIZE_SW_NE

Resize cursor from south-west to north-east (width/height resize)

SIZE_EW

SIZE_EW

Resize cursor from east to west (width-only resize)

SIZE_NS

SIZE_NS

Resize cursor from north to south (height-only resize)

MOVE

MOVE

Move a window in any direction

INVALID

INVALID

Indicates the mouse position is an invalid target

HAND

HAND

A hand pointer for hyperlink selection

POINTER_LOADING

POINTER_LOADING

Standard pointer with a loading icon (Windows only)

POINTER_HELP

POINTER_HELP

Standard pointer with a question mark (Windows only)

REAPER_FADEIN_CURVE

REAPER_FADEIN_CURVE

Adjust fade-in curve at start of media item

REAPER_FADEOUT_CURVE

REAPER_FADEOUT_CURVE

Adjust fade-out curve at start of media item

REAPER_CROSSFADE

REAPER_CROSSFADE

Adjust fade-out and fade-in curves between two items

REAPER_DRAGDROP_COPY

REAPER_DRAGDROP_COPY

Drag-and-drop-copy item

REAPER_DRAGDROP_RIGHT

REAPER_DRAGDROP_RIGHT

Mouse pointer indicating dragging an item to the right

REAPER_POINTER_ROUTING

REAPER_POINTER_ROUTING

Standard mouse pointer with stereo audio plug beneath

REAPER_POINTER_MOVE

REAPER_POINTER_MOVE

Standard mouse pointer with quad-arrow move icon

REAPER_POINTER_MARQUEE_SELECT

REAPER_POINTER_MARQUEE_SELECT

Standard mouse pointer with a dotted square indicating marquee select

REAPER_POINTER_DELETE

REAPER_POINTER_DELETE

Standard mouse pointer with an X on the bottom right indicating a delete action

REAPER_POINTER_LEFTRIGHT

REAPER_POINTER_LEFTRIGHT

Standard mouse pointer with left/right arrows on the bottom right

REAPER_POINTER_ARMED_ACTION

REAPER_POINTER_ARMED_ACTION

Standard mouse pointer with the letter A along the bottom right

REAPER_MARKER_HORIZ

REAPER_MARKER_HORIZ

Diamond marker with arrows to the left and right

REAPER_MARKER_VERT

REAPER_MARKER_VERT

Diamond marker with arrows above and below

REAPER_ADD_TAKE_MARKER

REAPER_ADD_TAKE_MARKER

Up/down arrows with a tuning fork (?) to the right

REAPER_TREBLE_CLEF

REAPER_TREBLE_CLEF

Treble clef with D major key signature

REAPER_BORDER_LEFT

REAPER_BORDER_LEFT

Left/right arrow with a left edge indicator

REAPER_BORDER_RIGHT

REAPER_BORDER_RIGHT

Left/right arrow with a right edge indicator

REAPER_BORDER_TOP

REAPER_BORDER_TOP

Up/down arrow with a top edge indicator

REAPER_BORDER_BOTTOM

REAPER_BORDER_BOTTOM

Up/down arrow with a bottom edge indicator

REAPER_BORDER_LEFTRIGHT

REAPER_BORDER_LEFTRIGHT

Left/right arrow indicating the middle point between two items

REAPER_VERTICAL_LEFTRIGHT

REAPER_VERTICAL_LEFTRIGHT

Left/right arrow centered on a vertical line

REAPER_GRID_RIGHT

REAPER_GRID_RIGHT

Left/right arrow on right edge of a grid

REAPER_GRID_LEFT

REAPER_GRID_LEFT

Left/right arrow on left edge of a grid

REAPER_HAND_SCROLL

REAPER_HAND_SCROLL

A gripped hand used for drag-moving

REAPER_FIST_LEFT

REAPER_FIST_LEFT

A right fist pointed right indicating pulling something to the left

REAPER_FIST_RIGHT

REAPER_FIST_RIGHT

A left fist pointed left indicating pulling something to the right

REAPER_FIST_BOTH

REAPER_FIST_GOATSE

Two fists overlapping and pulling in opposite directions

REAPER_PENCIL

REAPER_PENCIL

Pencil pointing up and to the left

REAPER_PENCIL_DRAW

REAPER_PENCIL_DRAW

A pencil pointing down and to the left with a drawn squiggle below

REAPER_ERASER

REAPER_ERASER

An eraser pointing down and to the left

REAPER_BRUSH

REAPER_BRUSH

A paint brush pointing down and to the left

REAPER_ARP

REAPER_ARP

A few stacked piano roll notes with an arrow pointing right

REAPER_CHORD

REAPER_CHORD

A few adjacent piano roll notes with an arrow pointing up

REAPER_TOUCHSEL

REAPER_TOUCHSEL

Right hand with index finger pointing up with an outlined plus sign

REAPER_SWEEP

REAPER_SWEEP

Two overlapping mouse pointers offset by a couple pixels in both directions

REAPER_FADEIN_CURVE_ALT

REAPER_FADEIN_CURVE_ALT

Upper left curved edge with arrows on either side pointing in opposite directions

REAPER_FADEOUT_CURVE_ALT

REAPER_FADEOUT_CURVE_ALT

Upper right curved edge with arrows on either side pointing in opposite directions

REAPER_XFADE_WIDTH

REAPER_XFADE_WIDTH

Two overlapping curves with a left/right arrow below

REAPER_XFADE_CURVE

REAPER_XFADE_CURVE

Two overlapping curves with separate left and right arrows on either side

REAPER_EXTMIX_SECTION_RESIZE

REAPER_EXTMIX_SECTION_RESIZE

Up and down arrows with a small crosshair in the middle

REAPER_EXTMIX_MULTI_RESIZE

REAPER_EXTMIX_MULTI_RESIZE

Up and down arrows with bottom border in the middle and a plus sign on the top right

REAPER_EXTMIX_MULTISECTION_RESIZE

REAPER_EXTMIX_MULTISECTION_RESIZE

REAPER_EXTMIX_SECTION_RESIZE but with a plus sign on the top right

REAPER_EXTMIX_RESIZE

REAPER_EXTMIX_RESIZE

REAPER_EXTMIX_MULTI_RESIZE without the plus sign

REAPER_EXTMIX_ALLSECTION_RESIZE

REAPER_EXTMIX_ALLSECTION_RESIZE

REAPER_EXTMIX_SECTION_RESIZE with a dotted-bordered diamond on the top right

REAPER_EXTMIX_ALL_RESIZE

REAPER_EXTMIX_ALL_RESIZE

REAPER_XFADE_CURVE with a dotted-bordered diamond on the top right

REAPER_ZOOM

REAPER_ZOOM

A magnifying glass

REAPER_INSERT_ROW

REAPER_INSERT_ROW

Narrow, more steeply angled mouse pointer pointing to the left

REAPER_RAZOR

REAPER_RAZOR

Razor blade (Reaper 6.24+)

REAPER_RAZOR_MOVE

REAPER_RAZOR_MOVE

Razor blade with quad-arrow move icon (Reaper 6.24+)

REAPER_RAZOR_ADD

REAPER_RAZOR_ADD

Razor blade with an outlined plus sign (Reaper 6.24+)

REAPER_RAZOR_ENVELOPE_VERTICAL

REAPER_RAZOR_ENVELOPE_VERTICAL

Up/down arrow with vertically oriented brace brackets (Reaper 6.29+)

REAPER_RAZOR_ENVELOPE_RIGHT_TILT

REAPER_RAZOR_ENVELOPE_RIGHT_TILT

Up/down arrow with ramp to right side (Reaper 6.29+)

REAPER_RAZOR_ENVELOPE_LEFT_TILT

REAPER_RAZOR_ENVELOPE_LEFT_TILT

Up/down arrow with ramp to left side (Reaper 6.29+)

rtk.font

Font constants and settings to be used across the UI.

The constants (i.e. those fields in uppercase) can be used with the fontflags attributes available on certain widgets (such as rtk.Text.fontflags), which takes a bitmap of these constants:

local t1 = rtk.Text{'just bold', fontflags=rtk.font.BOLD}
local t2 = rtk.Text{'bold and italicized', fontflags=rtk.font.BOLD|rtk.font.ITALICS}
BOLD

Font flag for bold text

ITALICS

Font flag for italicized text

UNDERLINE

Font flag for underlined text

multiplier

Global font size multiplier, automatically adjusted by platform. You'll need to call rtk.Window:queue_reflow() after changing this value.

rtk.keycodes

Numeric keycode constants used with rtk.Event.keycode.

UP

Up arrow key

DOWN

Down arrow key

LEFT

Left arrow key

RIGHT

Right arrow key

RETURN

Enter key (alias for ENTER)

ENTER

Enter key (alias for RETURN)

SPACE

Space bar

BACKSPACE

Backspace key

ESCAPE

Escape key

TAB

Tab key

HOME

Home key

END

End key

INSERT

Insert key

DELETE

Delete key

F1

F1 function key

F2

F2 function key

F3

F3 function key

F4

F4 function key

F5

F5 function key

F6

F6 function key

F7

F7 function key

F8

F8 function key

F9

F9 function key

F10

F10 function key

F11

F11 function key

F12

F12 function key

rtk.themes

A table of color/font themes used for rtk UIs, keyed on theme name. There are two themes out of the box:

  • dark: a high contrast theme with a dark gray background
  • light: a high contrast theme with a light gray background

You can add your own custom themes to this table and reference it by name in rtk.set_theme().

All colors must be specified in one of the supported color formats. These colors define defaults for various widgets, but colors can always be overridden on specific widget instances. All font values are in the form {font face name, font size} or nil to use default_font.

Custom values need to be set before widgets are instantiated: changing afterward doesn't dynamically update existing widgets.

Each theme table registered under rtk.themes contains the following fields:

dark boolean

true if the theme is dark (true here implies light is false)

light boolean

true if the theme is light (true here implies dark is false).

bg colortype

overall background color for the window over top all widgets are drawn and is the default color used by rtk.Window when rtk.Window.bg isn't explicitly specified

default_font table

global default font (default is {'Calibri', 18})

accent colortype

accent color used for things like mouseover highlights and selections

accent_subtle colortype

used in areas where a more subdued accent color is needed

tooltip_bg colortype

background color of the tooltip (default is white)

tooltip_text colortype

color of the tooltip text and border (default is black)

tooltip_font table

font used for tooltips (default is {'Segoe UI (TrueType)', 16})

text colortype

text color for text in widgets such as rtk.Text and rtk.Entry

text_faded colortype

a more subdued text color useful for less obtrusive text, which can be used for example with a status bar

text_font table

default font used for rtk.Text objects (defaults to default_font)

button colortype

the default color for rtk.Button surfaces

heading colortype

the default color for rtk.Heading text, which uses text if nil (default nil)

heading_font table

default font used for rtk.Heading objects (defaults to {'Calibri', 26})

button_label colortype

color of text in rtk.Button labels

button_font table

default font used for rtk.Button objects (defaults to default_font)

button_gradient_mul number

a multiplier that is applied to each of button_normal_gradient, button_hover_gradient and button_clicked_gradient (defaults to 1). Set this to 0 to use a single solid color for all buttons globally.

button_tag_alpha number

Opacity of the black overlay for tagged buttons (default 0.32).

button_normal_gradient number

the degree of gradient in normal button surfaces (i.e. not hovering or clicked) from -1 to 1, where negative values get darker toward the bottom of the surface, and positive values get lighter. Use 0 to disable the gradient and use a single surface color.

button_normal_border_mul number

multiplier appied to each color channel for the border of a button in its normal state

button_hover_gradient number

like button_gradient but applies to buttons when the mouse hovers over it

button_hover_brightness number

a multiplier to the value channel (in HSV colorspace) of the button color when the mouse hovers over it

button_hover_mul number

multiplier applied to each color channel of the button's surface when the mouse hovers over it

button_hover_border_mul number

like button_border_mul but applies to buttons when the mouse hovers over it

button_clicked_gradient number

like button_gradient but applies to buttons that are being clicked

button_clicked_brightness number

like button_hover_brightness but applies to buttons that are being clicked

button_clicked_mul number

like button_hover_mul but applies to buttons that are being clicked

button_clicked_border_mul number

like button_border_mul but applies to buttons that are being clicked

entry_font table

Default font used for rtk.Entry objects (defaults to default_font)

entry_bg colortype

the background color for rtk.Entry widgets

entry_placeholder colortype

the faded color for the optional placeholder of empty rtk.Entry widgets

entry_border_hover colortype

color of rtk.Entry borders when the mouse is hovering

entry_border_focused colortype

color of rtk.Entry borders when the widget is focused

entry_selection_bg colortype

background color of selected text in an rtk.Entry

popup_bg colortype or nil

background color of rtk.Popup widgets (if nil defaults to bg).

popup_overlay colortype or nil

default overlay of the window when rtk.Popup is opened (defaults to #00000040, which is black at 25% opacity).

popup_bg_brightness number

a multiplier to the value channel (in HSV colorspace) of the window background (bg) to be used as the rtk.Popup background when popup_bg is not specified.

popup_shadow colortype

the color of the shadow for rtk.Popup (alpha channel is respected)

popup_border colortype

the border color of rtk.Popups

slider colortype

color of rtk.Slider thumbs and active track segments

slider_track colortype

color of rtk.Slider tracks

slider_font table

font and size used for rtk.Slider labels (defaults to default_font)

slider_tick_label colortype

color used for rtk.Slider labels (defaults to text)

rtk.version

Information about the currently loaded rtk version.

If you're interested in checking REAPER's version rather than rtk's, see rtk.check_reaper_version()

Fields
rtk.version.string string

read-only

The stringified version of this rtk package, e.g. 1.2.5.

rtk.version.api number

read-only

The API version number. If the rtk version is 1.2.5 then this value is 1. See here for more details on API versioning.

rtk.version.major number

read-only

The major version number. This is identical to api.

rtk.version.minor number

read-only

The minor version number. If the rtk version is 1.2.5 then this value is 2.

rtk.version.patch number

read-only

The patch version number. If the rtk version is 1.2.5 then this value is 5.

Functions
rtk.version.check()

Checks the current rtk version against the given version component numbers

Functions

rtk.version.check(major, minor, patch)

Checks the current rtk version against the given version component numbers.

Usage
if rtk.version.check(1, 2) then
    return reaper.MB('rtk version 1.2 is required', 'Version too old', 0)
end
Parameters
major (number)

require at least this major (i.e. API) version

minor (number or nil)

require at least this minor version, provided the major version is satisfied. If nil, minor version is not checked and patch must also be nil.

patch (number or nil)

require at least this patch level, provided both major and minor versions are satisfied. If nil, patch level is not checked.

Return Values
(bool)

true if the current rtk version is at least as new as the given version