Added README

2000-08-07  Bradford Hovinen  <hovinen@helixcode.com>

	* screensavers/Makefile.am (EXTRA_DIST): Added README

capplets/screensaver/ChangeLog

@@ -1,5 +1,7 @@
 2000-08-07  Bradford Hovinen  <hovinen@helixcode.com>
 
+	* screensavers/Makefile.am (EXTRA_DIST): Added README
+
 	* expr.c: Allow values of multiple types
 
 	* main.c (main): Don't initialize glade

capplets/screensaver/screensavers/Makefile.am

@@ -9,7 +9,7 @@ Screensavers_DATA = \
 	qix.xml \
 	attraction.xml
 
-EXTRA_DIST = $(Screensavers_DATA)
+EXTRA_DIST = $(Screensavers_DATA) README
 
 noinst_PROGRAMS = extract-labels
 
@@ -20,6 +20,8 @@ extract_labels_LDADD = \
 	$(GNOME_LIBS) \
 	$(GNOME_XML_LIB)
 
+BUILT_SOURCES = qix.xml.h attraction.xml.h
+
 qix.xml.h: qix.xml extract-labels
 	./extract-labels qix.xml
 attraction.xml.h: attraction.xml extract-labels

capplets/screensaver/screensavers/README

@@ -0,0 +1,89 @@
+Instructions for creating screensaver description files
+
+The files that describe screensaver configuration dialogs are in XML;
+qix.xml and attraction.xml should prove adequate examples. There is
+one XML file per screensaver, with the name "<binary>.xml" where
+<binary> is the name of the screensaver's executable binary.
+
+1. Dialog Specification
+
+Each XML file contains a set of elements describing the various dialog 
+options in order by vertical position on the dialog. The valid element 
+names are:
+
+	<command> - Mandatory arguments not configurable by the user
+	<boolean> - Flags that can be made true or false
+	<number> - Any numeric value
+	<select> - An option menu
+	<hgroup> - A horizontally-oriented group of dialog elements
+
+Each dialog element must have an attribute "id" specifying a unique
+name for the element. Elements lacking that attribute will not be
+rendered. The id may be used to refer to a particular element
+elsewhere, for example when specifying that a particular element
+should only be enabled when a boolean option is set.
+
+<command> does not actually create a widget but merely informs the
+program that a particular argument must be present on the command
+line. It takes one attribute, "arg", that specifies the argument to be 
+passed.
+
+<boolean> creates a checkbox. It requires an attribute "label" that
+specifies the text that goes with the checkbox. The optional attribute 
+"arg-set" specifies what should be written on the command line when
+the checkbox is active. The attribute "test" specifies a boolean
+expression that tests whether the option is set on the command line.
+
+<number> creates either a spin button or a slider, depending on the
+value of the attribute "type" ("spinbutton" for the former, "slider"
+for the latter). In the former case, the three mandatory attributes
+"label", "low-label", and "high-label" specify the labels that appear
+above the slider, to the left, and to the right, respectively. In the
+latter case, only "label" is meaningful, and it is not mandatory. In
+both cases, the mandatory attributes "low" and "high" specify numeric
+values for the minimum and maximum acceptable values for the
+parameter, and the optional "default" (set to the average of high and
+low if not present) specifies the default value. The attribute "arg"
+specifies the command line fragment to write out with the character
+'%' replaced by the value supplied by the user.
+
+<select> creates an option menu. The optional "label" attribute
+specifies a label to appear to the left of the option menu. It must
+contain one or more <option> elements as children. Each <option> element
+is similar to a <boolean> element described above, with a mandatory
+label, a test, and a command line fragment to be written out. If one
+option in a select element does not have a test attribute, then it is
+set if and only if the tests for all other options fail.
+
+<hgroup> arranges its children horizontally, in a GtkHBox. The
+children appear in left-to-right order. It does not require an id
+attribute. When <number>'s are placed in an <hgroup>, they always
+appear as spinbuttons, never as sliders.
+
+2. Internationalization
+
+To internationalize a screensaver description, use the program
+extract-labels present in this distribution. Run the command
+
+   ./extract-labels <filename>
+
+to produce a file <filename>.h containing a list of gettext
+macros. <filename>.h may then be placed in POTFILES.in, and a
+dependency introduced in Makefile.am, so that translators may use
+their current tools to perform translations.
+
+3. Enabling and disabling controls
+
+Some options presented to screensavers are mutually exclusive. For
+example, in the case of Qix, it makes no sense to specify solid trails
+and a nonzero spread between lines at the same time. Therefore, both
+<boolean> and <option> allow widgets to be enabled on the condition
+that they are set. The attribute "enable" lists a set of
+comma-separated ids (no whitespace) for widgets that will become
+sensitive if the option is set. In the case of <option>'s, when a
+given option is selected, the ids listed for all other <option>'s will
+be disabled before the ids listed for the selected <option> are
+enabled.
+
+Copyright (C) 2000 Helix Code, Inc.
+Written by Bradford Hovinen <hovinen@helixcode.com>

capplets/screensaver/screensavers/attraction.xml

@@ -0,0 +1,40 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+
+<screensaver name="attraction">
+    <command arg="-root"/>
+    <select id="mode">
+	<option id="balls" label="Balls" arg-set="-mode balls"/>
+	<option id="lines" label="Lines" 
+	        arg-set="-mode lines" test="mode = lines"/>
+	<option id="tails" label="Tails" 
+	        arg-set="-mode tails" test="mode = tails"/>
+	<option id="polygons" label="Polygons" 
+		arg-set="-mode polygons" test="mode = polygons"/>
+	<option id="splines" label="Splines"
+		arg-set="-mode splines" test="mode = splines"/>
+    </select>
+    <number id="threshold" label="Threshold of repulsion" 
+	    low-label="Small" high-label="Large"
+	    low="0" high="500" default="100"
+	    type="slider" arg="-threshold %"/>
+    <number id="segments" label="Length of Trail"
+	    low-label="Short" high-label="Long"
+	    low="1" high="1000" default="500"
+	    type="slider" arg="-segments %"/>
+    <number id="speed" label="Speed"
+	    low-label="Slow" high-label="Fast" type="slider" arg="-delay %" 
+	    low="0" high="20000" default="10000"
+	    from-cli-conv="20000 - var" to-cli-conv="20000 - var"/>
+    <select id="use_color">
+	<option id="color" label="Full Color"
+	        enable="number_colors,color_contrast"/>
+	<option id="mono" label="Monochrome" arg-set="-mono" test="mono"/>
+    </select>
+    <number id="number_colors" label="Number of Colors"
+	    type="spinbutton" low="1" high="400" default="200" 
+	    arg="-colors %"/>
+    <number id="color_contrast" label="Color Contrast"
+	    low-label="Low" high-label="High" type="slider"
+	    low="0" high="25" default="3" arg="-color-shift %"/>
+</screensaver>
+