Overview Tomas Frydrych OpenedHand Ltd tf@o-hand.com 0.1 22 November 2007 Initial draft

Matchbox Window Manager II is a component framework for building customised window managers providing PDA-like (i.e., restricted-stack), window management compliant with the ICCCM and NET WM specifications. Matchbox Window Manager II (MBWM2) builds on the success of the original Matchbox Window Manager, using the same window-management paradigm, but offering significantly greater flexibility making it easy to create custom managers matching requirements for specific HW and UI design. The framework is built on the top of a lightweight object system, and provides a set of ready-made building blocks encapsulating the key parts and functionality of a window manager. The object system makes it easy to subclass the provided objects in order to achieve the required behaviour. The key features of the MBWM2 framework are: Ready-made client types for standard window types as defined by the ICCCM and NET WM specifications. Theme engines allowing powerful and yet minimal-effort theming. Window-compositing capabilities (optional). Support for GLib main loop (optional).

This section of the document describes the key blocks that are used to build a MBWM2 manager.

Each window managed by MBWM2 is encapsulated by a client object. MBWindowManagerClient is the base, abstract, type which provides API for manipulating the client objects, decorating the wrapped window as required. The base MBWindowManagerClient type is then sub-classed to handle specific window types according to requirments. To this end, the MBWindowManagerClass exposes a number of virtual methods that the sub-classes can override.

realize: responsible for creation of client resources, such as frame windows, and reparenting client windows. This method is usually overwritten by clients that do not require a frame. geometry: distributes the overall geometry available to the client between its constituent parts (the client, frame, etc). stack: carries out any action necessary to stack the client correctly, e.g., for clients with transient children, it ensures that both the client and the children are stacked correctly. show: carries out any required custom actions when the client is changing from a hidden to visible state; most clients need not to implement this method. hide: carries out any required custom actions when the client is changing from a visible to hidden state; most clients need not to implement this method. sync: flushes any internally scheduled changes to the display. focus: carries out any custom action required when the client is given focus; most clients need not to implement this method. theme_change: carries out any actions required when the theme has changed (for example, recreating decor windows, etc.). detransitize: this method is responsible for terminating any relationship between the (transient) client and its parent; it is typically called early in the process of the WM releasing a given client. Most clients do not need to implement this method. stacking_layer: calculates the stacking layer for the client. This method only needs to be implemented by clients whose stacking requirement change dynamically; for most clients the stacking layer is static, in which case it is enough to initialise it from the object _init method.

The MBWM2 framework recognises eight fundamental client types, for each of which it provides a sub-class of MBWMWindowManagerClient, listed in the following section; these sub-classes can be further sub-classed or replaced, should the customisation of the WM require that. The type of a given client can be queried using the MB_WM_CLIENT_CLIENT_TYPE() macro; the client type values are or-able. (NB: the client type should not be confused with the type of the object handling the client; the object type id is unique for each object class, and it is not or-able.)

The standard sub-classes of MBWindowManagerClient are in fact not derrived directly from MBWindowManagerClient, but from an intermediary helper class MBWMClientBase; they are as follows: MBWMClientApp, encapsulating top-level application windows. MBWMClientDialog, encapsulating dialogues. MBWMClientPanel, encapsulating panels, such as task-switchers. MBWMClientDesktop, encapsulating a desktop application. MBWMClientInput, encapsulating input windows, such as virtual keyboards. MBWMClientMenu, encapsulating menus. MBWMClientNote, encapsulating non-interactive message windows. MBWMClientOverride, encapsulating windows with override-redirect attribute set (this type is only used when running in compositing mode, since override windows are, by definition, unmanaged). Each individual client-type provides specific behaviour, primarily in regards to resizing and stacking. For an example of how to replace a default clients implementaion with a custom one, see the maemo WM in src/managers/maemo.

