Settings

A setting is named value that controls how DomTerm works, depending on user preference or environment.

Settings can be global settings, or local settings. Global settings are specified in a settings.ini configuration file, and apply to all sessions and windows managed by a server. Local settings are specified on the command line (or in the future a GUI) and apply to the current command, session, or window.

The settings that are active is the merge of the global and local settings, with the latter taking precedence.

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 this default 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

How the raw characters of a settings value is interpreted depends on the keyword: Each keyword expects the value to have a specific type and hence syntax. The raw value is the characters in the settings file or command-file; the actual value is how those characters are interpreted (parsed).

Some settings specify a list of values. In that case the values are seperated by newlines or (unquoted) semi-colons.

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.

String values

If the type of value is a string, the actual value is roughly the characters of the raw value with any non-nested quotoes removed. “Extra spaces” (more than one in a row, or at the start or end) that are not quoted are also removed. 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 currently also processed within single quotes, but that may change.)

Parsing as a string is the same as parsing as a command and then joining all the arguments separated by a single space.

String escapes

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

\"

\\

\/

The character following the backslash: Quotation Mark (Unicode 0x22), Backslash (Reverse solidus - Unicode 0xC), or plain slash (Unicode 0x2F - pointless but included for JSON compatibiity).

This is a superset of JSON.

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

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.

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

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); Epihany (on Gnome).

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.

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

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

keymap.line-edit = keymap-overrides

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

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

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

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, Wry, 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.