Controlling Settings ¶

Global settings from settings.ini file ¶

User preferences for DomTerm are normally in the file .config/domterm/settings.ini in the user’s home directory. This location can be overridden with the --settings command-line option; otherwise the location is $XDG_CONFIG_HOME/domterm/settings.ini, where XDG_CONFIG_HOME defaults to $HOME/.config. (For compatibility reasons, $HOME/.domterm/settings.ini is also checked if $XDG_CONFIG_HOME is unset, but that may go away.) On WSL (Windows Subsystem for Linux) the file is c:\Users\USER\AppData\Roaming\DomTerm\settings.ini.

You can override settings file with the -settings command-line argument. If the settings.ini is changed it is automatically re-loaded.

The syntax of settings.ini is a variant of the INI file format. A preference is written as:

keyword = value

For example:

window.geometry=800x600

Spaces before or after = are optional. A keyword should be a sequence of letters, numbers, periods or hyphens. The value is almost any sequence of characters (depending of the keyword), up to end of the line.

Multi-line values are written as an empty line following the ‘=’, and then one or lines starting with a single space followed by ‘|’. For example:

style.user =
 |div.domterm { --background-color: azure }
 |div.domterm-spacer {background: none }

In this cases the resulting value has two lines, with the two-character prefixes ‘ |’ removed.

Comment lines start with # in the first column. Comment lines and all-blank lines are ignored.

Local settings from command line ¶

On the domterm command line, you can specify a local setting with an argument that contains an equal sign (=) and that does not start with a hyphen (-). A settings argument is specified with other options before the command, if any. For example:

domterm style.dark=yes new bash

Command-line settings are used for the current command, including creating a new session or window.

For convenience in command-completion, you may optionally prefix the setting with an initial ‘=’:

domterm =style.dark=yes new bash

To change local settings for a current window, you can use the domterm settings command. This modifies the local settings of the current window.

domterm settings style.dark=yes

Settings values and syntax ¶

A setting value may be a string, a number, a boolean (true/false) value, or a combination of multiple of these values. How the raw text of setting is interpreted (parsed) depends on the setting, primarily the expected value type.

Some settings specify a list of values. For example a setting that specifies a command to be run will be a list of strings: the name of the command, followed by command-line arguments. The items in the list are separated by non-quoted spaces.

More complicated values (series or maps), separated by semi-colons or newlines, are discussed later.

Boolean values ¶

For a boolean value any one of true, yes, or on enable the preference; one of false, no, or off disable the preference.

Number values ¶

Numbers are either integer or floating-point.

You can specify a hexadecimal (base-16) integer with ‘0x’ prefix; an octal (base-8) integer with the ‘0o’ prefix; or a binary (base-2) integer with the ‘0b’ prefix. (Currently, non-decimal integers only work for settings marked with Template.)

String values ¶

When the setting value is a string or a string-list, the characters of the raw text are split into words: A sequence of regular characters, quoted strings, and escape sequences, separated by spaces. “Extra spaces” (more than one in a row, or at the start or end) that are not quoted are also removed.

If the value needed is a single string, then the words are combined to a single string, with one space between each word. If the value needed is a list of strings, then each word becomes one of the strings.

Both single quotes (apostrophes) and double quotes are handled. Thus the following are all equivalent:

history-storage-key=input history
history-storage-key=    input   history
history-storage-key="input history"
history-storage-key='input history'

Escape sequences starting with backslash (see below) are processed within double quotes and outside quotes. They are not processed within single quotes.

If an ending quote is doubled, then it is treated as a single literal delimiter. The following are all equivalent.

history-storage-key='can''t miss'
history-storage-key="can't miss"
history-storage-key=can\'t\ miss

String escapes ¶

\"

\\

etc for other non-letter non-control characters

The character following the initial backslash.

\a

Alert (Bell) (Unicode 0x07).

\b

Backspace (Unicode 0x08).

\e

Escape (Unicode 0x1B).

\f

Formfeed (Unicode 0x0c)

\n

Newline (Unicode 0x0A).

\r

Carriage return (Unicode 0x0D).

\t

Tab (Unicode 0x09).

