Matchbox X11 Window Manager Documentation

Matthew Allum

Copyright  2002 by Matthew Allum <mallum@handhelds.org>

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

Table of Contents
1. Introduction
2. Screenshots
3. Usage
   
    3.1. Launching Matchbox
    3.2. Configuration.
    3.3. Themes
    3.4. Shortcut keys.
   
4. Included Utilities.
5. Compiling and Installing.
6. Availability
7. FAQ
   
    7.1. Where's the app launcher menu ?
    7.2. How do I get that keyboard icon I saw in the screenshots?
    7.3. Matchbox segfaulted !
   
8. Mailing List
9. License
10. Credits

1. Introduction

Matchbox is a X11 window manager designed for computers with little screen real
estate, limited input devices and low cpu/storage resources. Touchscreen PDA's
fit well into this category.

Matchbox accomadates for these shortcomings by various means. Most importantly
by maximising windows to all available display space and only allowing one
'main' window to be visible at a time. The user is able to page through each
main window.

Matchbox does however facilitate other minor windows to share space at the same
time, these include toolbar, dockable and dialog windows.

Toolbar windows occupy space at the bottom of the display with multiple
instances stacking on top of each other. They work similar to toolbars in web
browser software allowing the space they use to be quickly freed and reclaimed.
Xkbd is an example of an application that uses a toolbar window.

For dockable windows, Matchbox optionally includes a configurable collapse-able
dock that holds small apps that are visible at all times. Examples include
small clocks, app launchers or resource meters.

Windows which set there 'transient' property are treated as dialogs. They are
set smaller than main windows, are drag-able and stay attached to their
'parent' during paging.

Other Features include;

  * Small binary size.
  * Only dependent on Xlib, and no other gui toolkits.
  * Keyboard shortcuts for window navigation / operations.
  * Theme-able.
  * Highly configurable.
  * Survives and adapts well to 'screen rotations'
  * Optionable compile time Xft ( Anti-Aliased font ) support.
  * Dist includes various useful apps;
   
      + minitime, a docked clock.
      + miniapm, a docked battery monitor.
      + minisys, a docked mem/cpu monitor.
      + monolauch, a simple dockable single program launcher.
      + mbcontrol, a tool for managing matchbox externally, used primarily for
        changing themes on the fly.

 

Matchbox is still in its infancy and should be considered unstable software.
There are probably many bugs unfortunately lurking in the code. If you catch
one, be sure to report it.

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

2. Screenshots

Screenshots are kept at http://www.handhelds.org/~mallum/screenshots/.
-------------------------------------------------------------------------------

3. Usage

Matchbox is designed to be intuitive. Navigation between main windows is
accomplished by clicking on the titlebar 'arrow' buttons or clicking on the
window title for a clickable dropdown list of currently active main windows.

Toolbar apps ( such as xkbd ) and the dockbar can be minimised by clicking the
small arrow at the side of the window. Once minimised they can be maximised by
clicking the collapsed bar. Toolbar apps are closed by clicking the cross at
the end of the bar.

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

3.1. Launching Matchbox

With no other window manager running, simply execute 'matchbox &'. More
sensably add matchbox to the end of your X Startup script ( such as .xsession
or .xinitrc ).

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

3.2. Configuration.

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

X Resources are 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 XServer for       |
|             |                        |       |matchbox to connect to.       |
|             |                        |       |Defaults to $DISPLAY          |
|             |                        |       |environmental variable.       |
|-------------+------------------------+-------+------------------------------|
|-theme       |matchbox.theme          |string |Specify the theme file to use.|
|             |                        |       |Defaults to default_theme_rc. |
|             |                        |       |The theme can also be changed |
|             |                        |       |whilst matchbox is executing  |
|             |                        |       |using the mbcontrol program.  |
|-------------+------------------------+-------+------------------------------|
|-modifier    |matchbox.modifier       |mod1|  |Specify the modifier key to be|
|             |                        |mod2|  |used in combination with      |
|             |                        |ctrl   |keyboard shortcut keys.       |
|             |                        |       |Defaults to mod2 ( record     |
|             |                        |       |button on the ipaq )          |
|-------------+------------------------+-------+------------------------------|
|-use_dock    |matchbox.dock           |yes|no |Specify whether or not to use |
|             |                        |       |the dock. Defaults to yes.    |
|-------------+------------------------+-------+------------------------------|
|-dockmax     |matchbox.dock.height.max|integer|Specify the height, in pixels,|
|             |                        |       |of the dock.                  |
|-------------+------------------------+-------+------------------------------|
|-dockmin     |matchbox.dock.height.min|integer|Specify the height, in pixels,|
|             |                        |       |of the dock when collapsed.   |
|             |                        |       |defaults to 4.                |
|-------------+------------------------+-------+------------------------------|
|-use_titlebar|matchbox.titlebar       |yes|no |Specify whether or not the    |
|             |                        |       |main windows have titlebars.  |
|             |                        |       |Defaults to yes.              |
|-------------+------------------------+-------+------------------------------|
|-help        |n/a                     |n/a    |Display a brief help message  |
|             |                        |       |and exit.                     |
+-----------------------------------------------------------------------------+

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

