Sessions and Windows ¶

DomTerm can “multiplex” multiple sub-windows, each containing a separate terminal emulator session or other information, such as a web browser. This is similar to tmux or GNU Screen.

This section explains these concepts in detail.

Windows and connections ¶

A window is an area of the screen where you can display or interact with a session or a browser: Either a top-level window (a window or tab managed by a window manager or a web browser), or a sub-window (managed by DomTerm), which can be a pane or a tab. A top-level window may be split vertically and/or horizontally into one or more panes (or tiles), which can each have multiple tabs, only one of which is visible at a time,

A non-session window displays something other than a DomTerm terminal session. The domterm browse command creates a non-session window that displays a specified web page. One use of this for is viewing documentation.

Window number ¶

Every window has a unique window number. Normally, when a new terminal session is created a window will be created with the same window number as the session number. However, there may be detached sessions without windows, and (rarely) there may be sessions that use multiple windows.

A window-number can be prefixed by a ‘:’ when a separator is desired or for disambiguation, like :2.

A remote session will have a connection number on the remote (process) end. The connection number is like a pseudo-window-number. It is unique and specific to the remote server. The local (display) end may have an unrelated window number.

Some commands may refer to a specific top-level window. The top-window-number shown by domterm status is usually the number of one of its subwindows, though sometimes it might be the number of a deleted window. To refer to a top-window you don’t have to use the top-window-number; you can use the number of any sub-window. You can use a prefix ‘^’ if you need to distinguish the top window as a whole from one of the sub-windows.

A window keeps the same window number if it is dragged from one top-level window to another. This may cause the top-window-number to change.

Window name ¶

The window name is an optional user-specified name for a window. It is recommended that this be unique, but that is not enforced. The window name can be specified with the --name option in the domterm new command or other command that creates a new window (such as browse or attach). You can also dynamically change the window name wirh a set-window-name command or an escape sequence:

echo -en "\e]30;window-name\007"

It is recommended (but not required) that a window name have the format of an “identifier”: The first character should be a letter, and the rest should be letters, digits, hyphen, or underscore.

Window specifier ¶

A window-specifier is used in various commands, and can be one of:

window-number

:window-number

The window with the specified window-number.

#session-number

The window(s) attached to the specified session.

window-name

The window(s) with the specified window-name.

.

The “current” window, which is the one that most recently has received focus.

^

The top-level window containing the current window.

*

All windows, including sub-windows.

^*

All top-level sub-windows.

^window-specifier

The top-level window(s) containing the specified windows.

window-specifier,window-specifier...

A comma-separated list of window specifiers.

Window title and icon title ¶

The window-title is an application-specific string associated with a window. For a browser window, the URL is used.

A terminal can sets its title dynamically using standard xterm escape sequences. They are commonly sent by shells (for example using bash’s PROMPT_COMMAND) and may include the current directory and maybe other information.

An application can also send an escape sequence to set an icon name. This is currently remembered but otherwise unused by DomTerm, unless no window title is set.

Window header - label and title ¶

The window label is used in a window or tab title to visually identify a window.

If the window has a window-name, that is used for the window-label. If the window-name is not unique, a colon and the window-number are added.

If there is no window-name, a label is constructed. By default this contains:

1. A generic descriptor (like DomTerm for a terminal window or Browser for a browser window);
2. a ‘#’ followed by the session number - but only for non-remote terminals and when the session number differs from the window number;
3. a ‘:’ followed by the window number;
4. in the case of a remote session: @host#remote-session-number

If there is room, the label is followed by the window-title in parenthesis.

You cannot customise the window label at the time of writing, but it planned as a future enhancement.

Sessions ¶

A session is an emulated terminal with a process running under it. A domterm server manages one or more sessions. Typically, for each user there is at most a single domterm server running at a time, though it is possible to create more: The server is created as needed, and exits when there are no more sessions. (Note that tmux uses “session” to refer to multiple processes running under the same server.)

Each session is usually displayed in a domterm window or window for short. If the session is not displayed in any window, we say it is detached. It is possible to display the same session in multiple windows.

Session number ¶

Every session has an integer session number. These numbers are unique within a domterm server: If you connect to a remote domterm server the session numbers may be different on the local and remote end.

In most cases the session number will be the same as the window-number of a window attached to it. The main (non-contrived) exception if for remote sessions: A remote process will have a session number local to the remote server, and a window number local to the local (display) server. (The local server will also have an internal pseudo-session-number for the ssh client process.)

A session-number can be prefixed by a ‘#’ when a separator is desired or for disambiguation, like: #2.

Session name ¶

A session may have a name, based on the name of the window attached to it. If there is more than one attached window that has a name, and the names are not identical, then there is no session name.

A detached session keeps the session name (if any) it had when detached. This is used as the default name when the window is attached.

Managing sessions ¶

Creating a new session is done by invoke the domterm command with the new sub-command, or with no arguments. See Creating a new session for details.

The sub-command list lists active sessions, as does status with more detail.

The sub-command attach connects to an existing session, often a detached session. You specify the session with a session-specifier.

You can detach the current session using either the keyboard short-cur Ctrl+Shift+A d or a menu command. More precisely, it marks the current session as want-to-detach, and closes the current window. If there are other windows on the session, they remain active, but the session is detached (rather than exits) when the last window on the session closes.

When a session is detached, it saves the display state, so it can be re-created if the session is later attached. There is no auto-save in case of unintentional detach, such as network failure or a browser crash, but there are plans to implement that.

Session specifier ¶

A session specifier (used by the domterm attach command) which can be any one of the following forms:

session-number

#session-number

The session with the given session-number.

window-number

:window-number

The session attached to the specified window.

name

The session whose session-name matches name, assuming there is only one such session. Can also be the session (if unique) that is attached to a window whose window-name matches name.

$pid

The session whose process ID (an integer) matches pid.