ROXTERM(1)

NAME
roxterm - terminal emulator

SYNOPSIS

roxterm [-? | --help] [--help-all] [--help-gtk] [-u | --usage] [--geometry=GEOM | -g GEOM] [--appdir=DIR] [--profile=PROFILE | -p PROFILE] [--colour-scheme=SCHEME | --color-scheme=SCHEME | -c SCHEME] [--shortcut-scheme=SCHEME | -s SCHEME] [--separate] [--replace] [--fork] [--hold] [--atexit=ACTION] [--directory=DIR | -d DIR] [--show-menubar] [--hide-menubar] [--maximise | -m] [--fullscreen | -f] [--borderless | -b] [--disable-sm] [--tab] [--zoom=ZOOM | -z ZOOM] [--title=TITLE | -T TITLE] [--tab-name=NAME | -n NAME] [--role=ROLE] [--session=SESSION] [--display=DISPLAY] [--execute COMMAND | -e COMMAND]

DESCRIPTION

ROXTerm is a terminal emulator. It provides features similar to gnome-terminal. It is based on the same VTE library, which implements a virtual terminal emulator.

The original design goals of ROXTerm were twofold. A small memory footprint and a quick start-up time. This was realised by not using the Gnome libraries and by moving the configuration GUI to a separate applet. However, thanks to all the features it has acquired over the years, ROXTerm can now be accused of bloat. But it is now very configurable indeed. It is aimed at "power" users who make heavy use of terminals and who wish to have fine control over the many options.

ROXTerm still supports the ROX desktop application layout it was named after. It can also be installed in a conventional manner for use in other desktop environments. Both X11 and Wayland are supported.

OPTIONS

