
                              XScreenSaver

            a screen saver and locker for the X window system
                            by Jamie Zawinski

                              version 4.08
                               18-Feb-2003

                     http://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 "foo" arg_set="-foo">

        or if "foo" is the default, and must be explicity turned off,

           <boolean "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, and never _arg-unset.

        One of the menu items (the default) should have no
        _arg-set.

-----------------------------------------------------------------------

  <string id="SYMBOLIC NAME"
           _label="USER VISIBLE STRING"
           arg="-SWITCH %"
           />

        This creates a text entry field.  Options should be obvious.

-----------------------------------------------------------------------

  <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.)

-----------------------------------------------------------------------

  <_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 "&lt;" instead of "<", etc.  Character
        entities are allowed; HTML (and other markup) is not.

-----------------------------------------------------------------------
