C compiler (such as GCC).
[optional] Autotools (autoconf, automake) if you modify some files.
Xlib headers and libraries (development package), distributed with XOrg.
the XML C parser and toolkit of Gnome, headers and libraries (development package).
[optional] the X FreeType headers and libraries (development package).
[optional] the XOrg XRender extension.
[optional] PNG format headers and libraries (development package).
[optional] JPEG format headers and libraries (development package).

Once you have the above dependencies installed, you are ready to build Firebox. Untar the archive and from inside the source tree and run:

$ ./configure
$ make install

Building from the Subversion repository may be more difficult. Please read the FAQ about it.

1.2. Running

For most people, Firebox binary is located in /usr/local/bin/.

1.2.1. Using the startx command.

The uncut version is:

$ startx /usr/local/bin/firebox -- :3

... where 3 is the index of a free display.

To run Firebox by only running startx, you need to edit your $HOME/.xinitrc file. This is a shell script, so to run Firebox a typical content is:

# [...]

exec firebox

Then make sure the file has enough rights:

$ chmod 700 .xinitrc

1.2.2. With a Display Manager.

The best should be consulting the documentation for your specific Display Manager in order to add entries into it.

Alternately, you can edit a $HOME/.xsession file. This small file can be made identical to the .xinitrc example above. With this method, you would choose "default" as the login target in your display manager.

In this case no exec right is needed.

Configuration.

Please use the preferences editor.

Themes.

This part describes the XML structure of theme files.

Even if it is quite detailed, the best will always be to have a look at existing themes. That way allows to learn quickly tips and tricks !

For a safer (and faster) approach, one can follow the following steps:

begin by reading the base, at least the 3.7.1 and 3.7.2 sections.
analyse the small theme called "Learning theme for beginners" (see the download page).
try to modify the more visual items.

The current theme is loaded from ~/.firebox/themes/current, which can be either a directory or a symbolic link. In all cases, it must contain a theme.xml file.

3.1. Theme file header.

The first section of a theme file is a header containing some information about the theme itself.

All its tags are located in:

<FireboxTheme>
    <Header>
    ...
    </Header>
</FireboxTheme>

The Header tag is composed of several tags which have only string values:

Title : arbitrary name given to the theme.
Version : version of the theme.
Require : required version of Firebox in order to make the theme fully working, for instance '0.5.0'.
Date : date of creation.
Author : name of the author.
Link : pointer to some URL.

3.2. Internal pictures

3.2.1. Desktop background.

Firebox can deal either with screen savers or images for desktop backgrounds. As programs can't come with themes without difficulty, only pictures are supported here.

Theme background pictures are defined like this:

<FireboxTheme>
    <Background>
        <Picture>my_picture.png</Picture>
    </Background>
</FireboxTheme>

3.2.2. Arrows for menus.

There are three types of arrow for menus. They may be defined like that:

<FireboxTheme>
    <SystemPictures>
        <SubmenusArrow>my_picture1.png</SubmenusArrow>
        <DMenuLeftArrow>my_picture2.png</DMenuLeftArrow>
        <DMenuRightArrow>my_picture3.png</DMenuRightArrow>
    </SystemPictures>
</FireboxTheme>

3.3. Size of items.

The six main tags of this section are located in:

<FireboxTheme>
    <Sizes>
    ...
    </Sizes>
</FireboxTheme>

3.3.1. Frame windows.

The Borders tag defines how big the frame windows are ; it has four attributes:

east : right border of the frame window.
north : top border of the frame window, ie. height of the titlebar.
west : left border of the frame window.
south : bottom border of the frame window.

The TitleBar tag sets up information about titlebar icon and buttons ; thus, it also has four useful attributes:

padding : space between the border and the first icon/button.
sep : space between two titlebar buttons.
width : width of titlebar buttons.
height : height of titlebar buttons.

3.3.2. Menus.

The Menu tag is used to define the required height of menu items. If a size is not stated, then its default value is the height of the font with which the caption is printed (or 0 for the separator bar).

header : height of the header menu entry.
entry : height of quite all menu entries.
separator : height of a separator bar.

The final height of a menu entry is equal to :

