FreeBSD Manual Pages
ROXTERM(1) User Commands ROXTERM(1) NAME roxterm - terminal emulator SYNOPSIS roxterm [-? | --help] [--help-all] [--help-gtk] [-u | --usage] [--geome- try=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-ter- minal. It is based on the same VTE library, which implements a virtual ter- minal 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 li- braries 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 af- ter. 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 start- ing 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 de- fault 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 ex- ists. 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 num- ber. --tab-name=NAME -n NAME Set tab name as displayed in its label. May include "%s" which is sub- stituted 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 configura- tion 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 dif- ferent 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 ses- sion/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 con- figuration 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 config- uration 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 (typi- cally 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-click- ing. 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 an- other 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 high- lights the address, but not the filename. Move the pointer over the file- name 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 ter- minal 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 appro- priate area of the configuration manager to set terminal background images. Hold down the Ctrl key while dragging a highlighted URI, to allow the ad- dress 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 op- tions, 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 edi- tor, either via the Configuration Manager or from a terminal's menu (Pref- erences 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 ~/.con- fig/roxterm.sourceforge.net. 2. ${XDG_CONFIG_DIRS}/roxtem.sourceforge.net, defaulting to /etc/xdg/rox- tem.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 environ- ment 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 re- main consistent. SetColourScheme("id", "scheme_name") Ask the terminal to use the named colour scheme. Tabs sharing the same win- dow 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 exam- ple: 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 (C) 2005-2020 Tony Houghton ROXTerm 01 April 2013 ROXTERM(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | SETUP | TABS | MENUS | URI HIGHLIGHTING | DRAG AND DROP | SESSIONS | CONFIGURATION | KEYBOARD SHORTCUTS | CONFIGURATION MANAGEMENT | ADVANCED | ENVIRONMENT | SEE ALSO | AUTHOR | AUTHOR | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=roxterm&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>