From 40fe2471d4f0e9b09e437e3f899e992655da5d0f Mon Sep 17 00:00:00 2001 From: Thomas Thurman Date: Thu, 29 Oct 2009 15:12:00 -0400 Subject: cowbell docs --- doc/cowbell/cowbell.docbook.xml | 877 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 877 insertions(+) create mode 100644 doc/cowbell/cowbell.docbook.xml diff --git a/doc/cowbell/cowbell.docbook.xml b/doc/cowbell/cowbell.docbook.xml new file mode 100644 index 00000000..3a5d428e --- /dev/null +++ b/doc/cowbell/cowbell.docbook.xml @@ -0,0 +1,877 @@ + + +
+ + Using Cowbell + The CSS on window borders experimental layout language + + Thomas + Thurman + Collabora Ltd + + + +
+ Credits + + Many thanks go to those without whom you would not be reading this document: + + + Collabora Ltd, who supported this work and allowed me to + build most of it on work time; + Danielle Madeley, who at GUADEC 2009 + first suggested the use of CSS on + window borders. + Robert Staudinger, who developed libccss, which does + all the parsing and some of the rendering. + Thomas Tallis, whose motet + Spem in alium became + something of a signature tune for the development of this project. + +
+ + + +
+ Getting started + + + Please bear in mind that Cowbell is still alpha quality software. + It may not always be the epitome of stability. + + +
An example + + Let's begin with an example of a Cowbell theme file: + + + +/* + * METACITY CSS SUNSHINE THEME + * Author: Thomas Thurman + * Design: Firinel Thurman + * Copyright (c) 2009 Collabora Ltd + * Released under the GNU GPL v2 or any later version at your option. + */ + +frame { + + -dc-title: "Sunshine"; + -dc-description: "A simple orange theme"; + -dc-creator: "Thomas Thurman"; + -dc-contributor: "Firinel Thurman"; + -dc-publisher: "The GNOME Foundation"; + -dc-rights: "http://www.gnu.org/licenses/gpl-2.0.html"; + -dc-rightsholder: "Collabora Ltd"; + -dc-date: "2009-10-28"; + -dc-identifier: "http://blogs.gnome.org/metacity/2009/10/29/sunshine/"; + + border-radius: 3px; + background-color: #c37004; + border: 1px #000 solid; +} + +title { + color: #ffce63; + text-align: left; +} + +area.titlebar { + border-top: 2px; + border-bottom: 2px; +} + +button { + width: 200px; + height: 200px; + + background-image: url('blank.png'); + background-size: contain; + + margin-left-width: 5px; + margin-right-width: 5px; +} + +button.menu { background-image: url('menu.png'); } +button.close { background-image: url('close.png'); } +button.maximize { background-image: url('max.png'); } +button.minimize { background-image: url('min.png'); } +button.shade { background-image: url('shade.png'); } +button.stick { background-image: url('stick.png'); } +button.above { background-image: url('above.png'); } + + + + + + + + + When you run this through Cowbell, the result looks like this. + + + + +
+ +
How to get Cowbell on your own system + + + + Download, compile, and install metacity-cowbell. + + + + Copy the contents of the + src/themes/Sunshine + directory to + ~/.themes/Sunshine/cowbell/. + + + + Set the current theme to be "Sunshine" in + /apps/metacity/general/theme. + + + + + Start Metacity. If you want to ensure the stability of + your own system's environment, run Metacity inside Xephyr. + + + + +
+ +
+ +
+ 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. + + + + +
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. + + + +
+ +
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 . + + + + The frame also holds attributes: see . + +
+ +
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 ). + +
+ +
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 ). + + + + It is possible that extra buttons beyond the classes given above + may one day be allowed. See . + + +
+ +
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 three groups: + + + + Power attributes say whether a particular action is possible. + State attributes say whether the frame is in a particular state. + Metadata attributes give simple information about the rendering application. + + + + 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. + + + + State and power attributes on the frame + + + + Action + State attribute + Power attribute + + + + + Show the menuNot availablecan-have-menu + CloseNot available: all windows are unclosedcan-be-closed + Maximiseis-maximizedcan-be-maximized + MinimizedNot available: minimised windows are not decoratedcan-be-minimized + Shadeis-shadedcan-be-shaded + Stickis-stuckNot available: all windows can be stuck + Aboveis-aboveNot available: all windows can float above + Horizontal resizeNot availablecan-be-horizontally-resized + Vertical resizeNot availablecan-be-vertically-resized + MoveNot availablecan-be-moved + Fullscreen (rather pointless; may remove)is-fullscreenNot available + Mark as needing attentionis-flashingNot 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, write + + frame[is-maximised="1"] { ... } + + + + +
+ +
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 , which will affect use + of URLs. + +
+ +
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. + + +
+ +
+ +
+ ISO 15836 (Dublin Core) metadata + + + Theme metadata is specified according to ISO 15836 + (Dublin Core). + There appears to be no prior attempt to + embed Dublin Core information into CSS, + so we need to invent a method. + + + + Each of the following should be set against the + frame object with no other + selectors. See the listing in + for an example. + + + + At some point, Cowbell will check basic metadata + information and refuse to load themes where + it is lacking. See . + + +
Core elements which should be used + + + + -dc-title: + a human-readable title for this stylesheet. + Example: "Sunshine". + + + -dc-description: + a human-readable description for this stylesheet. + Example: "A happy orange theme". + + + -dc-source: + a human-readable description of the source of this stylesheet. + Example: "Original stylesheet", or "Based on a Metacity theme + by Daniel Borgmann". + + + -dc-relation: + it is not clear whether this should be used to express "Requires" + or "IsBasedOn". For now, assume "IsBasedOn" and give the + permalink of the source theme, if any. + + + -dc-creator: + name or URL of the theme's creator. + (The Dublin Core specification says that names are + preferable to URLs, but URLs seem preferable in + this application.) + + + -dc-publisher: + name or URL of the theme's publisher, if any. + + + -dc-rights: + URL to the theme's licence. + + + -dc-rightsholder: + name or URL of the copyright holder. + + + -dc-date: + date of modification, in "YYYY-MM-DD" format. + This serves as a version number. + + + -dc-identifier: + a permalink for the theme. + + + -dc-provenance: + an explanation of the reasons for the theme's existence; + optional. + + + + +
+ +
Core elements which are constant and may be omitted + + -dc-type: always "Software". + -dc-format: always "text/css". + +
+ +
Core elements which are not appropriate + + -dc-subject: themes do not concern any subject. + -dc-coverage. + -dc-audience. + -dc-instructionalMethod. + -dc-accrualMethod. + -dc-accrualPeriodicy. + -dc-accrualPolicy. + +
+ +
+ +
+ Contribute! + + + You are encouraged to build CSS themes of your own, + and to look for bugs. When you do either, let us + know. We will fix the bugs and create a theme library. + + + + Porting themes from other formats is also encouraged. + +
+ +
+ The future + + There are many paths in the future of this project. + Some or all of them may be taken. + The readers are invited to advocate for any they favour, + and to suggest others. + +
Buttons: do what I mean + + Almost every Cowbell CSS file contains a series of + predictable rules, one for each button: + + + button.menu { width:200px; height:200px; background-image: url('menu.png'); } + button.close { width:200px; height:200px; background-image: url('close.png'); } + button.maximize { width:200px; height:200px; background-image: url('maximize.png'); } + button.minimize { width:200px; height:200px; background-image: url('minimize.png'); } + button.shade { width:200px; height:200px; background-image: url('shade.png'); } + button.stick { width:200px; height:200px; background-image: url('stick.png'); } + button.above { width:200px; height:200px; background-image: url('above.png'); } + + + It would make sense for Cowbell to check whether there were files named + button-*.png in the theme directory, and for each one + assume such a rule automatically. Rules in the theme would override such + implicit rules. + +
+ +
Single file doctrine + + Metacity themes are currently shipped in a zipfile + or tarball, which must be unpacked before use. + It may be more helpful if they can be used in the + shipping format. + + + + This may be accomplished by allowing Metacity to + read files out of tarballs. + + + + It is also possible that we can use + data: URLs + in order to keep all referents in the same file. + Code for this is already written but is not shipping. + + +
+ +
Pseudoclasses + + There is currently no way for buttons to change + their appearance when pressed or prelighted. + This could clearly be achieved using the + :hover + and + :active + pseudoclasses. This functionality is not + present in the current version; it will be + in a later version. + +
+ +
Debugging signals + + It would be helpful if a particular signal made + Metacity dump its parse tree of the CSS of the + current theme, and the calculated coordinates + of all the elements. This would also be useful + in writing automated tests. + +
+ +
Frenkle: an editor + + There are plans for a simple interactive editor + which will allow you to change the colours, alignment, + and so on on the fly. + +
+ +
Allowing the title to be absent + + In a future release, it will be possible for themes to + show no title. This will make themes such as + Prelude + possible under Cowbell. + + + + This will be acheived as follows: + + + title { display: none; } + area.titlebar { height: 15px; } + + + The height of area.titlebar will default to some + sensible value. + +
+ +
Allowing buttons to be absent + + Similarly, it should be possible to remove buttons using display: none;. + This would allow use of the common pattern where unfocused windows have no controls. + +
+ +
Metadata parsing + + Metacity should parse the theme's metadata (see ) + and refuse to load a theme where it is missing or clearly erroneous. + +
+ +
More colours + + At present, only literal colours can be used. We need to support colours + based on the GTK theme as well. + +
+ +
Cascades + + It may make sense to allow themes to inherit settings from other themes. + This would introduce dependency problems, however. + +
+ +
Filters + + Internet Explorer has a custom CSS property called + -ms-filter that allows various + graphical effects to be added to elements. We should + do something similar. In particular, we need: + + + + + + -cowbell-color to alter the + hue of an element. This would allow images to be + altered to fit a theme's colour scheme, even if that + colour scheme was based on GTK colours and so unknown + when the theme was written. Something similar to + this is present in the standard Metacity theme format. + + + + + + -cowbell-blur to blur an element. + This could be used to emphasise that a window is unfocused. + + + + + + -cowbell-flip, or + -cowbell-mirror, or + -cowbell-rotate, so that + images do not have to be supplied separately + for each edge or corner. + + + + +
+ +
Extra buttons + + The window manager is capable of adding other buttons than + the standard seven, but this has never been done in the past + because instructions for drawing them + would need to be added to every theme. + + + + Now that buttons are identified by their classes, + it is possible that some file format defining new buttons + could supply CSS supplemental to each theme, + describing how to draw the new button. + If the theme already described how to draw such a button, + it would take priority. + + + + Some possible uses for extra buttons: + + + + + "Take a screenshot of this window." + + + "Take a screencast of this window." + + + "Collaborate." (Share this window with someone else + across the network.) + + + "Notifise." + Some people would like to distinguish the action of closing a main window + (and quitting the application) from the action of sending a window to the + notification area, both of which are commonly done using the Close button. + + + + + In case extra buttons are in use, + themes should ensure that unknown buttons degrade + gracefully. + + +
+ +
<literal>area.filler</literal> + + It has been suggested that an extra area + could be added to fill in the space to the right of left-justified + titles, to the right of left-justified titles, and either side + of centred titles. + The class of this area would be + filler. + + + + This would allow, for example, background decorations to tile + a whole number of times yet not run under the title. + +
+ +
CSS in GConf + + It should be possible either to give overriding CSS in GConf, + or to specify an overriding stylesheet. + +
+ +
Of both kinds + + Cowbell-enabled Metacity only supports Cowbell themes, + and standard Metacity only supports standard themes. + When Cowbell is merged, it is intended that the final + version will support both kinds. + +
+ +
Other window managers + + It has always been the intention to design a method of + styling window borders using CSS which can be adopted by + multple window managers. Mutter is an obvious candidate, + but KWin and others could also be fertile targets for + ports. + +
+ +
+ +
-- cgit v1.2.1