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).

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 as long as an rtk.Window is currently open

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() ¶

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(). Another difference with reaper.defer() is that any callbacks scheduled with rtk.defer() will be ignored when rtk.quit() is called, whereas functions scheduled with reaper.defer() will be invoked.

It's generally recommended to prefer rtk.defer() over REAPER's native reaper.defer() API in order to benefit from the improved ergonomics and error handling.

See also rtk.callsoon()

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, this function abandons any deferred calls and exits immediately. Note that this only applies to deferred functions scheduled with rtk.defer(), rtk.callsoon(), or rtk.callafter(); any functions scheduled with REAPER's native reaper.defer() will be invoked.

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

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.

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

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.

These fields are available immediately upon loading the rtk module.

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).

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)

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}

Numeric keycode constants used with rtk.Event.keycode.

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:

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()

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