MAX(user defined size, size required for printing) + 2 x vertical padding (see below).

The Gap tag provides extra padding values ; it may contain the following attributes:

horizontal : left and right padding for menu items.
vertical : top and bottom padding for menu items.
icon : space between icon and text.

The Icon tag gives the size of icons thanks to its attributes:

menu : size for icons of the usual menus.
dmenu : size for icons of the dynamic menu.

3.3.3. Switch panels.

As there are two kinds of panels, the Panel tag contains more than only one tag:

Icon : properties of the area reserved for pictures in the panels.
Window : properties of the panel which is shown during window switching.
Desktop : properties of the panel which is shown during desktop switching.

The Icon has the following attributes:

hsep : size of the left and right borders ; space between the pictures area and the text.
vsep : size of the top and bottom borders.
size : size of the pictures area.

The Window and Desktop tag can have the attributes:

left : left padding for the text.
right : right padding for the text.

3.4. Text related information.

Text properties are located in:

<FireboxTheme>
    <Text>
    ...
    </Text>
</FireboxTheme>

Five types of font are used. Each one is materialized by a tag:

ClientTitle : font for client title.
MenuHead : font for menu header.
MenuItem : font for menu items.
Hit : font for the recognized typed string in the dynamic menu.
Panel : font for the panels.

In order to define its properties, each tag can have three sub tags.

3.4.1. Font name.

The text of the Font tag describes the font to use for a given text.

The font string is the one produced by tools such as xfontsel.

3.4.2. Alignment.

The text of the TextAlignment tag defines where the text is placed in the area.

There are three legal values:

Left : text is on the left.
Center : text is centred.
Right : text is on the right.

By default, only the titlebar text is centred. All the others are printed on the left.

3.4.3. Shadow position.

The TextShadow tag can have the following attributes:

alpha : alpha channel of the shadow.
x : offset of the shadow, 1 by default.
y : offset of the shadow, 1 by default.

3.5. Used colors.

As theme objects are used for rendering, there is no need of a lot of extra color definitions. Only colors for printing are lacking. That is why 2x4=8 tags are introduced. At first, the basic ones:

ClientTitle : color of the titlebar text.
SwitcherTitle : color of the text of the panels.
MenuHead : color of the text of the header entry of menus.
MenuItem : color of the text of all other entries of menus.

As shadows can be added, four extra tags are also added:

ClientTitleShadow : color of the titlebar shadow.
SwitcherTitleShadow : color of the shadow for the panels.
MenuHeadShadow : color of the shadow for the header entry of menus.
MenuItemShadow : color of the shadow for all other entries of menus.

By default, shadow colors are all black.

All of these tags are located in:

<FireboxTheme>
    <Colors>
    ...
    </Colors>
</FireboxTheme>

Each tag can have four attributes to refine the colors according a given state:

normal : default state.
disabled : the item is disabled.
active : the mouse is over the item or the window has the focus.
selected : the item is selected.

Depending on the target, it does not make sense to use all of these colors in all cases. For example, panels do not have a selected state.

Here is a sample of color definition:

<Colors>
<MenuItem normal="#c0c0c0" active="#ffffff"/>
</Colors>

3.6. Pictures for titlebar buttons.

All this section is located in:

<FireboxTheme>
    <TitleBarButtons>
    ...
    </TitleBarButtons>
</FireboxTheme>

There are four states for the titlebar buttons:

Normal : default state.
Pressed : when the button is pressed or when it remains selected.
Hover : when mouse moves over the button.
FocusLess : when the window which contains the button has not the focus.

For each of these four states, four kinds of buttons can be defined:

Close : typically, the button with a cross.
Maximize : used to make a window as bigger as possible.
Minimize : hides the window.
StrongStick : puts the window on every virtual desktops at top level.

Depending on the position of each of theses buttons, four pictures can be provided:

Default : default rendering.
LeftEnd : when the button is on the left of its group.
RightEnd : when the button is on the right of its group.
Alone : when the button is alone.

The filenames have to be given with no path. And all definitions must be grouped. For instance:

