Matchbox 0.5 Documentation (DRAFT)

Matthew Allum

Copyright  2003 Openedhand Ltd

-------------------------------------------------------------------------------

Table of Contents
1. Introduction
   
    1.1. Full feature list
   
2. Building Matchbox
   
    2.1. Configure Options
    2.2. Build examples
    2.3. CVS
   
3. Running Matchbox
4. Matchbox Window Manager
   
    4.1. Usage And Configuration
    4.2. Themes
    4.3. Shortcut keys
   
5. Matchbox Panel
   
    5.1. Usage And Configuration
    5.2. Panel Applications
       
        5.2.1. mbmenu
        5.2.2. monolaunch
        5.2.3. minitime
        5.2.4. minivol
        5.2.5. miniwave
        5.2.6. minisys
        5.2.7. miniapm
       
6. Matchbox Desktop
   
    6.1. Usage And Configuration
   
7. Other binaries
   
    7.1. LibMB
    7.2. mbcontrol
   
8. License
9. Credits

1. Introduction

Matchbox is a suite of tools for the user management of X11 applications.
Typically designed to be used on computers with little screen real estate,
limited input devices and low cpu/storage resources. PDA's, for example, fit
well into this category. 

 Matchbox consists of 5 main components - A window manager, A panel, a desktop,
a shared utility library, and a number of small panel applications. As well as
all working well together, they are also designed to work independantly of each
other. They adhere to freedesktop.org standards and they can be mixed and
matched with components from other supporting desktop enviroments ( such as
KDE3 and Gnome2 ). 

 Matchbox's core application is a window manager, which restrictive in nature,
maximizes application windows to all available display space, allowing just a
single one visible at anytime. The user navigates applications by paging
through them as if they were a stack of cards. 

 The panel provides a home for application launchers ( such as mbmenu and
monolaunch ) and basic monitoring / notification tools that provide infomation
such as battery power levels ( miniapm ). A number of panel apps are included
with the distrobution. 

 The desktop provides primarily an application launcher and task switcher. 

 All programs ( optional for Window Manager ) use libMB, an included shared
library which provides common functionailty such as image manipulation, panel
docking and other shared utility code. 

-------------------------------------------------------------------------------

1.1. Full feature list

  * Small, fast and light ( WM can be as little as 50k )
  * Numerous compile time features
  * Optionally dependant only on xlib
  * No GUI toolkit depencies
  * Fully Themeable
  * Keyboard shortcut support
  * Optional GPE / Gnome2 / KDE 3 integration
  * freedesktop.org standards support
   
      + NETWM window hints.
      + SYSTEM TRAY and XEMBED ( panel ).
      + XSETTINGS.
      + Startup Notification.
      + Icon spec support.
      + .desktop / vfolders.
   
  * XRandR aware.
  * Xft1 / Xft2 ( anti-alised text support )
  * PNG support
  * WM can compiled to be standalone, requiring no external files.
  * UTF8 support.
  * Dnotify support ( Linux only ).

-------------------------------------------------------------------------------

2. Building Matchbox

 Matchbox 0.5 brings many new features which are directed at build time. This
allows for fine grained control over base binary size and dependencies. 

matchbox uses GNU autotools, so building it should be straightforward:
        $./configure [options - see below]
        $make
        # This next step might require root access
        $make install
See the INSTALL file for standard details regarding autoconf. 

 Matchbox's configure script does little auto detection of librarys. The main
reason for this is not hamper cross compiling.  

 There is also an 'ipkg' make target which build an ipkg package of the built
binarys etc, suitable for use with embedded distrobutions which use this format
( familiar, OpenZaurus ). 

-------------------------------------------------------------------------------

2.1. Configure Options

  --enable-xft 

Xft is a X11 client side API for rendering high quality anti-aliased fonts. Xft
is included with XFree86 4.x and can also be downloaded from http://
www.fontconfig.org. Please insure once installed that 'xft-config' is in your
path and that you have some ttf fonts installed on your target system. 

  There are 2 versions of xft available, matchbox should compile happily with
