e7c670aa05
2001-07-18 Carlos Perelló Marín <carlos@gnome-db.org> * screensavers/*.xml: /s/label/_label, /s/low-label/_low-label/, /s/high-label/_high-label/ && removed the i18n section.
97 lines
4.8 KiB
Text
97 lines
4.8 KiB
Text
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. 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.
|
|
|
|
3. 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>
|