XScreenSaver
a screen saver and locker for the X window system
by Jamie Zawinski
version 5.40
12-Aug-2018
https://www.jwz.org/xscreensaver/
-----------------------------------------------------------------------
This directory contains XML files that describe each of the screenhacks;
the per-hack user interface is constructed based on the things in these
files. The files are loaded at run-time by xscreensaver-demo (also
known as "the Control Center screensaver properties capplet".)
The tags and parameters used here are:
-----------------------------------------------------------------------
<screensaver name="PROGRAM-NAME" _label="PRETTY NAME">
...
</screensaver>
This encloses the whole file: all of the tags described below
are inside this one.
-----------------------------------------------------------------------
<command arg="-SWITCH"/>
specifies that "-SWITCH" always appears on the command line.
You'll most often see this with "-root".
-----------------------------------------------------------------------
<boolean id="SYMBOLIC NAME"
_label="USER VISIBLE STRING"
arg-set="-SWITCH-A"
arg-unset="-SWITCH-B"
/>
This creates a checkbox.
"id" is currently unused, but may eventually be used for
letting other widgets refer to this one.
"_label" is the string printed next to the checkbox.
"arg-set" is what to insert into the command line if the
box is checked.
"arg-unset" is what to insert into the command line if the
box is unchecked.
You will probably never specify both "arg-set" and "arg-unset",
because the setting that is the default should insert nothing
into the command line (that's what makes it the default.)
For example:
<boolean _label="foo" arg-set="-foo" />
or if "foo" is the default, and must be explicity turned off,
<boolean _label="foo" arg-unset="-no-foo" />
-----------------------------------------------------------------------
<number id="SYMBOLIC NAME"
type="slider"
arg="-SWITCH %"
_label="HEADING LABEL"
_low-label="LEFT LABEL"
_high-label="RIGHT LABEL"
low="MIN VALUE"
high="MAX VALUE"
default="DEFAULT VALUE"
[ convert="invert" ]
/>
This creates a slider.
The _label is printed above the slider. The _low-label and
_high-label are printed to the left and right, respectively.
If any of the numbers you type has a decimal point, then
the range is assumed to be a floating-point value; otherwise,
only integral values will be used. So be careful about "1"
versus "1.0".
If convert="invert" is specified, then the value that the
user tweaks goes the other way from the value the command
line expects: e.g., if the slider goes from 10-20 and the
user picks 13, the converted value goes from 20-10 (and
would be 17.) This is useful for converting between the
concepts of "delay" and "speed".
In the "arg" string, the first occurence of "%" is replaced
with the numeric value, when creating the command line.
-----------------------------------------------------------------------
<number id="SYMBOLIC NAME"
type="spinbutton"
arg="-SWITCH %"
_label="HEADING LABEL"
low="MIN VALUE"
high="MAX VALUE"
default="DEFAULT VALUE"
[ convert="invert" ]
/>
This creates a spinbox (a text field with a number in it,
and up/down arrows next to it.)
Arguments are exactly like type="slider", except that
_low-label and _high-label are not used. Also, _label
appears to the left of the box, instead of above it.
-----------------------------------------------------------------------
<select id="SYMBOLIC NAME">
<option id="SYMBOLIC NAME"
_label="USER VISIBLE STRING"
arg-set="-SWITCH"
/>
[ ... more <options> ... ]
</select>
This creates a selection popup menu.
Options should have arg-set (arg-unset is not used here.)
One of the menu items (the default) should have no arg-set.
Each arg-set should begin with the same switch: that is,
all the args in a given menu should look like:
-mode one
-mode two
-mode three
and not
-this
-that
-the other
-----------------------------------------------------------------------
<string id="SYMBOLIC NAME"
_label="USER VISIBLE STRING"
arg="-SWITCH %"
/>
This creates a text entry field.
-----------------------------------------------------------------------
<file id="SYMBOLIC NAME"
_label="USER VISIBLE STRING"
arg="-SWITCH %"
/>
This creates a file entry field (a text field with a "Browse"
button next to it.)
-----------------------------------------------------------------------
<xscreensaver-text />
This indicates that this screen saver displays text via the
"xscreensaver-text" program.
In the X11 version, this tag does nothing: the text-related
preferences are in the main Screen Saver Preferences window,
not in the per-display-mode preferences.
In the MacOS version, the text-related preferences appear
in this pane, and this tag emits those several controls.
-----------------------------------------------------------------------
<xscreensaver-image />
This indicates that this screen saver displays images via the
"xscreensaver-getimage" program.
In the X11 version, this tag does nothing: the image-loading
and screen-grabbing-related preferences are in the main
Screen Saver Preferences window, not in the per-display-mode
preferences.
In the MacOS version, the image-related preferences appear
in this pane, and this tag emits those several controls.
-----------------------------------------------------------------------
<xscreensaver-updater />
Where to position the "Check for Updates" options.
This is used on MacOS and ignored on X11.
-----------------------------------------------------------------------
<video href="URL" />
A link to a Youtube preview of this screen saver.
-----------------------------------------------------------------------
<hgroup>
[ ... <boolean>s ... ]
[ ... <number>s ... ]
[ ... <select>s ... ]
[ ... <string>s ... ]
[ ... <file>s ... ]
[ ... <vgroup>s ... ]
</hgroup>
A horizontal group of widgets/groups. No more than 4 widgets
or groups should be used in a row.
-----------------------------------------------------------------------
<vgroup>
[ ... <boolean>s ... ]
[ ... <number>s ... ]
[ ... <select>s ... ]
[ ... <string>s ... ]
[ ... <file>s ... ]
[ ... <hgroup>s ... ]
</vgroup>
A vertical group of widgets/groups. No more than 10 widgets
or groups should be used in a column.
Since the default alignment of widgets is a column, the
<vgroup> element is only of use inside an <hgroup> element.
-----------------------------------------------------------------------
<_description>
FREE TEXT
</_description>
This is the description of the hack that appears in the right
part of the window. Lines are wrapped; paragraphs are separated
by blank lines. Lines that begin with whitespace will not be
wrapped (see "munch.xml" for an example of why.)
Make sure you use "<" instead of "<", etc. Character
entities are allowed; HTML (and other markup) is not.
-----------------------------------------------------------------------
If you are DTD-minded, you may also find the included files "xss.dtd"
and "xss.xsd" useful.
-----------------------------------------------------------------------
