ROXTerm
Author: Adrian Sampson
Description: ROXTerm: a full-featured VTE terminal emulator.

- Home
- News
- Installation
- User Guide

# Welcome

ROXTerm is a terminal emulator intended to provide similar features to gnome-terminal, based on the same VTE library. It was originally designed to have a smaller footprint and quicker start-up time by not using the Gnome libraries and by using a separate applet to provide the configuration GUI, but thanks to all the features it's acquired over the years ROXTerm can probably now be accused of bloat. However, it is more configurable than gnome-terminal and aimed more at "power" users who make heavy use of terminals.

It still supports the ROX desktop application layout it was named after, but can also be installed in a more conventional manner for use in other desktop environments.

# News

2025-09-09 Version 3.17.1

- Refactored HTML documentation.
- Added support for translations to the build system.

2018-03-01 Version 3.5.1

- Migrated to github.
- Use CMake build system.
- Fixed the geometry bug introduced by GTK 3.20.0.
- Removed X11-specific code and options for improved Wayland support.
- Minimum version requirements are now GTK 3.20 and vte 0.48.
- Improved support for URIs.
- Numerous other fixes and updates.

2015-12-02 Version 3.3.1

- Terminals running the default shell are only considered to be running (when confirming close actions) if the shells have child processes. This may only work in Linux.

2015-08-11 Version 3.1.1

- This version supports the saving and restoring of named user sessions.
- The initial number of tabs profile option has been removed; its functionality is better served by sessions.

2015-07-09 Version 3.0.1

- The GTK2 version has been dropped and only the vte-2.91 API (vte 0.38 or newer) is supported. You may need to change the background opacity setting (now found in the Appearance section of your profile) when upgrading from an earlier version.
- mscript.py now uses python3 by default, but is backwards compatible with python2. python3-lockfile is relatively new so you may need to explicitly run mscript.py in python2. To do this when building a Debian package edit debian/rules and change the dependencies in debian/control.

# Installation

## Download :

Visit the github project page to download snapshots. For a stable version use the latest numerical tag. If you are using an old LTS distro with a GTK3 version lower than 3.20 you should use roxterm 3.3.1, preferably from your distro's package manager. In case your distro is really old, roxterm 2.x supports GTK2.

## Requirements :

You need the libraries for GTK+3 which is pretty much standard on all free Unix derivatives these days. It needs at least version 2.16 of glib and GTK+ 3.20. You will also need vte/libvte (at least version 0.48 of vte-2.91), a GNOME component. D-BUS is also required (see below).

To compile ROXTerm you will need the header files for the above libraries. In packaging systems they usually come in packages whose names end in "-dev" or "-devel".

Prior to 3.5.0 ROXTerm used a bespoke build system called maitch. This requires python and the python 'lockfile' module. 3.5.0 uses the more conventional CMake.

### D-Bus

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 can start it by inserting 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

## Installing :

To install ROXTerm for ROX all you need to do is check it out or unpack it into your Apps directory and run it from there, but you will probably want to rename the folder to ROXTerm. For other systems ROXTerm may be installed in the typical CMake way:

mkdir build cd build cmake .. make -j 4 sudo make install

The `-j 4` is optional, to accelerate the build by using multiple processing threads. Replace the 4 with the number of "threads" or cores your CPU has.

Various other options are available, run

cmake --help

for details.

### Debian & Ubuntu

Up-to-date official Debian packages are not currently available, but packages from the Ubuntu PPA may be compatible, or you can take advantage of the debian build files provided.

You can use `sudo apt-get build-dep roxterm` at this point, but depending on the version already in your distro the set of packages may be out-of-date, so be prepared for dependency errors later and install the necessary packages at that point.

If not using a release snapshot it's a good idead to use `dch` to ensure the newest version number in `debian/changelog` has an appropriate version number eg what `./version.sh` generates in the file `version`, based on the output of `git describe`. Now you can build the packages eg with `debuild -b -uc -us`. Note the `-b`:- only binary packages can be built in the absence of an orig tarball.

# User Guide

## Tabs :

Each window can contain a number of tabs, each with its own terminal. Unlike gnome-terminal and earlier versions of ROXTerm, 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 '...', try making 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 Ctrl 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.

