[rkward-cvs] rkward/doc/en writing_plugins_introduction.docbook,1.5,1.6
Thomas Friedrichsmeier
tfry at users.sourceforge.net
Thu Mar 23 15:09:15 UTC 2006
Update of /cvsroot/rkward/rkward/doc/en
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19403
Modified Files:
writing_plugins_introduction.docbook
Log Message:
More documentation
Index: writing_plugins_introduction.docbook
===================================================================
RCS file: /cvsroot/rkward/rkward/doc/en/writing_plugins_introduction.docbook,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** writing_plugins_introduction.docbook 22 Mar 2006 21:16:08 -0000 1.5
--- writing_plugins_introduction.docbook 23 Mar 2006 15:09:13 -0000 1.6
***************
*** 649,652 ****
--- 649,683 ----
Some plugins - and as a matter of fact, the plot_options used as an example above, is one of them - are not complete by themselves. They simply do not have the GUI elements to select some important values. They are meant to be used only embedded into other plugins.
</para>
+ <para>
+ In how far is the plot_options plugin incomplete? Well, for some option settings, it needs to know the name of the objects/expressions for the x and y axes (actually it will do fine if it only has either, but it needs at least one to function properly). However, it does not have a mechansim of selecting those objects, or entering them any other way. So how does it know about them?
+ </para>
+ <para>
+ In the logic section of the plot_options plugin there are two additional lines, not covered, yet:
+ </para>
+ <programlisting>
+ <logic>
+ <external id="xvar" />
+ <external id="yvar" />
+
+ [...]
+ </logic>
+ </programlisting>
+ <para>
+ This defines two additional properties in the plot_options plugin, whose sole purpose is to be connected to some (yet unknown) properties of the embedding plugin. In the plot_options plugin those two properties are simply used like any other, and for instance there are calls to getRK("xvar") in the plot_options PHP template.
+ </para>
+ <para>
+ Now, for the incomplete plugin there is no way of knowing, where it will be embedded, and what the relevant settings in the embedding plugin will be called. So we need to add two additional lines in the embedding plugin's logic section as well:
+ </para>
+ <programlisting>
+ <logic>
+ [...]
+
+ <connnect client="plotoptions.xvar" governor="xvarslot.available" />
+ <connnect client="plotoptions.yvar" governor="yvarslot.available" />
+ </logic>
+ </programlisting>
+ <para>
+ This is nothing new in principle, we've covered <connect> statements in the <link linkend="logic">chapter of GUI logic</link>. You simply connect the values in two varlots (called "xvarslot" and "yvarslot" in this example) to the receiving "external" properties of the embedded plugin. That's it. Everything else is taken care of automatically.
+ </para>
</section>
</chapter>
***************
*** 654,657 ****
--- 685,1258 ----
<appendix id="reference">
<title>Reference</title>
+
+ <section id="propertytypes"><title>Types of properties / Modifiers</title>
+ <para>
+ At some places in this introduction we've talked about "properties" of GUI elements or otherwise. In fact there are several different types of properties. Usually you do not need to worry about this, as you can use common sense to connect any property to any other property. However, internally, there are different types of properties. What this matters for, is when fetching some special values in the PHP-template. In getRK ("id") statements you can also specify some so called "modifiers" like so: getRK ("id.modifier"). This modifier will affect, in which way the value is printed. Read on for the list of properties, and the modifiers they each make available:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>String properties</term>
+ <listitem>The most simple type of property, used to simply hold a piece of text. It does not provide any modifiers. If you attempt to fetch modified values from the PHP template, it will return the usual value, and a warning will be written to the terminal you're running rkward from.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Boolean properties</term>
+ <listitem>Properties that can either be on or off, true or false. For instance the properties created by <convert>-tags, also the property accompanying a <checkbox> (see below). The following values will be returned according to the given modifier:
+ <variablelist>
+ <varlistentry>
+ <term>No modifier ("")</term>
+ <listitem>By default the property will return the string "TRUE", if it is true, and "FALSE" otherwise. Boolean properties attached to a checkbox behave slightly differently, and return the strings you specified in the "value" and "value_unchecked" attributes.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"true"</term>
+ <listitem>Return the string as if the property was true, even if it is false</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"false"</term>
+ <listitem>Return the string as if the property was false, even if it is true</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"not"</term>
+ <listitem>Return the string as if the property held its opposite value (i.e. false if true, true if false)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"numeric"</term>
+ <listitem>Return the string "1" if the property is true, or "0" if it is false</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Integer properties</term>
+ <listitem>A property designed to hold an integer value (but of course it still returns a numeric character string to the PHP-template). It does not accept any modifiers. Used in <spinbox>es (see below)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Real number properties</term>
+ <listitem>A property designed to hold a real number value (but of course it still returns a numeric character string to the PHP-template). It does not accept any modifiers. Used in <spinbox>es (see below)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>RObject properties</term>
+ <listitem>A property designed a selection of one or more R objects. Used most porminently in varselectors and varslots. The following values will be returned according to the given modifier:
+ <variablelist>
+ <varlistentry>
+ <term>No modifier ("")</term>
+ <listitem>By default the property will the full name of the selected object. If more than one object is selected, the object names will be separated by linebreaks ("\n").</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"shortname"</term>
+ <listitem>Like above, but returns only short name(s) for the object(s). For instance an object inside a list would only be given the name it has inside the list, without the name of the list.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"label"</term>
+ <listitem>Like above, but returns the &kapp; label(s) of the object(s) (if no label availabe, this is the same as shortname)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>Code properties</term>
+ <listitem>A property held by plugins that generated code. This is important for embedding plugins, in order to embed the code generated by the embedded plugin into the code generated by the embedding (top-level) plugin. The following values will be returned according to the given modifier:
+ <variablelist>
+ <varlistentry>
+ <term>No modifier ("")</term>
+ <listitem>Returns the entire code, i.e. all the sections below concatenated to one string.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"preprocess"</term>
+ <listitem>Returns only the preprocess section of the code</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"calculate"</term>
+ <listitem>Returns only the calculate section of the code</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"printout"</term>
+ <listitem>Returns only the printout section of the code</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>"cleanup"</term>
+ <listitem>Returns only the cleanup section of the code</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="xmlelements"><title>Elements to be used in the XML description of the plugin</title>
+ <para>Properties held by the elements are listed in a <link linkend="elementproperties">separate section</link>.</para>
+
+ <section id="generalelements"><title>General elements</title>
+ <variablelist>
+ <varlistentry>
+ <term><document></term>
+ <listitem>Needs to be present in each description.xml-file as the root-node. No special function. No attributes</listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="interfaceelements"><title>Interface definitions</title>
+ <variablelist>
+ <varlistentry>
+ <term><dialog></term>
+ <listitem>Defines a dialog-type interface. Place the GUI-definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><label></term>
+ <listitem>Caption for the dialog</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><wizard></term>
+ <listitem>Defines a wizard-type interface. Place the GUI-definition inside this tag. Use only once per file, as a direct child of the document-tag. At least one of "dialog" or "wizard" tags is required for a plugin. Accepts only <page> or <embed>-tags as direct children. Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><label></term>
+ <listitem>Caption for the wizard</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="layoutelements"><title>Layout elements</title>
+ <para>All elements in this section accept an attribute id="identifierstring". This attribute is optional for all elements. It can be used, for example, to hide/disable the entire layout element and all the elements contained therein (see <link linkend="logic">chaper GUI logic</link>). The id-string may not contain "." (dot) or ";" (semicolon), and should generally be limited to alphanumeric characters and the underscore ("_"). Only the additional attributes are listed.</para>
+ <variablelist>
+ <varlistentry>
+ <term><page></term>
+ <listitem>Defines a new page inside a wizard. Only allowed as a direct child of a <wizard> element.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><row></term>
+ <listitem>All direct children of a "row" tag will be placed left-to-right.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><column></term>
+ <listitem>All direct children of a "column" tag will be placed top-to-bottom.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><frame></term>
+ <listitem>Draws a frame/box around its direct children. Can be used to visually group related options. Layout inside a frame is top-to-bottom, unless you place a <row> inside. Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><label></term>
+ <listitem>Caption for the frame (optional)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><tabbook></term>
+ <listitem>Organizes elements in a tabbook. Accepts only <tab>-tags as direct children.</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><tab></term>
+ <listitem>Defines a page in a tabbook. Place the GUI-definition for the tab inside this tag. May be used only as a direct child of a <tabbook> tag. A <tabbook> should have at least two defined tabs. Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><label></term>
+ <listitem>Caption for the tab page (required)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><text></term>
+ <listitem>Shows the text enclosed in this tag in the GUI. Linebreaks are interpreted as hard linebreaks!</listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="activeelements"><title>Active elements</title>
+ <para>All elements in this section accept an attribute id="identifierstring". This attribute is required for all elements. Only the additional attributes are listed. The id-string may not contain "." (dots).</para>
+ <variablelist>
+ <varlistentry>
+ <term><varselector></term>
+ <listitem>Provides a list of availabe objects from which the user can select one or more. Requires one or more <varslot>s as a counterpart to be useful. Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><label></term>
+ <listitem>Label for the varselector (optional, defaults to "Select variable(s)")</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varslot></term>
+ <listitem>Used in conjunction with a "varselector" to allow the user to select one or more variables. Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><label></term>
+ <listitem>Label for the varslot (recommended, defaults to "Variable:")</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><source></term>
+ <listitem>The varselector to fetch the selection from (required, unless you connect manually)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><required></term>
+ <listitem>Whether - for submitting the code - it is required that this varslot holds a valid value. See <link linkend="elementproperties">required-property</link> (optional, defaults to false)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><multi></term>
+ <listitem>Whether the varslot holds only one (default, "false"), or several objects</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><min_vars></term>
+ <listitem>Only meaningful if multi="true": Minimum number of vars to be selected for the selection to be considered valid (optional, defaults to "1")</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><min_vars_if_any></term>
+ <listitem>Only meaningful if multi="true": Some varslots may be considered valid, if, for instance, the varslot is either empty, or holds at least two values. This specifies how many variables have to be selected if any at all (2 in the example). (optional, defaults to "1")</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><max_vars></term>
+ <listitem>Only meaningful if multi="true": Maximum number of variables to select (optional, defaults to "0", which means no maximum)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><classes></term>
+ <listitem>If you specify one or more R classnames (separated by spaces (" ")), here, the varslot will only accept objects belonging to those classes (otional, <emphasis>use with great care</emphasis>, the user should not be prevented from making valid choices, and R has <emphasis>a lot</emphasis> of different classes!)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><types></term>
+ <listitem>If you specify one or more variables types (separated by spaced (" ")), here, the varslot will only accept objects of those types. Valid types are "unknown", "number", "string", "factor", "invalid". (Optional, <emphasis>use with great care</emphasis>, the user should not be prevented from making valid choices, and rkward does not always know the type of a variable)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><radio></term>
+ <listitem>Defines a group of radio-exclusive buttons (only one can be selected at a time). 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 radio control (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. Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><label></term>
+ <listitem>Label for the option (required)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><value></term>
+ <listitem>The string value the radio will return if this option is checked (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>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><checkbox></term>
+ <listitem>Defines a checkbox, i.e. a single option that can either be set to on or off. Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><label></term>
+ <listitem>Label for the checkbox (required)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><value></term>
+ <listitem>The value the checkbox will return if checked (required)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><value_unchecked></term>
+ <listitem>The value that will be returned if the checkbox is not checked (optional, defauls to "", i.e. an empty string)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><checked></term>
+ <listitem>Whether the option should be checked by default "true" or "false" (optional, default to "false")</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><spinbox></term>
+ <listitem>A spinbox in which the user can select a numeric value, using either direct keyboard input or small up/down arrows. Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><label></term>
+ <listitem>Label for the spinbox (recommend, default to "Enter value:")</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><min></term>
+ <listitem>The lowest value the user is allowed to enter in the spinbox (optional, defaults to the lowest value technically representable in the spinbox)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><max></term>
+ <listitem>The largest value the user is allowed to enter in the spinbox (optional, defaults to the highest value technically representable in the spinbox)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><initial></term>
+ <listitem>The initial value shown in the spinbox (optional, defaults to "0")</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><type></term>
+ <listitem>One of "real" or "integer". Whether the spinbox will accept real numbers or only integers (optional, defaults to "real")</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><default_precision></term>
+ <listitem>Only meaningful if the spinbox is of type="real". Specifies the default number of decimal places shown in the spinbox (only this many trailing zeros will be shown). When the user presses the up/down arrows, this decimal place will be changed. The user may still be able to enter values with a higher precision, however (see below) (optional, defaults to "2")</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><max_precision></term>
+ <listitem>Unfortunately, spinboxes do not yet accept true floating point numbers, but only numbers of a fixed precision. This specifies, how many decimal places will be available as a maximum (optional, defaults to "4")</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><formula></term>
+ <listitem>This advanced element allows the user to select a formula/set of interactions from selected variables. For instance for a GLM, this element can be used to allow the user to specify the interaction-terms in the model. Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><fixed_factors></term>
+ <listitem>The id of the varslot holding the selected fixed factors (required)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><dependent></term>
+ <listitem>The id of the varslot holding the selected dependent variable (required)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><embed></term>
+ <listitem>Embed a different plugin into this one (see <link linkend="embedding">chapter on embedding</link>). Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><component></term>
+ <listitem>The registered name of the component to embed (see <link linkend="pluginmap">chapter on registering components</link> (required)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><as_button></term>
+ <listitem>If set to "true", only a pushbutton will be placed in the embedding GUI, the embedded GUI will only be shown (in a separate window) when the pushbutton is pressed (optional, default is "false")</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><label></term>
+ <listitem>Only meaningful if as_button="true": The label of the button (recommend, default is "Options")</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="logicelements"><title>Logic section</title>
+ <variablelist>
+ <varlistentry>
+ <term><logic></term>
+ <listitem>The containing element for the logic section. All elements below are allowed only inside the <logic> element. Only one <logic> element is allowed per document, as a direct child of the <document> element. The logic section applies to both <dialog> and <wizard> GUIs in the same way.</listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><external></term>
+ <listitem>Creates a new (string) property that is supposed to be connected to an outside property if the plugin gets embedded. See <link linkend="embedding_incomplete">section on "incomplete" plugins</link>. Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><id></term>
+ <listitem>The id of the new property (required)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><convert></term>
+ <listitem>Create a new boolean properties that depends on the state of one or more different properties. Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><id></term>
+ <listitem>The id of the new property (required)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><sources></term>
+ <listitem>The ids of the properties this property will depend on. One or more properties may be specified, separated by ";" (required)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><mode></term>
+ <listitem>The mode of conversion/operation. One of "equals", "notequals", "range", "and", "or". If in mode equals, the property will only be true, if the value of all of its sources equals the attribute standard (see below). If in at mode notequals, the property will only be true, if the value of all of its sources are different from the attribute standard (see below). If in mode range, the sources have to be numeric (integer or real). The property will only be true, if all sources are in the range specified by the attributes min and max (see below). If in mode and, the sources have to be boolean properties. The property will only be true, if all the sources are true simultaniously. If in mode or, the sources have to be boolean properties. The property will only be true, if at least one of the sources is true. (required)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><standard></term>
+ <listitem>Only meaningful in modes equals or notequals: the string value to compare against (required if in one of these modes)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><min></term>
+ <listitem>Only meaningful in mode range: the minimum value to compare against (optional, defaults to the lowest floating point number representable on the machine)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><max></term>
+ <listitem>Only meaningful in mode range: the maximum value to compare against (optional, defaults to the largest floating point number representable on the machine)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><require_true></term>
+ <listitem>If set to "true", the property will become required, and will only be considered valid, if its state is true/on. Hence, if the property is false, it will block the submit button (optional, defaults to "false". <emphasis>Caution:</emphasis> If you use this, make sure the user can easily detect what's wrong, such as by showing an explanatory <text>)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><connect></term>
+ <listitem>Connects two properties. The client property will be changed whenever the governor property changes (but not the other way around!). Attributes:
+ <variablelist>
+ <varlistentry>
+ <term><client></term>
+ <listitem>The id of the client property, i.e. the property that will be adjusted (required)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><governor></term>
+ <listitem>The id of the governor property, i.e. the property that will adjusts the client property. This may include a modifier (required)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><reconcile></term>
+ <listitem>If "true", the client property will make adjust the governor property on connection in such a way that the governor property will only accept values that are also acceptable by the client (e.g. suppose the governor is a numeric property with min value "0", and the client is a numeric property with min value "100". The min of both properties will be adjusted to 100, if reconcile="true"). Generally works only for properties of the same basic type (optional, default to "false")</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ </section> <!-- Elements in main XML -->
+
+ <section id="elementproperties"><title>Properties of plugin elements</title>
+ <para>All <link linkend="layoutelements">layout elements</link>, and all <link linkend="activeelements">active elements</link> hold the following properties, accessible via "id_of_element.name_of_property":
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>visible</term>
+ <listitem>Whether the GUI element is visible or not (boolean)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>enabled</term>
+ <listitem>Whether the GUI element is enabled or not (boolean)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>required</term>
+ <listitem>Whether the GUI element is required (to hold a valid setting) or not. If you set an element to not enabled/not visible, you should also set it to not required! (boolean)</listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ In addition to this, some elements have additional properties you can connect to. Most active elements also have a "default" property whose value will be returned on calls to getRK ("..."), if no specific property was named, as described below.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><text></term>
+ <listitem>Default property is text
+ <variablelist>
+ <varlistentry>
+ <term>text</term>
+ <listitem>The text displayed (text)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varselector></term>
+ <listitem>No default property
+ <variablelist>
+ <varlistentry>
+ <term>available</term>
+ <listitem>All objects available for selection. You probably do not want to use this. Used internally (RObject)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>selected</term>
+ <listitem>The objects currently selected. You probably do not want to use this. Used internally (RObject)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><varslot></term>
+ <listitem>Default property is "available"
+ <variablelist>
+ <varlistentry>
+ <term>available</term>
+ <listitem>All objects held in the varslot (RObject)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>selected</term>
+ <listitem>Of the objects held in the varslot, those that are currently selected. You probably do not want to use this. Used internally (RObject)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>source</term>
+ <listitem>A copy of the objects selected in the corresponding varselector. You probably do not want to use this. Used internally (RObject)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><radio></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>
+ <varlistentry>
+ <term>state</term>
+ <listitem>State of the checkbox (on or off) (boolean)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><spinbox></term>
+ <listitem>Default property is either "int" or "real" depending on the spinbox's mode
+ <variablelist>
+ <varlistentry>
+ <term>int</term>
+ <listitem>Integer value held by the spinbox, or nearest integer, if in real mode (integer)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>real</term>
+ <listitem>Real value held by the spinbox (and integer, if in integer) (real)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><formula></term>
+ <listitem>Default property is "model"
+ <variablelist>
+ <varlistentry>
+ <term>model</term>
+ <listitem>The current model string (string)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>table</term>
+ <listitem>The data.frame holding the required variables. If variables from only one data.frame are used, the name of that data.frame is returned. Otherwise a new data.frame is constructed as required (string)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>labels</term>
+ <listitem>If variables from multiple data.frames are involved, their names may get mangled (for instance, if both data.frames contain a variable named "x"). This returns a list with the mangled names as indices and the descriptive label as value (string)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>fixed_factors</term>
+ <listitem>The fixed factors. You probably do not want to use this. Used internally (RObject)</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>dependent</term>
+ <listitem>The dependent variable(s). You probably do not want to use this. Used internally (RObject)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><embed></term>
+ <listitem>No default property
+ <variablelist>
+ <varlistentry>
+ <term>code</term>
+ <listitem>The code generated by the embedded plugin (code)</listitem>
+ </varlistentry>
+ </variablelist></listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="pluginmapelements"><title>Elements for use in .pluginmap files</title>
+ </section>
+ </appendix>
+
+ <appendix id="troubleshooting">
+ <title>Troubleshooting during Plugin development</title>
</appendix>
More information about the rkward-tracker
mailing list