From http://www.jwz.org/xscreensaver/xscreensaver-5.22.tar.gz
[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 5.22
8                                16-Jul-2013
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 _label="foo" arg-set="-foo" />
64
65         or if "foo" is the default, and must be explicity turned off,
66
67            <boolean _label="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 (arg-unset is not used here.)
135
136         One of the menu items (the default) should have no arg-set.
137
138         Each arg-set should begin with the same switch: that is,
139         all the args in a given menu should look like:
140
141            -mode one
142            -mode two
143            -mode three
144
145         and not
146
147            -this
148            -that
149            -the other
150
151 -----------------------------------------------------------------------
152
153   <string id="SYMBOLIC NAME"
154            _label="USER VISIBLE STRING"
155            arg="-SWITCH %"
156            />
157
158         This creates a text entry field.
159
160 -----------------------------------------------------------------------
161
162   <file id="SYMBOLIC NAME"
163         _label="USER VISIBLE STRING"
164         arg="-SWITCH %"
165         />
166
167         This creates a file entry field (a text field with a "Browse"
168         button next to it.)
169
170 -----------------------------------------------------------------------
171
172   <xscreensaver-text />
173
174         This indicates that this screen saver displays text via the
175         "xscreensaver-text" program.  
176
177         In the X11 version, this tag does nothing: the text-related
178         preferences are in the main Screen Saver Preferences window,
179         not in the per-display-mode preferences.
180
181         In the MacOS version, the text-related preferences appear
182         in this pane, and this tag emits those several controls.
183
184 -----------------------------------------------------------------------
185
186   <xscreensaver-image />
187
188         This indicates that this screen saver displays images via the
189         "xscreensaver-getimage" program.  
190
191         In the X11 version, this tag does nothing: the image-loading
192         and screen-grabbing-related preferences are in the main
193         Screen Saver Preferences window, not in the per-display-mode
194         preferences.
195
196         In the MacOS version, the image-related preferences appear
197         in this pane, and this tag emits those several controls.
198
199 -----------------------------------------------------------------------
200
201   <hgroup>
202     [ ... <boolean>s ... ]
203     [ ... <number>s ... ]
204     [ ... <select>s ... ]
205     [ ... <string>s ... ]
206     [ ... <file>s ... ]
207     [ ... <vgroup>s ... ]
208   </hgroup>
209
210         A horizontal group of widgets/groups.  No more than 4 widgets 
211         or groups should be used in a row.
212
213 -----------------------------------------------------------------------
214
215   <vgroup>
216     [ ... <boolean>s ... ]
217     [ ... <number>s ... ]
218     [ ... <select>s ... ]
219     [ ... <string>s ... ]
220     [ ... <file>s ... ]
221     [ ... <hgroup>s ... ]
222   </vgroup>
223
224         A vertical group of widgets/groups.  No more than 10 widgets 
225         or groups should be used in a column.
226         
227         Since the default alignment of widgets is a column, the 
228         <vgroup> element is only of use inside an <hgroup> element.
229
230 -----------------------------------------------------------------------
231
232   <_description>
233         FREE TEXT
234   </_description>
235
236         This is the description of the hack that appears in the right
237         part of the window.  Lines are wrapped; paragraphs are separated
238         by blank lines.  Lines that begin with whitespace will not be
239         wrapped (see "munch.xml" for an example of why.)
240
241         Make sure you use "&lt;" instead of "<", etc.  Character
242         entities are allowed; HTML (and other markup) is not.
243
244 -----------------------------------------------------------------------
245
246 If you are DTD-minded, you may also find the included files "xss.dtd"
247 and "xss.xsd" useful.
248
249 -----------------------------------------------------------------------