either, though it is recommended you use xft2 if at all possible. 

  Building with xft also enables support for UTF8 text.  

  It is *recommended* you enable this. 

  --enable-png 

  Enables support for 'portable network graphics' compressed image format.
PNGS's have an alpha channel, so things will look visually more impressive if
you turn this on, though memory usage and cpu requirements will be slightly
increased.  

  It is *recommended* you enable this. 

  --enable-dnotify 

  Dnotify is a Linux only 2.4.x kernel feature that allows for apps to get
signaled when a requested directory or file is changed. 

  The app launcher menu and desktop use this feature. The additional code is
very small. 

  --enable-expat  

  Matchbox has its own very simple internal XML parser for it's theme files.
Selecting this option, it will use the more featured Expat library instead.  

  With expat you will get support for UTF8 theme files and more verbose error
messages.  

  Worth enabling if you are using xft and that is dependent on expat anyway. 

  --enable-libsn  

  This allows matchbox, mbmenu, mbdesktop to participate in 'startup
notification'. This gives you a busy cursor for toolkits that support startup
notification ( GTK2.2 ) , and solid 'single instance application' support. 

  You can get the library from; http://www.freedesktop.org/software/ 

  --disable-keyboard 

  Disables support for keyboard shortcuts. Saves a few bytes.  

  --enable-standalone  

  Builds matchbox window manager as a standalone binary, requiring no external
files ( i.e. theme config files. ). Useful for testing as you can just run the
matchbox binary without having to install anything else. 

  This option will disable themeing, but reduce the final binary size if the
window manager quite considerably.  

--enable-debug  

  Builds matchbox with gdb debugger support and enables debug messages on
stdout. 

--enable-xsettings  

  Enables use of XSettings, a protocol for simple config settings. You can grab
the lib from http://handhelds.org/~mallum/downloadables/
Xsettings-client-0.10.tar.gz . Matchbox uses the XSettings Net/ThemeName key to
set the current theme. Also see http://www.freedesktop.org/standards/
xsettings.html. 

-------------------------------------------------------------------------------

2.2. Build examples

  Build a fully featured matchbox;  

  ./configure --enable-xft --enable-png --enable-dnotify \ --enable-expat
--enable-libsn --enable-xsettings

  Build a tiny 'plain' matchbox. 

  ./configure --enable-standalone --disable-keyboard  

-------------------------------------------------------------------------------

2.3. CVS

If you are building from CVS, you will need automake 1.4, autoconf, aclocal 1.4
and libtool.

Before running ./configure, be sure to run ./autoconfigure.sh.

Some things to remember when building CVS;

  * All configure option combinations may not work. Check the source of
    'buildarm.sh' to see what options I'm currently using to build snapshot
    ipkgs - these are probably safe.
  * Remember its development code and bad things may happen.

-------------------------------------------------------------------------------

3. Running Matchbox

Add something like the following to your .xinitrc / .xsession files;

mbdesktop &
mbstart --orientation south &
exec matchbox
and restart X Windows.

Alternatively, if you are running a desktop enviroment such as GNOME, run the
following command before starting X windows ( you may need to add it to ~
/.profile )
export WINDOW_MANAGER=/usr/bin/matchbox

-------------------------------------------------------------------------------

4. Matchbox Window Manager

Matchbox manages windows in a restrictive PDA style way where applications are
arranged in a stack with only one visible at any time. Application dialog
windows are kept on the stack with there parents.

Matchbox also supports other 'non-applcation' window types such as panels,
desktops and toolbar windows.

As well as being useful for handheld devices, the window manager should also be
of use on platforms such as kiosks, or media/settop box's where only basic
window management is needed.

-------------------------------------------------------------------------------

4.1. Usage And Configuration

matchbox [options]
Matchbox supports optional configuration via command line options and/or X
Resource settings.

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;