Note that if the pointer is over the server address portion of a URL it only highlights the address, omitting 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:.

As of version 2.9.1 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". Attempting to match more generic hostnames would cause too many false positives. If you regularly use a non-matching ssh server consider adding a matching alias in /etc/hosts.

## Drag & Drop :

You can now drag items onto terminal windows. Text objects are fed to the terminal as if typed. Files and URIs have their location (filename or URI) 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. Holding down Ctrl while dragging a highlighted URI allows 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. Note that versions prior to 1.9 used button 2 (middle). Button 2 is now a shortcut to paste the contents of the clipboard as the tab's name.

## Named User Sessions :

New in version 3.1.1 is the ability to save named user sessions. Click Save Session... in the File menu to name your session and save it. A session saves the state of current windows and tabs but not the terminals' text content. A session can be restored with roxterm's --session command-line option, or will be restored automatically if 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 (sometimes also referred to as accelerators). Colour Schemes and Profiles apply to one tab at a time, but Keyboard Shortcuts apply to all tabs in the same window to avoid the potential for confusion from different tabs having different shortcuts for switching tabs. New windows and tabs inherit settings from the window/tab they were opened from.

Prior to version 1.15.1 all tabs had to share the same Profile, but this has been changed. In consequence a profile's font and other settings which affect a terminal's size may be overridden to keep geometry consistent across a number of tabs in one window.

The Preferences menu allows you to select the current profile etc (this setting will not be remembered; use the configuration manager to set the defaults), 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 it. Each item also has a radio button. The item with the selected radio is the default for new terminals. Note that character encodings are handled slightly differently.

## Keyboard Shortcuts :

ROXTerm allows the shortcuts 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.

## Configuration Management :

You can also run the configuration manager by selecting "Configure..." in ROX's menu for the ROXTerm application or by running roxterm-config if ROXTerm has been installed conventionally.

Configuration files can easily be swapped with other users. Each profile, colour scheme and keyboard shortcut scheme has a single file associated with it; saving a valid file in the appropriate directory will create a profile etc with the same name as the file.

The directory locations for these configuration files follow the XDG Base Directory specification. In descending order of priority they are:

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

Files will be loaded from any and all the above locations; files in high priority locations shadow ones with the same name in lower priority locations. Files are only saved in the first location.

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 "Globals" contains miscellaneous options which don't fall into the above categories, including the default profile etc for new terminals.

## Command-line Options :

ROXTerm accepts a number of command-line options. Run:

roxterm --help

for a full list.

From version 1.1.0 ROXTerm defaults to using only one process for all terminals so that you can drag tabs between windows. If you run the command again it sends a D-BUS message to the existing process to signal it to open a new terminal, and the second process exits. To make a roxterm command run in its own separate process use the --separate option.

Note that the --colour_scheme and --shortcut_scheme options have been replaced by --colour-scheme and --shortcut-scheme respectively in 1.7.0 (underscores changed to hyphens) but the old versions remain usable for backwards compatibility.

## GTK Styling :

Like any VTE-based terminal, you can apply custom GTK styles on ROXTerm terminals.

A common use-case is to add padding around the terminal content. You can do this by adding the following to your global GTK stylesheet in ~/.config/gtk-3.0/gtk.css:

VteTerminal, vte-terminal { -VteTerminal-inner-border: 20px; padding: 20px; }

Per-profile styling is possible by targeting specific classes in the GTK stylesheet. For example, if you want to apply a different padding to a profile named "Minimal", while still keeping your default padding, you can add this style rule after the previous one:

VteTerminal.roxterm-Minimal, vte-terminal.roxterm-Minimal { -VteTerminal-inner-border: 2px; padding: 2px; }

When a profile name contains spaces, the generated class replaces them with hyphens.

## Advanced D-Bus Usage :

From version 1.14.0 advanced users can use D-Bus to configure terminals from other applications and scripts. There are three D-Bus methods especially for this purpose; they require an id code to target a specific terminal; each terminal's id code can be read from the environment variable ROXTERM_ID in the shell/application running in it. The D-Bus object path and interface for the methods are "net.sf.roxterm.Options" and "/net/sf/roxterm/Options" respectively. 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 therefore 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