<TitleBarButtons>

    <Normal>
        <Close>
            <Default>button_close_n.png</Default>
            <LeftEnd>button_close_n_left_end.png</LeftEnd>
        </Close>
        <Maximize>
            <Default>button_max_n.png</Default>
        </Maximize>
    </Normal>

    <Pressed>
        <Close>
            <Default>button_close_s.png</Default>
        </Close>
    </Pressed>

    <FocusLess>
        <Maximize>
            <Default>button_u.png</Default>
            <Alone>button_u_alone.png</Alone>
        </Maximize>
    </FocusLess>

</TitleBarButtons>

If a position is not used, then the default picture is used. If a button does not appear for a given state, then the hardcoded version is used.

3.7. Basic bricks for display.

3.7.1. Common base.

A brick refers to an area to be rendered. All basic bricks share one screen coordinates and one size.

The coordinates are given by the Position tag. This tag has two main attributes:

x : abscissa of the item.
y : ordinate of the item.

Theses two attributes can have numerical values, but also some special string keywords:

%MIN_POSITION% : left position in the available area.
%MID_POSITION% : middle position in the available area.
%MAX_POSITION% : right position in the available area.
%APPICON% : size of the application icon in the titlebar.
%MINI_DESK% : width of mini desktops table in the switch panel.
%LBUTTONS% : width of the left group of buttons in the titlebar.
%RBUTTONS% : width of the right group of buttons in the titlebar.
%WIN_TOP_LEFT% : position of the left upper corner of a user window in the frame window.
%WIN_TOP_RIGHT% : position of the right upper corner of a user window in the frame window.
%WIN_BTM_LEFT% : position of the left lower corner of a user window in the frame window.
%WIN_BTM_RIGHT% : position of the right lower corner of a user window in the frame window.
%EAST% : size of the right border in the frame window.
%NORTH% : size of the top border in the frame window.
%WEST% : size of the left border in the frame window.
%SOUTH% : size of the bottom border in the frame window.

By default, a position is initialized with the following values:

<Position x="0" y="0"/>

Moreover, values can be combined using plus and minus. For instance:

<Position x="%SOUTH% + 23 - %RBUTTONS%"/>

To summarize (all the squares are 20x20 big):

A: default ; no need of definition.

B: <Position x="31" y="%MID_POSITION%"/>

C: <Position x="%MID_POSITION%" y="%MID_POSITION%"/>

D: <Position x="%MID_POSITION% + 20" y="%MID_POSITION% - 20"/>

E: <Position x="%MAX_POSITION% - 20" y="%MAX_POSITION%"/>

To compute the size of an item, there is the Size tag which is working like the Position tag ; thus it has two main attributes, too:

width : width of the item.
height : height of the item.

These two attributes can have numerical values, but also some special string keywords:

%MAX_SIZE% : size of the available area.
%APPICON% : size of the application icon in the titlebar.
%MINI_DESK% : width of mini desktops table in the switch panel.
%LBUTTONS% : width of the left group of buttons in the titlebar.
%RBUTTONS% : width of the right group of buttons in the titlebar.
%WIN_WIDTH% : width of the user window.
%WIN_HEIGHT% : height of the user window.
%EAST% : size of the right border in the frame window.
%NORTH% : size of the top border in the frame window.
%WEST% : size of the left border in the frame window.
%SOUTH% : size of the bottom border in the frame window.

By default, a size is initialized with the following values:

<Size width="%MAX_SIZE%" height="%MAX_SIZE%"/>

To continue with the sample panel (let us consider that %APPICON% is equal to 28 pixels):

A: <Size width="50" height="20"/>

B: <Size width="20"/>

C: <Size width="20" height="%MAX_SIZE% - %APPICON%"/>

D: <Size height="20"/>

E: <Size width="20" height="20"/>

The only exception for default size is with pictures (see below): default values are equal to the image dimensions.

3.7.2. How works the machinery ?

Window shapes and rendering objects share a lot of common points. That is why they are handled in a similar way.

Both of them are defined by a position and a size. So both of them can have one Position tag and one Size tag as basic properties. Theme shapes and theme objects will then extend these properties by their own tags.

Another major point is that any shape or object can contain other shapes and objects.

Thus, items are handled like this: parent first, children next. And each time an item is processed, its available work area is restricted to its parent's one.

For instance:

