7976bc426782c99c0879a9641fa2b94b983124b2
[xscreensaver] / hacks / config / README
1
2                               XScreenSaver
3
4             a screen saver and locker for the X window system
5                             by Jamie Zawinski
6
7                               version 4.16
8                                12-May-2004
9
10                      http://www.jwz.org/xscreensaver/
11
12 -----------------------------------------------------------------------
13
14 This directory contains XML files that describe each of the screenhacks;
15 the per-hack user interface is constructed based on the things in these
16 files.  The files are loaded at run-time by xscreensaver-demo (also
17 known as "the Control Center screensaver properties capplet".)
18
19 The tags and parameters used here are:
20
21 -----------------------------------------------------------------------
22
23   <screensaver name="PROGRAM-NAME" _label="PRETTY NAME">
24      ...
25   </screensaver>
26
27         This encloses the whole file: all of the tags described below
28         are inside this one.
29
30 -----------------------------------------------------------------------
31
32   <command arg="-SWITCH"/>
33
34         specifies that "-SWITCH" always appears on the command line.
35         You'll most often see this with "-root".
36
37 -----------------------------------------------------------------------
38
39   <boolean id="SYMBOLIC NAME"
40            _label="USER VISIBLE STRING"
41             arg-set="-SWITCH-A"
42             arg-unset="-SWITCH-B"
43            />
44
45         This creates a checkbox.
46
47         "id" is currently unused, but may eventually be used for
48         letting other widgets refer to this one.
49
50         "_label" is the string printed next to the checkbox.
51
52         "arg-set" is what to insert into the command line if the
53         box is checked.
54
55         "arg-unset" is what to insert into the command line if the
56         box is unchecked.
57
58         You will probably never specify both "arg-set" and "arg-unset",
59         because the setting that is the default should insert nothing
60         into the command line (that's what makes it the default.)
61         For example:
62
63            <boolean "foo" arg_set="-foo">
64
65         or if "foo" is the default, and must be explicity turned off,
66
67            <boolean "foo" arg_unset="-no-foo">
68
69 -----------------------------------------------------------------------
70
71   <number id="SYMBOLIC NAME"
72           type="slider"
73           arg="-SWITCH %"
74           _label="HEADING LABEL"
75           _low-label="LEFT LABEL"
76           _high-label="RIGHT LABEL"
77           low="MIN VALUE"
78           high="MAX VALUE"
79           default="DEFAULT VALUE"
80           [ convert="invert" ]
81           />
82
83         This creates a slider.
84
85         The _label is printed above the slider.  The _low-label and
86         _high-label are printed to the left and right, respectively.
87
88         If any of the numbers you type has a decimal point, then
89         the range is assumed to be a floating-point value; otherwise,
90         only integral values will be used.  So be careful about "1"
91         versus "1.0".
92
93         If convert="invert" is specified, then the value that the
94         user tweaks goes the other way from the value the command
95         line expects: e.g., if the slider goes from 10-20 and the
96         user picks 13, the converted value goes from 20-10 (and
97         would be 17.)  This is useful for converting between the
98         concepts of "delay" and "speed".
99
100         In the "arg" string, the first occurence of "%" is replaced
101         with the numeric value, when creating the command line.
102
103 -----------------------------------------------------------------------
104
105   <number id="SYMBOLIC NAME"
106           type="spinbutton"
107           arg="-SWITCH %"
108           _label="HEADING LABEL"
109           low="MIN VALUE"
110           high="MAX VALUE"
111           default="DEFAULT VALUE"
112           [ convert="invert" ]
113           />
114
115         This creates a spinbox (a text field with a number in it,
116         and up/down arrows next to it.)
117
118         Arguments are exactly like type="slider", except that
119         _low-label and _high-label are not used.  Also, _label
120         appears to the left of the box, instead of above it.
121
122 -----------------------------------------------------------------------
123
124   <select id="SYMBOLIC NAME">
125     <option id="SYMBOLIC NAME"
126             _label="USER VISIBLE STRING"
127             arg-set="-SWITCH"
128             />
129     [ ... more <options> ... ]
130   </select>
131
132         This creates a selection popup menu.
133
134         Options should have _arg-set, and never _arg-unset.
135
136         One of the menu items (the default) should have no
137         _arg-set.
138
139 -----------------------------------------------------------------------
140
141   <string id="SYMBOLIC NAME"
142            _label="USER VISIBLE STRING"
143            arg="-SWITCH %"
144            />
145
146         This creates a text entry field.  Options should be obvious.
147
148 -----------------------------------------------------------------------
149
150   <file id="SYMBOLIC NAME"
151         _label="USER VISIBLE STRING"
152         arg="-SWITCH %"
153         />
154
155         This creates a file entry field (a text field with a "Browse"
156         button next to it.)
157
158 -----------------------------------------------------------------------
159
160   <_description>
161         FREE TEXT
162   </_description>
163
164         This is the description of the hack that appears in the right
165         part of the window.  Lines are wrapped; paragraphs are separated
166         by blank lines.  Lines that begin with whitespace will not be
167         wrapped (see "munch.xml" for an example of why.)
168
169         Make sure you use "&lt;" instead of "<", etc.  Character
170         entities are allowed; HTML (and other markup) is not.
171
172 -----------------------------------------------------------------------