Matthew Allum OpenedHand Ltd mallum@openedhand.com 2005 OpenedHand Ltd 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. You may obtain a copy of the GNU Free Documentation 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. This is version 1.0 of The Matchbox manual.

The Matchbox project aims to increase X Windows practicality and usability on embedded type hardware by providing a number of interchangeable tools that make up a flexible lightweight base user interface. This includes at its a core a stack based PDA style window manager. Also included is a panel or dock, a PDA style launcher, software input methods and more. This manual outlines the usage of the projects core applications. For newer applications not covered here refer to the individual package's README file or doc directory.

With the creation of Handhelds.org and its communitys work with to make Linux and X Windows run efficiently on iPaq devices it soon became apparent to me, as an avid handhelds.org hacker, that pre existing X11 window managers were a poor fit on a device with such low resources, a small 240x320 display and very limited input mechanisms ( no keyboard, touchscreen ). To improve on this situation, Matchbox window manager was born. The plan was to leverage the huge amount of existing X11 applications and toolkits and attempt to make them usable on such a device with little or no modification. This would also make embedded application development more familiar and easier for existing desktop orientated developers. As the project grew, more features were added to the window manager, and where practical, more support for other desktop standards and protocols ( see freedesktop.org ) were added as well as new supporting applications such as the matchbox panel and desktop. Nowadays matchbox is used on a wide range of non desktop type embedded devices. Matchbox's build and run time flexibility allow it to be tailored to a target platforms resources, feature requirements and physical form.

The Matchbox window manager is responsible for managing X11 client window geometry and stacking order, as well as providing decorations and controls to the window borders. Matchbox's style of management is restrictive in nature, setting application windows with a maximized static geometry in a browsable stack or deck with only one application being visible at any time. Different, though applicable, rules apply to other window types such as dialogs, panels and input method windows. The design is such as to make application management on platforms with small displays and limited input mechanisms more useable. Through standardized client window property hints, themeing and both runtime and build time options, matchbox-window-manager provides much flexibility for tailoring to a particular embedded UI style both in look and feel. Matchbox window manager is included in the matchbox-window-manager package, which is part of the Matchbox project. This document describes version 1.0 of Matchbox window manager. The window manager is the matchbox project's most developed and core application.

With an X Server running and the DISPLAY environment variable set correctly, run matchbox window manager via; matchbox-window-manager [options] Matchbox window manager supports optional configuration via command line options and/or X Resource settings ( if X Resource support is disabled at build time this will not work. ). For general usage one should not need to set any command line options. X Resources are usually set options per user in ~/.Xdefaults and globally in (install prefix)/share/matchbox/defaults. Command line options take precedence over both of these. Options, are; -display <string> Specify the X Server for matchbox to connect to. Defaults to DISPLAY environment variable. -theme <string> Specify the theme name to use, describing the window managers' look and feel'. The directory's; ~/.theme/[theme name]/matchbox and (install prefix)/share/themes/[themename]/matchbox will be checked for a valid theme.xml file. If the file is not found or invalid, matchbox will revert to its default theme ( (install prefix)/share/themes/Default/matchbox ) Themeing will not be available if matchbox is compiled with the --enable-standalone option. The corresponding X Resource key is matchbox.theme . -use_titlebar <yes|no> Specify whether if application windows have title bar decorations. Defaults to yes. This option is useful if you are running Matchbox on platforms where you intend to run just one application, or you want all applications to run 'full screen' - a set-top box style environment for example. Dialog windows will however be decorated. The corresponding X Resource key is matchbox.titlebar . -use_lowlight <yes|no> Enables an effect to make modal dialog windows 'super' modal. All other windows are low-lighted out. This option is EXPERIMENTAL and alway active in a composite enabled build. Dialog windows must specify they are modal for this option to work. The low-lighted color is specified by the current theme.xml file. The corresponding X Resource key is matchbox.lowlight . -use_dialog_mode <free|const|const-horiz> Decides the strategy the window manager uses to position and resize dialogs. By default, dialogs will be restrained to fit on the display not covering any panels or input/toolbar windows. free, will remove any window manager intervention. static, the user cannot change dialog position or stacking order. const-horiz is like the 'const' option but will make all dialogs the full screen width and allow movement only in the vertical. The corresponding X Resource key is matchbox.dialog . -use_desktop_mode <decorated|plain> Decides if desktop' windows ( such as Nautilus or matchbox-desktop ) are decorated or 'fullscreen'. Defaults to plain. The corresponding X Resource key is matchbox.desktop . -use_cursor <yes|now> If enabled, an attempt is made to hide the mouse cursor completely. This can be overridden by applications such as xterms. This option will likely be depreciated in future releases, as it does not provide a 100% solution. An improved way of providing this effect is to use libXcursor with a 'blank' ( eg all cursors are fully alpha ) theme. See . The corresponding X Resource key is matchbox.cursor . -use_super_modal <yes|now> If enabled, dialog windows setting there modal hint are made 'super' modal, in that when active all other user window interaction is blocked. This option should be considered experimental and likely to change. The corresponding X Resource key is matchbox.supermodal . -force-dialogs <comma separated name list> Specify a comma separated list of window titles, whose windows when matched are forced to be treated as dialogs rather than application windows. It is advised not to use this option, but adapt the required application to set the correct windows hints. The corresponding X Resource key is matchbox.forcedialogs . --sm-client-id <session manager client ID> Specify the session manager client ID. Only used if built with session manager support. The corresponding X Resource key is matchbox.session . -help Display a brief help message and build configuration details. Matchbox window manager also uses environment variables for advanced usage. These are MB_SYNC If set all X11 communication will be synchronous, only used for debugging. MB_HUNG_APP_HANDLER Specify the full path to a binary to be optionally called to handle a 'hung' application. It will be the passed both the process ID and window ID of the hung application.