Table 1. Matchbox options

+---------------------------------------------------------------------------------+
|Command Line |XResource Key    |Value |Description                               |
|Switch       |                 |Type  |                                          |
|-------------+-----------------+------+------------------------------------------|
|-display     |matchbox.display |string|Specify the X Server for matchbox to      |
|             |                 |      |connect to. Defaults to $DISPLAY          |
|             |                 |      |environmental variable.                   |
|-------------+-----------------+------+------------------------------------------|
|-theme       |matchbox.theme   |string|Specify the theme name to use. The        |
|             |                 |      |directorys;                               |
|             |                 |      |                                          |
|             |                 |      |~/.theme/[theme name]/matchbox            |
|             |                 |      |$PREFIX/share/themes/[theme name]/matchbox|
|             |                 |      |                                          |
|             |                 |      |will be checked for a valid theme.xml     |
|             |                 |      |file. If the file is not found or invalid,|
|             |                 |      |matchbox will revert to its defualt theme.|
|             |                 |      |                                          |
|             |                 |      |This option will not work if matchbox is  |
|             |                 |      |compiled with the --enable-standalone     |
|             |                 |      |option.                                   |
|-------------+-----------------+------+------------------------------------------|
|-use_titlebar|matchbox.titlebar|yes|no|Specify whether or not the main windows   |
|             |                 |      |have titlebars. Defaults to yes.          |
|             |                 |      |                                          |
|             |                 |      |This option is useful if your running     |
|             |                 |      |matchbox on platforms where you intend to |
|             |                 |      |run just one application, or you want all |
|             |                 |      |applications to run 'full screen'.        |
|             |                 |      |                                          |
|             |                 |      |The advantage of this, rather than running|
|             |                 |      |no window manager is that dialog windows  |
|             |                 |      |still get decorations and you do actually |
|             |                 |      |have some window management. Remember you |
|             |                 |      |can use keyboard shortcuts to navigate    |
|             |                 |      |applications.                             |
|-------------+-----------------+------+------------------------------------------|
|-use_lowlight|matchbox.lowlight|yes|no|Enables an effect to make modal dialog    |
|             |                 |      |windows 'super' modal. All other windows  |
|             |                 |      |are lowlighted out.                       |
|             |                 |      |                                          |
|             |                 |      |Dialog windows must specify they are modal|
|             |                 |      |for this option to work.                  |
|-------------+-----------------+------+------------------------------------------|
|-use_cursor  |matchbox.cursor  |yes|no|If enabled, matchbox attempts to hide the |
|             |                 |      |mouse cursor completely. This can be      |
|             |                 |      |overidden by applications such as xterms. |
|-------------+-----------------+------+------------------------------------------|
|-help        |n/a              |n/a   |Display a brief help message and build    |
|             |                 |      |details.                                  |
+---------------------------------------------------------------------------------+

-------------------------------------------------------------------------------

4.2. Themes

The window manager is fully themeable. Themeing is configured by simple xml
files found in; $PREFIX/share/themes/[selected theme name]/matchbox See the
'blondie' theme.xml file for details on the format. It is fully commented.  

As well as being selected on startup, themes can be changed on the fly. There
are various ways to do this.

If you compiled matchbox without libxsettings support, use mbcontrol to change
the current theme.

mbcontrol -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 matchbox distribution tarball contains three themes: blondie - a bells and
whistles png based theme for PDA's, bluebox - an xpm based theme and gorilla -
a theme for larger displays.

-------------------------------------------------------------------------------

4.3. Shortcut keys

Matchbox Has defineable shortcut keys which can be used to perform window
operations or launch applications. The location of the config file is PREFIX/
share/matchbox/kbdconfig , this can be overridden by the user have a
.mbkdbconfig file in there home directory.

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 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' [1] - You get a busy
    cursor during startup
  * !$ 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.

[1] - Application must support startup notification ( eg use gtk 2.2 toolkit )