<ThemeObject type="rect">
    <Colors bg="#ffffff"/>

    <ThemeObject type="rect">
        <Colors bg="#ffff00"/>
        <Size height="55"/>

        <ThemeObject type="rect">
            <Colors bg="#ff0000"/>
            <Position x="%MID_POSITION%" y="10"/>
            <Size width="20"/>
        </ThemeObject>

    </ThemeObject>

    <ThemeObject type="rect">
        <Colors bg="#ffff00"/>
        <Position y="%MAX_POSITION%"/>
        <Size width="60" height="120"/>

        <ThemeObject type="rect">
            <Colors bg="#ff0000"/>
            <Position x="%MID_POSITION%" y="10"/>
            <Size width="20"/>
        </ThemeObject>

    </ThemeObject>

</ThemeObject>

The red areas are not the same, whereas they have the same definition. That is because of their parent yellow area, on which their position and their size are computed.

3.7.3. Window shapes.

Shapes define regions that are subtracted to the original surface of the target. Basically, their main aim is to produce non rectangular windows.

Thus, the Shape tag can have two attributes:

xsi:type : type of the shape.
operation: if the value is 'subtract', then the shape is subtracted to the region subtracted to the final surface (<-> the shape is added).

By default, the operation attribute is not used.

Four types of shapes are supported.

The placebo_shape type is an empty theme shape. It aims to only contain other theme shapes.

The rect_shape type defines a rectangular shape. There is no need of extra tags other than the Position and Size ones (if needed).

For instance:

<Shape xsi:type="rect_shape">
<Position x="5" y="5"/>
<Size width="%MAX_SIZE% - 5" height="%MAX_SIZE% - 5"/>
</Shape>

The poly_shape type creates a polygonal shapes. It uses as many Point tags as wanted, which are only renamed Position tags.

For instance:

<Shape xsi:type="rect_shape">
    <Size width="66" height="77"/>
    <Point x="5" y="5"/>
    <Point x="15" y="25"/>
    <Point x="45" y="33"/>
</Shape>

Finally, the img_shape type loads the alpha layer of a picture to build a shape. Like for theme objects, it drives to two extra tags:

Source : filename of the picture to load.
Scale : policy to follow when the available size is not equal to the picture size.

Right values for this last tag are:

width : only the width is preserved.
height : only the height is preserved.
center : not yet supported.
scretch : the picture gets scretch ; this is the default choice.
tiled : the resulting picture is tiled.

For instance:

<Shape xsi:type="img_shape">
<Source>picture.png</Source>
<Scale>tiled</Scale>
</Shape>

3.7.4. Rendering objects.

Theme objects are small bricks for rendering. The ThemeObject tag can only have one attributes:

xsi:type : type of the object.

Five types of objects are supported.

The placebo type is an empty theme object. It aims to only contain other theme objects, or to mark some areas for further processing with its Area tag, which must have one of the following string values:

lbuttons : not yet supported.
title : refers to the titlebar string.
rbuttons : not yet supported.
menuhead : refers to the menu header caption.
menuitem : refers to the menu items caption.
apps : refers to the application name in the window switching panel.
desktops : refers to the desktop name in the corresponding panel.

The line type draws line or polygons. It uses as many Point tags as wanted, which are only renamed Position tags. The rendering color is provided by the border attribute of a Colors tag.

For instance:

<ThemeObject xsi:type="line">
    <Colors border="#000000"/>
    <Point x="2" y="2"/>
    <Point x="%MAX_POSITION%" y="10"/>
</ThemeObject>

The rect type draws a rectangle, filled or not. It uses the bg and border attributes of a Colors tag for rendering. If one of these attributes is missing, then the background or the border (depending on the attribute) is skipped.

For instance:

<ThemeObject xsi:type="rect">
    <Colors bg="#000000" border="#00ff00"/>
    <Position x="1" y="1"/>
    <Size width="%MAX_SIZE% - 1" height="%MAX_SIZE% - 1"/>
</ThemeObject>

The img type draws pictures. Like for theme shapes, it drives to two extra tags:

Source : filename of the picture to load.
Scale : policy to follow when the available size is not equal to the picture size.

Right values for this last tag are:

