Custom Action¶

A Custom Action is a plugin feature that acts as a new action within qtermy. It can be invoked with parameters just like an ordinary action, from any setting that specifies an action string. This includes action bindings in a keymap. Simply prepend the string "Custom" to the name of the custom action as passed to registerCustomAction() and join it together with any parameters separated by vertical bar (|) characters.

Custom actions have access to a rich API that exposes much of qtermy's internal state. It's even possible to prompt the user for string values and to register timers and callback functions to be notified of attribute changes. Custom actions can invoke other actions, including custom actions, although such invocations will not be made until after control has returned from the custom action.

The file action.mjs.example distributed with qtermy implements a variety of sample custom actions and is annotated with explanatory comments. The file rectcopy.mjs is another custom action implementing rectangle copy of selected text.

The entry point to a custom action is the run function passed to plugin.registerCustomAction(), which is called once each time the action is invoked:

run_function(manager[, arg1, arg2...])¶: Invokes the custom action with the specified manager handle. The remaining arguments are the parameters specified in the action invocation, if any.

Handle Interface
Manager Interface
Server Interface
Terminal Interface
Viewport Interface
Settings Interface
Buffer Interface
Cursor Interface
Persistent Interface
Region Interface

Handle Interface ¶

The custom action API is based primarily on typed handles, which are Javascript objects that provide interfaces to specific objects within qtermy such as windows, terminals, settings objects, etc. Handles have the following common methods across all object types:

handle.isValid()¶: Returns whether the handle is valid. Handles become invalid when their underlying object is deleted. A handle which has been saved across Javascript entry points must be checked using this method before using it.

handle.setPrivateData(name, value)¶: Attaches an arbitrary value to the handle with the given name. It can be retrieved using getPrivateData from any handle of the same type which references the same underlying object.

handle.getPrivateData(name)¶: Returns a value previously attached to the handle using setPrivateData, or undefined if no such value exists.

handle.setInterval(callbackObj, timeout)¶

Installs a notification callback to be called on a periodic interval. The callback will be called repeatedly until canceled.

Arguments:	callbackObj (object) -- See below timeout (integer) -- A nonzero timeout interval expressed in tenths of a second.
Returns:	An object with a `cancel` method that will cancel the timer.

The callbackObj must define its callback field to a method which takes a handle as its first argument. The object may also contain arbitrary private fields for the plugin's own use. For protection against future API changes, name private fields starting with an underscore (_) character. A return value other than true or undefined from the callback method will cancel the timer.

Manager Interface ¶

A manager handle represents an application window. Since actions may need to display modal dialogs, all actions are invoked in the context of an application window.

manager.invoke(actionName[, arg1, arg2...])¶

Invokes the specified action with the given parameters, if any. The actual invocation will be delayed until after control has returned from Javascript. Multiple action invocations will be run in the order they are made.

If it's necessary to regain control after the action has been invoked, register a callback using setInterval.

manager.notifySend(summary, body)¶: Calls NotifySend with the given summary and body.

manager.listServers()¶: Returns a list of server handles corresponding to all currently connected servers.

manager.getServerById(uuid)¶: Returns a server handle for the given server UUID string, or undefined if no such server is connected.

manager.getActiveServer()¶: Returns a server handle for the active server, or undefined if there is no active server.

manager.getLocalServer()¶: Returns a server handle for the local server, or undefined if there is no local server connected.

manager.listTerminals()¶: Returns a list of terminal handles corresponding to all terminals.

manager.getTerminalById(uuid)¶: Returns a terminal handle for the given terminal UUID string, or undefined if no such terminal exists.

manager.getActiveTerminal()¶: Returns a terminal handle for the active terminal, or undefined if there is no active terminal.

manager.createTerminal(server, profile[, termParams])¶

Creates a new terminal on the given server, with the given profile, using the given parameters.

Arguments:	server (handle) -- A server handle. profile (handle) -- A profile handle. termParams (object) -- See below
Returns:	A terminal handle for the new terminal.

