Matthew Allum matthew@openedhand.com 2003 Openedhand Ltd

Matchbox allows both its visual look and interface to be defined at run time and changed on the fly. This document describes how its done, describing the creation of a matchbox window manager theme.xml file and configuration syntax for the themeing of the panel, desktop and icons. Matchbox must be compiled *without* the --enable-standalone for themeing. Its assumed the reader is familiar with using xml or xml-like mark up languages such as html. This document is relevant for matchbox 0.9 release.

The first thing todo is to decide on a name for you new theme and create one of the following directory's; $HOME/.themes/[theme_name]/matchbox/ $PREFIX/share/themes/[theme_name]/matchbox/ Your theme.xml file will go in this directory together with any images your theme uses. To then test your theme, start matchbox like matchbox -theme [theme_name] Alternatively you can also use 'matchbox-remote -t [theme_name]' to switch themes on the fly whilst matchbox is executing. If enabled enabled both GConf and XSettings can also be used to change the matchbox theme. If matchbox fails to parse a theme file, it will switch to its default theme and print basic error information on why it failed to stdout. Now open up the theme.xml file and create the top level <theme> element. <?xml version="1.0"?> <theme name="An Example theme" author="Matthew Allum - mallum@handhelds.org" desc="A simple demonstartion theme" version="1.0" engine_version="1" > <!-- this is where the actual theme definition is defined --> </theme> The various theme attributes should be self explanatory. The 'engine_version' attribute should be set to 1 as to work with 0.5+ versions of matchbox. The theme.xml file is then split into 2 major sections. The first listing the actual resources ( such as fonts and images ) required by the theme and then the next listing how these resources are used for the decoration of each type of window frame.

There are 3 types of resources that are currently supported; colors, fonts and pixmaps ( images ). Each resource has an 'id' attribute so it can be later referenced. Colors A color looks like; <color id="blue" def="#0000ff" /> The definition is in the format #rrggbb[aa]. The alpha part is optional. Fonts A font looks like; <font id="myfont" def="Sans,fixed bold 8" /> or <font id="myfont" def="Sans Serif-8:bold|fixed" /> You can use XFT or GTK2 style font naming. Pixmaps A pixmap looks like; <pixmap id="close-button" filename="close_button.png" /> The filename lists an image in the current directory. Make sure the image format used is supported by your matchbox build. XPM is always supported but lacks an alpha channel like PNGS. Our theme file now looks like; <?xml version="1.0"?> <theme name="my new theme" author="Matthew Allum - mallum@handhelds.org" desc="A simple demonstartion theme" version="1.0" engine_version="1" > <color id="blue" def="#0000ff" /> <color id="black" def="#ffffff" /> <color id="bluegrey" def="#ccccff" /> <font id="myfont" def="Sans Serif-8|fixed" /> <pixmap id="close-button" filename="close_button.png" /> <pixmap id="next-button" filename="next_button.png" /> <!-- frame definitions will go here --> </theme> Now we have the resources for are theme set up, the next step is to define the actual frame decorations, but first we must learn about the various window types supported by matchbox.

