[rkward-cvs] SF.net SVN: rkward: [1136] trunk/rkward

tfry at users.sourceforge.net tfry at users.sourceforge.net
Fri Jan 12 14:38:35 UTC 2007 

Revision: 1136
          http://svn.sourceforge.net/rkward/?rev=1136&view=rev
Author:   tfry
Date:     2007-01-12 06:38:35 -0800 (Fri, 12 Jan 2007)

Log Message:
-----------
Documentation for, and small fixes to dropdown plugin element (NOT for 0.4.5)

Modified Paths:
--------------
    trunk/rkward/TODO
    trunk/rkward/doc/en/writing_plugins_introduction.docbook
    trunk/rkward/rkward/plugins/plots/scatterplot.xml

Modified: trunk/rkward/TODO
===================================================================
--- trunk/rkward/TODO	2007-01-12 13:59:40 UTC (rev 1135)
+++ trunk/rkward/TODO	2007-01-12 14:38:35 UTC (rev 1136)
@@ -183,6 +183,10 @@
 	- create a spinbox, that can really deal with real numbers
 		- whenever the value changes (user entered text, or clicked up/down), the value will be translated into an integer number, and an integer exponent (in mapTextToValue(), and mapValueToText ()?)
 		- step size will be auto-adjusted logarithmically (e.g. always third most significant digit)
+	- multi-object option group:
+		- provide the set of enclosed options for each of the selected variables
+		- will provide dynamic properties based on which variables are selected in the source
+		- how to determine default values?
 
 Documentation:
 	- add an example to show rkward-specific commands (rk.print, rk.graph)

Modified: trunk/rkward/doc/en/writing_plugins_introduction.docbook
===================================================================
--- trunk/rkward/doc/en/writing_plugins_introduction.docbook	2007-01-12 13:59:40 UTC (rev 1135)
+++ trunk/rkward/doc/en/writing_plugins_introduction.docbook	2007-01-12 14:38:35 UTC (rev 1136)
@@ -405,8 +405,30 @@
 </document>
 </programlisting>
 <para>
-Finally we close the <document>-tag, and that's it. The GUI is defined. You can save the file now. But how does R-syntax get generated from the GUI-settings? I'll deal with that next.
+Finally we close the <document>-tag, and that's it. The GUI is defined. You can save the file now. But how does R-syntax get generated from the GUI-settings? I'll deal with that in the <link linkend="phptemplate">next chapter</link>.
 </para>
+
+<section id="mainxmltips">
+<title>Some considerations on GUI design</title>
+<para>
+This section contains some general considerations on which GUI elements to use where. If this is your first attempt of creating a plugin, feel free to skip over this section, as it isn't relevant to getting a basic GUI working. Come back here, later, to see, whether you can refine your plugin's GUI in some way or another.
+</para>
+
+<section id="radio_vs_checkbox_vs_dropdown">
+<title><radio> vs. <checkbox> vs. <dropdown></title>
+<para>
+The three elements <radio>, <checkbox>, <dropdown>, all serve a similar function: To select one out of a several options. Obviously, a checkbox only allows to chose between two options: checked or not checked, so you can't use it, if there are more than two options to chose from. But when to use which of the elements? Some rules of thumb:
+</para>
+<para>
+If you find yourself creating a <radio> or <dropdown> with only two options, ask yourself, whether the question is essentially a yes / no type of question. E.g. a choice between "adjust results" and "do not adjust results", or between "remove missing values" and "keep missing values". In this case a <checkbox> is the best choice: It uses little space, will have the least words of labels, and is easiest to read for the user. There are very few situations where you should chose a <radio> over a <checkbox>, when there are only two options. An example of that might be: "Method of calculation: 'pearson'/'spearman'". Here, more methods might be thinkable, and they don't really form a pair of opposites.
+</para>
+<para>
+Chosing between a <radio> and a <dropdown> is mostly a question of space. The <dropdown> has the advantage of using little space, even if there are a lot of options to chose from. On the other hand, a <radio> has the advantage of making all possible choices visible to the user at once, without clicking on the dropdown arrow. Generally, if there are six or more options to chose from, a <dropdown> is preferrable. If there are five or less options, a <radio> is the better choice.
+</para>
+</section>
+
+</section>
+
 </chapter>
 
 <chapter id="phptemplate">