If termParams is provided, its fields are used to override the settings in the given profile. All fields are optional.

theme

A theme handle from which the terminal's Palette and Dircolors will be set.

palette

A palette object as described by terminal.palette. Unspecified indices (holes) will be filled with values from the compiled-in default palette. The terminal's Palette and Dircolors will be set from the result.

layout

See terminal.layout.

fills

See terminal.fills.

badge

See terminal.badge.

icon

See terminal.icon.

attributes

A dictionary of additional key/value pairs to set as terminal attributes.

environment

A list of strings of the form +name=value to set an environment variable or -name to remove an environment variable. These will be applied on top of the profile's Environment setting.

manager.getActiveViewport()¶: Returns a viewport handle for the active viewport, or undefined if there is no active viewport.

manager.getGlobalSettings()¶: Returns a settings handle for the Global settings.

manager.getDefaultProfile()¶: Returns a settings handle for the global default profile.

manager.listThemes()¶: Returns a map of settings handles corresponding to all themes. The map keys are the theme names.

manager.listPanes()¶

Returns a list of objects corresponding to this application window's split window panes. Each object has the following fields:

viewport: A viewport handle for the pane.
index: The pane's index number, as displayed in the viewport (with ShowMainIndex) or terminal thumbnail (with ShowThumbnailIndex).

manager.prompt(callbackObj, prompt[, initial])¶

Prompts the user for a string value. Only one prompt can be displayed at a time.

Arguments:	callbackObj (object) -- See below prompt (string) -- The prompt message to display to the user. initial (string) -- An optional initial value for the input text field.
Returns:	`true` on success, `false` if the prompt cannot be displayed

The callbackObj must define its callback field to a method which takes a manager handle as its first argument and the user-provided string as its second argument. This will be invoked if and when the user accepts the dialog. The object may also contain arbitrary private fields for the plugin's own use. For protection against future API changes, name private fields starting with an underscore (_) character.

manager.copy(string)¶: Copies the given string to the clipboard as UTF-8 text.

manager.clientId¶: (API version 1.3) The UUID of this client.

manager.getClientAttribute(name)¶: (API version 1.3) Returns the value of the named client attribute, or undefined if it doesn't exist.

Server Interface ¶

A server handle represents a connected server.

server.id¶: The UUID of the server.

server.getAttribute(name)¶: Returns the value of the named server attribute, or undefined if it doesn't exist.

server.getActiveManager()¶: Returns a manager handle for the active application window.

server.listTerminals()¶: Returns a list of terminal handles corresponding to the server's terminals.

server.getDefaultProfile()¶: Returns a settings handle for the server's DefaultProfile.

server.setAttributeNotifier(callbackObj, name[, timeout])¶

Installs a notification callback to be called whenever the named attribute changes on this server.

Arguments:	callbackObj (object) -- See below name (string) -- The name of the attribute to monitor. timeout (integer) -- An optional timeout expressed in tenths of a second. The monitor will be automatically canceled after the timeout has elapsed. If not specified, the monitor will remain active until explicitly canceled.
Returns:	An object with a `cancel` method that will cancel the attribute monitor.

The callbackObj must define its callback field to a method which takes a server handle as its first argument, the new value of the attribute as its second argument, and the attribute name as its third argument. The object may also contain arbitrary private fields for the plugin's own use. For protection against future API changes, name private fields starting with an underscore (_) character. A return value other than true or undefined from the callback method will cancel the attribute monitor.

Terminal Interface ¶

terminal.id¶: The UUID of the terminal.

terminal.width¶: The width of the terminal's screen in character cells.

terminal.height¶: The height of the terminal's screen in character cells.

terminal.palette¶: An object specifying hex RGB values by numeric index. When reading, all indices will be set. When writing, unspecified indices (holes) will be filled with values from the terminal's current palette. Use the value 0x1000000 for a "disabled" extended color. The object's dircolors field specifies a dircolors string.