Before we go on to defining the decorations for each window type, its important to understand the various types of windows supported by matchbox and how decorations are then made up for each type. Matchbox supports 4 main window types for which decorations can be defined. For each window type, one or more <frame> tags are defined. The window types are; Main window frames A 'main' application window. Can have all 4 sides defined Dialog window frames Popup or dialogs windows Can also have all 4 sides defined Can also optionally have a dialog-north frame. This is used for border-only dialogs. You can also optionally specify 'message' alternate window decorations. These are dialogs with The WM_HINTS 'urgency' bit set. They are defined just like dialogs with there frame id set to 'message', 'message-south', 'message-east' etc. Toolbar/Input window frames Defines the decorations for toolbar windows - such as xkbd Has 2 states maximized and minimized, both are defined separately. Note, an matchbox window manager built with 'alternate input manager windows' does not provide any themeing for these windows. The windows are decoration free. Menu window This is the optional drop down task menu used by matchbox titlebar to quickly select between clients. Each window type <frame> will then have a possible number of <layer> tag children. These tags describe each graphical layer that builds up the eventual window frame decoration. The layers are likely to reference the earlier listed resources. Positioning and sizing of each layer is covered in the next section. A layer can be of various types and have various attributes, these types include; plain A rectangle of solid color. The 'color' attribute references a previously defined color id. pixmap A pixmap stretched to its defined area. The 'pixmap' attribute references a previously defined pixmap id. pixmap-tiled Like the above but tiles a pixmap rather than stretches it. label This specify where the window title text is to be drawn. Both a 'font' and 'color' attribute are used to specify its look. This layer is always painted last on top of all others. gradient-horiz Paints a horizonaltal gradient, specified with the attributes startcol and endendcol. gradient-vert Like the above but vertical. iconn Paints the current window icon. Each <frame> may also have <button> tag children. These define valid buttons with an 'action' attribute specifying what action should be taken by the window manager when it is activated. Buttons are painted above any layers. Valid button actions include; next Brings the next main client to the top of the matchbox window stack. Used only by the main window type. Only painted when there are multiple main clients prev Brings the previous main client to the top of the matchbox window stack. Used only by then main window type. Only painted when there are multiple main clients. close Closes the window. Valid for all non border ( eg *-east, *-west, *-south ) frame types. hide Collapses a main application windows title bar. Used only by the main window type. menu Produces the drop down task menu. Used only by the main window type. Only painted when there are multiple main clients. help A help button. Used only by the main and dialog window type. accept A accept button. Used only by the main and dialog window type. custom A misc 'platform' specific button. Used only by the main and dialog window type. maximise Used by a minimized toolbar window frame type. minimise used by a maximized toolbar window frame type. Also works for app windows in matchbox 0.9 Now we'll move on to seeing how these are used.

We will now step through creating the frame decoration declarations for each window type, starting with main application windows. First you define a frame element, and set its height. This is the application toolbar. <frame id="main" height="20"> .... </frame> The height is defined, but the width could be anything. The theme cannot define the screen size the user is using ! This is an important thing to remember than many theme elements are sized dynamically and you theme design has to take account of this. The next step is to build up the frame layers <layer x="0" y="0" w="100%" h="100%" type="plain" color="blue" /> This creates a blue background ( remember the 'blue' color we created earlier ) of solid color. The x, y, w and h attributes covers the position and size of the layer. They can be; Percentages of the total frame size Absolute values from each side of the frame ( by using -/+ive values ) Reference the labels ( titles ) position ( lablex, labelw ) ...or simple combinations of a maximum of two of the above. See what is defined here for examples, and experiment ! This same system is used for positioning all theme elements. As an example of this we'll now create another layer, again of solid color with in this one. <layer x="2" y="2" w="100%-4" h="100%-4" type="plain" color="bluegrey" /> We then add where we want the title text of the window to appear <layer x="6" y="1" w="100%-24" h="20" type="label" color="black" justify="left" font="myfont" /> The justify attribute specifys how the text is aligned in the defined layer box, can be left, right or middle. The next thing to do is add some buttons to the frame. All button types are optional. In this example we will use just a menu button and a close. Here is the close button xml; <button x="-20" y="2" w="16" h="16" action="close" > <active pixmap="close-button" blend="-150"/> <inactive pixmap="close-button" /> </button> Like layers, you define the area covered by the button. You then define the inactive and optionally inactive states of the button ( eg when its pressed / released ) . You can specify a different image for each state but here we'll use the same image but with the blend attribute - this changes the amount of alpha used to paint the image. We'll also make the title display the task menu when clicked on. To do this we add a button tag like; <button x="labelx" y="0" w="labelw" h="100%" action="menu" options="inputonly" /> This button uses the 'inputonly' option to specify the button is activated by clicking on a invisible area of the display. we now have a very simple window titlebar. We'll also create simple decorations for the other 3 border of the main window frame; <frame id="main-east" width="2" > <layer x="0" y="0" w="100%" h="100%" type="plain" color="blue" /> </frame> <frame id="main-west" width="2" > <layer x="0" y="0" w="100%" h="100%" type="plain" color="blue" /> </frame> <frame id="main-south" height="2" > <layer x="0" y="0" w="100%" h="100%" type="plain" color="blue" /> </frame> The above creates a simple 2 pixel blue border around the rest of the window. shows the created main window.

