git.hungrycats.org Git - xscreensaver/blob - 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.24
   8                                07-Dec-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   <xscreensaver-updater />
 202
 203         Where to position the "Check for Updates" options.
 204         This is used on MacOS and ignored on X11.
 205
 206 -----------------------------------------------------------------------
 207
 208   <hgroup>
 209     [ ... <boolean>s ... ]
 210     [ ... <number>s ... ]
 211     [ ... <select>s ... ]
 212     [ ... <string>s ... ]
 213     [ ... <file>s ... ]
 214     [ ... <vgroup>s ... ]
 215   </hgroup>
 216
 217         A horizontal group of widgets/groups.  No more than 4 widgets
 218         or groups should be used in a row.
 219
 220 -----------------------------------------------------------------------
 221
 222   <vgroup>
 223     [ ... <boolean>s ... ]
 224     [ ... <number>s ... ]
 225     [ ... <select>s ... ]
 226     [ ... <string>s ... ]
 227     [ ... <file>s ... ]
 228     [ ... <hgroup>s ... ]
 229   </vgroup>
 230
 231         A vertical group of widgets/groups.  No more than 10 widgets
 232         or groups should be used in a column.
 233
 234         Since the default alignment of widgets is a column, the
 235         <vgroup> element is only of use inside an <hgroup> element.
 236
 237 -----------------------------------------------------------------------
 238
 239   <_description>
 240         FREE TEXT
 241   </_description>
 242
 243         This is the description of the hack that appears in the right
 244         part of the window.  Lines are wrapped; paragraphs are separated
 245         by blank lines.  Lines that begin with whitespace will not be
 246         wrapped (see "munch.xml" for an example of why.)
 247
 248         Make sure you use "&lt;" instead of "<", etc.  Character
 249         entities are allowed; HTML (and other markup) is not.
 250
 251 -----------------------------------------------------------------------
 252
 253 If you are DTD-minded, you may also find the included files "xss.dtd"
 254 and "xss.xsd" useful.
 255
 256 -----------------------------------------------------------------------