terminal.font¶: The string describing the terminal's Font. This property can be written.

terminal.layout¶: A WidgetLayout string in the format specified by termyctl. This property can be written.

terminal.fills¶: A ColumnFills string in the format specified by termyctl. This property can be written.

terminal.badge¶: A Badge format string. This property can be written.

terminal.icon¶: The terminal's FixedThumbnailIcon. An empty string indicates no fixed icon. This property can be written.

terminal.rows¶: A buffer handle for the terminal's scrollback buffer.

terminal.ours¶: (API version 1.3) Whether this client holds ownership of the terminal.

terminal.getAttribute(name)¶: Returns the value of the named terminal attribute, or undefined if it doesn't exist.

terminal.getActiveManager()¶: Returns a manager handle for the active application window.

terminal.getProfile()¶: Returns a settings handle for the terminal's current profile.

terminal.getTheme()¶: (API version 1.2) Returns a theme handle for the theme matching the terminal's current Palette, or undefined if there is no matching theme.

terminal.getServer()¶: Returns a server handle for the terminal's server.

terminal.setAttributeNotifier(callbackObj, name[, timeout])¶: Installs a notification callback to be called whenever the named attribute changes on this terminal. Refer to server.setAttributeNotifier().

terminal.getStart()¶: Returns a cursor pointing to the top of the terminal's screen.

terminal.getEnd()¶: Returns a cursor pointing to the bottom of the terminal's screen.

terminal.nextRegionId()¶: Same as processContext.nextRegionId().

terminal.createRegion(start, end[, regionParams])¶

Creates a semantic region in the same manner as a semantic parser.

Arguments:	start (handle) -- A cursor at the desired start position. end (handle) -- A cursor at the desired end position. regionParams (object) -- See Region Parameters.
Returns:	A region handle for the new region, or `undefined` if the region could not be created.

terminal.createNote(start, end[, noteParams])¶

Creates an annotation.

Arguments:	start (handle) -- A cursor at the desired start position. end (handle) -- A cursor at the desired end position. noteParams (object) -- See below
Returns:	`true` if the annotation was successfully created, `false` otherwise.

If noteParams is provided, its text field is used to set the annotation's note text and its char field is used to set the annotation's note character. Both fields are optional. Refer to Create Annotation for more information.

Viewport Interface ¶

A viewport handle represents a split window pane.

viewport.width¶: The width of the viewport in character cells.

viewport.height¶: The height of the viewport in character cells.

viewport.active¶: Whether the viewport is the active viewport in its application window.

viewport.primary¶: Whether the viewport is the active viewport in its application window and the window either has input focus or last received input focus.

viewport.rows¶: A buffer handle for the scrollback buffer of the viewport's terminal.

viewport.getTerminal()¶: Returns a terminal handle for the viewport's terminal.

viewport.getStart()¶: Returns a cursor pointing to the top of the viewport.

viewport.getEnd()¶: Returns a cursor pointing to the bottom of the viewport.

viewport.getSelectedJob()¶: Returns a region handle for the viewport's selected job, or undefined if there is none.

viewport.getSelection()¶: Returns a region handle for the viewport's active text selection, or undefined if there is none.

viewport.createSelection(start, end)¶

Creates a text selection.

Arguments:	start (handle) -- A cursor at the desired start position. end (handle) -- A cursor at the desired end position.
Returns:	A region handle for the new text selection.

viewport.createFlash(start, end, regionParams)¶

Creates a short-lived, animated semantic region to draw the user's attention to a specific piece of text.

Identical to terminal.createRegion(), but regionParams may contain the following additional optional fields:

duration

The number of times to flash the semantic region. A default value will be used if unspecified.

callback

A callback method as described by handle.setInterval() which will be called after the animation has finished. The callback will only be called once.

viewport.getMousePosition()¶: If the viewport is active, returns a cursor pointing to the location of the mouse pointer within the viewport, otherwise returns undefined.

