 |  |
| | |
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;
Specify the X Server for matchbox to connect to. Defaults to DISPLAY environment variable.
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 )
![[Tip]](images/tip.png) | Note |
|---|---|
Themeing will not be available if matchbox is compiled with the --enable-standalone option. | |
The corresponding X Resource key is matchbox.theme .
Specify whether if application windows have title bar decorations. Defaults to yes.
| Tip |
|---|---|
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 .
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 .
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 .
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 .
If enabled, an attempt is made to hide the mouse cursor completely. This can be overridden by applications such as xterms.
| Warning |
|---|---|
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 http://projects.o-hand.com/matchbox/sources/utils/. | |
The corresponding X Resource key is matchbox.cursor .
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 .
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 .
Specify the session manager client ID. Only used if built with session manager support.
The corresponding X Resource key is matchbox.session .
Display a brief help message and build configuration details.
Matchbox window manager also uses environment variables for advanced usage. These are
If set all X11 communication will be synchronous, only used for debugging.
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;
Table 1. matchbox-remote command line options
| 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
| |  | |
 |