## GNOME Terminal User's Guide

2000
Miguel de Icaza
Michael Zucchi
Alexander Kirillov

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found here.

Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps.

## Description

&term; is a terminal emulator program that is part of the GNOME project. It provides access to the Unix shell on the GNOME environment.

&term; supports colour display (see for details) and provides mouse support to applications that are aware of mouse events for xterm-like terminals.

## Basic usage

### Shells

&term; starts the default shell (command line interpreter) for the user. Advanced UNIX shells can significantly extend the capabilities of the usual command line prompt. For example, bash shell (which is the default shell for most Linux distributions) provides command completion (try entering beginning of a command or file name and press Tab key), history buffer (you can recall previously entered commands by pressing Up arrow key), and much more. For complete documentation, see the manual pages for appropriate shells.

### Scrolling

&term; provides scrollbar so that you can scroll back and see previous commands and output; this is especially convenient when a command output does not fit in one screen. By default, the scrollbar is placed on the right side of the terminal window. You can change its location or remove the scrollbar altogether using the Preferences dialog.

You can also use keyboard for scrolling: Shift-PgUp scrolls up, Shift-PgDown — down.

### Emulation

The term is designed to emulate the xterm program provided by the X Consortium. The xterm program in turn is an almost-complete emulation of the DEC VT102 terminal.

The GNOME terminal program supports the same extensions to the VT102 that the xterm program provides, through special escape sequences. The xterm program is an evolving program. Recent changes to xterm have been been incorporated into &term;. This includes emulation of the newer DEC VT220 escape sequences.

In simpler terms, this means that GNOME terminal understands all the commands (escape sequences) used by VT102/VT220 terminals for things like positioning of the cursor on screen. Therefore, you can run in &term; any application that is designed to work inside VT102/VT220/xterm terminals and all the controls (such as arrows, PageUp/PageDown keys, Tab key, etc) will work as expected.

## Menus

&term; provides a number of control features accessible via the menus located at the top of the terminal window, and a pop-up menu available by pressing the right mouse button while holding the CTRL key.

### File menu

New terminal

  Create a new terminal window. This is an efficient way to create multiple terminals, as this uses less system resources than starting a separate copy of &term;. (For advanced users: the new terminal window created in this way is owned by the same process, with the same PID as the original terminal. Each window starts its own sub-shell process, however.)

Hide menubar

  Hides the main menubar on the terminal, creating a neater, smaller terminal. The menubar can be retrieved using the pop-up menu.

Close terminal

  Closes the current terminal. It also closes any other terminals opened via the command line in that terminal. If this is the last terminal to be closed, then the &term; program exits.

### Edit menu

Paste

  Pastes the current selection or clipboard into the terminal. This can also be achieved by pressing the middle mouse button.

### Settings menu

Preferences ...

  Displays the Preferences dialogue, described in .

Reset Terminal

  Resets the terminal parameters. This will not clear the screen or move the cursor, but any subsequent terminal output will be reset to the default font and attributes.

Reset and Clear

  Resets the terminal parameters, also clearing the screen. All character fonts and attributes are reset.

Colour selector ...

  Can be used to drag-and-drop colours into the terminal. See for details.

### Help menu

GNOME terminal users guide ...

  How to get to this document from within &term;.

About ...

  A little bit of kudos for all of the very hard working guys who made it all possible.

### Pop-up menu

The pop-up control menu can be invoked by clicking with the right mouse button anywhere in the terminal window with the CTRL key depressed. (It is sometimes not necessary to hold down the CTRL key to get the pop-up menu, but do not assume this is always so.). It is provided as a simple short-cut to some of the commands of the main menus; this is especailly useful when the menubar is hidden. The following items are available:

New terminal ...

  Creates a new terminal window.

Preferences ...

  Displays the Preferences dialogue, described in .

Show menubar

  Checking/unchecking this option shows or hides the menubar at the top of the terminal window.

Secure keyboard

  This option forces all the keyboard input to be sent directly to the terminal, and bypass anything else. This is useful in the (rare) situation when the same X server is used by many users, and the X server is not using proper authentication methods, thus making it possible for other users to snoop on what you are typing. In such a situation, it is advised that you switch to "secure keyboard" mode before entering any confidential information, such as passwords.

Reset terminal

  Resets the terminal attributes (font and background) without clearing the screen.

Reset and Clear

  Resets the terminal attributes and clears the screen.

Open in browser

  If the mouse pointer was over a URL (for example, an Internet address) when the pop-up menu was invoked, then this option is available to launch a browser to view the URL. Using CTRL-left mouse button is a shortcut for this menu item.

## Configurable options

Configurable options are configurable via the preferences dialogue, which can be invoked by selecting Preferences menu item in the Settings menu.

### General options

While most options are self-explanatory, some are discussed below in more detail.

Terminal Class

  Sets the terminal class for the current configuration or terminal. Refer to the section on classes for further information.

Use --login by default

  If this option is selected, &term; will launch the shell in login mode (it will run all of your login initialization scripts in this mode). See also information about `--login` and `--nologin` command line options.

Select-by-word characters

  Defines a list of characters (or character classes) that should be considered 'word characters'. These are used when selecting text by word.

