# Xfce 4 Panel

### Jasper Huijsmans

`<jasper@xfce.org>`

This manual describes `xfce4-panel` version 4.2.0. Last updated: Jan 2005

Copyright © 2004 Jasper Huijsmans

## Introduction

The Xfce 4 panel is part of the Xfce 4 Desktop Environment and features program launchers, panel menus, a clock, a desktop switcher and more. Many aspects of the panel can be configured through graphical dialogs. This manual should provide you with all necessary information on how to adjust the panel to your liking.

## Getting Started

You will usually start the panel as part of your Xfce session, using the `startxfce4` script. The command that will be run for the panel is `xfce4-panel`.

When you start the panel you will see a bar appearing at the bottom of your screen, looking like this:

Figure 1. Default Xfce panel

The figure shows the default panel configuration with one open panel menu. Hovering the mouse over an item will show a tooltip. The Xfce Panel makes extensive use of left and right mouse buttons. Left clicking performs the default action of an item, while right-clicking usually brings up a context menu. Shift + left click may commonly be used instead of a right-click. Note that this manual assumes the use of a right-handed mouse.

There is a move handle on each side of the panel. You can use it to drag the panel anywhere on the edges of the screen. Dragging over half of the screen will move the panel to the opposite screen edge. Clicking with the right mouse button on one of them shows a popup menu ... Go on, try it ;-)

Figure 2. Move handle popup menu

The area between the move handles contains panel items. The available items are are described in the "Panel Items" section. Most items perform an action when clicked. Right-clicking on an item will popup a menu from which you can open a properties dialog, remove the item or add a new item. Items can also be added from the right-click menu on one of the move handles (see above).

Figure 3. Item popup menu

When you want to add an item, a dialog is opened showing all available panel items. Some items can appear only once in the panel, e.g. the system tray, and they will appear greyed out when one is already present.

Figure 4. Add item dialog

Global panel preferences can be changed from the Xfce 4 Settings Manager, which can be started either from a panel launcher, or by running `xfce-settings-show`. See "Panel Preferences" for an explanation of the available options.

## Panel Items

The Xfce 4 panel has the possibility to load external plugins as well as builtin ones. In this section we will only describe panel items that are installed with the panel.

The properties dialog for a panel item can be opened from the right-click menu on the item. Each type of panel item has its own configuration dialog. Every dialog offers at least these options:

- Change the position of the item on the panel.
- Remove the item.
- Close the dialog.

### Launcher

The most common panel item is the launcher item. It allows you to start programs from the panel. The properties dialog offers the following options:

Icon

  The icons used by the panel will follow the icon theme you choose from the user interface settings dialog. Of course you can also choose a custom icon, either by browsing the file system from the button next to the entry or by dragging an image on the preview area from a file manager.

Command

  You can type the command to run or browse the file system. There is an option to start in a terminal and one to use startup notification. This last option means that the window manager can show an hourglass while the program is loading. But, the application has to support it as well. Programs build with Gtk 2.2 should support it.

Tooltip

  The panel item will show this tooltip if you hold the mouse over it.

Menu

  A launcher can have a panel menu attached to it. When this option is selected a small button with an arrow will appear next to the item. Look here for more info on panel menus. The position of the menu button can be changed from the global settings dialog.

Figure 5. Launcher item

### Xfce Clock

The Xfce Clock has a number of options to change the way it looks. There are three clock types available: analog, digital and LED. There is an option to show seconds and for the digital and LED clock types you can choose whether the clock will be in 24 hour mode, 12 hour mode, or 12 hour mode with AM/PM indication. The clock shows the current date as a tooltip. Clicking on the clock will not perform any action.

Figure 6. Clock item

### Mail checker

The mail checker monitors a mailbox for incoming mail. The mailbox can be in mbox or Maildir format.

The mailbox icon will follow your icon theme. You can choose the location of the mailbox, the command to run when you click on the button and the interval between checks. The command has the same options as the launcher item command (see above). You can also choose a command to run when new mail arrives.

Figure 7. Mail checker item

For advanced usage you can also provide a remote POP3 mailbox if you use the following format for the mailbox entry: `pop3://user:password@server:port`. If you omit the port it will default to 110.

Note that this feature is still experimental. Before using it, make sure you have a good network connection, because when the mail check fails it can block the panel.

### Desktop Switcher and Graphical Pager

The panel provides two items that deal with virtual desktops. A CDE-like desktop switcher, that shows buttons with the desktop name and a graphical pager that shows a miniature view of the desktops and even allows you to move windows to another workspace by dragging the mini-window in the pager. The graphical pager also allows you to change workspaces by using the mouse scrollwheel.

For the graphical pager you can set the number of rows to use, or columns when the panel is in vertical mode.