ROXTerm follows the usual GNU command line syntax. Both long options starting with two dashes (`-') and short single dash options are provided. Here follows a summary of options.

-? --help
    Show a list of ROXTerm options.

--help-gtk
    Show only the GTK+ options.

--help-all
    Show all options.

--usage
    Show a brief summary of usage.

-d DIRECTORY --directory=DIRECTORY
    Run shell/command in DIRECTORY.

-g COLUMNSxROWS+X+Y --geometry=COLUMNSxROWS+X+Y
    COLUMNSxROWS specifies the size of the terminal window in units of characters. +X+Y is optional and specifies the offset in DPI-scaled pixels of the left and top edges of the window relative to the display. “-” may be used in place of “+” to refer to the right and/or bottom edges. Offsets are deprecated and generally only supported in X11.

--appdir=DIR
    Application directory when run as a ROX app.

--show-menubar --hide-menubar
    Whether to show or hide the menubar, overriding the profile. The default is to show it.

--maximise -m
    Make initial terminal window take up the whole screen, but keep the window frame decorations.

--fullscreen -f
    Make initial terminal window take up the whole screen with no window furniture.

--borderless -b
    Disable window decorations like title bar, resize controls and frame border, if the window manager supports this.

--tab
    If possible open the new terminal in an existing window rather than open a new window. If used in conjunction with -T/--title the tab will be placed in an existing window with the same title template if one exists. This option overrides --zoom and --fullscreen.

--zoom=ZOOM -z ZOOM
    Scale terminal's font by a factor of ZOOM (1.0 is normal size).

-p PROFILE --profile=PROFILE
    Use the named profile.

-c SCHEME --colour-scheme=SCHEME --color-scheme=SCHEME
    Use the named colour scheme.

-s SCHEME --shortcut-scheme=SCHEME
    Use the named keyboard shortcut scheme.

--title=TITLE -T TITLE
    Set window title template. May include "%s" which is substituted with the full contents of the tab's label, "%n" which is substituted by the number of tabs, and "%t" which is substituted by the current tab number.

--tab-name=NAME -n NAME
    Set tab name as displayed in its label. May include "%s" which is substituted with the window title string set by the terminal, "%n" which is substituted by the number of tabs, and "%t" which is substituted by the current tab number.

--separate
    Use a separate process for this terminal.

--fork
    Always fork into the background. Usually the first instance stays in the foreground and subsequent invocations return once they have asked the master instance to handle their command. This option causes the master instance to fork itself into the background; the foreground process returns once the master is ready to handle further commands.

--atexit=ACTION
    What should be done with the tab after the shell command exits. Choose one of: close, hold, respawn, ask.

--hold
    An alias for --atexit=hold. Keep the tab open.

--replace
    Replace any existing instance as ROXTerm D-BUS service provider.

--role=ROLE
    Set the WM_WINDOW_ROLE property on the window. This can be used to uniquely identify a window across sessions, or in selecting configuration resources by window managers.

--session=SESSION
    Restore the named user session.

--display=DISPLAY
    The named X server display to use. If you use roxterm on multiple different displays on the same system then you need to use the --separate option as well.

-e --execute
    Execute remainder of the command line inside the terminal. This must be the final option. If there is only one following argument, it is parsed in case it is a command with space-separated arguments that was passed to roxterm in quotes. If there is more than one argument they are treated as a command and arguments without parsing.

SETUP

D-Bus is a messaging system which ROXTerm uses to connect terminals with its configure tool. ROXTerm uses the "session" bus, which should be started along with your desktop environment. Current versions of ROX, GNOME and KDE/Plasma session managers all launch D-Bus. If you use some other session/desktop/window manager, which doesn't launch D-Bus, you need to start it yourself. Insert something like this near the start of your .xinitrc or .xsession:

            if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then
                eval `dbus-launch --sh-syntax --exit-with-session`
                export DBUS_SESSION_BUS_ADDRESS
            fi

This setup provides a way to map an arbitrary number of profiles onto configuration filenames.

TABS

Each window can contain a number of tabs, each with its own terminal. The tab bar is always shown by default, even if there is only one tab, to avoid resizing inconsistencies, but this is configurable.

If you experience a problem with tab labels shrinking, after dragging tabs so that they only have room to display '...', then make sure the pointer is over the body of a terminal when you drop a dragged tab, not over the tab bar area.

MENUS

When the menu bar is hidden, the popup menu duplicates the same items as in the menu bar. This gives you full access to all the functions with the menu bar hidden. The menu bar is effectively redundant, but provided to make ROXTerm appear more straightforward for first-time users. It can be turned on and off for a particular window or more permanently by using the configuration manager.

The popup menu also allows email and web addresses to be opened in external applications, if such an address is highlighted by the pointer being over it.

URI HIGHLIGHTING

When the pointer is over an address that ROXTerm recognises as a URI (typically a web URL or email address) it is highlighted by underlining and a change of pointer shape. You can open the address either by right-clicking on it and choosing Open... in the menu or by holding Ctrl and left-clicking. The applications used to handle these addresses may be set with the configuration tool, otherwise it will try to find a suitable default.

Also, by holding down the Ctrl key, you can drag a URI to pass it to another application which is willing to accept it as a URI or text. Dragging it into the same window it came from pastes the address back in.

If the pointer is over the server address portion of a URL it only highlights the address, but not the filename. Move the pointer over the filename to get the whole URL. Similarly, you can highlight an email address with or without a leading mailto:.

SSH URI and hostname matching is supported. URIs including a path name can only be copied to the clipboard. In the absence of a pathname, ROXTerm can also start a ssh session to the described host. Plain hostnames are also matched, but only if they start with "ssh", or end with ".local" or ".lan".

DRAG AND DROP

You can drag items onto terminal windows. Text objects are fed to the terminal as if typed. Files and URIs have their location fed in rather than the object's contents. Graphical files can also be dragged onto the appropriate area of the configuration manager to set terminal background images. Hold down the Ctrl key while dragging a highlighted URI, to allow the address to be dragged to another application.

You can now drag tabs by their labels to reorder them within a window or to move them to another ROXTerm window or, by dropping them outside a ROXTerm window, move tabs to new windows of their own. Use mouse button 3 (the right button) to move an unselected tab without selecting it. Button 2 is a shortcut to paste the contents of the clipboard as the tab's name.

SESSIONS

User sessions can be saved under a name. Click Save Session... in the File menu. A session preserves the current state windows and tabs, but not their textual content. A session can be restored with the --session option. It will be restored by the default if it is named 'Default'. Leaving the field blank is equivalent to 'Default'.

CONFIGURATION

Configuration is based on named profiles, so you can save different sets of options and switch between them quickly. There are profiles for general options, colour schemes and keyboard shortcuts. Colour Schemes and Profiles apply to one tab at a time, but Keyboard Shortcuts apply to all tabs in the same window. New windows and tabs inherit settings from the window/tab they were opened from.

The Preferences menu allows you to select the current profile. Open the configuration manager to edit the current profile or colour scheme, or to manage all settings. In the configuration manager you can select one of the four types of option groups and edit, copy, delete or rename them. The item with the selected radio button is the default for new terminals.

KEYBOARD SHORTCUTS

ROXTerm allows the keyboard shortcut profiles to be edited in a text editor, either via the Configuration Manager or from a terminal's menu (Preferences submenu). The action names correspond to the localised labels used in the menu items. The new shortcuts should automatically be reloaded when you save the file. Alternatively, selecting a scheme in the Preferences menu now forces it to be reloaded. The default file for keyboard shortcuts is:

            ~/.config/roxterm.sourceforge.net/Shortcuts/Default.

The default keyboard shortcuts are:

            Ctrl+Shift+N    New Window
            Ctrl+Shift+T    New Tab
            Ctrl+Shift+Q    Close Window
            Ctrl+Shift+W    Close Tab
            Ctrl+PageUp     Previous Tab
            Ctrl+PageDown   Next Tab
            Ctrl+Shift+A    Select All
            Ctrl+Shift+C    Copy
            Ctrl+Shift+V    Paste
            Ctrl+Shift+M    Show Menubar
            Ctrl+plus       Zoom In
            Ctrl+minus      Zoom Out
            Ctrl+0          Normal Size
            F11             Full Screen
            Ctrl+Shift+B    Borderless
            Shift+Up        Scroll Up One Line
            Shift+Down      Scroll Down One Line
            F1              Show Manual
            Ctrl+Shift+Y    Copy & Paste
            Ctrl+Shift+F    Find...
            Ctrl+Shift+I    Find Next
            Ctrl+Shift+P    Find Previous

In addition, tabs can be selected by Alt+1, where 1 is to be replaced by the tab number. This can be disabled in the profile.

CONFIGURATION MANAGEMENT

Run the configuration manager by selecting "Configure..." in ROXTerm's menu or run roxterm-config.

Configuration files can be swapped with other users. Each profile, colour scheme and keyboard shortcut scheme consists of a single file. Saving a file in the appropriate directory will create a profile with the same name as the file.

Locations for files follow the XDG Base Directory specification.

    1. ${XDG_CONFIG_HOME}/roxterm.sourceforge.net, defaulting to ~/.config/roxterm.sourceforge.net.

    2. ${XDG_CONFIG_DIRS}/roxtem.sourceforge.net, defaulting to /etc/xdg/roxtem.sourceforge.net.

    3. ROXTerm/Config for ROX users, or ${datadir}/roxterm/Config for others. ${datadir} is usually /usr/share for packages or /usr/local/share when compiled from source.

Within any or each of those locations, profiles are saved in a "Profiles" subdirectory, colour schemes in "Colours" and keyboard shortcut schemes in "Shortcuts". A file called "Global" contains miscellaneous options, which don't fall into the above categories, including the default profile for new terminals.

ADVANCED

ROXTerm terminals can be configured from applications and scripts via D-BUS. For this purpose there are three methods. They require an ID code to target a specific terminal. Each roxterm's ID can be read from the environment variable ROXTERM_ID in the shell or application running in it. The D-Bus object path is "net.sf.roxterm.Options" and the D-Bus interface is "/net/sf/roxterm/Options". The methods are:

            SetProfile("id", "profile_name")

Ask the terminal to use the named profile. Note that any other tabs in the same window will be updated to the same new profile. All tabs in one window must have the same profile, so that their font size and terminal size remain consistent.

            SetColourScheme("id", "scheme_name")

Ask the terminal to use the named colour scheme. Tabs sharing the same window may have different colour schemes from each other.

            SetShortcutScheme("id", "scheme_name")

Ask the terminal to use the named keyboard shortcut scheme. Tabs sharing the same window must also share the same shortcut scheme.

Example using dbus-send in a shell script:

          dbus-send --session /net/sf/roxterm/Options \
               net.sf.roxterm.Options.SetColourScheme \
               string:$ROXTERM_ID string:GTK

You may also send D-Bus signals to change individual options within a named profile or colour scheme using the methods StringOption, IntOption (also used for boolean options) and FloatOption. All terminals using the named profile or colour scheme are affected, but only temporarily. The options are not saved for new terminals. The methods all take 3 arguments:

    • Full profile name, including a prefix of "Profiles/" or "Colours/"

    • Option name

    • Value

To see which option names you can use, check the config files, from which the types can be deduced. Example using dbus-send in a shell script:

            dbus-send --session /net/sf/roxterm/Options \
                net.sf.roxterm.Options.StringOption \
                string:Colours/GTK string:background 'string:#ffffff'

A third possible use is to notify roxterm that a profile, colour scheme or shortcuts scheme has been changed by an external program and all terminals using that profile etc need to reload it:

            OptionsChanged("family_name", "profile_name")

where family_name is one of "Profiles", "Colours" or "Shortcuts". For example:

            dbus-send --session /net/sf/roxterm/Options \
                net.sf.roxterm.Options.OptionsChanged \
                string:Profiles string:Default

ENVIRONMENT

The following environment variables are set or used by roxterm:

COLORTERM
    This is set to "truecolor" by VTE if the window supports 16 million colors.

EDITOR
    The name of the editor. Defaults to "gedit", "kate", "gvim", "emacs", whichever appears first in PATH.

LANG
    The language of the help URI. This defaults to "en".

ROXTERM_ID
    The unique identity of the roxterm D-Bus instance.

ROXTERM_NUM
    The number of toplevel windows which are managed by this roxterm process.

ROXTERM_PID
    The process identifier of roxterm.

TERM
    The name of the terminfo description, which is xterm-256color.

VTE_VERSION
    The version number of the VTE library.

WINDOWID
    The decimal X Window ID of the toplevel roxterm window. Only supported in an X environment.

XDG_CONFIG_HOME
    Where to save roxterm sessions. Defaults to ~/.config. Sessions are saved under $XDG_CONFIG_HOME/roxterm.sourceforge.net/UserSessions/.

SEE ALSO

file:///usr/local/share/doc/roxterm/en/index.html

AUTHOR

This manual page was written by Tony Houghton <h@realh.co.uk>. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any later version published by the Free Software Foundation.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL.

AUTHOR

Tony Houghton
    Developer

COPYRIGHT
Copyright © 2005-2020 Tony Houghton