# Terminal Emulator

&date;
2003 2004 2005 os-cillation

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, with no Front-Cover Texts, and with no Back-Cover Texts. The complete license text is available from the Free Software Foundation.

Benedikt Meurer

    benny@xfce.org

os-cillation System development Software developer
Andrew Conkling

    andrewski@fr.st

This manual describes version &version; of &application;.

## Introduction to &application;

### What is a terminal emulator?

The UNIX operating system was originally designed as a text-only system, controlled by commands entered with a keyboard. This is known as a command-line interface (CLI). The X Window System, Xfce, and other projects have since added a graphical user interface to UNIX, thats what you are actually using now. But the addition of a graphical user interface doesn't mean that the CLI is dead. The CLI is still around and is frequently the easiest, fastest, and most powerful way to perform a certain task. In fact, power users would be lost without the CLI.

&application; is what is known as an X terminal emulator, often referred to as terminal or shell. It provides an equivalent to the old-fashioned text screen on your desktop, but one which can easily share the screen with other graphical applications. Windows users may already be familar with the MS-DOS Prompt utility, which has the analogous function of offering a DOS command-line under Windows, though one should note that the UNIX CLI offer far more power and ease of use than does DOS.

&application; emulates the xterm application developed by the X Consortium. In turn, the xterm application emulates the DEC VT102 terminal and also supports the DEC VT220 escape sequences. An escape sequence is a series of characters that start with the Esc character. &application; accepts all of the escape sequences that the VT102 and VT220 terminals use for functions such as to position the cursor and to clear the screen.

### What makes &application; special?

&application;'s advanced features include a simple configuration interface, the ability to use multiple tabs with terminals within a single window, the possibility to have a pseudo-transparent terminal background, and a compact mode (where both the menubar and the window decorations are hidden) that helps you to save space on your desktop.

The following key features are available:

- Multiple tabs per window
- Customizable toolbars, which can be changed using an integrated graphical toolbar editor
- Ability to configure nearly every aspect of &application; in the Preferences dialog
- Good integration with the Xfce desktop environment in particular, but also with every other Linux desktop
- Session management support
- Real multihead support (both MultiScreen and Xinerama mode)
- Standards compliance (see the freedesktop.org website)
- D-BUS based terminal service facility to minimize the number of processes in the system
- High degree of maintainability by making best use of GTK+ and GObject.

Besides these key features, &application; supports all features you would expect from a modern terminal emulator.

## Getting started

### Starting &application;

The easiest way to start &application; is to use the applications menu of your desktop; for Xfce, point your mouse cursor to the desktop, press the right mouse button and choose System Terminal.

You can also start &application; from a command line or from the Application launcher. Just hit Alt F2, type ``Terminal`` and click the button Run.

### When you first start &application;

When you start &application; for the first time, the application opens a terminal window with default settings.

Example of a default terminal window

The terminal window displays a command prompt where you can type UNIX commands. The command prompt may vary depending on the configuration of your shell. The cursor is positioned at the command prompt. When you type a UNIX command and press Return, the computer executes the command. By default, &application; will use the login shell of the user who starts the application (`/bin/bash` in case of a default Linux installation).

&application; sets the following environment variables for the command running inside the terminal window:

`TERM`

  Set to `xterm` or `xterm-color`, you can configured the value from the preferences dialog.

`COLORTERM`

  Set to `Terminal` by default.

`DISPLAY`

  Set to the X11 display of the terminal by default.

`WINDOWID`

  Set to the X11 window identifier of the terminal by default.

### Working with multiple terminals

&application; provides a tab feature that enables you to open several terminals within a single window. Each terminal is opened in a separate tab. Click on the appropriate tab to display the terminal in the window. Each tabbed terminal in a window is separate subprocess, so you can use each terminal for a different task.

Example of a terminal window with tabs

See for information about how to open a new tabbed terminal.

You can close a terminal tab by clicking on the close button in the terminal tab header or by choosing File Close Tab from the menubar.

## Usage

### To open and close terminals

