roxterm - Man Page

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]

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.

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]

Set the size of the terminal window. Optionally a position may be given as well.

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

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.

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.

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.

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

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.

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

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.

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.

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

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

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

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.

Tony Houghton

Copyright © 2005-2020 Tony Houghton

xde-menu(1).