The window manager is fully theme-able. Themeing is configured by simple XML files found in (install prefix)/share/themes/[selected theme name]/matchbox . See the 'blondie' theme.xml file for details on the format or read the Matchbox Themeing-Howto. As well as being selected on startup, themes can be changed 'on the fly;. There are various ways to do this. The easiest way is to use matchbox-remote to change the current theme; matchbox-remote -t <theme name> Alternatively if you compiled with XSettings support, you will be able to use the Gnome2 / GPE / KDE3 desktop configuration tools to change the theme. The XSettings key used is Net/ThemeName. Using XSettings allows the window manager theme to change with the toolkit theme. The Window Manager distribution tarball contains three themes: Default - a rather plain and simple default theme, blondie - a bells and whistles PNG based theme for PDA's, MBOpus - a theme for larger displays.

The window manager has redefinable shortcut keys which can be used to perform window operations or launch applications. The location of the config file is (install prefix)/share/matchbox/kbdconfig , this can be overridden by the user having a ~/.matchbox/kdbconfig file. The config file is made up of one definition per line each in the format <keys definition>=<action> 'Keys Definition' consists of an optional series of modifier keys in angle brackets followed by the actual key symbol. Action can be one of next, prev, close, taskmenu, hidetitle, fullscreen and desktop for various window operations. The action can be prefixed with special characters to launch applications. Prefixes are; ! Launch application with just a standard fork-exec. !! Launch application with 'startup-notification' - provides feedback of application startup cycle. Application must support startup notification ( eg uses GTK 2.2 or above ) !$ Launch or raise preexisting application, keeping just a single instance running. [1] For example <ctrl><alt>p=prev Binds the combination of alt, ctrl and p to show the previous window. <ctrl>x=!xterm Binds the combination of ctrl x to launch an xterm. See the installed kbdconfig file for more examples. The matchbox window manager can be configured to use gconf to store keyboard shortcuts - the kbdconfig file will then be ignored. The advantage of using gconf is the shortcuts can be changed on the fly without requiring a restart of the window manager. The 'action' syntax is the same as above. You should use gconftool or gconf-editor to set documented keys under /apps/matchbox.