To open a new terminal window:

  Choose File Open Terminal (or right-click the terminal window and choose Open Terminal).

  The new terminal inherits the working directory from its parent terminal.

To close a terminal window:

  Choose File Close Window.

  This action closes the terminal and terminates any subprocesses that you opened from the terminal. If you close the last terminal window, the &application; application exits.

To add a new tabbed terminal to a window:

  Choose File Open Tab (or right-click the terminal window and choose Open Tab).

  The new terminal inherits the working directory from the previously active terminal.

### To modify a terminal window

To hide the menubar:

  Choose View Show Menubar (or right-click the terminal window and choose Show Menubar).

To show a hidden menubar:

  Right-click the terminal window and choose Show Menubar from the popup menu.

To show or hide the toolbars:

  Choose View Show Toolbars.

To customize the toolbars:

  Be sure to show the toolbars first; then choose Edit Toolbars....

To show or hide the window decorations:

  Choose View Show Window Borders.

To put a terminal window into fullscreen

  Choose View Fullscreen from the menubar (or right-click the terminal window and choose Fullscreen).

To change the appearance of the terminal window:

  See for information about the options that you choose in the Terminal Preferences dialog to change the appearance and behaviour of the terminal windows. For example, you can change the background color or the location of the scrollbar.

### To work with the contents of terminal windows

To scroll through previous commands and output:

  Perform one of the following actions:

  - Use the scrollbar, which is usually displayed on the right side of each terminal window.

  - Press the Shift Page Up, Shift Page Down, Shift Up, Shift Down, Shift Home, or Shift End keys.

  - Use the middle wheel button on your mouse if applicable

  &application; mimics the FreeBSD console when Scroll Lock is pressed. When scroll lock is active, ordinary input and output from the shell is suspended and you can scroll through the history with Shift Page Up and Shift Page Down or using the optional scrollbar. Press Ctrl S to activate the scroll lock and Ctrl Q to disable it afterwards.

  The number of lines that you can scroll back in the terminal window is determined by the Scrollback setting in the General section of the Terminal Preferences dialog.

To select and copy text:

  You can select text in any of the following ways:

  - To select a character at a time, click on the first character that you want to select and drag the mouse to the last character that you want to select.

  - To select a word at a time, double-click on the first word that you want to select and drag the mouse to the last word that you want to select.

  - To select a line at a time, triple-click on the first line that you want to select and drag the mouse to the last line that you want to select.

  These actions select all text between the first and last items. For all text selections, &application; copies the selected text into the clipboard when you release the mouse button. To explicitly copy the selected text, choose Edit Copy.

To paste text into a terminal:

  If you previously copied text to the clipboard, you can paste the text into a terminal by performing one of the following actions:

  - To paste text that you copied by selection only, middle-click at the command prompt. If you do not have a middle mouse button, refer to the X Server documentation for information about how to emulate the middle mouse button.

  - To paste text that you explicitly copied, choose Edit Paste.

To drag a file name into a terminal window:

  You can drag a file name to a terminal from another application such as a file manager or a web browser. The terminal displays the path and the full name of the URI.

To access a hyperlink:

  To access a Uniform Resource Locator (URL) that is displayed in a terminal window, perform the following steps:

  1. Move the mouse over the URL until the URL is underlined.

  2. Right-click on the URL to open the context menu.

  3. Choose Open Link from the context menu to start your preferred Web Browser and display the file located at the URL.

  See about how to configure the preferred Web Browser for Terminal and how to disable this feature.

To compose an email:

  To compose an email to an address that is displayed in a terminal window, perform the following steps:

  1. Move the mouse over the email address until the email address is underlined.

  2. Right-click on the email address to open the context menu.

  3. Choose Compose Email from the context menu to compose an email in your preferred Mail Reader.

  See about how to configure the preferred Mail Reader for Terminal and how to disable this feature.

### To change the terminal title

Set title dialog

To change the title of the currently displayed terminal, perform the following three steps:

1. Choose Terminal Set Title... or double-click the the terminal tab header.

2. Type the new title in the Title text box. &application; applies the change immediately.