-------------------------------------------------------------------------------

5. Matchbox Panel

The matchbox panel is a small, always visibile, area of the display which holds
application launchers, or simple user infomation type tools, such as a battery
power level monitor.

It features simple session management to record what apps are 'parented', and a
popup menu to add / remove apps. Both of these options can be disabled.

-------------------------------------------------------------------------------

5.1. Usage And Configuration

mbdock [options]

Table 2. Matchbox Panel command line options

+-----------------------------------------------------------------------------+
|Command Line      |Value Type      |Description                              |
|Switch            |                |                                         |
|------------------+----------------+-----------------------------------------|
|-display, -d      |string - X11    |Specify the X Server for the panel to    |
|                  |Display name    |connect to. Defaults to $DISPLAY         |
|                  |                |environmental variable.                  |
|------------------+----------------+-----------------------------------------|
|-geometry, -g     |string - X11    |specify the position and size of the     |
|                  |geometry spec   |panel.                                   |
|------------------+----------------+-----------------------------------------|
|--id              |integer         |Specify a unique id for the panel. This  |
|                  |                |is needed if you wish to run multiple    |
|                  |                |panels.                                  |
|------------------+----------------+-----------------------------------------|
|--orientation     |north|east|south|Specify where on the display the panel   |
|                  ||west           |should be located                        |
|------------------+----------------+-----------------------------------------|
|--no-session, -ns |na              |Disable the panels sessioning mechanism  |
|------------------+----------------+-----------------------------------------|
|--no-menu, -nm    |na              |Diable the panels popup menu             |
|------------------+----------------+-----------------------------------------|
|--overide-bubbles,|na              |If panel message bubbles are decorated by|
|-o                |                |the window manager ( not matchbox ),     |
|                  |                |provide this option                      |
|------------------+----------------+-----------------------------------------|
|--bgcolor, -c     |#rrggbb         |Specify a background color for the dock  |
|------------------+----------------+-----------------------------------------|
|--bgpixmap, -b    |image filename (|Specify a tiled background for the panel |
|                  |xpm | png - if  |                                         |
|                  |png support     |                                         |
|                  |compiled in )   |                                         |
|------------------+----------------+-----------------------------------------|
|--bgtrans, -bt    |'yes'|          |Specify the panel transparency. For this |
|                  |transparency    |to work you need either mbdesktop        |
|                  |percentage      |running, or a program that sets the root |
|                  |                |window pixmap and exports it Pixmap ID ( |
|                  |                |esetroot is an example of this ).        |
+-----------------------------------------------------------------------------+

The panel will get it's theme setting for the current set themes theme.desktop
file. See the blondie themes file for infomation on setable parameters.

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

-------------------------------------------------------------------------------

5.2. Panel Applications

5.2.1. mbmenu

A menu based application launcher. Reads entrys from debian style /usr/lib/menu
entrys and .desktop files found in $PREFIX/share/applications/ .

mbmenu reads theme settings from the theme.desktop file as the panel.

mbmenu will also participate in single instance / startup notification
protocols. Just like the keyboard shortcuts.

-------------------------------------------------------------------------------

5.2.2. monolaunch