\uHHHH

Unicode 0xHHHH where HHHH are 4 hex digits.

\u{HHHHHH}

Unicode 0xHHHHHH where HHHHHH are 1-6 hex digits.

\v

Veritcal tab (Unicode 0x0B).

Command values ¶

A command is an application name (executable or script or alias) followed by optional arguments, separated by spaces. Special characters (including spaces) can be protected in single quotes (apostropes) or double quotes, as in typical shells. Escape sequences starting with backslash (see above) are processed within double quotes and outside quotes. (They are currently also processed within single quotes, but that may change.)

The following information about commands is subject to change to use the template framework.

Commands that display a session should include the pattern %U for URL that is filled in by the server. If the command does not contain a %U, it is added at the end.

A command-candidates value is a list of one or more command values separated by non-quoted newlines or semi-colons. For example if fontend.default=firefox;chrome is set, then DomTerm will try first look for the firefox browser, and if that is not found it will look for chrome.

A command-conditionals value is a command-candidates where each command is prefixed with zero or more conditions in {...} braces. All of the conditions must be satisfied for the following value to be selected. A condition is one or simple simple conditions, optionally negated (by being prefixed by ‘!’), separated by vertical bars ‘|’. For example the condition {A|!B|C|!D} is true if either of the simple conditions A or C is true, or if B or D is false.

The syntax and meaning of a simple condition depends on the keyword. For example, the command.ssh keyword accepts simple conditions of the form @hostname or user@hostname, as shown in this example:

command.ssh =
 | {@gnu.org}ssh -E /tmp/gnu-ssh.log
 | ssh -E /tmp/ssh.log

This runs ssh with the -E /tmp/gnu-ssh.log when connecting remotely to gnu.org, but with the flag -E /tmp/ssh.log when connecting to other hosts.

Color values ¶

Colors should be specified using #RRGGBB syntax. For example, to change the color for “blue” to a more subdued value do:

domterm settings "color.blue=#3465a4"

You can also use any color syntax supported by CSS if you use the default DomTerm engine, but this is not currently suppered if xtermjs is selected.

Series values ¶

A phrase is one or more words (separated by spaces) that are evaluated to either a simple value or a list. Some settings (for example browser.default) take a series, which is one or more phrases, separated by semi-colon or newline.

Map values ¶

A map is a table from a key (usually a string) to some other value (such as a command). Syntactially, it is like a phrase, which entries separated by semi-colons. However, the first word of each phrase is the key: a word that ends in an unquoted colon (which is not part of the key).

Settings that expect a map include keymap.master and keymap.line-edit.

Template values ¶

This is work-in-progress. The plan is for all (or at least most) settings values to become templates.

The value for some settings may be a template, which can contain value substitutions, expressions, and conditions.

A template will be expanded to a value, either in the frontend or the backend. Template expansion is not yet implemented by the backend.

Template parts ¶

template-word-part ::= regular-character | template-escape | double-quoted-stpring | single-quoted-string | template-substiution

template-word ::= template-word-part⁺

A template-word is a sequence of regular printing characters, escaped characters, quoted strings, or substitutions surrounded by braces.

A template-phrase is a sequence of template-words separated by unquoted spaces (horizontal white space). A template-phrase is ended by an unquoted ‘;’ (semicolon), unquoted newline (vertical white space), or a non-matching unquoted ‘}’ (right brace).

Value substitution ¶

A value substitution is a variable name surrounded by braces. It is replaced by the current value of the variable. A variable is some other settings name, or perhaps an automatically-generated value. Currently, the only supported variables are other frontend settings.

For example the default value for color.caret is

color.caret = {color.foreground} {color.background}

This means that the current values of the color.foreground and color.background settings are substituted, resulting in a list of two color values. If either color.foreground or color.background changes then the value of color.caret is re-evaluated and updated automatically.

Expression substitution ¶

An expression substitution is a template-operator followed by zero or more template-arguments, inside braces. Note that expressions are written in prefix or “Polish” notation, similar to Lisp (but using braces instead of parenthesis).

template-operator ::= template-word

template-argument ::= template-word