The created Main window decorations

Dialog window creation is very similar to a main window. See the final example for how its done. shows the created dialog window.

The created Dialog window decorations

Next is the creation of the toolbar window decorations. Toolbar windows in matchbox exist in two states - maximized and minimized, and separate decorations for both these states need to be defined. This looks like; <frame id="utility-max" width="20"> <layer x="0" y="0" w="100%" h="100%" type="plain" color="blue" /> <layer x="2" y="2" w="100%-4" h="100%-4" type="plain" color="bluegrey" /> <button x="2" y="2" w="16" h="16" action="minimize" > <active pixmap="next-button" blend="-150"/> <inactive pixmap="next-button" /> </button> </frame> <frame id="utility-min" height="20"> <layer x="0" y="0" w="100%" h="100%" type="plain" color="blue" /> <layer x="2" y="2" w="100%-4" h="100%-4" type="plain" color="bluegrey" /> <layer x="6" y="2" w="100%-30" h="20" type="label" color="black" justify="left" font="myfont" /> <button x="0" y="0" w="100%-25" h="100%" action="maximize" options="inputonly"/> <button x="-20" y="2" w="20" h="20" action="close" > <active pixmap="close-button" blend="-150"/> <inactive pixmap="close-button" /> </button> </frame> Toolbar windows currently have no borders defined.

The created utility-min window decorations

The created utility-max window decorations

The final frame decoration to be defined is the task menu. The task menu decorations are defined slightly differently than other decorations. Firstly as both the task menu's width and height are dynamic. The optional border_north, border_south, border_west and border_east frame attribute values add padding to this dynamic size. The font and font color must be defined as attributes in the frame tag. Optionally a 'highlight' attribute can be used to define the color of an active entry. The rest of the definitions within the frame tag describe the background - there is NO label tag. <frame id="menu" font="myfont" color="black" > <layer x="0" y="0" w="100%" h="100%" type="plain" color="blue" /> <layer x="2" y="2" w="100%-4" h="100%-4" type="plain" color="bluegrey" /> </frame>

The created menu window decorations

You now have a completed theme file. The full file can be found here. It should be noted that the matchbox theme parser is built for speed and small size and is therefore not very verbose in reporting any theme misconfigurations. For example; a missing or mispelt required frame parameter ( such as height ) will simply default to 0 with no user visible warning. The theme will still run but the defined frame will likely be invisible as it will have a height of Zero ! One should therefore take extra care in defining themes and in the presence of unexpected decoration behaviour double check theme.xml definitions.

Apart from just the window manager, the various included matchbox utilities are also theme-able.

'mbdock' and the menu's used by apps lile mbmenu can also be themed. Rather than use the theme.xml file, they use a theme.desktop file which exists in the same directory as the theme.xml file. The files format consists of one key/value pair per line for each visual attribute to be changed. Here is the theme.desktop file for the blondie theme. [Desktop Entry] Type=MBTheme Name=Blondie Comment=Blondie theme PanelBgColor=#e2dec6 PanelFgColor=black MenuBgColor=#e2dec6 MenuFgColor=black MenuBdColor=#9d9a8a MenuHlColor=black The following keys are valid; PanelBgColor Sets the background color used by matchbox-panel. Can be either a color name or specified in the form #RRGGBB. PanelBgTrans Sets the transparency of matchbox-panel. Ranges from 0-255, 0 being totally transparent. This option is UNSUPPORTED, use at your own risk. PanelBgPixmap Sets a titled background image for matchbox-panel. Set to the full path of a supported image file. TitlebarDockBgColor, TitlebarDockBgPixmap Like the above but used by panels reparented in the titlebar. PanelMsgBgCol, PanelMsgBgUrgentCol, PanelMsgFgCol Sets colors for panel 'message bubbles'. PanelMsgFont Sets the font for panel 'message bubbles'. PanelFgColor Sets the foreground color to be used by panel applets such as minitime. MenuBgColor Sets the background color of any matchbox menu's. MenuFgColor Sets the foreground color ( eg text ) of any matchbox menu's. MenuBdColor Sets the border color of any matchbox menu's. MenuHLColor Sets highlighted text color of any selected menu items. MenuFont Sets the font used by any menus. Like font definitions in theme.xml files, it can be GTK2 or Xft style font definition. MenuTransparency This option will make the menu transparent. This option is UNSUPPORTED. Use at your own risk. DesktopBgSpec Set the desktop background. For infomation on format, run 'mbdesktop --help'.