viewport.scrollTo(cursor, exact)¶

Scrolls the viewport to a specific location in the scrollback buffer.

Arguments:	cursor (cursor) -- A cursor at the desired row. exact (boolean) -- If true, the top of the viewport will be placed at the given row or as close to the given row as possible. If false, the viewport will be scrolled in the direction of the row until it is visible within the viewport.

Settings Interface ¶

A settings handle refers to a settings object.

settings.name¶: The name of the settings object.

settings.getSetting(name)¶: Retrieves a setting by its full name (including the category), for example Effects/EnableTextBlink in the Global settings. The value returned will depend on the setting.

settings.getKeymap()¶: For profile handles only, returns a settings handle for the profile's Keymap.

settings.getPalette()¶: (API version 1.2) For profile and theme handles only, returns a palette object as described by and suitable for assignment to terminal.palette.

settings.lookupShortcut(actionString)¶: For keymap handles only, looks up the action string in the keymap. If there is an action binding for it, returns an object with expression and additional fields describing the binding.

Buffer Interface ¶

A buffer handle provides an array-like interface to a terminal's scrollback buffer. Accessing the handle using an array subscript will return a cursor pointing to the start of the given row, indexed starting from the top of the scrollback buffer.

buffer.length¶: Returns number of rows in the scrollback buffer. Note that the scrollback buffer is considered to include the terminal screen itself.

buffer.origin¶: Returns the true index of the first row in the scrollback buffer. This is the row number it would have if the scrollback buffer were of size 2⁶⁴ rather than the configured size. Some actions take true index numbers as parameters.

Cursor Interface ¶

A cursor points to a specific character position within a terminal's scrollback buffer. The fields of a cursor are read-only. Use the cursor's methods to reposition it.

The terminal's Encoding determines the width and combining characteristics of individual code points which in turn affects the behavior of cursors.

Important

Cursors are invalidated once control returns from Javascript. To track a particular location across Javascript entry points, use a persistent cursor.

cursor.row¶: The cursor's row, indexed from the top of the scrollback buffer.

cursor.offset¶: The offset of the cursor within the row's text string, measured in UTF-16 code points. Use this value when performing Javascript string computations.

cursor.column¶: The "x position" of the cursor indexed from zero. This is the character cell where the cursor would appear on the terminal screen.

cursor.columns¶: The "x width" of the row. This is the number of character cells occupied by the row's text.

cursor.character¶: The number of logical characters between the beginning of the row and the cursor. Double-width characters may cause this value to differ from the cursor's column.

cursor.characters¶: The total number of logical characters in the row's text.

cursor.text¶: The text of the row.

cursor.continuation¶: Whether the row is a continuation row, meaning that the previous row exceeded the width of the terminal screen and wrapped onto this row.

cursor.flags¶: Low-level row flags. This includes the continuation flag as well as double-width and double-height flags.

cursor.compareTo(other)¶: Compares this cursor to another cursor. Returns -1, 0, or 1 if this cursor points to a location before, equal to, or after the other cursor's location, respectively.

cursor.clone()¶: Returns a new cursor pointing to the same location as this cursor.

cursor.toPersistent()¶: Returns a new persistent cursor at this cursor's location. This can be converted back to a cursor at a later time.

cursor.getJob()¶: Returns a region handle for the job enclosing the cursor position, or or undefined if there is none.

cursor.measureColumns(string)¶: Returns the "x width" of the given string. This is the number of character cells occupied by the string's text.

cursor.measureCharacters()¶: Returns the number of logical characters in the given string.

cursor.moveByRows(delta)¶: Moves the cursor by the specified number of rows. A positive number moves down in the scrollback buffer. If necessary, the cursor's character position will be adjusted to fit within the text of the new row. Returns a reference to the cursor.

cursor.moveToRow(row)¶: Moves the cursor to the specified row, indexed from the top of the scrollback buffer. Returns a reference to the cursor.