template-expression ::= { template-operator [optional-space template-argument]^* }

Here is a simple but contrived example that sets log.js-string-max to 100 times the value of log.js-verbosity.

log.js-string-max = {* 100 {log.js-verbosity}}

These are the operators implemented so far - more are planned:

+

The arguments are coerced to numbers and added. If there are no arguments, the result is 0.

*

The arguments are coerced to numbers and multiplied. If there are no arguments, the result is 1.

Conditional template ¶

template-conditional ::= {? template-condition^* ; template-then-phrase ]; template-else-phrase] }

template–phrase ::= template-phrase | ? template-condition^* ; template-then-phrase ]; template-else-phrase]

template-condition ::= [!]template-word

For example the default for the color.background depends on whether style.dark is true:

color.background = {?{style.dark};#fffff8;{color.black}}

Available settings ¶

shell.default = command ¶

Specify a default “shell” command to execute when creating a new terminal. The command can include arguments, separated by spaces. You can uses quotes, as in a shell.

The default is the value of the SHELL environment variable; if that is not set the default is /bin/bash.

browser.default = browser-specifier ¶

The browser-like program used to create new top-level windows, unless overridden by a specific browser-specifier option.

The browser-specifier is a kind of command-candidates value: a list of command front-end, separated by newlines or semi-colons. The commands are tried left-to-right, until one is found that exists and is executable. See browser specifier for details.

The default is currently:

browser.default = electron;qt;chrome-app;firefox;browser

except on windows where it is:

browser.default = edge-app;electron;qt;chrome-app;firefox;browser

command.firefox = command ¶

command.chrome = command

command.electron = command

Command to use for respectively firefox, chrome, or electron.

The default for these is to search in the PATH, possibly with some platform-depending knowledge of default locations.

command.headless = command ¶

Command used when the --headless option requests an “invisible” headless window.

command.get-clipboard = command ¶

command.get-selection = command

Command that prints the string contents of the clipsboard (or the selection) to standard output. If the command’s output ends with a newline, it is removed. (If your command doesn’t write a newline at the end, you can add it, for example with echo.) When the user requests a Paste operation, the request is (in most cases - except for Electron) forwarded to the server, which runs the named command. The is done because browser security restrictions may limit when JavaScript can read the clipboard. If unspecified, the default depends on the platform and what helper programs are evailable. (See the get_clipboard_command function in the lws-term/utils.cc source file.)

window.geometry = geometry ¶

Control the size and/or position of new top-level windows using the syntax of a geometry specifier. A specified position is ignored if there are other windows.

The default is 800x600.

Appearance and styling ¶

style.user = css-style-rules ¶

Set the user stylesheet to the rules in css-style-rules. The latter is typically a multi-line value.

See the Styling section for examples.

style.qt = css-style-rules ¶

qtdomterm only: Set styling for QT user interface widgets. For example to specify the color green for text in QMenu do:

style.qt =
 |QMenu { color: green; }

See more examples.

style.dark = value ¶

Template. This option (if set) selects “reverse video”, which is a color preference for a darker background and a ligher foreground (text). The default is auto, which follows the system/desktop preference if possible, or otherwise off, which selects lighter background and a darker foreground colors.

Whether auto works depends on browser and system support. It is known to work on Firefox on MacOS and Gnome; Electron and Wry on MacOS (but not Gnome); Epiphany (on Gnome).

color.background = color ¶

Template. Set the default background color. Most of the terminal window will have this color, unless overridden.

The default depends on the style.dark setting: {?{style.dark};{color.black};#fffff8}.

color.foreground = color ¶

Template. Set the default foreground color. This is used for text, unless overridden.

The default depends on the style.dark setting: {?{style.dark};#fffff;{color.black}}.

color.black = color ¶

color.red = color

color.green = color

color.yellow = color

color.blue = color

color.magenta = color

color.cyan = color

color.white = color

color.bright-black = color

color.bright-red = color

color.bright-green = color

color.bright-yellow = color

color.bright-blue = color

color.bright-magenta = color

color.bright-cyan = color

color.bright-white = color

Template. Change the values of the basic 16 colors selected by the escape sequences "\e[30m" to "\e[37m" and "\e[90m" to "\e[97m" (for setting foreground color), and "\e[40m" to "\e[47m" and "\e[100m" to "\e[107m" (for setting background color).

style.blink-rate = [hide-time [show-time]] ¶

style.blink-rate = hide-time,show-time

Control rate of blinking text. The text is invisible for hide-time seconds, and then visible for show-time seconds, and then repeats. Blinking is disabled if hide-time is zero. If only one value is specified, show-time defaults to hide-time. If neither is specified the default is 0.3,0.7.

style.caret = value ¶

style.edit-caret = value

Change the style of the caret (text input cursor). See caret styling.

color.caret = caret-color caret-accent-color ¶

Template. Set the color of the caret (text input cursor). The caret-accent-color is used for the foreground (text) when using a block or blinking-block caret.

color.selection = text-color active-background-color [inactive-background-color] ¶

Template. Set the color of the selection. The text-color is used for the text (the foreground). The background color is active-background-color (in a focused window) or inactive-background-color (if the window does not have focus). If active-background-color is specified but inactive-background-color is not, then the former is used for the latter.

window-scale = value ¶

The window-scale setting scales (zooms) entire top-level windows by the given value factor, which defaults to 1.0. All sub-windows (panes) and menus and titlebars are also scaled, as long as you’re using DomTerm (non-system) titlebars and menus.

If using the settings command, use the ^ (top) modifier to specify a top window (as opposed to a pane). To scale by 20% the window that includes pane 2 you can do:

domterm -w ^2 settings window-scale=1.2

The effective window scale is the window-scale setting but modified by the window-zoom-in, window-zoom-out, and window-zoom-reset (menu or keyboard shortcut) commands for each window.

pane-scale = value ¶

Like window-scale, but scale the specified panes only. The value is multiplied by the effective window scale. If this is in settings.ini it applies by default to all panes, but not the titlebar or menu. You can change the scale for each pane individually:

domterm -w 3 settings pane-scale=0.8

The effective pane scale is the pane-scale setting multiplied by the effective window scale, and modified by the pane-zoom-in, pane-zoom-out, and pane-zoom-reset commands.

Key and mouse handling ¶

open.file.application = command-conditionals ¶

open.link.application = command-conditional

List of applications to try when clicking on a link. If the link’s href is a file: URL, then the open.file.application list is tried first; then the open.link.application list is tried. For a non-file: URL, only the open.link.application list is tried.

For details, see link-handlers.

keymap.master = keymap-overrides ¶

Template. Add or replace keybindings that are active in all modes. See Keyboard shortcuts for defaults and an example.

keymap.line-edit = keymap-overrides ¶

Template. Add or replace keybindings for input line editing.

Remote connnections ¶

command.remote-domterm = command-conditionals ¶

When connecting to a remote server over ssh, the command that runs domterm on the server. The default is domterm, but you may need to use this option if domterm is not in the remote PATH or you want to pass extra options (perhaps for debugging or logging) to domterm. The value is conditional, where the simple conditions have the form of either @hostname or user@hostname. For example:

command.remote-domterm =
 | {@192.168.1.55}/home/bothner/DT/bin/domterm
 | {jones@mac.example.com}/Users/jones/bin/domterm -d 15

The user and hostname are matched literally against those used to connect remotely. If user is specified it must match exactly, otherwise any (or no) user matches.

command.ssh = command-conditionals ¶

The command to use instead of ssh to connect to a remote server. The value is a list of alternative commands, optionally prefixed by conditions, in the same way as for command.remote-domterm.

predicted-input-timeout = timeout ¶

When the user types a “simple” keyboard action (a printable character, left/right arrow key, backspace, or delete) the keystroke will be sent from DomTerm to the user application which will then update the display (“echo”) in the “standard” way. However, there is a delay caused by the round trip from browser to application and back which may be noticable, especially if browser and application are separated by a network. To hide this delay, DomTerm will guess that the keystroke will have the “standard” effect, and tentatively update the display before it gets the confirming echo. DomTerm will undo the predicted update unless it received a confirming echo within timeout seconds. The default timeout is 0.4 seconds.

The following settings are used to timeout if a connection fails. All these values are in seconds; no timeout happens if the values are zero.

remote-input-interval = input-interval ¶

If non-zero, the local browser sends input data at least as frequently as every input-interval seconds. If there is no keyboard or other event, artificial data is sent. Defaults to 10 seconds,

remote-input-timeout = input-timeout

If the remote (application) end has not received any input data in input-timeout seconds and input-timeout is non-zero, it assume the connection has failed. Defaults to twice remote_input_interval.

remote-output-interval = output-interval

If non-zero, the remote (application) sends some data to the local browser at least every remote_output_interval seconds. Defaults to 10 seconds.

remote-output-timeout = output-timeout

If the local browser end of the connection has not received any output from the remote application end in remote_output_timeout seconds (and it is non-zero), it assume the connection has failed. (This timeout is both in the browser front-end, and in the domterm server on the local end of the ssh connection.) Defaults to twice remote_output_interval.

Debugging and logging ¶

log.file = specifier ¶

Send logging output (as controlled by the -d and --verbose flags) to the specified file. The specifier can be one of these special values: stderr writes log entries to standard error, with timestamps and colors; stderr-notimestamp (or notimestamp) is the same as stderr without timestamps; stdout writes to standard output, with timestamps and no colors. Otherwise, specifier is printf-style format string that is used for a file that is appended to: %P is replaced by Process ID of the domterm process; %% is a literal percent symbol.

The default is /tmp/domterm-%P.log.

log.js-verbosity = level ¶

Template. Write more information to the JavaScript console.

log.js-to-server = setting ¶

Send diagnostic/logging messages in the browser (normally written to the JavaScript console as controlled by by log.js-verbosity) where it is written using lwsl_notice to the location specified by log.file.

Sets the -d option to 5 if not specified; if specified the -d mask must have 4 set in the mask. (If you divide mask by 4, the result must be an odd integer.)

log.js-string-max = length ¶

Template. If positive, maximum length of strings to print to the JavaScript console.

debug.input.extra-delay = delay ¶

Delay an extra delay seconds before sending keyboard and other events from client (browser) to server (application). Especially useful for testing predicted-input-timeout, which should be higher than debug.input.extra-delay.

output-byte-by-byte = count ¶

Template. When a front-end receives N output bytes to process, it may handle multiple bytes (such as simple text) in one go. This option forces the last count bytes to be processed one at a time. (The first N-count bytes, if any, are processed first as a unit.) The default for count is 0 (normal processing). The value -1 means handle each byte one-by-one; this is useful for testing that things work (albeit slowly) even if the output arrived in small chunks.

Miscellaneous settings ¶

history.storage-key = string ¶

A string (default "DomTerm.history" used as an identifier for the JavaScripr storage mechanism to preserve line-editing history.

history.storage-max = number ¶

Maximum number of entries (default 200) of line-editing history to preserve,

password-hide-char = string ¶

Character used to hide characters in password fields. The default is "\u25CF" “black circle”. To change it to “bullet” you can do:

domterm settings password-hide-char="\u2022"

password-show-char-timeout = number ¶

Number of seconds (default 0.8) to show the actual password character before it is replaced by the password-hide-char.

terminal.minimum-width = width ¶

Mininum logical width (default 5, in columns/characters) of a terminal: If the available width is less, use this width for line-wrapping etc. (This avoids certain pathological behavior.)

titlebar = mode ¶

Use a custom titlebar for main (top-level) windows. Only the Electron, Wry, and Qt front-ends support disabling the system titlebar (on other platforms the custom titlebar is additional). The mode can be system to use the system titlebar, or domterm to use a custom titlebar (in HTML). Further options and customization is planned for later. The default on Electron and Qt is domterm, and system otherwise.

subwindows = mode ¶

If mode is no, disable support for sub-windows, which means all windows are top-level windows. Defaults to yes, unless running under a tiling window manager. (Currently only Sway is detected.) (Experimental.)

xtermjs = value

If the boolean value is true, use the xterm.js terminal emulator. If value is dom, canvas, or webgl select that xterm.js “renderer”.