## 5. Matchbox Desktop

The desktop is kept at the very bottom of the window stack. It is provided primarily as an application launcher but can be extended for numerous other uses.

### 5.1. Usage And Configuration

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

`matchbox-desktop [options]`

Options are;

Table 5. Matchbox Desktop command line options

Command Line Switch | Value Type | Description
--- | --- | ---
-display |  | Display to connect to
--bg | str | See below for details
--icon-size | integer | Icon size
--icon-padding | integer | Spacing in pixels between icons
--font | font definition, | Icon font, eg Sans Bold 10 or Sans-10:bold
--titlefont | font definition, | Title font
--fontcol | color definition (#rrggbb) | Font color
--no-outline |  | Text is drawn without outline

The value used to define various background types should follow the following formats.

- img-stretched:[filename]

- img-tiled:[filename]

- img-centered:[filename]

- col-solid:[color definition]

- col-gradient-vertical:[start color],[end color]

- col-gradient-horizontal:[start color],[end color]

a color is specified as a color name or an rgb def in the form 'rgb:r/g/b' or '#RGB

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

### 5.2. Plugin Modules

matchbox-desktop uses dynamically loadable modules to populate itself with entry's.

Matchbox comes with 3 modules. A main application launcher which uses .desktop files, a simple tasks manager and a simple file browser.

What modules are used are set in `(install prefix)/lib/matchbox/mbdesktop_modules` or set per user in `~/.matchbox/mbdesktop_modules`.

Its quite easy to write your own modules. Please refer to the desktop/modules directory for examples.

### 5.3. Adding Icons And Folders

| Note
The following is also true for mb-applet-menu-launcher.

The directory's `(install prefix)/share/applications` and `~/applications` are checked for the existence of 'INI style' .desktop files. A .desktop contains information about a program entry including its name, icon, executable string etc.

A simple example is;

    	  [Desktop Entry]
    	  Name=Figment
    	  Comment=An Outliner
    	  Exec=figment
    	  Icon=figment.png
    	  Type=Application
    	  Categories=Application;Core;

The Icon entry should not specify a path, just the filename of the required image located in `(install prefix)/share/pixmaps`. Locale based entrys can be added by appending a [contry_code] to the required key.

Information for what and how matchbox-desktop should create folders for the above entries is stored in `(install prefix)/share/matchbox/vfolder` and overridden by `~/.matchbox/vfolders/` .

The directory should contain a root.order file, a root.directory file, and optionally a number of other .directory files describing each folder.

The .directory files are just like .desktop files but describe a folder rather than a application. The root.order files specifys which and what order the directory files should be displayed in.

A .directory file should have a 'match' key of which its value is used to compare against .desktop files Categories key value. This decides which folder a .desktop file ends up in. If the match key is set to 'fallback', any Categories that are not matched will end up here.

The fill desktop entry spec can be found at freedesktop.org, also a nice introduction to .desktop files can be found at Suns developer site. Note Matchbox currently supports only the 'core' of the specification.