3. Click the button Close or press the Return key to close the Set Title dialog.

To reset the terminal title to its default behaviour, perform the same three steps as described above, but enter an empty title.

### To recover your terminal

This section provides some advice if you have problems with terminals.

To reset the state of the terminal:

  Choose Terminal Reset.

To reset the terminal and clear the terminal screen:

  Choose Terminal Reset and Clear.

You can also use the shell commands ``reset`` and ``clear`` to recover your terminal.

### To customize the toolbars

As already mentioned, &application; includes support for customizable toolbars. The toolbars are disabled by default, you will have to explicitly enable it. Choose View Show Toolbars from the menubar to display the toolbars in the current window. If you want to permanently use the toolbars, see .

Once the toolbars are shown, choose Edit Toolbars... from the menubar or right-click one of the toolbars and choose Customize Toolbar... from the context menu. This opens the Toolbar Editor window, which allows you to customize the toolbars in the current terminal window.

Customizing the toolbars

Just drag an item from the Toolbar Editor window and drop it on a toolbar to add that item to the specific toolbar or drag an item from a toolbar to the Toolbar Editor to remove it from the toolbar. You can add additional toolbars by clicking the button Add a new toolbar and remove toolbars by right-clicking the toolbar and selecting Remove Toolbar from the context menu. You can also choose a different style for a toolbar from the context menu.

### To switch between different encodings

&application; itself does not (yet) include builtin support for switching encodings on the fly in a terminal session. But since &application; implements an UTF-8 mode, you can use the Luit application to switch between different character encodings within a terminal session.

## Preferences

Preferences

To configure &application;, choose Edit Preferences... or right-click the terminal area of the window and choose Preferences.... This will bring up the Terminal Preferences dialog, which allows you to adjust &application;'s behaviour to your needs.

### General

General preferences

Initial title

  Use this text box to specify the initial title of terminals. New terminals will have the initial title.

Dynamically-set title

  Use this drop-down list to specify how to handle dynamically-set titles, that is, terminal titles set by the commands that run in the terminal.

Run command as login shell

  Select this option to force &application; to run your shell as a login shell when you open new terminals. See the documentation of your shell for details about differences between running it as interactive shell and running it as login shell.

Update utmp/wtmp records when command is launched

  Select this option to insert a new entry in the utmp and wtmp records when a new terminal is opened.

Scroll on output

  Select this option to enable you to scroll the output on the terminal while the terminal continues to display more output from a command.

Scroll on keystroke

  Select this option to enable you to press any key on the keyboard to scroll down the terminal window to the command prompt. This action only applies if you scrolled up the terminal window and you want to return to the command prompt.

Scrollbar is

  Use this drop-down list to specify the position of the scrollbar in terminal windows.

Scrollback

  Use this spin box to specify the number of lines that you can scroll back using the scrollbar or the mouse wheel. For example, if you specify 1000 you can scroll back the last 1000 lines displayed in the terminal.

### Appearance

Appearance preferences

Font

  Click on the button to select the font type and font size you want to use for the terminal.

  Use the option Enable anti-aliasing for the terminal font to control whether you want &application; to use anti-aliasing when rendering text in the terminals. Disabling this option can impressively speed up terminal rendering performance and reduce the overall system load on slow systems.

  The option Allow bold text controls whether Terminal allows the application running inside to use bold text or not. If disabled, all text will appear in the selected font, else certain text will appear in bold face.

Background

  Select a background for the terminal window. The options are as follows:

  - None (use solid color)

    Select this option to use the background color that is specified in the Colors section as the background color for the terminal.

  - Background image

    Select this option to use an image file as the background for the terminal. Use the Image file entry box to specify the location and name of the image file. Alternatively, click on the button besides the entry box to search for and select the image file.

    Use the Style option to control the appearance of the background image. &application; supports tiling, centering, scaling and strechting background images.

  - Transparent background

    Select this option to use a transparent background for the terminal.

  If you have selected Background image or Transparent background, you can use the slider Shade transparent or image background to shade or dim the background of the terminal.

