1ROXTERM(1) User Commands ROXTERM(1)
2
6 roxterm - terminal emulator
7
9 roxterm [-? | --help] [--help-all] [--help-gtk] [-u | --usage]
10 [--geometry=GEOM | -g GEOM] [--appdir=DIR]
11 [--profile=PROFILE | -p PROFILE]
12 [--colour-scheme=SCHEME | --color-scheme=SCHEME | -c SCHEME]
13 [--shortcut-scheme=SCHEME | -s SCHEME] [--separate] [--replace]
14 [--fork] [--hold] [--atexit=ACTION] [--directory=DIR | -d DIR]
15 [--show-menubar] [--hide-menubar] [--maximise | -m]
16 [--fullscreen | -f] [--borderless | -b] [--disable-sm] [--tab]
17 [--zoom=ZOOM | -z ZOOM] [--title=TITLE | -T TITLE]
18 [--tab-name=NAME | -n NAME] [--role=ROLE] [--session=SESSION]
19 [--display=DISPLAY] [--execute COMMAND | -e COMMAND]
20
22 ROXTerm is a terminal emulator. It provides features similar to
23 gnome-terminal. It is based on the same VTE library, which implements a
24 virtual terminal emulator.
25 The original design goals of ROXTerm were twofold. A small memory
27 footprint and a quick start-up time. This was realised by not using the
28 Gnome libraries and by moving the configuration GUI to a separate
29 applet. However, thanks to all the features it has acquired over the
30 years, ROXTerm can now be accused of bloat. But it is now very
31 configurable indeed. It is aimed at "power" users who make heavy use of
32 terminals and who wish to have fine control over the many options.
33 ROXTerm still supports the ROX desktop application layout it was named
35 after. It can also be installed in a conventional manner for use in
36 other desktop environments. Both X11 and Wayland are supported.
37
39 ROXTerm follows the usual GNU command line syntax. Both long options
40 starting with two dashes (`-') and short single dash options are
41 provided. Here follows a summary of options.
42 -? --help
44 Show a list of ROXTerm options.
45 --help-gtk
47 Show only the GTK+ options.
48 --help-all
50 Show all options.
51 --usage
53 Show a brief summary of usage.
54 -d DIRECTORY --directory=DIRECTORY
56 Run shell/command in DIRECTORY.
57 -g COLUMNSxROWS[+X+Y] --geometry=COLUMNSxROWS[+X+Y]
59 Set the size of the terminal window. Optionally a position may be
60 given as well.
61 --appdir=DIR
63 Application directory when run as a ROX app.
64 --show-menubar --hide-menubar
66 Whether to show or hide the menubar, overriding the profile. The
67 default is to show it.
68 --maximise -m
70 Make initial terminal window take up the whole screen, but keep the
71 window frame decorations.
72 --fullscreen -f
74 Make initial terminal window take up the whole screen with no
75 window furniture.
76 --borderless -b
78 Disable window decorations like title bar, resize controls and
79 frame border, if the window manager supports this.
80 --tab
82 If possible open the new terminal in an existing window rather than
83 open a new window. If used in conjunction with -T/--title the tab
84 will be placed in an existing window with the same title template
85 if one exists. This option overrides --zoom and --fullscreen.
86 --zoom=ZOOM -z ZOOM
88 Scale terminal's font by a factor of ZOOM (1.0 is normal size).
89 -p PROFILE --profile=PROFILE
91 Use the named profile.
92 -c SCHEME --colour-scheme=SCHEME --color-scheme=SCHEME
94 Use the named colour scheme.
95 -s SCHEME --shortcut-scheme=SCHEME
97 Use the named keyboard shortcut scheme.
98 --title=TITLE -T TITLE
100 Set window title template. May include "%s" which is substituted
101 with the full contents of the tab's label, "%n" which is
102 substituted by the number of tabs, and "%t" which is substituted by
103 the current tab number.
104 --tab-name=NAME -n NAME
106 Set tab name as displayed in its label. May include "%s" which is
107 substituted with the window title string set by the terminal, "%n"
108 which is substituted by the number of tabs, and "%t" which is
109 substituted by the current tab number.
110 --separate
112 Use a separate process for this terminal.
113 --fork
115 Always fork into the background. Usually the first instance stays
116 in the foreground and subsequent invocations return once they have
117 asked the master instance to handle their command. This option
118 causes the master instance to fork itself into the background; the
119 foreground process returns once the master is ready to handle
120 further commands.
121 --atexit=ACTION
123 What should be done with the tab after the shell command exits.
124 Choose one of: close, hold, respawn, ask.
125 --hold
127 An alias for --atexit=hold. Keep the tab open.
128 --replace
130 Replace any existing instance as ROXTerm D-BUS service provider.
131 --role=ROLE
133 Set the WM_WINDOW_ROLE property on the window. This can be used to
134 uniquely identify a window across sessions, or in selecting
135 configuration resources by window managers.
136 --session=SESSION
138 Restore the named user session.
139 --display=DISPLAY
141 The named X server display to use. If you use roxterm on multiple
142 different displays on the same system then you need to use the
143 --separate option as well.
144 -e --execute
146 Execute remainder of the command line inside the terminal. This
147 must be the final option. If there is only one following argument,
148 it is parsed in case it is a command with space-separated arguments
149 that was passed to roxterm in quotes. If there is more than one
150 argument they are treated as a command and arguments without
151 parsing.
152
154 D-Bus is a messaging system which ROXTerm uses to connect terminals
155 with its configure tool. ROXTerm uses the "session" bus, which should
156 be started along with your desktop environment. Current versions of
157 ROX, GNOME and KDE/Plasma session managers all launch D-Bus. If you use
158 some other session/desktop/window manager, which doesn't launch D-Bus,
159 you need to start it yourself. Insert something like this near the
160 start of your .xinitrc or .xsession:
161 if test -z "$DBUS_SESSION_BUS_ADDRESS" ; then
163 eval `dbus-launch --sh-syntax --exit-with-session`
164 export DBUS_SESSION_BUS_ADDRESS
165 fi
166 This setup provides a way to map an arbitrary number of profiles onto
169 configuration filenames.
170
172 Each window can contain a number of tabs, each with its own terminal.
173 The tab bar is always shown by default, even if there is only one tab,
174 to avoid resizing inconsistencies, but this is configurable.
175 If you experience a problem with tab labels shrinking, after dragging
177 tabs so that they only have room to display '...', then make sure the
178 pointer is over the body of a terminal when you drop a dragged tab, not
179 over the tab bar area.
180
182 When the menu bar is hidden, the popup menu duplicates the same items
183 as in the menu bar. This gives you full access to all the functions
184 with the menu bar hidden. The menu bar is effectively redundant, but
185 provided to make ROXTerm appear more straightforward for first-time
186 users. It can be turned on and off for a particular window or more
187 permanently by using the configuration manager.
188 The popup menu also allows email and web addresses to be opened in
190 external applications, if such an address is highlighted by the pointer
191 being over it.
192
194 When the pointer is over an address that ROXTerm recognises as a URI
195 (typically a web URL or email address) it is highlighted by underlining
196 and a change of pointer shape. You can open the address either by
197 right-clicking on it and choosing Open... in the menu or by holding
198 Ctrl and left-clicking. The applications used to handle these addresses
199 may be set with the configuration tool, otherwise it will try to find a
200 suitable default.
201 Also, by holding down the Ctrl key, you can drag a URI to pass it to
203 another application which is willing to accept it as a URI or text.
204 Dragging it into the same window it came from pastes the address back
205 in.
206 If the pointer is over the server address portion of a URL it only
208 highlights the address, but not the filename. Move the pointer over the
209 filename to get the whole URL. Similarly, you can highlight an email
210 address with or without a leading mailto:.
211 SSH URI and hostname matching is supported. URIs including a path name
213 can only be copied to the clipboard. In the absence of a pathname,
214 ROXTerm can also start a ssh session to the described host. Plain
215 hostnames are also matched, but only if they start with "ssh", or end
216 with ".local" or ".lan".
217
219 You can drag items onto terminal windows. Text objects are fed to the
220 terminal as if typed. Files and URIs have their location fed in rather
221 than the object's contents. Graphical files can also be dragged onto
222 the appropriate area of the configuration manager to set terminal
223 background images. Hold down the Ctrl key while dragging a highlighted
224 URI, to allow the address to be dragged to another application.
225 You can now drag tabs by their labels to reorder them within a window
227 or to move them to another ROXTerm window or, by dropping them outside
228 a ROXTerm window, move tabs to new windows of their own. Use mouse
229 button 3 (the right button) to move an unselected tab without selecting
230 it. Button 2 is a shortcut to paste the contents of the clipboard as
231 the tab's name.
232
234 User sessions can be saved under a name. Click Save Session... in the
235 File menu. A session preserves the current state windows and tabs, but
236 not their textual content. A session can be restored with the --session
237 option. It will be restored by the default if it is named 'Default'.
238 Leaving the field blank is equivalent to 'Default'.
239
241 Configuration is based on named profiles, so you can save different
242 sets of options and switch between them quickly. There are profiles for
243 general options, colour schemes and keyboard shortcuts. Colour Schemes
244 and Profiles apply to one tab at a time, but Keyboard Shortcuts apply
245 to all tabs in the same window. New windows and tabs inherit settings
246 from the window/tab they were opened from.
247 The Preferences menu allows you to select the current profile. Open the
249 configuration manager to edit the current profile or colour scheme, or
250 to manage all settings. In the configuration manager you can select one
251 of the four types of option groups and edit, copy, delete or rename
252 them. The item with the selected radio button is the default for new
253 terminals.
254
256 ROXTerm allows the keyboard shortcut profiles to be edited in a text
257 editor, either via the Configuration Manager or from a terminal's menu
258 (Preferences submenu). The action names correspond to the localised
259 labels used in the menu items. The new shortcuts should automatically
260 be reloaded when you save the file. Alternatively, selecting a scheme
261 in the Preferences menu now forces it to be reloaded. The default file
262 for keyboard shortcuts is:
263 ~/.config/roxterm.sourceforge.net/Shortcuts/Default.
265 The default keyboard shortcuts are:
268 Ctrl+Shift+N New Window
270 Ctrl+Shift+T New Tab
271 Ctrl+Shift+Q Close Window
272 Ctrl+Shift+W Close Tab
273 Ctrl+PageUp Previous Tab
274 Ctrl+PageDown Next Tab
275 Ctrl+Shift+A Select All
276 Ctrl+Shift+C Copy
277 Ctrl+Shift+V Paste
278 Ctrl+Shift+M Show Menubar
279 Ctrl+plus Zoom In
280 Ctrl+minus Zoom Out
281 Ctrl+0 Normal Size
282 F11 Full Screen
283 Ctrl+Shift+B Borderless
284 Shift+Up Scroll Up One Line
285 Shift+Down Scroll Down One Line
286 F1 Show Manual
287 Ctrl+Shift+Y Copy & Paste
288 Ctrl+Shift+F Find...
289 Ctrl+Shift+I Find Next
290 Ctrl+Shift+P Find Previous
291 In addition, tabs can be selected by Alt+1, where 1 is to be replaced
294 by the tab number. This can be disabled in the profile.
295
297 Run the configuration manager by selecting "Configure..." in ROXTerm's
298 menu or run roxterm-config.
299 Configuration files can be swapped with other users. Each profile,
301 colour scheme and keyboard shortcut scheme consists of a single file.
302 Saving a file in the appropriate directory will create a profile with
303 the same name as the file.
304 Locations for files follow the XDG Base Directory specification.
306 1. ${XDG_CONFIG_HOME}/roxterm.sourceforge.net, defaulting to
308 ~/.config/roxterm.sourceforge.net.
309 2. ${XDG_CONFIG_DIRS}/roxtem.sourceforge.net, defaulting to
311 /etc/xdg/roxtem.sourceforge.net.
312 3. ROXTerm/Config for ROX users, or ${datadir}/roxterm/Config for
314 others. ${datadir} is usually /usr/share for packages or
315 /usr/local/share when compiled from source.
316 Within any or each of those locations, profiles are saved in a
318 "Profiles" subdirectory, colour schemes in "Colours" and keyboard
319 shortcut schemes in "Shortcuts". A file called "Global" contains
320 miscellaneous options, which don't fall into the above categories,
321 including the default profile for new terminals.
322
324 ROXTerm terminals can be configured from applications and scripts via
325 D-BUS. For this purpose there are three methods. They require an ID
326 code to target a specific terminal. Each roxterm's ID can be read from
327 the environment variable ROXTERM_ID in the shell or application running
328 in it. The D-Bus object path is "net.sf.roxterm.Options" and the D-Bus
329 interface is "/net/sf/roxterm/Options". The methods are:
330 SetProfile("id", "profile_name")
332 Ask the terminal to use the named profile. Note that any other tabs in
335 the same window will be updated to the same new profile. All tabs in
336 one window must have the same profile, so that their font size and
337 terminal size remain consistent.
338 SetColourScheme("id", "scheme_name")
340 Ask the terminal to use the named colour scheme. Tabs sharing the same
343 window may have different colour schemes from each other.
344 SetShortcutScheme("id", "scheme_name")
346 Ask the terminal to use the named keyboard shortcut scheme. Tabs
349 sharing the same window must also share the same shortcut scheme.
350 Example using dbus-send in a shell script:
352 dbus-send --session /net/sf/roxterm/Options \
354 net.sf.roxterm.Options.SetColourScheme \
355 string:$ROXTERM_ID string:GTK
356 You may also send D-Bus signals to change individual options within a
359 named profile or colour scheme using the methods StringOption,
360 IntOption (also used for boolean options) and FloatOption. All
361 terminals using the named profile or colour scheme are affected, but
362 only temporarily. The options are not saved for new terminals. The
363 methods all take 3 arguments:
364 · Full profile name, including a prefix of "Profiles/" or "Colours/"
366 · Option name
368 · Value
370 To see which option names you can use, check the config files, from
372 which the types can be deduced. Example using dbus-send in a shell
373 script:
374 dbus-send --session /net/sf/roxterm/Options \
376 net.sf.roxterm.Options.StringOption \
377 string:Colours/GTK string:background 'string:#ffffff'
378 A third possible use is to notify roxterm that a profile, colour scheme
381 or shortcuts scheme has been changed by an external program and all
382 terminals using that profile etc need to reload it:
383 OptionsChanged("family_name", "profile_name")
385 where family_name is one of "Profiles", "Colours" or "Shortcuts". For
388 example:
389 dbus-send --session /net/sf/roxterm/Options \
391 net.sf.roxterm.Options.OptionsChanged \
392 string:Profiles string:Default
393
396 The following environment variables are set or used by roxterm:
397 COLORTERM
399 This is set to "truecolor" by VTE if the window supports 16 million
400 colors.
401 EDITOR
403 The name of the editor. Defaults to "gedit", "kate", "gvim",
404 "emacs", whichever appears first in PATH.
405 LANG
407 The language of the help URI. This defaults to "en".
408 ROXTERM_ID
410 The unique identity of the roxterm D-Bus instance.
411 ROXTERM_NUM
413 The number of toplevel windows which are managed by this roxterm
414 process.
415 ROXTERM_PID
417 The process identifier of roxterm.
418 TERM
420 The name of the terminfo description, which is xterm-256color.
421 VTE_VERSION
423 The version number of the VTE library.
424 WINDOWID
426 The decimal X Window ID of the toplevel roxterm window. Only
427 supported in an X environment.
428 XDG_CONFIG_HOME
430 Where to save roxterm sessions. Defaults to ~/.config. Sessions are
431 saved under $XDG_CONFIG_HOME/roxterm.sourceforge.net/UserSessions/.
432
434 file:///usr/share/doc/roxterm/en/index.html
435
437 This manual page was written by Tony Houghton <h@realh.co.uk>.
438 Permission is granted to copy, distribute and/or modify this document
439 under the terms of the GNU General Public License, Version 2 or any
440 later version published by the Free Software Foundation.
441 On Debian systems, the complete text of the GNU General Public License
443 can be found in /usr/share/common-licenses/GPL.
444
446 Tony Houghton
447 Developer
448
450 Copyright © 2005-2020 Tony Houghton
451ROXTerm 01 April 2013 ROXTERM(1)