diff options
-rw-r--r-- | doc/cowbell/cowbell.docbook.xml | 877 |
1 files changed, 877 insertions, 0 deletions
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 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<article> + <articleinfo> + <title>Using Cowbell</title> + <subtitle>The CSS on window borders experimental layout language</subtitle> + <author> + <firstname>Thomas</firstname> + <surname>Thurman</surname> + <affiliation><orgname>Collabora Ltd</orgname></affiliation> + </author> + </articleinfo> + + <section id="credits"> + <title>Credits</title> + + <para>Many thanks go to those without whom you would not be reading this document:</para> + + <itemizedlist> + <listitem><para><ulink url="http://www.collabora.co.uk">Collabora Ltd</ulink>, who supported this work and allowed me to + build most of it on work time;</para></listitem> + <listitem><para>Danielle Madeley, who at GUADEC 2009 + first suggested the use of CSS on + window borders.</para></listitem> + <listitem><para>Robert Staudinger, who developed libccss, which does + all the parsing and some of the rendering.</para></listitem> + <listitem><para><ulink url="http://www.hoasm.org/IVM/Tallis.html">Thomas Tallis</ulink>, whose motet + <ulink url="http://www.youtube.com/watch?v=7Cn7ZW8ts3Y"><foreignphrase lang="la">Spem in alium</foreignphrase></ulink> became + something of a signature tune for the development of this project.</para></listitem> + </itemizedlist> + </section> + +<!-- + <section> + <title>Why CSS?</title> + + <para>...</para> + + <section><title>Why not metacity-theme-n.xml?</title> + <para>...</para> + </section> + + <section><title>Why not SVG?</title> + <para>...</para> + </section> + + <section><title>What do other window managers do?</title> + <para>...</para> + </section> + + </section> +--> + + <section id="primer"> + <title>Getting started</title> + + <para> + Please bear in mind that Cowbell is still alpha quality software. + It may not always be the epitome of stability. + </para> + + <section id="example"><title>An example</title> + <para> + Let's begin with an example of a Cowbell theme file: + </para> + + <programlisting> +/* + * 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'); } +</programlisting> + + <mediaobject> + <imageobject> + <imagedata fileref="sunshine.png" format="PNG"/> + </imageobject> + <caption> + <para> + When you run this through Cowbell, the result looks like this. + </para> + </caption> + </mediaobject> + + </section> + + <section id="yoursystem"><title>How to get Cowbell on your own system</title> + + <itemizedlist> + <listitem> + <para>Download, compile, and install metacity-cowbell.</para> + </listitem> + + <listitem> + <para>Copy the contents of the + <filename>src/themes/Sunshine</filename> + directory to + <filename>~/.themes/Sunshine/cowbell/</filename>.</para> + </listitem> + + <listitem> + <para>Set the current theme to be "Sunshine" in + <filename>/apps/metacity/general/theme</filename>. + </para> + </listitem> + + <listitem> + <para>Start Metacity. If you want to ensure the stability of + your own system's environment, run Metacity inside Xephyr.</para> + </listitem> + + </itemizedlist> + + </section> + + </section> + + <section id="format"> + <title>The file format</title> + + <para> + Cowbell theme files are expressed in CSS. + CSS was originally designed for styling web pages. + If you are not familiar with CSS, please read + <ulink url="http://www.w3.org/MarkUp/Guide/Style">Dave Raggett's introduction to CSS</ulink> + before you continue reading this document. + </para> + + <para> + 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. + </para> + + <para> + The structure will always contain the same set of elements + in roughly the same relationship to one another. + Here is <ulink url="elements.svg">a diagram of those relationships</ulink>. + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="elements.png" format="PNG"/> + </imageobject> + <caption> + <para> + Relationships between + the Cowbell elements. + </para> + </caption> + </mediaobject> + + <section id="rules"><title>Rules for all elements</title> + <para>Any element can be styled using:</para> + <itemizedlist> + <listitem> + <para> + Border settings, including radius values for rounding. + However, a few border styles are not supported by libccss and + therefore not by Cowbell. + </para> + </listitem> + <listitem> + <para> + Padding settings. + </para> + </listitem> + <listitem> + <para> + Margin settings. + However, margin settings on the frame would be nonsensical + and are therefore ignored. + </para> + </listitem> + <listitem> + <para> + Background settings. + </para> + </listitem> + </itemizedlist> + </section> + + <section id="framerules"><title>Rules for the frame</title> + <para> + If you set a border radius on the frame, + the window itself will gain rounded edges. + Non-circular elliptical edges are not yet supported. + </para> + <para> + The <literal>frame</literal> element also carries + the metadata; see <xref linkend="metadata"/>. + </para> + + <para> + The frame also holds attributes: see <xref linkend="attrs"/>. + </para> + </section> + + <section id="titlerules"><title>Rules for the title</title> + <para> + The <literal>title</literal> element is the + only element which contains stylable content. + You may set values for <literal>text-align</literal>, + <literal>color</literal>, and so on. + Later, we will add support for CSS3-specific rules such as + <literal>text-shadow</literal> and + <literal>text-outline</literal>. + </para> + + <para> + The choice of font is not under theme control. + Any attempt to set it will be ignored. + </para> + + <para> + The old theme format allowed themes to give + a scaling factor for the font size (ranging + from <literal>xx-small</literal> to + <literal>xx-large</literal>). + This is no longer supported, although + perhaps it should be. + </para> + + <para> + There is currently no provision for a theme + not to show a title. This will be possible + in a future release (see <xref linkend="notitle"/>). + </para> + </section> + + <section id="buttonrules"><title>Rules for buttons</title> + <para> + Buttons may be distinguished by their class. + Here is <ulink url="buttons.svg">a diagram of the available button class names and functions:</ulink> + </para> + + <mediaobject> + <imageobject> + <imagedata fileref="buttons.png" format="PNG"/> + </imageobject> + <caption> + <para> + The available button class names and functions. + </para> + </caption> + </mediaobject> + + <para> + The order, choice, and alignment of buttons is not under theme control. + </para> + + <para> + 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 <literal>button</literal> element which specifies width and height, + and then overriding as necessary. + </para> + + <para> + If a button's width must be constrained, then + <literal>min-width</literal> or + <literal>max-width</literal> or both may be specified. + </para> + + <para> + 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 <xref linkend="gconfcss"/>). + </para> + + <para> + It is possible that extra buttons beyond the classes given above + may one day be allowed. See <xref linkend="morebuttons"/>. + </para> + + </section> + + <section id="attrs"><title>Using attributes</title> + <para> + 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: + </para> + <programlisting> + frame[is-focused="1"] area.titlebar { background-color: red; } + frame[is-focused="0"] area.titlebar { background-color: blue; } + </programlisting> + + <para> + The attributes fall into three groups: + </para> + + <itemizedlist> + <listitem><para>Power attributes say whether a particular action is possible.</para></listitem> + <listitem><para>State attributes say whether the frame is in a particular state.</para></listitem> + <listitem><para>Metadata attributes give simple information about the rendering application.</para></listitem> + </itemizedlist> + + <para> + The metadata attributes are: + </para> + + <itemizedlist> + <listitem><para><literal>wm</literal> gives the name of the window manager; Metacity sets "<literal>metacity</literal>".</para></listitem> + <listitem><para><literal>cowbell1</literal> is set to "<literal>1</literal>" for anything implementing this specification + or a superset of it.</para></listitem> + </itemizedlist> + + <para> + All the other attributes are booleans. They are set to "0" for false, and "1" for true. + </para> + + <table> + <title>State and power attributes on the frame</title> + <tgroup cols="3"> + <thead> + <row> + <entry>Action</entry> + <entry>State attribute</entry> + <entry>Power attribute</entry> + </row> + </thead> + + <tbody> + <row><entry>Show the menu</entry><entry>Not available</entry><entry><literal>can-have-menu</literal></entry></row> + <row><entry>Close</entry><entry>Not available: all windows are unclosed</entry><entry><literal>can-be-closed</literal></entry></row> + <row><entry>Maximise</entry><entry><literal>is-maximized</literal></entry><entry><literal>can-be-maximized</literal></entry></row> + <row><entry>Minimized</entry><entry>Not available: minimised windows are not decorated</entry><entry><literal>can-be-minimized</literal></entry></row> + <row><entry>Shade</entry><entry><literal>is-shaded</literal></entry><entry><literal>can-be-shaded</literal></entry></row> + <row><entry>Stick</entry><entry><literal>is-stuck</literal></entry><entry>Not available: all windows can be stuck</entry></row> + <row><entry>Above</entry><entry><literal>is-above</literal></entry><entry>Not available: all windows can float above</entry></row> + <row><entry>Horizontal resize</entry><entry>Not available</entry><entry><literal>can-be-horizontally-resized</literal></entry></row> + <row><entry>Vertical resize</entry><entry>Not available</entry><entry><literal>can-be-vertically-resized</literal></entry></row> + <row><entry>Move</entry><entry>Not available</entry><entry><literal>can-be-moved</literal></entry></row> + <row><entry>Fullscreen (rather pointless; may remove)</entry><entry><literal>is-fullscreen</literal></entry><entry>Not available</entry></row> + <row><entry>Mark as needing attention</entry><entry><literal>is-flashing</literal></entry><entry>Not available</entry></row> + </tbody> + </tgroup> + </table> + + <para> + Beware of two common mistakes with attributes: + </para> + + <itemizedlist> + <listitem><para> + Do not write + <programlisting> + frame[is-maximised] { ... } + </programlisting> + because this tests whether the frame <emphasis>has</emphasis> an attribute called + <literal>is-maximised</literal>, which it always does. + </para></listitem> + <listitem><para> + Do not write + <programlisting> + frame[is-maximised=1] { ... } + </programlisting> + because this is invalid CSS, and a conforming parser must ignore the whole rule. + Instead, write + <programlisting> + frame[is-maximised="1"] { ... } + </programlisting> + </para></listitem> + </itemizedlist> + + </section> + + <section id="urls"><title>URLs</title> + <para> + Two kinds of URLs are accepted, for example, + as arguments to <literal>background-image</literal>: + </para> + + <itemizedlist> + <listitem><para> + <literal>wm:</literal>; only in + <literal>wm:icon</literal>, which yields the + icon of the application which owns the + current window. + </para></listitem> + + <listitem><para> + <literal>file:</literal>, 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 "<literal>file:</literal>" part of the name + may be omitted. + </para></listitem> + + </itemizedlist> + + <para> + There is no access to HTTP or similar remote protocols. + </para> + + <para> + libccss appears to require the target of URLs to be + an actual file on disk. Because of this, + <literal>wm:icon</literal> always returns + the same image at present. This will be fixed in + a later release. + </para> + + <para> + See also the discussion of the Single File Doctrine + in <xref linkend="single"/>, which will affect use + of URLs. + </para> + </section> + + <section id="units"><title>Units</title> + + <para> + At present, the only unit which is known to work well + is pixels (<literal>px</literal>). + </para> + + <para> + In the future, other units may be available. Millimetres + (<literal>mm</literal>) 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. + </para> + + </section> + + </section> + + <section id="metadata"> + <title>ISO 15836 (Dublin Core) metadata</title> + + <para> + Theme metadata is specified according to ISO 15836 + (<ulink url="http://dublincore.org/">Dublin Core</ulink>). + There appears to be no prior attempt to + embed Dublin Core information into CSS, + so we need to invent a method. + </para> + + <para> + Each of the following should be set against the + <literal>frame</literal> object with no other + selectors. See the listing in <xref linkend="primer"/> + for an example. + </para> + + <para> + At some point, Cowbell will check basic metadata + information and refuse to load themes where + it is lacking. See <xref linkend="dcparse"/>. + </para> + + <section><title>Core elements which should be used</title> + <para> + <itemizedlist> + + <listitem><para><literal>-dc-title</literal>: + a human-readable title for this stylesheet. + Example: "Sunshine". + </para></listitem> + + <listitem><para><literal>-dc-description</literal>: + a human-readable description for this stylesheet. + Example: "A happy orange theme". + </para></listitem> + + <listitem><para><literal>-dc-source</literal>: + a human-readable description of the source of this stylesheet. + Example: "Original stylesheet", or "Based on a Metacity theme + by Daniel Borgmann". + </para></listitem> + + <listitem><para><literal>-dc-relation</literal>: + 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. + </para></listitem> + + <listitem><para><literal>-dc-creator</literal>: + 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.) + </para></listitem> + + <listitem><para><literal>-dc-publisher</literal>: + name or URL of the theme's publisher, if any. + </para></listitem> + + <listitem><para><literal>-dc-rights</literal>: + URL to the theme's licence. + </para></listitem> + + <listitem><para><literal>-dc-rightsholder</literal>: + name or URL of the copyright holder. + </para></listitem> + + <listitem><para><literal>-dc-date</literal>: + date of modification, in "YYYY-MM-DD" format. + This serves as a version number. + </para></listitem> + + <listitem><para><literal>-dc-identifier</literal>: + a permalink for the theme. + </para></listitem> + + <listitem><para><literal>-dc-provenance</literal>: + an explanation of the reasons for the theme's existence; + optional. + </para></listitem> + + </itemizedlist> + </para> + </section> + + <section><title>Core elements which are constant and may be omitted</title> + <itemizedlist> + <listitem><para><literal>-dc-type</literal>: always "Software".</para></listitem> + <listitem><para><literal>-dc-format</literal>: always "text/css".</para></listitem> + </itemizedlist> + </section> + + <section><title>Core elements which are not appropriate</title> + <itemizedlist> + <listitem><para><literal>-dc-subject</literal>: themes do not concern any subject.</para></listitem> + <listitem><para><literal>-dc-coverage</literal>.</para></listitem> + <listitem><para><literal>-dc-audience</literal>.</para></listitem> + <listitem><para><literal>-dc-instructionalMethod</literal>.</para></listitem> + <listitem><para><literal>-dc-accrualMethod</literal>.</para></listitem> + <listitem><para><literal>-dc-accrualPeriodicy</literal>.</para></listitem> + <listitem><para><literal>-dc-accrualPolicy</literal>.</para></listitem> + </itemizedlist> + </section> + + </section> + + <section> + <title>Contribute!</title> + + <para> + 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. + </para> + + <para> + Porting themes from other formats is also encouraged. + </para> + </section> + + <section> + <title>The future</title> + + <para>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.</para> + + <section><title>Buttons: do what I mean</title> + <para> + Almost every Cowbell CSS file contains a series of + predictable rules, one for each button: + </para> + <programlisting> + 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'); } + </programlisting> + <para> + It would make sense for Cowbell to check whether there were files named + <filename>button-*.png</filename> in the theme directory, and for each one + assume such a rule automatically. Rules in the theme would override such + implicit rules. + </para> + </section> + + <section id="single"><title>Single file doctrine</title> + <para> + 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. + </para> + + <para> + This may be accomplished by allowing Metacity to + read files out of tarballs. + </para> + + <para> + It is also possible that we can use + <ulink url="http://tools.ietf.org/html/rfc2397">data: URLs</ulink> + in order to keep all referents in the same file. + Code for this is already written but is not shipping. + </para> + + </section> + + <section id="pseudo"><title>Pseudoclasses</title> + <para> + There is currently no way for buttons to change + their appearance when pressed or prelighted. + This could clearly be achieved using the + <literal>:hover</literal> + and + <literal>:active</literal> + pseudoclasses. This functionality is not + present in the current version; it will be + in a later version. + </para> + </section> + + <section id="debug"><title>Debugging signals</title> + <para> + 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. + </para> + </section> + + <section id="frenkle"><title>Frenkle: an editor</title> + <para> + There are plans for a simple interactive editor + which will allow you to change the colours, alignment, + and so on on the fly. + </para> + </section> + + <section id="notitle"><title>Allowing the title to be absent</title> + <para> + In a future release, it will be possible for themes to + show no title. This will make themes such as + <ulink url="http://www.kryogenix.org/days/2009/01/01/my-window-theme">Prelude</ulink> + possible under Cowbell. + </para> + + <para> + This will be acheived as follows: + </para> + <programlisting> + title { display: none; } + area.titlebar { height: 15px; } + </programlisting> + <para> + The height of <literal>area.titlebar</literal> will default to some + sensible value. + </para> + </section> + + <section id="nobutton"><title>Allowing buttons to be absent</title> + <para> + Similarly, it should be possible to remove buttons using <literal>display: none;</literal>. + This would allow use of the common pattern where unfocused windows have no controls. + </para> + </section> + + <section id="dcparse"><title>Metadata parsing</title> + <para> + Metacity should parse the theme's metadata (see <xref linkend="metadata"/>) + and refuse to load a theme where it is missing or clearly erroneous. + </para> + </section> + + <section id="colours"><title>More colours</title> + <para> + At present, only literal colours can be used. We need to support colours + based on the GTK theme as well. + </para> + </section> + + <section id="cascades"><title>Cascades</title> + <para> + It may make sense to allow themes to inherit settings from other themes. + This would introduce dependency problems, however. + </para> + </section> + + <section id="filters"><title>Filters</title> + <para> + Internet Explorer has a custom CSS property called + <literal>-ms-filter</literal> that allows various + graphical effects to be added to elements. We should + do something similar. In particular, we need: + </para> + + <itemizedlist> + <listitem> + <para> + <literal>-cowbell-color</literal> 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. + </para> + </listitem> + + <listitem> + <para> + <literal>-cowbell-blur</literal> to blur an element. + This could be used to emphasise that a window is unfocused. + </para> + </listitem> + + <listitem> + <para> + <literal>-cowbell-flip</literal>, or + <literal>-cowbell-mirror</literal>, or + <literal>-cowbell-rotate</literal>, so that + images do not have to be supplied separately + for each edge or corner. + </para> + </listitem> + </itemizedlist> + + </section> + + <section id="morebuttons"><title>Extra buttons</title> + <para> + 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. + </para> + + <para> + 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. + </para> + + <para> + Some possible uses for extra buttons: + </para> + + <itemizedlist> + <listitem><para> + "Take a screenshot of this window." + </para></listitem> + <listitem><para> + "Take a screencast of this window." + </para></listitem> + <listitem><para> + "Collaborate." (Share this window with someone else + across the network.) + </para></listitem> + <listitem><para> + <ulink url="http://blogs.gnome.org/metacity/2008/12/23/notifisation/">"Notifise."</ulink> + 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. + </para></listitem> + </itemizedlist> + + <para> + In case extra buttons are in use, + themes should ensure that unknown buttons degrade + gracefully. + </para> + + </section> + + <section id="filler"><title><literal>area.filler</literal></title> + <para> + It has been suggested that an extra <literal>area</literal> + 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 <literal>area</literal> would be + <literal>filler</literal>. + </para> + + <para> + This would allow, for example, background decorations to tile + a whole number of times yet not run under the title. + </para> + </section> + + <section id="gconfcss"><title>CSS in GConf</title> + <para> + It should be possible either to give overriding CSS in GConf, + or to specify an overriding stylesheet. + </para> + </section> + + <section id="kinds"><title>Of both kinds</title> + <para> + 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. + </para> + </section> + + <section id="otherwms"><title>Other window managers</title> + <para> + 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. + </para> + </section> + + </section> + +</article> |