Display menubar in new windows

  Select this option to show the menubar on new terminal windows by default.

Display toolbars in new windows

  Select this option to show toolbars on new terminal windows by default.

Display borders around new windows

  Select this option to show window decorations on new terminal windows by default.

### Colors

Color preferences

Foreground and Background

  Click on the Text color button to choose the color &application; uses to draw normal text - an application running inside the terminal can also request a different color choosen from the palette below to draw text.

  Click on the Background color button to choose the default background for terminal windows. This color is also used in background tinting when Transparent background or Background image is selected.

Palette

  The terminal provides the application running inside with a palette of 16 colors. You can customize this colors using the 16 color buttons.

### Shortcuts

Shortcut preferences

Shortcut keys

  The Shortcut keys section of the dialog lists the shortcut keys that are defined for each menu item. The shortcut keys enable you to use the keyboard to choose a menu item rather than use the mouse. A shortcut key can be any non-modifier key or any combination of a non-modifier key and several modifier keys, where modifier keys are Alt, Ctrl and the like.

  Compose shortcut

  To change a shortcut key for a menu item, double click the item in the list and press the key combination you want to set. To disable a shortcut for a specific menu item, double click the menu item in the list and click the button Clear.

Disable all menu access keys (such as Alt+f)

  Select this option to disable the access keys that are defined to enable you to use keyboard instead of the mouse to select a menu item. Each access key is identified by an underlined letter on a menu or dialog option. In some cases, you must press the Alt key in combination with the access key to perform the action.

Disable menu shortcut key (F10 by default)

  Select this option to disable the shortcut key that is defined to enable you to access the &application; menus. The default shortcut key to access the menus is F10.

### Advanced

Advanced preferences

Backspace key generates

  Use the drop-down list to select the function that you want the Backspace key to perform.

Delete key generates

  Use the drop-down list to select the function that you want the Delete key to perform.

$TERM setting

  This specifies the value the `$TERM` environment variable is set to, when a new terminal tab or terminal window is opened. The default should be ok for most systems. If you have problems with colors in some applications or if you think that a certain application behaves oddly, try `xterm-color` here.

Reset compatibility options to defaults

  Click this button to reset the options on the Compatibility tabbed section to its defaults settings.

Double click

  Use this text box to specify characters or groups of characters that &application; considers to be words when you select text by word.

## Preferred Applications

As of version 0.2.4, &application; supports opening hyperlinks and composing emails using an external web browser and mail reader. This section describes how to configure which Web Browser and Mail Reader you want to use (see for details how access hyperlinks and compose emails).

Applications

To configure your preferred applications for &application;, choose Edit Applications... from the main menu bar. This will bring up the the Preferred Applications dialog.

Preferred Applications

This dialog allows you to choose your preferred Web Browser, which will be used to open hyperlinks, and your preferred Mail Reader, which will be used to compose emails. Click on the buttons to change the appropriate setting. This will bring up a drop down menu.

Choose preferred application

If you choose Disable this feature from the Web Browser menu, opening hyperlinks from &application; will be disabled. If you choose Disable this feature from the Mail Reader menu, composing emails from &application; will be disabled.

Next in the menu is a list of default applications - automatically detected on your system - you can choose from. Choose Other... in case your preferred application does not show up in the list of default applications or if you want to use specific flags to launch an application. (Use %u to represent the URL when executed, e.g. `browser --newtab %u`.) This will bring up a dialog that lets you enter a custom application.

Choose custom Web Browser

You can either enter the name or the full path of the application's binary, depending on whether the application is installed in the systems search path, or you can press the button labeled Browse... to select the application's binary in a graphical way.

## Advanced topics

### Command line Options

When &application; is started from the command line or from a panel launcher, several options can be specified to modify its behaviour.

`--help`

  List the various command line options supported by &application; and exit

`--version`

  Display version information and exit

`--disable-server`

  Do not register with the D-BUS session message bus

`--execute` ...

  Execute the remainder of the command line inside the terminal

`--command` command

  Execute command inside the terminal

`--working-directory` directory

  Set directory as the working directory for the terminal