width : only the width is preserved.
height : only the height is preserved.
center : not yet supported.
scretch : the picture gets scretch ; this is the default choice.
tiled : the resulting picture is tiled.

For instance:

<ThemeObject xsi:type="img">
<Source>picture.png</Source>
</ThemeObject>

Finally, the gradient type defines gradients. Such object relays on several Point tags, which contains all the properties of the Position tag, plus one extra attribute named color which gives the current color for the current point.

For instance:

<ThemeObject xsi:type="gradient">
    <Position x="1" y="1"/>
    <Size width="%MAX_SIZE% - 1" height="%MAX_SIZE% - 1"/>
    <Point color="#ff0000"/>
    <Point color="#0000ff" x="%MAX_POSITION%" y="%MAX_POSITION%"/>
</ThemeObject>

3.8. Highlight border for windows.

Highlight border definitions are located here:

<FireboxTheme>
    <HighlightBorder>
        <Normal>
        ...
        </Normal>
        <Emergency>
        ...
        </Emergency>
    </HighlightBorder>
</FireboxTheme>

The Normal tag is used during window switching, the other one in case of urgency.

Both of them can have theme shapes and theme objects.

3.9. Client window body.

At first, theme shape for non rectangular clients can be defined in the Client tag, located in:

<FireboxTheme>
    <Client>
    ...
    </Client>
</FireboxTheme>

Client bodies rendering is divided into four parts:

TitleBar : the area containing the application icon, client title and buttons.
Title : the string provided by the running application.
Body : borders surrounding the user client.
Border : client's own internal borders (often 2-pixels thick).

The Border and Body tag are exceptional cases: they are drawn on the same area. The former is drawn first, the latter second. Then, the seven client handlers are added.

Thus, even if borders are features required by user windows, there is no need to render them as the theme objects in Body can do the job.

Firebox does not check if they overlap or not.

As the parts depend on the state of their client frame, each tag contains two extra tags:

Focused : the window has the focus.
Unfocused : the window does not have the focus.

These two state tags can contain theme objects for rendering.

If the unfocussed state is not defined, the focused one is used.

For instance, a client body sample could be:

<FireboxTheme>
    <Client>
    ...
        <TitleBar>
            <Focused>
            ...
            </Focused>
        </TitleBar>
    </Client>
</FireboxTheme>

3.10. Client handlers for resizing.

In order to allow resizing with mouse, small areas are attached to each client frame. For each of these areas, a tag is defined: TopLeft, TopRight, MidLeft, MidRight, BottomLeft, BottomMid, and BottomRight.

All of them are located in:

<FireboxTheme>
    <ClientHandlers>
    ...
    </ClientHandlers>
</FireboxTheme>

As the areas depend on the state of their client frame, each tag contains two extra tags:

Focused : the window has the focus.
Unfocused : the window does not have the focus.

These two state tags can contain theme objects for rendering.

If the unfocussed state is not defined, the the focused one is used.

3.11. Client and root menus.

Menus are composed of some elements:

Main panel (Board tag).
Header entry (mainly in Head/Base tag).
Default entry (Item/Normal).
Separation (Separator tag).
Active entry (Item/Selected tag).
First entry of the list (FirstItem tag).
Last entry of the list (LastItem tag).
Arrow (see section 3.2.2).

3.11.1. Menu board.

If needed, a global theme shape and a global theme object can be defined in the Board tag:

<FireboxTheme>
    <Menu>
        <Board>
        ...
        </Board>
    </Menu>
</FireboxTheme>

3.11.2. Header entry.

The header can be defined with a theme shape and a theme object. Both of them are located in a tag called Base:

<FireboxTheme>
    <Menu>
        <Head>
            <Base>
            ...
            </Base>
        </Head>
    </Menu>
</FireboxTheme>

As the text of the entry can be surrounded by a particular rendering, it is also possible to add an extra theme object in the Caption tag:

<FireboxTheme>
    <Menu>
        <Head>
            <Caption>
            ...
            </Caption>
        </Head>
    </Menu>
</FireboxTheme>

3.11.3. Common entries.

Depending on the position of the item to be rendered, there is a fine-grained definition. Thus three tags (FirstItem, Item and LastItem) are used to draw menu items.

