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;

...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. Figure 1, “” shows the created main window.

Figure 1. 

[D]

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

Figure 1, “” shows the created dialog window.

Figure 2. 

[D]

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.

Figure 3. 

[D]

Figure 4. 

[D]

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>

Figure 5. 

[D]

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.