`--title` title

  Set title as the initial window title for the terminal

`--display` display

  Open terminal window on the X screen specified by display.

`--geometry` geometry

  Sets the geometry of the last-specified window to geometry. Read ``man` `X`` for more information on how to specify window geometries.

`--role` role

  Sets the window role of the last-specified window to role. Applies to only one window and can be specified once for each window you create from the command line. It is mostly used for session management inside &application;.

`--startup-id` id

  Specifies the startup notification id for the last-specified window. Used internally to forward the startup notification id when using the D-BUS service.

`--fullscreen`

  Set the last-specified window into fullscreen mode; applies to only one window; can be specified once for each window you create from the command line.

`--show-menubar`

  Turn on the menubar for the last-specified window. Can be specified once for each window you create from the command line.

`--hide-menubar`

  Turn on the menubar for the last-specified window. Can be specified once for each window you create from the command line.

`--show-borders`

  Turn on the window decorations for the last-specified window. Applies to only one window. Can be specified once for each window you create from the command line.

`--hide-borders`

  Turn off the window decorations for the last-specified window. Applies to only one window. Can be specified once for each window you create from the command line.

`--show-toolbars`

  Turn on the toolbars for the last-specified window. Applies to only one window. Can be specified once for each window you create from the command line.

`--hide-toolbars`

  Turn off the toolbars for the last-specified window. Applies to only one window. Can be specified once for each window you create from the command line.

`--tab`

  Open a new tab in the last-specified window. More than one of these options can be provided.

`--window`

  Open a new window containing one tab. More than one of these options can be provided.

For example, say you want to open a new terminal window with two tabs in it, where the first tab should run `mutt` and the second tab should run `mc`, and the window should have 80 columns and 40 rows, then you would use the following command to start Terminal:

    Terminal --geometry 80x40 --command mutt --tab --command mc

### Files and Environment Variables

Terminal uses the Basedir Specification as defined on Freedesktop.org to locate its data and configuration files. This means that file locations will be specified as a path relative to the directories described in the specification.

`${XDG_CONFIG_HOME}`

  The first base directory to look for configuration files. By default this is set to `~/.config/`.

`${XDG_CONFIG_DIRS}`

  A colon separated list of base directories that contain configuration data. By default the application will look in `${sysconfdir}/xdg/`. The value of `${sysconfdir}` depends on how the program was build and will often be `/etc/` for binary packages.

`${XDG_DATA_HOME}`

  The root for all user-specific data files. By default this is set to `~/.local/share/`.

`${XDG_DATA_DIRS}`

  A set of preference ordered base directories relative to which data files should be searched in addition to the `${XDG_DATA_HOME}` base directory. The directories should be separated with a color.

`${XDG_CONFIG_DIRS}/Terminal/terminalrc`

  This is the location of the configuration file that includes the preferences which control the look and feel of &application;.

`${XDG_DATA_DIRS}/Terminal/Terminal.ui`

  This is the location of the main user interface description file. It includes the definitions for the main menubar and the right-click menu.

`${XDG_DATA_DIRS}/Terminal/Terminal-toolbars.ui`

  This file includes the user interface definition for the toolbars. If you customize the toolbars using the graphical toolbars editor, &application; will store the new toolbars layout in the file `${XDG_DATA_HOME}/Terminal/Terminal-toolbars.ui`.

### Hidden options

&application; offers a few hidden options to allow powerusers to control various advanced settings and to reduce the number of options in the user interface. To set any of these options, you will have to open the file `${XDG_CONFIG_HOME}/Terminal/terminalrc` in your favourite text editor and edit the section `[Configuration]`; simply create the file if it does not already exist. For example, your `terminalrc` could look like

    [Configuration]
    MiscBell=TRUE
    MiscConfirmClose=FALSE
    MiscCursorBlinks=TRUE
    MiscCycleTabs=TRUE
    MiscTabCloseButtons=TRUE

plus all the options that are controlled through the preferences dialog.

`MiscBell`

  Enables (`MiscBell=TRUE`) or disables (`MiscBell=FALSE`) the audible terminal bell. It is disabled by default.