These definitions are located in:

<FireboxTheme>
    <Menu>
        <FirstItem>
        ...
        </FirstItem>
        <Item>
        ...
        </Item>
        <LastItem>
        ...
        </LastItem>
    </Menu>
</FireboxTheme>

NB: the FirstItem tag is not used if a menu header has already be drawn in the same menu.

NB2: for the dynamic menu, only the Item tag is used.

Depending on the state to render, theses tags can have sub tags called Selected and Normal. Each of them can contain both a theme shape and a theme object.

As the text of all these entries can be surrounded by a particular rendering, it is also possible to add an extra theme object in the ItemCaption tag:

<FireboxTheme>
    <Menu>
        <Head>
            <ItemCaption>
            ...
            </ItemCaption>
        </Head>
    </Menu>
</FireboxTheme>

3.11.4. Separator bar.

The separator bar can not always be a simple bar. Because its layout is involved in the global display of a menu, its shape has to be considered.

That is why a theme shape and a theme object may be located in the Separator tag:

<FireboxTheme>
    <Menu>
        <Separator>
        ...
        </Separator>
    </Menu>
</FireboxTheme>

3.11.5. Dynamic menu board.

As the dynamic menu shares lots of things with common menus, it does not need special part for its rendering.

Its panel background is the only item which can be customized. Thus the DMenuBoard tag allows to define it thanks to a special theme object.

This definition is located in:

<FireboxTheme>
    <Menu>
        <DMenuBoard>
        ...
        </DMenuBoard>
    </Menu>
</FireboxTheme>

3.12. Switch panels.

3.12.1. Window panel.

The WindowPanel tag describes the look of the panel shown when switching between windows.

It can contain a theme shape and a theme object ; both of them are stored in:

<FireboxTheme>
    <WindowPanel>
    ...
    </WindowPanel>
</FireboxTheme>

3.12.2. Desktop panel.

The WindowPanel tag describes the look of the panel shown when switching between desktops.

It can contain a theme shape and a theme object ; both of them are stored in:

<FireboxTheme>
    <DesktopPanel>
    ...
    </DesktopPanel>
</FireboxTheme>

3.12.3. Desktop cells.

To customize the small cells of the desktop panel, two extra theme objects can be used.

They are located in:

<FireboxTheme>
    <DesktopPanel>
        <SelectedDeskCell>
        ...
        </SelectedDeskCell>
        <DeskCell>
        ...
        </DeskCell>
    </DesktopPanel>
</FireboxTheme>

Appendix.

4.1. Default key bindings.

The key combo has the following syntax: Modifier[Modifier[Modifier...]]-Key. The available modifiers are:

S - the Shift key.
C - the Control key.
A - the Alt key.

Here are the basic default key bindings:

AS-Tab	Show the previous client window.
A-Tab	Show the next client window.
CA-Left	Move to the previous virtual desktop.
CA-Up	Move to the upper virtual desktop.
CA-Right	Move to the next virtual desktop.
CA-Down	Move to the lower virtual desktop.
A-S	Display the customized dynamic menu.
A-P	Display the dynamic menu containing all programs found in `$PATH`.
A-Return	Run a terminal using the `$TERM` environment variable.

When a normal menu is shown, the following keybindings are used by default:

Left	Select the parent menu, if any.
Up	Select the previous item, or the last one if none.
Right	Select the first child menu, if any.
Down	Select the next item, or the first one if none.
Return	Execute the selected menu item.
Escape	Hide the current menu.

Here are the default key bindings used with dynamic menus:

End	Select the last dmenu item.
Right	Select the next item, or the first one if none.
C-Right	Select the first item in the next range of items.
Left	Select the previous item, or the last one if none.
C-Left	Select the first item in the previous range of items.
Home	Select the first dmenu item.
BackSpace	Delete the last typed character.
Return	Execute the selected menu item.
Escape	Hide the dynamic menu.

4.2. XML validation schemas.

The files are located in the schemas/ directory in the main package.

The typical command to validate a XML file is to run:

$ xmllint --schema reference_schema.xsd my_file_to_validate.xml > /dev/null

For themes definitions, the right schema is theme.xsd.