[rkward-cvs] SF.net SVN: rkward:[4467] trunk/rkward
tfry at users.sourceforge.net
tfry at users.sourceforge.net
Wed Nov 28 18:38:30 UTC 2012
Revision: 4467
http://rkward.svn.sourceforge.net/rkward/?rev=4467&view=rev
Author: tfry
Date: 2012-11-28 18:38:29 +0000 (Wed, 28 Nov 2012)
Log Message:
-----------
More documentation for the optionset (a bit more reference to come)
Modified Paths:
--------------
trunk/rkward/doc/rkwardplugins/index.docbook
trunk/rkward/rkward/plugin/rkoptionset.cpp
Modified: trunk/rkward/doc/rkwardplugins/index.docbook
===================================================================
--- trunk/rkward/doc/rkwardplugins/index.docbook 2012-11-28 13:30:25 UTC (rev 4466)
+++ trunk/rkward/doc/rkwardplugins/index.docbook 2012-11-28 18:38:29 UTC (rev 4467)
@@ -1489,7 +1489,7 @@
Sometimes you want to repeat a set of options for an arbitrary number of items. E.g. suppose you want to implement a plugin for sorting a data.frame. You may want to allow for sorting by an arbitrary number of columns (in case of ties among the first column(s)). This could simply be realized by allowing the user to select multiple variables in a <command><varslot></command> with <parameter>multi="true"</parameter>. But if you want to extend this, e.g. allowing the user to specify for each variable whether it should be converted to character / numeric, or whether sorting should be ascending or descending, you need more flexibility. Other examples would be plotting multiple lines in one plot (allowing to select object, line style, line color, etc. for each line), or specifying a mapping for recoding from a set of old values to new values.
</para>
<para>
- Enter the <command><optionset><command>. Let's look at a simple example, first:
+ Enter the <command><optionset></command>. Let's look at a simple example, first:
</para>
<programlisting>
<dialog [...]>
@@ -1529,7 +1529,7 @@
names, and <function>getList("set.gender")</function> for an array of "m"/"f" strings.
</para>
<para>
- Note that there are no restrictions on what you can place inside an <command><optionset><command>. You can even use <link linkend="embedding">embedded</link> components. Just as with any other element, all you have to do is to collect the output
+ Note that there are no restrictions on what you can place inside an <command><optionset></command>. You can even use <link linkend="embedding">embedded</link> components. Just as with any other element, all you have to do is to collect the output
variables of interest in an <command><option></command>-specification. In the case of embedded plugins, this is often a section of the "code" property. E.g.:
</para>
<programlisting>
@@ -1561,7 +1561,7 @@
defined. Only to the currently selected item in the set.
</para>
</note>
- <sect2 id="optionset_driven"/>
+ <sect2 id="optionset_driven">
<title>"Driven" optionsets</title>
<para>
So far we have considered an <command><optionset></command> that provides buttons for adding / removing items. However,
@@ -1569,7 +1569,7 @@
options for customizing some aspects of each item in an <command><optionset></command>. E.g. suppose you want to allow
the user to plot several objects inside one plot. For each object, the user should be able to specify line color.
You <emphasis>could</emphasis> solve this by placing a <command><varselector></command> and
- <command><varslot></command> inside the <command><content></content> area, allowing the user to select one item
+ <command><varslot></command> inside the <command><content></command> area, allowing the user to select one item
at a time. However, it will mean much less clicks for the user, if you use a <command><varslot multi="true"></command>
<emphasis>outside</emphasis> the <command><optionset></command>, instead. Then you will connect this selection of objects
to a so-called "driven" optionset. Here's how:
@@ -1599,10 +1599,40 @@
</dialog>
</programlisting>
<para>
- TODO</para>
+ We'll start looking at the example at the bottom. You'll note that two <command><option></command> specifications have
+ <parameter>external="true"</parameter>. This tells &rkward; that these are controlled from outside the <command><optionset></command>. Here, the sole purpose of the "varnames"-option is to provide easy-to-read labels in the
+ <command><optiondisplay></command> (it is connected to the "shortname" modifier of the property holding the selected
+ objects). The purpose of the "vars"-option is to serve as the "key" column, as specified by
+ <command><optionset keycolumn="vars"...></command>. This means that for each entry in this list, the set will offer
+ one set of options, and options are logically tied to these entries. This column is connected to the property holding the
+ selected objects in the <command><varslot></command>. I.e. for each object that is selected there, the <command><optionset></command> will allow to specify line color.
+ </para>
+ <note>
+ <para>
+ External column can also be <parameter>connect</parameter>ed to properties inside the
+ <command><content></command> region. However, it is important to note that options declared
+ <parameter>external="true"</parameter> should never be modified from inside the <command><optionset></command>, and
+ options declared <parameter>external="false"</parameter> (the default) should never be modified from outside the
+ <command><optionset></command>.
+ </para>
+ </note>
</sect2>
- <sect2 id="optionset_alternatives"/>
+ <sect2 id="optionset_alternatives">
<title>Alternatives: When not to use optionsets</title>
+ <para>
+ Optionsets are a powerful tool, but they can sometimes do more harm than good, as they add considerable complexity, both
+ from the perspective of a plugin developer, and from the perspective of a user. Thus, think twice, when using them. Here's
+ some adivce:
+ </para>
+ <itemizedlist>
+ <listitem><para>For some simple cases, the <command><matrix></command> element may provide a useful lightweight alternative.</para></listitem>
+ <listitem><para>Don't make your plugin do too much. We gave the example of using an optionset for a plugin to
+ draw several lines within one plot. But in general it is not a good idea to create a plugin that will produce individual
+ plots for each item in an optionset. Rather make the plugin produce one plot, and the user can call it multiple times.
+ </para></listitem>
+ <listitem><para>If you don't expect more than two or three items in a set, consider repeating the options, manually,
+ instead.</para></listitem>
+ </itemizedlist>
</sect2>
</sect1>
@@ -2634,6 +2664,60 @@
</varlistentry>
<varlistentry>
+<term><optionset></term>
+<listitem><para>A UI for repeating a set of options for an arbitrary number of items (<link linkend="optionset">introduction to optionsets</link>). Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><min_rows></term>
+ <listitem><para>If specified, the set will be marked invalid, unless it has at least this number of rows (optional, integer).</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><min_rows_if_any></term>
+ <listitem><para>Like min_rows, but will only be tested, if there is at least one row (optional, integer).</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><max_rows></term>
+ <listitem><para>If specified, the set will be marked invalid, unless it has at most this number of rows (optional, integer).</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><keycolumn></term>
+ <listitem><para>Id of the column to act as keycolumn. An optionset with a (valid) keycolumn will act as a "driven" optionset. An optionset with no keycolumn will allow manual insertion / removal of items. The keycolumn must be marked as external. (optional, defaults to no keycolumn).</para></listitem>
+ </varlistentry>
+ </variablelist>
+Child-elements:
+ <variablelist>
+ <varlistentry>
+ <term><option></term>
+ <listitem><para>Declares one option of the set. For each value that you want to fetch from the optionset, you must declare a separate <option>. Attributes:
+ <variablelist>
+ <varlistentry><term>id</term>
+ <listitem><para>The id of the option (required, string).</para></listitem></varlistentry>
+ <varlistentry><term>external</term>
+ <listitem><para>Set to true, if the option is controlled from outside the optionset (optional, boolean, defaults to false).</para></listitem></varlistentry>
+ <varlistentry><term>label</term>
+ <listitem><para>If given, the option will be displayed in the <optiondisply> in a column by that label (optional, string, defaults to not displayed).</para></listitem></varlistentry>
+ <varlistentry><term>connect</term>
+ <listitem><para>The property to connect this option to, given as id inside the <content>-area. For external <option>s, the corresponding value will be set to the externally set value. For regular (non-external) <option>s,
+ the corresponding row of the <option>-property, will be set when the property changes inside the content-area. (optional, string, defaults to not connected).</para></listitem></varlistentry>
+ <varlistentry><term>default</term>
+ <listitem><para>Only for external columns: The value to assume for this column, if no value is known for an entry. Rarely useful. (Optional, defaults to empty string)</para></listitem></varlistentry>
+ </variablelist>
+ </para></listitem></varlistentry>
+ <varlistentry>
+ <term><content></term>
+ <listitem><para>Declare the content / UI of the set. No attributes. All usual active, passive, and layout elements are allowed as childname elements. In addition, the following special child-elements are allowed:
+ <variablelist>
+ <varlistentry><term>optiondisplay</term>
+ <listitem><para>TODO</para></listitem></varlistentry>
+ <varlistentry><term>property</term>
+ <listitem><para>TODO</para></listitem></varlistentry>
+ </variablelist>
+ </para></listitem></varlistentry>
+ </variablelist>
+</para></listitem>
+</varlistentry>
+
+<varlistentry>
<term><browser></term>
<listitem><para>An element designed to select a single filename (or directory name). Note that this field will take any string, even though it is meant to be used for files, only:
<variablelist>
@@ -3038,6 +3122,25 @@
</varlistentry>
<varlistentry>
+ <term><optionset></term>
+ <listitem><para>No default property.
+ <variablelist>
+ <varlistentry>
+ <term>row_count</term>
+ <listitem><para>Number of items in the optionset (integer). Read-only.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>current_row</term>
+ <listitem><para>Currently active item in the optionset (integer). -1 for no active item. Read-write.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>option_ids</emphasis></term>
+ <listitem><para>For each <option> you define, a string list property will be created with the specified id.</para></listitem>
+ </varlistentry>
+ </variablelist></para></listitem>
+</varlistentry>
+
+<varlistentry>
<term><browser></term>
<listitem><para>Default property is "selection"
<variablelist>
Modified: trunk/rkward/rkward/plugin/rkoptionset.cpp
===================================================================
--- trunk/rkward/rkward/plugin/rkoptionset.cpp 2012-11-28 13:30:25 UTC (rev 4466)
+++ trunk/rkward/rkward/plugin/rkoptionset.cpp 2012-11-28 18:38:29 UTC (rev 4467)
@@ -46,7 +46,7 @@
min_rows = xml->getIntAttribute (element, "min_rows", 0, DL_INFO);
min_rows_if_any = xml->getIntAttribute (element, "min_rows_if_any", 1, DL_INFO);
- max_rows = xml->getIntAttribute (element, "max", INT_MAX, DL_INFO);
+ max_rows = xml->getIntAttribute (element, "max_rows", INT_MAX, DL_INFO);
// build UI framework
QVBoxLayout *layout = new QVBoxLayout (this);
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