3.3. Themes

Matchbox supports simple themes to change its look. A single default theme is
included with the main distribution. See the mb-themes package for extra ones (
blue, rage and yawn ).

See (install prefix)/share/matchbox/themes for examples. They are pretty self
explanatory.

Themes can be selected on startup via the '-theme' switch or changed on the fly
using the included utility 'mbcontrol'.

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

3.4. Shortcut keys.

Matchbox operation can be controlled with the keyboard by holding the defined
modifier key ( default mod2 ) and one of the following;

  * Arrow left or p.
   
    Go to previous main window.
  * Arrow right, n or Tab.
   
    Go to Next main window.
  * Return.
   
    Close current main window.
  * l or Arrow down.
   
    Collapse all toolbars but not dock
  * r or Arrow up.
   
    Raise all toolbars but not dock
  * R.
   
    Collapse all toolbars and dock
  * L.
   
    Raise all toolbars and dock

Shortcuts will eventually be user definable.

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

4. Included Utilities.

  * minitime [options ...].
   
    A dockable clock. Currently supports -f and -c switches for font and colour
    respectively.
  * miniapm.
   
    A dockable battery monitor, currently a little broken :(
  * minisys [options...].
   
    A dockable mem/cpu monitor. Run with '-h' to see options.
  * monolauch [-k] <xpm to use> <window name> <program to run>.
   
    A single app launcher which sits in the dock with the selected xpm icon.
    Initial click will launch the selected program, next click will hide the
    programs window, next will show the window, next will hide, and so on for
    ever.... Passing -k option will kill the program rather than hide it.
    Originally based on xsingleinstance.
  * mbcontrol [ options...].
   
    When run with a '-r' it will output the current theme file matchbox is
    using to stdout. When run with '-t <theme_file>', matchbox will switch to
    that theme. Be aware however if the theme file doesn't exist, matchbox will
    rudely exit ( To be fixed! )

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

5. Compiling and Installing.

matchbox uses autoconf, so building it should be straightforward:
        $./configure
        $make
        # This next step might require root access
        $make install
See the INSTALL file for (standard) gory details regarding autoconf.

Configure currently supports the following options;

  * --enable-debug
   
    configure for a debug build
   
  * --enable-xft
   
    configure to use XFT library for anti-aliased fonts.
   
Make also has an 'ipkg' target for building shiny ipkgs.

A prebuilt ipkg is included in the familiar linux distributions unstable feed.

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

6. Availability

Source tarballs and debs are available from http://www.handhelds.org/~mallum/
downloadables/

Bleeding edge source is available from handhelds.org cvs under apps/matchbox.
See http://www.handhelds.org/sources.html

ARM binarys for the Compaq Ipaq are available in ipkg from from the familiar
distribution unstable feed. See http://familiar.handhelds.org.

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

7. FAQ

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

7.1. Where's the app launcher menu ?

There isn't one. Use a separate app such as gtk-menu ( lives in the dock ) ,
gpe-appmgr ( PDA style launcher ), or lots of monolauch's .

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

7.2. How do I get that keyboard icon I saw in the screenshots?

monolaunch provides this. Run monolauch like this;

monolauch /usr/share/xkbd/img/kbd.xpm xkbd xkbd

Adding the '-k' switch to monolaunch will cause xkbd to completely disappear
rather than minimise to a bar.

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

7.3. Matchbox segfaulted !

Remember matchbox is still in its early stages of development and is known to
crash on occasion. The important thing to do is to mail me explaining exactly
what happened and how to reproduce it, so I can fix it!

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

8. Mailing List

Matchbox has a mailing list for both users and developers of matchbox.

Subscribe at http://www.handhelds.org/mailman/listinfo/matchbox

Archives are available at http://www.handhelds.org/pipermail/matchbox/

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

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

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

10. 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 goto
Carl Worth and Nils Ferber for initial help with the project.

Be sure to check out other exciting software by me including; xkbd - a xlib
virtual on-screen keyboard, pikpak - a python gtk front end to ipkg, gtksolo -
a gtk module which turns held down left clicks into right clicks on gtk apps
and jabberpy - a Python library for the Jabber instant messaging protocol.

Matchbox is copyright Matthew Allum 2002. 