monolaunch can be used to create simple panel launchers.
monolaunch [options..] [ [ <xpm|png filename> <command> ] [ --desktop <.desktop file> ]

Table 3. monolaunch command line options

+-----------------------------------------------------------------------------+
|Command Line    |Value    |Description                                       |
|Switch          |Type     |                                                  |
|----------------+---------+--------------------------------------------------|
|-display        |         |Display to connect to                             |
|----------------+---------+--------------------------------------------------|
|--title         |str      |Set the panel apps title, defaults to command line|
|                |         |string.                                           |
|----------------+---------+--------------------------------------------------|
|-icon-dimention,|integer  |Set maximum size of panel icon                    |
|-i              |         |                                                  |
|----------------+---------+--------------------------------------------------|
|--kill, -k      |na.      |Toggle app by destroying, rather than iconizing   |
|----------------+---------+--------------------------------------------------|
|--respawn, -l   |na.      |Launch multiple copies of the command line        |
|----------------+---------+--------------------------------------------------|
|--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 |Alternate folder icon                             |
|                |filename |                                                  |
+-----------------------------------------------------------------------------+

Examples

-------------------------------------------------------------------------------

5.2.3. minitime

A simple clock. Run with -h to see simple options available.  
-------------------------------------------------------------------------------

5.2.4. minivol

A volume control. Takes only a -display option.  
-------------------------------------------------------------------------------

5.2.5. miniwave

Monitors the strength of wireless connections. Takes only a -display option.  
-------------------------------------------------------------------------------

5.2.6. minisys

A memory / cpu usage monitor. Takes only a -display option.  
-------------------------------------------------------------------------------

5.2.7. miniapm

A bettery power level monitor - it requires libapm to build. Takes only a
-display option.  
-------------------------------------------------------------------------------

6. Matchbox Desktop

The desktop is kept at the very bottom of the window stack. It is provided as
an application launcher and task switcher.

Mbdesktop should be considered alpha software. It is still in it's early stages
but is useable.

-------------------------------------------------------------------------------

6.1. Usage And Configuration

mbdesktop [options]

Table 4. Matchbox Desktop command line options

+-----------------------------------------------------------------------------+
|Command Line|Value Type     |Description                                     |
|Switch      |               |                                                |
|------------+---------------+------------------------------------------------|
|-display    |               |Display to connect to                           |
|------------+---------------+------------------------------------------------|
|--bg        |str            |The value can be used to define various         |
|            |               |background types in 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]                                      |
|------------+---------------+------------------------------------------------|
|--iconsize  |integer        |Icon size ( defaults to 32 )                    |
|------------+---------------+------------------------------------------------|
|--font      |font definition|Icon font                                       |
|------------+---------------+------------------------------------------------|
|--titlefont |font definition|Title font                                      |
|------------+---------------+------------------------------------------------|
|--fontcol   |color          |Font color                                      |
|            |definition (#  |                                                |
|            |rrggbb)        |                                                |
|------------+---------------+------------------------------------------------|
|--folderimg |img filename   |Alternate folder icon                           |
|------------+---------------+------------------------------------------------|
|--desktopdir|path           |Path to .desktop files ( default: $PREFIX/share/|
|            |               |applications )                                  |
|------------+---------------+------------------------------------------------|
|--pixmapsdir|path           |Path to .desktop file pixmpas ( default: $PREFIX|
|            |               |/share/pixmaps )                                |
+-----------------------------------------------------------------------------+
-------------------------------------------------------------------------------

7. Other binaries

-------------------------------------------------------------------------------

7.1. LibMB

  * Shared code for numerous aplications.
  * Current interface should be considered in progress.
  * Documentation coming soon.

-------------------------------------------------------------------------------

7.2. mbcontrol

A command line tool to externally control matchbox.

+-----------------------------------------------------------------------------+
|Command Line    |Value   |Description                                        |
|Switch          |Type    |                                                   |
|----------------+--------+---------------------------------------------------|
|-theme          |Theme   |switch matchbox theme                              |
|                |name    |                                                   |
|----------------+--------+---------------------------------------------------|
|-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 mbmenu ( if running )                     |
+-----------------------------------------------------------------------------+

-------------------------------------------------------------------------------

8. License

Matchbox is free software released under the terms of the GNU General Public
License, (GPL). 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, or (at your option) any later version.

Matchbox 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.

-------------------------------------------------------------------------------

9. Credits

Matchbox is written by Matthew Allum. It was originally based on aewm, but has
since undergone rewrites and now bares little resemblance. Thanks also go to
Carl Worth and Nils Faerber for initial help with the project.

Matchbox is copyright OpenedHand Ltd 2003. 