Icons used by mbmenu, mbdesktop and most of the included matchbox panel/dock apps are also theme-able. They follow a basic implementation of the icon theme spec found at freedesktop.org. The basic mechanism works by 'overriding' the applications default icon. For example before checking $PREFIX/share/pixmaps for a specified icon file, matchbox applications will check the following; $HOME/.icons/ $HOME/.icons/[theme_name]/[size]x[size]/[type]/ $PREFIX/share/icons/[theme_name]/[size]x[size]/[type]/ Where [size] is usually one of 48, 36, 32, 24 or 16 and [type] can be anything ( usually 'apps', 'emblems' etc ). So as long as you know the image filename an application wants ( hint: look at its .desktop file ), a theme can change its icons appearance. Here is a list of icon names used by the various parts of matchbox. If matchbox is compiled without png support assume an xpm extension. Icons used by menus and matchbox-desktop; === mbdesktop.png mbfolder.png mbfolderprev.png mbnoapp.png mbup.png mbdown.png mbadd.png mbremove.png mbexit.png mblock.png Icons used by the various panel apps; === miniapm-power.png miniapm.png mbmenu.png mbmenu-active.png # Optional mbterm.png minisys.png minitime.png minivol-high.png minivol-low.png minivol-mid.png minivol-zero.png miniwave-icon.png broken-0.png no-link-0.png signal-1-40.png signal-41-60.png signal-61-80.png signal-81-100.png

Themeing containing a number of 'experimental' features, these features are likely to change between matchbox releases. buttons can have 'pressonly' in there options attribute. If this is set the button will get activated on press, rather than release.

Please send questions to mallum@openedhand.com.

Add an options='shaped' attribute to the windows types frame definition. Any parts of the defined frame that has a completely transparent alpha channel will be transparent. See the blondie theme for an example.

Use the top level 'appicon' tag. eg; <pixmap id="defaulticon" filename="defaulticon.png" /> <appicon pixmap="defaulticon">

Use the top level 'lowlight' tag. eg; <color id="mylowlightcol" def="#819cba33" /> <lowlight color="mylowlightcol" /> Note, matchbox wm must be run with '-use_lowlight yes' switch for this to take effect.

Firstly matchbox-window-manager must be built with the --enable-composite compile option and both composite librarys and a composite enabled X Server for this options to take effect. Shadows are created with the top level <shadow/> tag. eg; <shadow style="gaussian" color='shadowcol' /> style, can be one of gaussian, simple ( solid color ) or none. color, specifys the shadow color. Other attributes available include integer ( can be negaive ) shadow offsets - dx,dy and shadow padding - width, height. Currently these options only work for simple shadows. Also it should be stressed this functionality is highly experimental.

Use a 'panel' tag in the the main frame definition. eg; <panel x="100%-60" y="0" w="50" h="100%" /> Note, matchbox-panel must be run with '--titlebar' for it to reparent in this defined area.

Matchbox window manager keeps a cached pixel representation of a single, text free, application window title bar decoration image. This is needed for the compositing of button images and as a performance optimisation. This caching can be disabled if; your main window title bar theme consists of a single or few images, and any titlebar button images do not contain an alpha component. To disable, add a cache attribute set to false to your root theme.xml tag; <theme cache="false" ... /> By setting the enviromental variable MB_THEME_ALWAYS_CACHE this attribute can be overidden and always ignored. This functionality should be considered experimental. Memory, in bytes, saved approximates width x height x display bytes per pixel of you application window title bar decoration only.

See the various themes included with the matchbox distrubution ( in data/themes ) and the matchbox-themes-extras package. 'Blondie' is a fairly advanced 'heavy' theme that uses many themeing properties. Bluebox is a lighter XPM based theme. Borillo is a relatively simple theme designed more for larger displays, using few (2) external images. Also the matchbox-tests package contains the 'mbtest' theme which uses many of the experimental features.