The MBWMTheme is an abstract object encapsulating a theme engine. It handles parsing of the XML theme description, API for querying various parameters that are specified by a theme, and API for drawing window decorations for specific client types. The framework provides three different theme engines: MBWMThemeSimple; this is the default engine that uses only basic Xlib API for drawing the window decors. It is built if the PNG theme engine is not enabled via the --enable-png-theme configure option. MBWMThemePng; a theme engine which 'cuts out' window decorations from a single PNG template image. This engine makes it possible to design complex, visually impressive, themes with minimal effort. It needs to be enabled explicitly with --enable-png-theme.

MBWMLayout provides the logic for distributing the screen real estate between the managed clients. This is intrinsic to the MBWM2 management paradigm, and should rarely need to be subclassed when designing a custom manager.

MBWindowManager is the core object representing the window manager itself. It provides the essential functionality of the manager, which in most cases will be extended through a custom sub-classed object. To this end, MBWindowManager exposes a number of virtual methods.

process_cmdline: handles command-line options; if the custom object implements this method, it should chain up to the method provided by it's parent class, so that standard MBWM2 options get handled correctly. client_new: method used to allocate instances of MBWindowManagerClient and its sub-classes; any manager that uses custom MBWindowManagerClient sub-classes must implement this method. layout_new: method used to allocate an instance of the MBWMLayout object; this method needs to be implemented only if the custom WM sub-classes MBWMLayout. client_activate: method used to activate a client; this method only needs to be implemented if the custom WM requires some special action to be taken while activating a client (in which case the custom method should chain up to that of the parent class). client_hang: this method allows the custom WM to handle a hang client in a specific way (the default action is to shut it down); used as part of the ping protocol. client_responding: this method allows the custom WM to handle client's response to a ping in a specific way (the default action is to NOP); used as part of the ping protocol.

The component framework provides all the functionality necessary for a basic window manager, so that only a dozen or so lines of code are required to create one; such a basic manager implementation is provided in src/managers/simple. For a more specialised window manager it will be necessary to subclass some of the framework objects. Typically, you will need to provide a sub-classed MBWindowManager object (implementing the custom client_new() virtual function), and subclasses of MBWindowManagerClient for any client types for which customised behaviour is required. An example of a more specialised window manager can be found in src/managers/maemo, containing a window manager customised to the needs of the Nokia Maemo platform.

The MBWM II theme consists of an XML description and, in case of a PNG-based theme, the theme image. There are two distinct theme engines provided: a simple engine, using back Xlib drawing primites, and a PNG-based engine. The simple engine is suitable for simple themes with minimal frills. The PNG engine, on the other hand, facilitates the creation of visually impressive and complex themes; it is based on single template image, which contains all the elements the theme consists of, with the location of each element is described in the xml description file. Essentially, the PNG image can be thought of as a screen shot, or a mockup of the screen; however, it does not have to match the size of the screen (indeed, in order to save HW resources, the image should contain minimum of 'dead' space). PNG themes can also use shaped windows; any transparent pixels in any of the decorations will be excluded from the window shape (as long as the both the theme and the relevant client is marked as using shaped windows in the XML description). The XML theme description uses the following elements:

The top level element of the theme, with the following attributes: name: name of the theme. author: name of the author. desc: longer description of the theme, e.g., for display in a GUI theme switcher. version: version of the theme. engine-version: must be "2" for MBWM2. engine-type: type of theme engine preferred by this theme; legitimate values are "png" and "default" (default is "default"). shaped: whether this theme uses shaped windows; "yes" or "no", default "no" (only available for PNG themes; see the "client" element for more information).

The img element specifies the source image for a png theme; it will be ignored if the png engine is not used. It has the following attributes: src: the name of the image, which will be looked for in the same directory from which theme description has been loaded.