### Background image configuration

In the Image tab, you can set the background image to use for the terminal. Possible choices are

- None — in this case, &term; will use the background color as set in Colors tab

- Background pixmap — this option allows you to choose an image file to be used as background. You can press Browse button to choose the image file.

- Transparent — this option makes &term; use "transparent" background. It is not really transparent: it just mimics the background of your desktop (root window), much like a chameleon does. Do not expect to see other windows through the &term;, though.

For Pixmap and Transparent backgrounds, you can also check the button Shade background, which will "shade", or "dim", the background image.

### Colour configuration

Gnome terminal fully supports the colour extensions used by xterm. Colors tab allows you to control those colours.

Colour scheme

  Some applications are capable of using the colour capabilities of a terminal. The way the interaction between an application and the terminal is set up is that the application can request one of sixteen named colours (ANSI colours), such as "blue" or "bright red": for example, mutt mail reader can use red colour to show urgent messages. However, it is up to the terminal to decide which exact tint to use for "bright red" or "blue". This collection of sixteen colours is called a palette, or "colour scheme".

  &term; supports four colour schemes: the Linux console scheme, the Color Xterm scheme, the rxvt colour scheme, and a completely customizable colour scheme. They all are slightly different: for example, Linux console uses light gray in place of "white", while rxvt uses real white.

  If you have selected the custom option, then all 16 colours (nominally 8 colours and 8 bright colours) can be customized by clicking on the colour selector buttons.

Foreground/Background colours

  Here you can set the default terminal foreground and background colours, which are used when no colours have been requested by the application running inside of &term;.

  The following options are available: white on black, black on white, green on black, black on light yellow, and custom. How these actually appear depends on the palette selected (for the white on black and black on white options). Custom allows you to select the default foreground and background colours individually and separate from the palette.

  Additionally, the user can drag a colour from the rectangular box beneath the colour wheel from any GNOME colour selector or colour source and drop it into the terminal. If the user drops the colour on a blank space, it will set the background, if the user drops the colour on a cell that contains a character, it will change the foreground. This will also automatically change foreground/background type to Custom colours and set the custom foreground or background colour.

### Scrolling

In this tab you can set the position of the scrollbar and the number of lines to keep in memory for scrolling.

## Mouse usage

The mouse can be used to select (copy), and extend-select text, paste text from other terminals or applications, and bring up a menu.

### Selection

The following assumes a standard three-button mouse that has not been made left-handed via the control center. Left-handed mice will of course work, but with the right button instead of the left one, and so on.

The left mouse button can be used to initiate a selection. If the mouse button is clicked once, and dragged, then characters are selected individually. If you drag past the vertical boundaries of the window it will scroll to keep up.

If the left mouse button is double-clicked, then the selection will be by word-characters. Hold the mouse button down on the second click to drag the mouse and enlarge the selection. The word-characters are defined in the General options tab of Preferences dialogue.

Finally, if the left mouse button is triple-clicked and held, whole lines are selected as you drag the mouse up and down.

The right mouse button can be used to extend the selection. Simply scroll to where you wish to extend the selection to, and click the right mouse button in the desired place. Again, single, double and triple clicks will result in by-character, by-word, or by-line selection.

For all cases, releasing the mouse button automatically copies the selected text into the clipboard, so that it may be pasted to other applications. Note that any screen output will clear the highlighting of the selection, but it will still be kept in the clipboard.

### Pasting text

If the middle mouse button is pressed, then the current selection is pasted into the window. This can be used to transfer text from other applications.

If you only have a two-button mouse, then your X server probably has a method of emulating the middle mouse button. The most common method is to emulate the middle mouse button by simultaneous pressing of left and right mouse buttons. Refer to your X server documentation for further information.

### Wheel mouse

If you have a wheel mouse (which sends mouse button 4 and mouse button 5 events), then you can use the wheel to scroll up and down through the scrollback buffer.

### Control Menu

The pointer can also be used to bring up a control-menu, which can be used to reset the terminal or bring back the main menubar, if it has been hidden. To invoke this menu, click anywhere in the terminal with the right mouse button while holding down the CTRL key.

### Launching URL's

Gnome terminal can be used to select URL's (Uniform Resource Locators; most commonly, Internet addresses, such as `http://www.gnome.org`) from the text display, simply by moving the mouse over the URL text. The URL will be highlighted, by being redrawn with an underline, and the mouse pointer will change to a pointing hand.

Invoking the control-menu while over a highlighted URL will add a new option to load that URL into a browser.

Pressing the left mouse button, while holding down the CTRL key is a shortcut to launch the URL immediately.

### Drag and Drop

Drag and drop can be used for a number of operations within the terminal.

Dragging files

  If files are dragged into the terminal, then their full filename is pasted into the window. URL's can also be dropped in this way.

Dragging colours

  A colour can be dragged from another gnome application, or from the colour selector into the display. If it lands on a character, it sets the foreground colour, otherwise it sets the background colour. Refer to the colour configuration section.

## Terminal classes

