3. The file format
Cowbell theme files are expressed in CSS. CSS was originally designed for styling web pages. If you are not familiar with CSS, please read Dave Raggett's introduction to CSS before you continue reading this document.
CSS has traditionally been used to style other documents. However, when you use CSS to style window borders, you should forget the idea of a document which you are styling. Instead, you are styling an abstract data structure.
The structure will always contain the same set of elements in roughly the same relationship to one another. Here is a diagram of those relationships.
Relationships between the Cowbell elements.
3.1. Rules for all elements
Any element can be styled using:
Border settings, including radius values for rounding. However, a few border styles are not supported by libccss and therefore not by Cowbell.
Padding settings.
Margin settings. However, margin settings on the frame would be nonsensical and are therefore ignored.
Background settings.
3.2. Rules for the frame
If you set a border radius on the frame, the window itself will gain rounded edges. Non-circular elliptical edges are not yet supported.
The frame element also carries the metadata; see Section 4.
The frame also holds attributes: see Section 3.5.
3.3. Rules for the title
The title element is the only element which contains stylable content. You may set values for text-align, color, and so on. Later, we will add support for CSS3-specific rules such as text-shadow and text-outline.
The choice of font is not under theme control. Any attempt to set it will be ignored.
The old theme format allowed themes to give a scaling factor for the font size (ranging from xx-small to xx-large). This is no longer supported, although perhaps it should be.
There is currently no provision for a theme not to show a title. This will be possible in a future release (see Section 6.6).
3.4. Rules for buttons
Buttons may be distinguished by their class. Here is a diagram of the available button class names and functions:
The available button class names and functions.
The order, choice, and alignment of buttons is not under theme control.
Buttons are the only elements whose width and height can be set in the CSS. However, these only serve to establish an aspect ratio. The height of all buttons will change if the height of the titlebar changes. It is an error not to specify width and height for a button. (In the future, they should have some sensible default.) This requirement is most easily satisfied by writing a rule for the generic button element which specifies width and height, and then overriding as necessary.
If a button's width must be constrained, then min-width or max-width or both may be specified.
The standard version of the theme format allows the user to specify a special blank button called "spacer" which does nothing. This is not supported in Cowbell. It should be possible to emulate it using CSS overrides (see Section 6.14).
It is possible that extra buttons beyond the classes given above may one day be allowed. See Section 6.12.
3.5. Using attributes
The frame is the only element which holds attributes. If you try to read the attributes of other elements, the behaviour is undefined. Instead, use the descendant selector. For example, to give the focused window a red titlebar and all others a blue titlebar:
frame[is-focused="1"] area.titlebar { background-color: red; }
frame[is-focused="0"] area.titlebar { background-color: blue; }
The attributes fall into four groups:
Power attributes say whether a particular action is possible.
State attributes say whether the frame is in a particular state.
The type attribute gives information about the type of a frame's window.
Metadata attributes give simple information about the rendering application.
The possible values for the type attribute are: normal, dialog, modal-dialog, utility, menu, and border. (It can theoretically also be unknown, but this should never happen in practice.)
The metadata attributes are:
wm gives the name of the window manager; Metacity sets "metacity".
cowbell1 is set to "1" for anything implementing this specification or a superset of it.
All the other attributes are booleans. They are set to "0" for false, and "1" for true.
Table 1. State and power attributes on the frame
| Action | State attribute | Power attribute |
|---|---|---|
| Show the menu | Not available | can-have-menu |
| Close | Not available: all windows are unclosed | can-be-closed |
| Maximise | is-maximized | can-be-maximized |
| Minimized | Not available: minimised windows are not decorated | can-be-minimized |
| Shade | is-shaded | can-be-shaded |
| Stick | is-stuck | Not available: all windows can be stuck |
| Above | is-above | Not available: all windows can float above |
| Horizontal resize | Not available | can-be-horizontally-resized |
| Vertical resize | Not available | can-be-vertically-resized |
| Move | Not available | can-be-moved |
| Fullscreen (rather pointless; may remove) | is-fullscreen | Not available |
| Mark as needing attention | is-flashing | Not available |
Beware of two common mistakes with attributes:
Do not write
frame[is-maximised] { ... }because this tests whether the frame has an attribute called is-maximised, which it always does.Do not write
frame[is-maximised=1] { ... }because this is invalid CSS, and a conforming parser must ignore the whole rule. Instead, writeframe[is-maximised="1"] { ... }
3.6. URLs
Two kinds of URLs are accepted, for example, as arguments to background-image:
wm:; only in wm:icon, which yields the icon of the application which owns the current window.
file:, for a PNG file in the same directory as the CSS file. Do not use JPEG; libccss does not like it. Do not attempt to use files from other directories. The "file:" part of the name may be omitted.
There is no access to HTTP or similar remote protocols.
libccss appears to require the target of URLs to be an actual file on disk. Because of this, wm:icon always returns the same image at present. This will be fixed in a later release.
See also the discussion of the Single File Doctrine in Section 6.2, which will affect use of URLs.
3.7. Units
At present, the only unit which is known to work well is pixels (px).
In the future, other units may be available. Millimetres (mm) would be especially useful: for example, they would permit us to add a border to all windows with a given width regardless of the screen resolution.