ifdef::basebackend-manpage[]
:doctitle: domterm-window-specifier(1)

== Name
domterm - window specifier options
endif::[]
ifndef::basebackend-manpage[]
== domterm window specifier options
endif::[]

== Synopsis

`--electron` `--qt`
`--browser` `--firefox` `--chrome` `--google-chrome`
`--below` `--above` `--left` `--right` `--tab` `--pane`
`--print-url` `--detached`

== Description

Domterm commands that create a new window take an optional
window-specifier option to describe how to create the new window.
For example the following command creates a new
sub-window (pane) below the current window:

    `domterm new --below`

Commands that take window specifiers include `new`, `attach`,
`browse`, and `view-saved`.

== Create top-level window

If there is no window-specifier option, the default is given by the
`frontend.default` preference (by default read in the `settings.ini` file).
That is a list of possible browser commands (similar to what might
follow the `--browser=` option).
The first command in the list that executable is used.
If the preference is unset, the default is currently
`electron;qt;chrome;firefox;browser`, though that may change.

The best user experience is currently either `--electron` or `-qt`.
Both of these look and feel like traditional terminal emulator application,
with a menubar and popup menu suitable for a terminal (rather than a browser).

`--electron`::
    Use a front-end based on https://electron.atom.io/[Electron].

`--qt`::
`--qtdomterm`::
`--qtwebengine`::
    Use a front-based on the https://www.qt.io/[Qt toolkit],
    including https://wiki.qt.io/QtWebEngine[QtWebEngine].

`--browser`::
    Creates a new window or tab in your preferred desktop browser.

``--browser=``_command_::

Invoke _command_ to create a new window. The _command_ is a multi-word
template, where `%U` is replaced by a URL generated by domterm.
If _command_ contains a `$` it is processed by the default shell;
the program should either deamonize itself or otherwise run in the background
(perhaps by using `&`). If _command_ does _not_ contain a `$`,
domterm splits it into words and runs it directly (daemonized).
For example:
+
----
domterm --browser='firefox --new-window %U'
----
+
If there is no `%U` in the _command_, it is equivalent
to `--browser=`_command_ `" %U"`.

`--firefox`::
`--browser=firefox`::

    Create a new window or tab in the Firefox browser.
    May use platform-specific logic to find Firefox.
    Currently does so on Mac OS; otherwise just checks your PATH.

`--chrome`::
`--google-chrome`::
`--browser=google`::

     Create a new window or tab in the Google Chrome browser.
     Checks `CHROME_BIN` environment variable; otherwise
     looks for `chrome` or `google-chrome` in the PATH.

== Create new panes or tabs

`--tab`::
    Create new tab. 

`--left`::
`--right`::
`--below`::
`--above`::
    If there is a current DomTerm window, split it in two,
    and create a new window to the left/right/above/below the old one.

`--pane`::

    Equivalent to either `--right` or `--below` depending on
    the current window’s width/height ratio. 

== Special cases

`--detached`::
    When creating a new session, it is detached, without a window.

`--print-url`::
   Do not open a new window.  Instead print out a URL
   that can be used in a browser to open a window.
   This is used by https://atom.io/packages/atom-domterm[atom-domterm].