cursor.moveByOffset(delta)¶: Moves the cursor by the specified number of UTF-16 code points within its current row. Use this method when performing Javascript string computations. The new cursor location will be adjusted to the nearest logical character. Returns a reference to the cursor.

cursor.moveToOffset(offset)¶: Moves the cursor to the specified string offset within its current row, measured in UTF-16 code points. Use this method when performing Javascript string computations. The new cursor location will be adjusted to the nearest logical character. Returns a reference to the cursor.

cursor.moveByColumns(delta)¶: Moves the cursor by the specified number of character cell positions or "x width" within its current row The new cursor location will be adjusted to the nearest logical character. Returns a reference to the cursor.

cursor.moveToColumn(column)¶: Moves the cursor to the specified character cell position or "x position" within its current row. The new cursor location will be adjusted to the nearest logical character. Returns a reference to the cursor.

cursor.moveByCharacters(delta)¶: Moves the cursor by the specified number of logical characters within its current row. Returns a reference to the cursor.

cursor.moveToCharacter(pos)¶: Moves the cursor to the specified logical character position within its current row. Returns a reference to the cursor.

cursor.moveToEnd()¶: Moves the cursor to the end of its current row. Returns a reference to the cursor.

cursor.moveToNextJob()¶: Moves the cursor to the beginning of the next job and returns a region handle for it. If there is no such region, the cursor is unchanged and undefined is returned.

cursor.moveToPreviousJob()¶: Moves the cursor to the beginning of the previous job and returns a region handle for it. If there is no such region, the cursor is unchanged and undefined is returned.

cursor.moveToNextNote()¶: Moves the cursor to the beginning of the next annotation and returns a region handle for it. If there is no such region, the cursor is unchanged and undefined is returned.

cursor.moveToPreviousNote()¶: Moves the cursor to the beginning of the previous annotation and returns a region handle for it. If there is no such region, the cursor is unchanged and undefined is returned.

cursor.moveToFirstRow()¶: Moves the cursor to the beginning of the first row in the scrollback buffer. Returns a reference to the cursor.

cursor.moveToLastRow()¶: Moves the cursor to the beginning of the last row in the scrollback buffer. Returns a reference to the cursor.

cursor.moveToScreenStart()¶: Moves the cursor to the top of the terminal's screen. Returns a reference to the cursor.

cursor.moveToScreenEnd()¶: Moves the cursor to the bottom of the terminal's screen. Returns a reference to the cursor.

cursor.moveToScreenCursor()¶: Moves the cursor to the location of the terminal's text cursor within its screen. Returns a reference to the cursor.

Persistent Interface ¶

A persistent cursor points to a specific character position within a terminal's scrollback buffer. Unlike an ordinary cursor, it can be stored across Javascript entry points. However, it may not be possible to restore a saved persistent cursor if the saved location has scrolled off the top of the scrollback buffer.

persistent.toCursor()¶: Returns a new cursor at the persistent cursor's location, or undefined if the location is no longer within the scrollback buffer.

Region Interface ¶

A region handle refers to a region.

region.id¶: The ID of the region (an unsigned integer).

region.flags¶: Low-level region flags.

region.getAttribute(name)¶: Returns the value of the named region attribute, or undefined if it doesn't exist.

region.getStart()¶: Returns a cursor pointing to the beginning of the region.

region.getEnd()¶: Returns a cursor pointing to the end of the region.

region.getPrompt()¶: Returns a region handle for the prompt region belonging to the given job, or undefined if this region is not a job region or the region does not exist.

region.getCommand()¶: Returns a region handle for the command region belonging to the given job, or undefined if this region is not a job region or the region does not exist.

region.getOutput()¶: Returns a region handle for the output region belonging to the given job, or undefined if this region is not a job region or the region does not exist.

region.getJob()¶: Returns a region handle for the job region enclosing this region, or undefined if this region is not a prompt, command, or output region or the region does not exist.