90 lines
4.2 KiB
Text
90 lines
4.2 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. 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.
|
||
|
|
|
||
|
|
Copyright (C) 2000 Helix Code, Inc.
|
||
|
|
Written by Bradford Hovinen <hovinen@helixcode.com>
|