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.
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.
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
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.
For a boolean value any
one of true
, yes
, or on
enable the preference;
one of false
, no
, or off
disable the preference.
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.
\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).
\u
HHHHUnicode 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.
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.
shell.default =
commandSpecify 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-specifierThe 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 =
commandcommand.chrome =
commandcommand.electron =
commandCommand 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 =
commandCommand used when the --headless
option requests
an “invisible” headless window.
command.get-clipboard =
commandcommand.get-selection =
commandCommand 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 =
geometryControl 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
.
style.user =
css-style-rulesSet 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-rulesqtdomterm
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 =
valueThis 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-timeControl 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 =
valuestyle.edit-caret =
valueChange the style of the caret (text input cursor). See caret styling.
window-scale =
valueThe 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 =
valueLike 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.
open.file.application =
command-conditionalsopen.link.application =
command-conditionalList 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-overridesAdd or replace keybindings that are active in all modes. See Keyboard shortcuts for defaults and an example.
keymap.line-edit =
keymap-overridesAdd or replace keybindings for input line editing.
command.remote-domterm =
command-conditionalsWhen 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-conditionalsThe 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 =
timeoutWhen 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-intervalIf 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-timeoutIf 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-intervalIf 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-timeoutIf 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
.
log.file =
specifierSend 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 =
levelWrite more information to the JavaScript console.
log.js-to-server =
settingSend 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 =
lengthIf positive, maximum length of strings to print to the JavaScript console.
debug.input.extra-delay =
delayDelay 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 =
countWhen 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.
history.storage-key =
stringA string (default "DomTerm.history"
used as an identifier
for the JavaScripr storage mechanism to preserve line-editing history.
history.storage-max =
numberMaximum number of entries (default 200) of line-editing history to preserve,
password-hide-char =
stringCharacter 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 =
numberNumber of seconds (default 0.8) to show the actual password character
before it is replaced by the password-hide-char
.
terminal.minimum-width =
widthMininum 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 =
modeUse 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 =
modeIf 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 =
valueIf the boolean value is true, use the xterm.js terminal emulator.