`MiscConfirmClose`

  Controls whether &application; popups a confirmation dialog when the user tries to close a terminal window with multiple tabs in it. Can be either `TRUE` (the default) or `FALSE`.

`MiscCursorBlinks`

  Enable this option to display a cursor that blinks. Can be either `TRUE` or `FALSE` (the default).

`MiscCycleTabs`

  This option controls whether you can circulate through terminal tabs. That is, whether you are able to go from the last tab to the first tab using the Next Tab button from the Go menu (or the associated keyboard shortcut), and from the first tab to the last tab using the Previous Tab button from the Go menu. The option can be either `TRUE` or `FALSE`.

  This behaviour is disabled by default, because it tends to confuse users.

`MiscTabCloseButtons`

  This setting controls whether &application; provides a close button with the terminal tab title. Can be either `TRUE` (the default) or `FALSE`.

## Frequently asked questions

The intent of this section is to collect the quite numerous frequently asked question that relate to working with &application;, or even terminal emulators in general. If you know of a question thats missing from this page, please file a request.

### &application; complains about `Unable to start terminal server: Unable to connect to D-BUS message daemon`, what can I do?

&application; tries to reduce the number of running instances by establishing a D-BUS service that handles all terminal windows. The message above tells you that &application; wasn't able to connect to the D-BUS session message daemon and register a service. This is just a warning, you can use the terminal without the D-BUS service feature as well.

To start the D-BUS session message daemon when you login to your X session, either modify your xinitrc file and change the line `xfce4-session` to `dbus-launch xfce4-session` or use `dbus-launch startxfce4` to start Xfce instead. If you don't use Xfce, please look at the documentation of your desktop environment on how to enable the D-BUS session daemon.

### Home and End keys don't work in &application;, what's wrong?

This problem is actually a bug in vte, the terminal widget used by &application;. A patch for vte that fixes the problem is available here (this patch was created with version 0.11.11 of vte, it may not work with other versions). Thanks to Auke Kok for this patch.

### How to customize the menus in &application;?

You can customize the main menubar and the right-click popup menu by editing the file `Terminal/Terminal.ui`. Create a copy of this file before you actually start editing it. For example, say you installed Terminal in `/usr/local`, then you would perform the following steps:

    $ mkdir -p ~/.local/share/Terminal
    $ cd ~/.local/share/Terminal
    $ cp /usr/local/share/Terminal/Terminal.ui .

Now you can safely edit the file `~/.local/share/Terminal/Terminal.ui` to customize the menus. See the GtkUIManager documentation for details on the file format. The changes will only be visible in new terminal windows.

If you choose to customize your menus this way, you'll have to take care to sync your customized `Terminal.ui` file when you upgrade to a newer &application; release to keep up with user interface changes and additions.

## Support

To report a bug or to make a suggestion regarding this application or this manual, use the bug tracking system at http://bugs.os-cillation.de/. Remember that useful bug reports are ones that get bugs fixed, so a useful bug report has two qualities:

- Reproducible. If the developer cannot see the bug himself to prove that it exists, he will most probably not be able to fix it at all. Every detail you can provide helps.

- Specific. The quicker the developer can isolate the problem to a specific area, the more likely he will expediently fix it.

In case you want to request a new feature, please make clear why you consider it a worth addition for the application. It is more likely that a new feature gets added if you provide good arguments for the feature. It will increase the chance of addition even more if you provide a patch that implements the requested feature, but make sure that you read the file HACKING - especially the section labeled Coding Style - before you start hacking up the source.

Else, if you have questions about the use or installation of this software, please ask on the os-cillation forum or point your IRC client to irc.freenode.net, join the channel #xfce and ask for help.

## About &application;

&application; was written by Benedikt Meurer (benny@xfce.org). Visit the os-cillation website for more information.

This documentation was written by Benedikt Meurer (benny@xfce.org) and Andrew Conkling (andrewski@fr.st). The lastest version of this document is always available from the Terminal website.

This software is distributed 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.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.