A very simple shell script to start Matchbox window manager, desktop and panel ( if available ). Run as part of your X startup scripts ( eg. ~/.xinitrc or from the command line via; matchbox-session The file will check for in order and exec ~/.matchbox/session and /etc/matchbox/session if they exist. If they don't exist sensible defaults will be run. The reasoning behind this file is that distributions containing Matchbox can easily tailor startup options ( by supplying a /etc/matchbox/session ) for their platform. Matchbox window manager can be built with basic 'real' X11 session manager support. If so, this should be used instead of the matchbox-session mechanism.

A command line tool to externally control Matchbox. Launch via; matchbox-remote [options] options are; Option Value Type Description -theme Theme name switch Matchbox theme -r na. Print current Matchbox theme to stdout -exit na. Request Matchbox window manager to exit -next na. Request Matchbox window manager to 'page' to next window -prev na. Request Matchbox window manager to 'page' to previous window -desktop na. Request Matchbox window manager to toggle desktop visibility -mbmenu na. activate mb-applet-menu-launcher ( if running ) -input-toggle 1|0 Toggles selected input method active via mb-input-manager ( if running ) -composite-toggle na. Toggles compositing on/off. ( if matchbox-window-manager is built with composite support )

This section is intended for application authors who want to better integrate there applications with matchbox window manager rather than being for general users Matchbox window manager uses the EWMH hints and tranciency to identify how a window should be managed and stacked. TO COMPLETE

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.

With an X Server running and the DISPLAY environment variable set correctly, run matchbox panel via; matchbox-panel [options] Options are; 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.

The matchbox-panel package includes a number of simple panel apps. All of which understand the following 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. matchbox-panel-manager is a GTK based applications for managing the order of panel applets.

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. Menu entrys from Debian style /usr/lib/menu entry's will also be used if the MB_USE_DEB_MENUS environmental variable is set.

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> 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. mb-applet-launcher can be togeather with matchbox-remote to create window-manager controlling buttons.

A simple clock.

Monitors the strength of wireless connections.

A memory / cpu usage monitor.

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

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.

With an X Server running and the DISPLAY environment variable set correctly, run matchbox desktop via; matchbox-desktop [options] Options are; 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.

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.

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.

For further help please visit the Matchbox Project Web page, subscribe to the mailing list or pop into the #matchbox IRC channel on freenode. Please send feature requests and bug reports to the Matchbox bug tracking database. For paid support, consulting and custom development please visit OpenedHand.

Matchbox was primarily written by Matthew Allum. See individual package AUTHORS files for other contributors. (mallum@openedhand.com). To find more information about Matchbox, please visit the Matchbox Project Web page. This manual was written by Matthew Allum (mallum@openedhand.com). Please send all comments and suggestions regarding this manual to Matthew or report them in the bug tracker.

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

Firstly its recommended if your not used to building software from source, you should check your distribution for pre built binary matchbox packages. All Matchbox packages use GNU autotools and are configured and build by the usual; % ./configure % make % sudo make install You can see the various compile time options for enabling extra features and dependencies by running. % ./configure --help

Virtually all packages are dependant on libmatchbox. You should build and install libmatchbox first. All font and image operations are provided to other matchbx packages via libmatchbox. Therefore the configure options you choose here ( such as Pango, JPEG support ) will affect dependant packages. Matchbox-window-manager can be built without libmatchbox using the --enable-standalone options. It is highly recommeded you only do this is you intend to run only the window manager with no bells and whistles such as themeing. This build option is intended mainly for platforms where resources are very low or you want a quick and dependency free window manager for testing on a new platform. If you decide to install the matchbox-panel or matchbox-desktop packages you should install the matchbox-common package first. It contains icons and launcher configuration data shared by both the desktop and the panel menu launcher. If you encounter problems building, please report to the mailing list for help.

An automated build script is available to ease the build process. This will build a fully featured matchbox environment including the window manager, desktop, panel and panel applications. Download matchbox-autobuild.sh script. Open in your favorite text editor, edit the variables at the top of the top and then run.

If you plan on building from SVN, then before you build; autoconf --version must report 2.5 or later automake --version must report 1.7.x libtool --version must report 1.5 (available from http://ftp.club.cc.cmu.edu/\pub/gnu/libtool/libtool-1.5.tar.gz if your distribution doesn't have it) pkg-config --version must report 0.9.0 or later You will also need GConf2 Development packages and Check installed ( These are only needed if building from SVN, optional if building from release tarballs ).