The client element specifies theming requirements for a client type; any client types that are not specified will be handled with the defaults of the theme engine for that particular client type. The client element has the following attributes: type: the type of client to which this description applies; legal values are "app", "dialog", "panel", "input", "desktop", "notification" (client of type MBWMClientTypeMenu and MBWMClientTypeOverride cannot be themed). shaped: whether this client uses shaped windows; "yes" or "no", default "no". (Shapped windows are only supported with PNG themes, where the invisible parts of the decorations are transparent in the theme image.) x, y, width, height: geometry for the client. (Note that for most client types it makes little sense to specify geometry in the theme, and the values will be ignored. The notable exception to this are panel clients, the position and size of which might be theme-dependent, as for example, with the maemo status bar.)

The decor element specifies how its parent client should be decorated. It has the following attributes: type: the decor type; legal values are "north", "south", "east", "west". show-title: whether the client title (such as window name) should be displayed on the decor; legal values are "yes", "no", default is "no". template-x: for PNG-based themes this is the the x coordinates of the decor in the image; ignored for other theme engines. template-y: for PNG-based themes this is the the y coordinates of the decor in the image; ignored for other theme engines. template-width: width of the decor. For PNG themes this value has to be given explicitly, and is the width of the decor in the image (if actual decor is wider than this value, the image will be expanded by tiling the middle section); for other themes, it has to be given for east and west decors (for north and south decors width is implied and the attribute will be ignored.) template-height: height of the decor. For PNG themes this value has to be given explicitly, and is the height of the decor in the image (if actual decor is taller than this value, the image will be expanded by tiling the middle section); for other themes, it has to be given for north and south decors (for east and west decors height is implied and the attribute will be ignored.) template-pad-offset: for PNG-based themes this is an offset (from template-x for "north"/"south" decors or template-y "east"/"west" decors) to a segment in your template image that can be used to pad the decor when it is wider/taller than the underlying template image. As well as locating the template data to copy for padding it also specifies the position at which padding is inserted. template-pad-length: for PNG-based themes, used in conjunction with the template-pad-offset attribute, this specifies the length of the segment in your template image that is used for padding decors that are wider/taller than your template image. font-family: the font to be used for any text display on the decor. font-size: the size of font to be used for any text display on the decor. color-fg: the foreground colour to use. color-bg: the basic background colour. If a background color is specfied for a PNG based theme, the decor will be first filled with this color, and then the PNG image will be composited over it; in this case, the images for any buttons must be located of the decor, and the "inactive-x", "inactive-y" of the "button" element used.

button element describes a button that belongs to its parent decor; it has the following attributes: type: type of the button; legal values are "minimize", "accept", "close", "menu", "fullscreen", "help". packing: "start" or "end". Whether the button should be packaged from start or end of the decor, default "end"; this parameter is ignored for PNG themes (in which buttons are placed explicitely, see below). template-x: for PNG-based themes this is the the x coordinates of the button in the image; the button must be located directly on the parent decor. Ignored for other theme engines. template-y: for PNG-based themes this is the the y coordinates of the button in the image; the button must be located directly on the parent decor. Ignored for other theme engines. width: width of the button. height: height of the button. template-inactive-x: for PNG-based themes this is the the x coordinates of the button in inactive state in the image; ignored for other theme engines. (The inactive image can be located directly on the decor image, in which case, this parameter is unnecessary.) template-inactive-y: for PNG-based themes this is the the y coordinates of the button in inactive state in the image; ignored for other theme engines. (The inactive image can be located directly on the decor image, in which case, this parameter is unnecessary.) template-active-x: for PNG-based themes this is the the x coordinates of the button in active state in the image; ignored for other theme engines. template-active-y: for PNG-based themes this is the the y coordinates of the button in active state in the image; ignored for other theme engines. press-activates: "yes" or "no"; whether the button responds to a press of the pointer, or its release.

OpenedHand Ltd Unit R, Homesdale Business Center 216-218 Homesdale Rd Bromley, BR1 2QZ England +44 (0) 208 819 6559 info@openedhand.com