@@ -1186,8 +1208,18 @@
 	</variablelist></listitem>
 </varlistentry>
 <varlistentry>
+<term><dropdown></term>
+<listitem>Defines a group of options of which one and only one can be selected at the same time, using a dropdown list. This is functionaly equivalent to a <radio>, but looks different. Requires at least two <option>-tags as direct children. No other tags are allowed as children. Attributes:
+	<variablelist>
+	<varlistentry>
+	<term><label></term>
+	<listitem>Label for the dropdown list (recommended, defaults to "Select one:")</listitem>
+	</varlistentry>
+	</variablelist></listitem>
+</varlistentry>
+<varlistentry>
 <term><option></term>
-<listitem>Can only be used as a direct child of a <radio> element. Represents one selectable option in a radio control. The <option> elements do not take an "id" attribute. Only the <radio> needs one. Attributes:
+<listitem>Can only be used as a direct child of a <radio> or <dropdown> element. Represents one selectable option in a radio control or dropdown list. The <option> elements do not take an "id" attribute. Only the parent element (<radio> or <dropdown>) needs one. Attributes:
 	<variablelist>
 	<varlistentry>
 	<term><label></term>
@@ -1195,11 +1227,11 @@
 	</varlistentry>
 	<varlistentry>
 	<term><value></term>
-	<listitem>The string value the radio will return if this option is checked (required)</listitem>
+	<listitem>The string value the parent element will return if this option is checked/selected (required)</listitem>
 	</varlistentry>
 	<varlistentry>
 	<term><checked></term>
-	<listitem>Whether the option should be checked by default "true" or "false". Only one button in a <radio> may be set to checked="true". If no button is set to checked, the first button in the radio will be checked automatically. (optional, default to "false")</listitem>
+	<listitem>Whether the option should be checked/selected by default "true" or "false". Only one button in a <radio> may be set to checked="true". If no option is set to checked, the first option in the parent element will be checked/selected automatically. (optional, default to "false")</listitem>
 	</varlistentry>
 	</variablelist></listitem>
 </varlistentry>
@@ -1485,6 +1517,20 @@
 	</variablelist></listitem>
 </varlistentry>
 <varlistentry>
+<term><dropdown></term>
+<listitem>Default property is "string"
+	<variablelist>
+	<varlistentry>
+	<term>string</term>
+	<listitem>The value of the currently selected option (string)</listitem>
+	</varlistentry>
+	<varlistentry>
+	<term>number</term>
+	<listitem>The number of the currently selected option (options are numbered top-to-bottom, starting at 0) (integer)</listitem>
+	</varlistentry>
+	</variablelist></listitem>
+</varlistentry>
+<varlistentry>
 <term><checkbox></term>
 <listitem>Default property is "state"
 	<variablelist>

Modified: trunk/rkward/rkward/plugins/plots/scatterplot.xml
===================================================================
--- trunk/rkward/rkward/plugins/plots/scatterplot.xml	2007-01-12 13:59:40 UTC (rev 1135)
+++ trunk/rkward/rkward/plugins/plots/scatterplot.xml	2007-01-12 14:38:35 UTC (rev 1136)
@@ -208,7 +208,7 @@
 	<!--type
 	-->
 		<page>
-			<radio id="type" label="Type of graphics" >
+			<dropdown id="type" label="Type of graphics" >
 				<option value="'p'" label="Plot individual points " />
 				<option value="'l'" label="Plot lines " />
 				<option value="b" label="Plot points connected by lines (both)" />
@@ -217,7 +217,7 @@
 				<option value="'s'" label="Step-function plots : the top of the vertical defines the point" />
 				<option value="'S'" label="Step-function plots : the bottom of the vertical defines the point" />
 				<option value="custoType" label="Customize" />
-			</radio>
+			</dropdown>
 			<input size="medium" id="typeCusto" label="Give a character vector eg : c('p','l')" />
 		</page>
 		<!--titre-->


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

More information about the rkward-tracker mailing list