Figure 8. Graphical pager

### System Buttons

A systembuttons item shows one or two buttons which can perform special system actions. The buttons follow your panel icon theme. There are four buttons available:

Lock

  Runs the `xflock4` script that will attempt to lock the screen using either xscreensaver or if that fails xlock.

Exit

  This will popup a logout dialog to end your Xfce session.

Info

  The info button will show the About Xfce 4 dialog.

Setup

  Pressing the setup button will open the Xfce settings manager dialog, from which you have access to the settings for all Xfce components as well as some system settings, such as mouse behaviour and user interface settings.

Figure 9. Systembuttons item

### Separator

This item simply adds a separator line to the panel. It has no options to set except its position.

Note that it may be a bit hard to popup the right-click menu, because you only have a small area to click on.

Figure 10. Item without options

## Panel Menus

Panel launcher items can have a menu associated with it, which can be opened by clicking on the small arrow button next to the item. The actual position of these popup buttons is configurable from the global preferences dialog. You can also open the menu by pressing the launcher button and holding it down. After a short delay the menu will open.

Use the 'Add launcher' item at the top of a panel menu to add a new item or drag an executable to this item from a file manager. To remove items from a panel menu use the 'Remove' button in the properties dialog.

A special feature of panel menus is that they can be detached from the panel and live in their own window. To detach a menu click on the small line at the bottom of the menu (see the screenshot of the default panel).

The properties dialog for a menu item is opened immediately when clicking the right mouse button. The dialog itself is very similar to the dialog for launcher type panel items.

Figure 11. Menu Item

## Panel Preferences

The properties dialog for the Xfce 4 Panel can be opened from the Xfce 4 Settings Manager or from the right-click menu on one of the panel move handles.

Figure 12. Panel Settings

### Appearance

Size

  There are four panel sizes available: small, medium big and huge. Medium is the default.

Orientation

  The Xfce 4 Panel can be set to a vertical orientation as well as the standard horizontal layout.

Popup position

  This option change the position of the buttons that open a panel menu. It can be above, below, to the left or to the right of their associated panel item.

### Behaviour

Autohide

  If you choose autohide, the panel will collapse to a thin bar. Moving the mouse over it will unhide the panel.

## Advanced

### Files and Environment Variables

Xfce now 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 list of system directories that contain configuration data. By default the panel will look in `${sysconfdir}/xdg/` and `/etc/xdg/`. The value of ${sysconfdir} depends on how the program was build and will often be `/etc/` for binary packages.

<basedir>/xfce4/panel/contents.xml

  This is the location of the xml configuration file that describes the contents of the panel, relative to the base directories metioned above.

<basedir>/xfce4/mcs_settings/panel.xml

  This is the relative location of the global panel settings. This file is managed by the settings manager, rather than by the panel itself.

<basedir>/xfce4/kiosk/kioskrc

  Kiosk Mode configuration file. See next section for an explanation.

<basedir>/xfce4/transparency

  Transparency configuration. Further explanation is given in this section below.

None of the configuration files, except `kioskrc` and `transparency`, are designed to be edited by hand; in fact the changes will be overwritten if you edit them while the panel and the settings manager are running.

### Kiosk Mode

The panel now has support for Kiosk Mode, that will prevent users from making changes to their panel configuration. To use it you have to edit or create the file `${sysconfdir}/xdg/xfce4/kiosk/kioskrc`.

The best way to explain the format of this file is by using an example. The xfce4-panel section of your kioskrc might look like this:

    [xfce4-panel]
    CustomizePanel=%powerusers,foo

This allows only users in the group powerusers and the user foo to customize their panels.

### Transparency

Please, note that transparency only works with an X server that supports the Composite extension, like XOrg >= 6.8.0 and the composite extension has been enabled in the configuration file and the window manager supports it (e.g. `xfwm4` has to be compiled with `--enable-compositor`).

By default the panel will be transparent unless the autohide option has been set. When the mouse moves over the panel, the transparency will be temporarily removed.

You can create the file `<basedir>/xfce4/transparency` if you want to change the transparency value for the panel (or the iconbox). Create the file and add a line with the format `panel=<value>`, where value is a number between 0 and 100. Setting it to 0 effectively turns transparency off.

For example, a transparency file may look like this:

    panel=25
    iconbox=0

## About `xfce4-panel`

`xfce4-panel` was written by Jasper Huijsmans (`<jasper@xfce.org>`). To find more information, please visit the Xfce web site.

To report a bug or make a suggestion regarding this application or this manual, use the bug tracking system at http://bugzilla.xfce.org/.

If you have questions about the use or installation of this package, please ask on the xfce mailing list. Development discussion takes place on the xfce4-dev mailing list.

`xfce4-panel` 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.