1ROXTERM(1)                       User Commands                      ROXTERM(1)
2
3
4

NAME

6       roxterm - terminal emulator
7

SYNOPSIS

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

DESCRIPTION

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
26       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
34       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

OPTIONS

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
43       -? --help
44           Show a list of ROXTerm options.
45
46       --help-gtk
47           Show only the GTK+ options.
48
49       --help-all
50           Show all options.
51
52       --usage
53           Show a brief summary of usage.
54
55       -d DIRECTORY --directory=DIRECTORY
56           Run shell/command in DIRECTORY.
57
58       -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
62       --appdir=DIR
63           Application directory when run as a ROX app.
64
65       --show-menubar --hide-menubar
66           Whether to show or hide the menubar, overriding the profile. The
67           default is to show it.
68
69       --maximise -m
70           Make initial terminal window take up the whole screen, but keep the
71           window frame decorations.
72
73       --fullscreen -f
74           Make initial terminal window take up the whole screen with no
75           window furniture.
76
77       --borderless -b
78           Disable window decorations like title bar, resize controls and
79           frame border, if the window manager supports this.
80
81       --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
87       --zoom=ZOOM -z ZOOM
88           Scale terminal's font by a factor of ZOOM (1.0 is normal size).
89
90       -p PROFILE --profile=PROFILE
91           Use the named profile.
92
93       -c SCHEME --colour-scheme=SCHEME --color-scheme=SCHEME
94           Use the named colour scheme.
95
96       -s SCHEME --shortcut-scheme=SCHEME
97           Use the named keyboard shortcut scheme.
98
99       --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
105       --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
111       --separate
112           Use a separate process for this terminal.
113
114       --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
122       --atexit=ACTION
123           What should be done with the tab after the shell command exits.
124           Choose one of: close, hold, respawn, ask.
125
126       --hold
127           An alias for --atexit=hold. Keep the tab open.
128
129       --replace
130           Replace any existing instance as ROXTerm D-BUS service provider.
131
132       --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
137       --session=SESSION
138           Restore the named user session.
139
140       --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
145       -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

SETUP

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
162                   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
167
168       This setup provides a way to map an arbitrary number of profiles onto
169       configuration filenames.
170

TABS

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
176       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
189       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

URI HIGHLIGHTING

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
202       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
207       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
212       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

DRAG AND DROP

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

SESSIONS

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

CONFIGURATION

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

KEYBOARD SHORTCUTS

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
264                   ~/.config/roxterm.sourceforge.net/Shortcuts/Default.
265
266
267       The default keyboard shortcuts are:
268
269                   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
292
293       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

CONFIGURATION MANAGEMENT

297       Run the configuration manager by selecting "Configure..." in ROXTerm's
298       menu or run roxterm-config.
299
300       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
305       Locations for files follow the XDG Base Directory specification.
306
307        1. ${XDG_CONFIG_HOME}/roxterm.sourceforge.net, defaulting to
308           ~/.config/roxterm.sourceforge.net.
309
310        2. ${XDG_CONFIG_DIRS}/roxtem.sourceforge.net, defaulting to
311           /etc/xdg/roxtem.sourceforge.net.
312
313        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
317       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

ADVANCED

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
331                   SetProfile("id", "profile_name")
332
333
334       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
339                   SetColourScheme("id", "scheme_name")
340
341
342       Ask the terminal to use the named colour scheme. Tabs sharing the same
343       window may have different colour schemes from each other.
344
345                   SetShortcutScheme("id", "scheme_name")
346
347
348       Ask the terminal to use the named keyboard shortcut scheme. Tabs
349       sharing the same window must also share the same shortcut scheme.
350
351       Example using dbus-send in a shell script:
352
353                 dbus-send --session /net/sf/roxterm/Options \
354                      net.sf.roxterm.Options.SetColourScheme \
355                      string:$ROXTERM_ID string:GTK
356
357
358       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
365       ·   Full profile name, including a prefix of "Profiles/" or "Colours/"
366
367       ·   Option name
368
369       ·   Value
370
371       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
375                   dbus-send --session /net/sf/roxterm/Options \
376                       net.sf.roxterm.Options.StringOption \
377                       string:Colours/GTK string:background 'string:#ffffff'
378
379
380       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
384                   OptionsChanged("family_name", "profile_name")
385
386
387       where family_name is one of "Profiles", "Colours" or "Shortcuts". For
388       example:
389
390                   dbus-send --session /net/sf/roxterm/Options \
391                       net.sf.roxterm.Options.OptionsChanged \
392                       string:Profiles string:Default
393
394

ENVIRONMENT

396       The following environment variables are set or used by roxterm:
397
398       COLORTERM
399           This is set to "truecolor" by VTE if the window supports 16 million
400           colors.
401
402       EDITOR
403           The name of the editor. Defaults to "gedit", "kate", "gvim",
404           "emacs", whichever appears first in PATH.
405
406       LANG
407           The language of the help URI. This defaults to "en".
408
409       ROXTERM_ID
410           The unique identity of the roxterm D-Bus instance.
411
412       ROXTERM_NUM
413           The number of toplevel windows which are managed by this roxterm
414           process.
415
416       ROXTERM_PID
417           The process identifier of roxterm.
418
419       TERM
420           The name of the terminfo description, which is xterm-256color.
421
422       VTE_VERSION
423           The version number of the VTE library.
424
425       WINDOWID
426           The decimal X Window ID of the toplevel roxterm window. Only
427           supported in an X environment.
428
429       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

SEE ALSO

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

AUTHOR

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
442       On Debian systems, the complete text of the GNU General Public License
443       can be found in /usr/share/common-licenses/GPL.
444

AUTHOR

446       Tony Houghton
447           Developer
448
450       Copyright © 2005-2020 Tony Houghton
451
452
453
454ROXTerm                          01 April 2013                      ROXTERM(1)
Impressum