Instructions for creating screensaver description files

The files that describe screensaver configuration dialogs are in XML;
qix.xml and attraction.xml should prove adequate examples. There is
one XML file per screensaver, with the name "<binary>.xml" where
<binary> is the name of the screensaver's executable binary.

1. Dialog Specification

Each XML file contains a set of elements describing the various dialog 
options in order by vertical position on the dialog. The valid element 
names are:

	<command> - Mandatory arguments not configurable by the user
	<boolean> - Flags that can be made true or false
	<number> - Any numeric value
	<select> - An option menu
	<hgroup> - A horizontally-oriented group of dialog elements

Each dialog element must have an attribute "id" specifying a unique
name for the element. Elements lacking that attribute will not be
rendered. The id may be used to refer to a particular element
elsewhere, for example when specifying that a particular element
should only be enabled when a boolean option is set.

<command> does not actually create a widget but merely informs the
program that a particular argument must be present on the command
line. It takes one attribute, "arg", that specifies the argument to be 
passed.

<boolean> creates a checkbox. It requires an attribute "label" that
specifies the text that goes with the checkbox. The optional attribute 
"arg-set" specifies what should be written on the command line when
the checkbox is active. The attribute "test" specifies a boolean
expression that tests whether the option is set on the command line.

<number> creates either a spin button or a slider, depending on the
value of the attribute "type" ("spinbutton" for the former, "slider"
for the latter). In the former case, the three mandatory attributes
"label", "low-label", and "high-label" specify the labels that appear
above the slider, to the left, and to the right, respectively. In the
latter case, only "label" is meaningful, and it is not mandatory. In
both cases, the mandatory attributes "low" and "high" specify numeric
values for the minimum and maximum acceptable values for the
parameter, and the optional "default" (set to the average of high and
low if not present) specifies the default value. The attribute "arg"
specifies the command line fragment to write out with the character
'%' replaced by the value supplied by the user.

<select> creates an option menu. The optional "label" attribute
specifies a label to appear to the left of the option menu. It must
contain one or more <option> elements as children. Each <option> element
is similar to a <boolean> element described above, with a mandatory
label, a test, and a command line fragment to be written out. If one
option in a select element does not have a test attribute, then it is
set if and only if the tests for all other options fail.

<hgroup> arranges its children horizontally, in a GtkHBox. The
children appear in left-to-right order. It does not require an id
attribute. When <number>'s are placed in an <hgroup>, they always
appear as spinbuttons, never as sliders.

2. Internationalization

To internationalize a screensaver description, use the program
extract-labels present in this distribution. Run the command

   ./extract-labels <filename>

to produce a file <filename>.h containing a list of gettext
macros. <filename>.h may then be placed in POTFILES.in, and a
dependency introduced in Makefile.am, so that translators may use
their current tools to perform translations.

3. Enabling and disabling controls

Some options presented to screensavers are mutually exclusive. For
example, in the case of Qix, it makes no sense to specify solid trails
and a nonzero spread between lines at the same time. Therefore, both
<boolean> and <option> allow widgets to be enabled on the condition
that they are set. The attribute "enable" lists a set of
comma-separated ids (no whitespace) for widgets that will become
sensitive if the option is set. In the case of <option>'s, when a
given option is selected, the ids listed for all other <option>'s will
be disabled before the ids listed for the selected <option> are
enabled.

4. Boolean and arithmetic expressions

These are used in two places: the "test" attribute and two other
attributes used to perform basic arithmetic manipulation on arguments
before writing them to the command line. The syntax is similar to most 
programming languages, with `=' being the equality test. The words
`and', `or', and `not' are used as boolean connectives. Identifiers
are interpreted as the values associated with arguments on the command 
line if they are present; arguments without values are given the
boolean value true. Identifiers not present on the command line are
interpreted as literal strings.

The attributes "from-cli-conv" and "to-cli-conv", when placed in a
<number> element, convert values from those present on the command
line to those in the dialog and vice versa, respectively. They are
arithmetic expressions interpreted in the normal way, with the literal 
"var" replaced by the value to be converted. This can be used, for
example, when converting the value of the "-delay" argument to a more
meaningful value for speed.

Copyright (C) 2000 Helix Code, Inc.
Written by Bradford Hovinen <hovinen@helixcode.com>