The GNOME terminal allows you to have different configuration profiles to suit different uses (different background colours, presence, absence or position of scrollbars, and so on). To set these up, invoke the Preferences dialogue from the Settings menu of &term;. Select the options you prefer (these changes will be made to your currently-open terminal, so you can see what they look like), and before closing the preferences box, make sure you have put a new name in the Terminal Class field.

To activate a specific class at program startup you can use the `--tclass` command line option

## Command line options

- `--background COLOUR`

  Used to specify the background colour for the terminal at startup. The COLOUR can be any form accepted by your windowing system.

- `--tclass CLASSNAME`

  Specifies the terminal class used to configure the terminal at startup.

- `--command CMD, -e CMD`

  Runs the CMD command at startup time.

- `--execute CMD ARGS, -x CMD ARGS`

  Executes the command CMD with its arguments ARGS on startup. No arguments beyond this one will be processed by the terminal. This behaviour mimics the `xterm -e` behaviour.

- `--font FONT`

  Sets the font of the terminal to FONT

- `--foreground COLOUR`

  Sets the foreground of the terminal to COLOUR .

- `--geometry GEOMETRY`

  Specifies the startup geometry for this terminal. The geometry specifies the desired width and height in terminal characters. For example: `--geometry=80x40` will create an eighty-column by forty-line terminal. You can also specify the location of the terminal window on the screen; for example, `--geometry=80x40+100+200` will create a window whose top left corner is 100 pixels to the right and 200 pixels down from the top left corner of the screen, while `--geometry=80x40+100-200` will give a window whose bottom left corner is 100 pixels to the right and 200 pixels up from the bootm left corner of the screen.

- `--login`

  Make &term; launch the shell in login mode (it will run all of your login initialization scripts in this mode).

- `--nologin`

  Make &term; only launch a shell, without running any login initialization scripts. This is the default, unless you have selected Use --login by default in the preferences dialog.

- `--noutmp`

  Indicates that this and the associated shell should not be registered in the system database of users logged into the computer.

- `--utmp`

  Indicates that the user wants this terminal to be registered in the system database of users logged into the computer (the utmp database). This is the default.

- `--lastlog`

  Always create a lastlog entry for each terminal login.

- `--nolastlog`

  Do not create a lastlog entry for each terminal login.

- `--title TITLE, -t TITLE`

  Makes &term; use TITLE for the window caption.

- `--termname TERMNAME`

  Makes &term; use TERMNAME as the value of the `TERM` environment variable.

- `--start-factory-server`

  Try to start the TerminalFactory service for this terminal (see below).

- `--use-factory`

  If there is already a terminal process started with `--start-factory-server` option, then running the command `gnome-terminal --use-factory` will create a new terminal window owned by the existing teminal process. In other words, it will have the same effect as choosing File New terminal in the existing terminal.

  If there is no TerminalFactory running, then this option has no effect.

You can use more than one option at once: for example, on a machine with the text-based web browser Lynx installed, `gnome-terminal --title Web --command lynx` will open a &term; which starts up Lynx and has a titlebar which says "Web".

## Environment

The following variables are set by &term;:

- `TERM`

  This variable is set to "xterm" by default. Some curses implementations and applications based on curses might want the value to be xterm-color, color-xterm or xterm-debian to support colour. You might need to change this setting if your application does not display in colour to one of those values. This can now be set via the `--termname` command line option.

- `COLORTERM`

  This variable is set to "gnome-terminal". Various applications (especially the Slang-based applications) use this setting to determine whether the terminal supports colour.

- `WINDOWID`

  This variable contains the X11 Window identifier. This is used sometimes by applications to modify the contents of this window or provide special effects.

## Authors

A large number of people work together to bring you the &term;:

Michael Zucchi coded the Zvt widget engine; Miguel de Icaza and Jay Painter improved it and did further debugging and maintenance. George Lebl added transparency and backing pixmap support to the widget. Michael Zucchi later significantly improved the transparency and pixmap support, adding smoother/faster display and an optional scrolling mode.

Miguel did the main gnome terminal program, and Erik Troan provided the terminal class support along with various other features. Jeff Garzik, Jay, Christopher Blizzard, Michael, Jens Lautenbacher, Tom Tromey, Tristan Tarrant, Jonathan Blandford and Michael Zucchi provided extra bug fixes and minor enhancements. Nat Friedman reviewed the user interface to conform to the GNOME guidelines. Felix Bellaby, Tom Tromey and Manish Vachharajani implemented and improved the session management code.

Please send all comments, suggestions, and bug reports to the GNOME bug tracking database. Instructions for submitting bug reports can be found on-line at http://bugs.gnome.org/Reporting.html. You can also use Bug Report Tool (`bug-buddy`), available in the Utilities submenu of Main Menu, for submitting bug reports.

This manual was written by Miguel de Icaza and Michael Zucchi with minor contributions by Alexander Kirillov. Please send all comments and suggestions regarding this manual to the GNOME Documentation Project by sending an email to docs@gnome.org. You can also add your comments online by using the GNOME Documentation Status Table.

## License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is included as an appendix to the GNOME Users Guide. You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

        Free Software Foundation, Inc.
        59 Temple Place - Suite 330
        Boston, MA 02111-1307
        USA