## 4. Matchbox Panel

The Matchbox panel is a lightweight, always visible application that occupy s a rectangular area of the display. It is intended to hold applets such as application launchers, and simple user information type tools, such as a battery power level monitor or clock.

The panel can supports different orientations and sizes. It conforms to the System Tray Protocol specification for 'docking' applets.

The panel optionally features simple session management to remember what apps are 'parented', and a popup menu to add / remove apps. The popup menu is enabled by clicking and holding on a free area of the panel.

The Matchbox panel is included in the `matchbox-panel` package, which is part of the Matchbox project. A number of simple panel 'applets' are also included. This document describes version 0.9 of the matchbox panel.

Other panels conforming to EWMH specifications such as the GNOME and KDE panels or your own creation can be used with matchbox window manager.

### 4.1. Usage And Configuration

With an X Server running and the DISPLAY environment variable set correctly, run matchbox panel via;

`matchbox-panel [options]`

Options are;

Table 2. Matchbox Panel command line options

Option | Value Type | Description
--- | --- | ---
-display, -d | string - X11 Display name | Specify the X Server for the panel to connect to. Defaults to `DISPLAY` environmental variable.
--id | integer | Specify a unique id for the panel. This is needed if you wish to run multiple panels.
--orientation | north|east|south|west | Specify what edge on the display the panel should be located
--margins | <left/right>[, <top/bottom>] panel applet offsets in pixels | Specify panel margin around applets. Defaults to 2,2
--padding | <int> | Specify spacing between panel applets in pixels
--titlebar |  | Requests the panel is re-parented in the window titlebar. See below for limitations.
--size | size in pixels | Specify the height/width of panel
--no-session, -ns | na | Disable the panels sessioning mechanism
--default-apps, -da | Comma separated list of panel apps or 'none' | Specify a list of apps to be started in order when a session file does not exist. If set to 'none' no default panel apps are started.
--no-menu, -nm | na | Diable the panels popup menu
--overide-bubbles, -o | na | If panel message bubbles are decorated by your chosen window manager, use this option as a workaround
--bgcolor, -c | #rrggbb | Specify a background color for the dock
--bgpixmap, -b | image filename | Specify a tiled background for the panel
--bgtrans, -bt | 'yes'|transparency percentage | Specify the panel 'psuedo' transparency. For this to work you need either matchbox-desktop running, or a program that sets the root window pixmap and exports it Pixmap ID ( matchbox-desktop will set this ).

Its possible for matchbox-panel to be reparented in main application window titlebars with the '--titlebar' switch. For this to work, the Matchbox WM theme.xml file must define an area in the main window frame for the panel via a <panel> tag.

Also in this mode, the switches --size, --orientation, --bgtrans and --use-flip will have no effect.

Some examples of panel usage ;

A transparent 60 pixel wide side panel

`matchbox-panel --size 60 --orientation east --bgtrans yes &`

Running 2 panels at the top and bottom of the display

`matchbox-panel --orientation north & matchbox-panel --id 2 --orientation south &`

An 'embedded titlebar' clock panel with no sessioning and no menu.

`matchbox-panel --titlebar --no-menu --no-session --default-apps minitime &`

The panel is fully themeable and will follow the current window manager theme. Refer to the Matchbox Themeing-Howto for more infomation.

Setting a background option on the command line will override any external theme settings having an effect of the panel background.

### 4.2. Panel Applications

The matchbox-panel package includes a number of simple panel apps. All of which understand the following options;

Table 3. General Panel App command line options

Command Line Switch | Value Type | Description
--- | --- | ---
--display, -d | string | X11 Display to connect to
--offset, -o | integer | Specify the number of pixels to position the app from the trays origin. Note its unlikely many trays will allow free positioning. The matchbox panel uses positive/negative offset values to determine what side of the tray the app is stacked. Negative values will stack the app at the beginning of the panel, anything else will stack from the end.
--no-session, -ns | na | Stops the panel from storing the application in its session file.

Panel applets also honor the `SYSTEM_TRAY_ID` environmental var used to specify the panel ID to dock with.

| Tip
matchbox-panel-manager is a GTK based applications for managing the order of panel applets.

#### 4.2.1. mb-applet-menu-launcher

A menu based application launcher. Reads .desktop files found in `(install prefix)/share/applications/` ( and `~/.applications` ).

The menu structure is defined by .directory files found in `(install prefix)/share/matchbox/vfolders` ( See the section on matchbox-desktop for more info ).

mb-applet-menu-launcher reads theme settings from the theme.desktop file as the panel.

mb-applet-menu-launcher will also participate in single instance / startup notification protocols. Just like the window manager keyboard shortcuts.

| Tip
Menu entrys from Debian style `/usr/lib/menu` entry's will also be used if the `MB_USE_DEB_MENUS` environmental variable is set.

#### 4.2.2. mb-applet-launcher

mb-applet-launcher can be used to create simple panel launchers. Launch via;

`mb-applet-launcher [options..] <xpm|png filename> <command> ]`

or alternatively;

`mb-applet-launcher --desktop <.desktop file>`

Table 4. monolaunch command line options

Command Line Switch | Value Type | Description
--- | --- | ---
--title | str | Set the panel apps title, defaults to command line string.
--kill, -k | na. | Toggle app by destroying, rather than iconizing
--respawn, -l | na. | Launch multiple copies of the command line
--no-animation,-na | na. | Disables launch animation.
--message, -m | na | Capture the output of the command and send it as a message bubble to the dock when the applet is clicked.
--desktop | .desktop filename | Use just this option to create a launcher from an existing .desktop file.

| Tip
mb-applet-launcher can be togeather with matchbox-remote to create window-manager controlling buttons.

#### 4.2.3. mb-applet-clock

A simple clock.

#### 4.2.4. mb-applet-wireless

Monitors the strength of wireless connections.

#### 4.2.5. mb-applet-system-monitor

A memory / cpu usage monitor.

#### 4.2.6. mb-applet-battery

A battery power level monitor - it requires libapm to build.