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

Thu Feb 1 21:19:10 UTC 2007

Revision: 1283
          http://svn.sourceforge.net/rkward/?rev=1283&view=rev
Author:   tfry
Date:     2007-02-01 13:19:10 -0800 (Thu, 01 Feb 2007)

Log Message:
-----------
Documentation for preview functionality

Modified Paths:
--------------
    trunk/rkward/ChangeLog
    trunk/rkward/doc/en/writing_plugins_introduction.docbook
    trunk/rkward/rkward/plugin/rkpreviewbox.cpp

Modified: trunk/rkward/ChangeLog
===================================================================

--- trunk/rkward/ChangeLog	2007-02-01 20:41:17 UTC (rev 1282)
+++ trunk/rkward/ChangeLog	2007-02-01 21:19:10 UTC (rev 1283)
@@ -10,7 +10,7 @@
 - analysis folder for analysis plugins (Wilcoxon and Ansari-Bradley tests moved to analysis)
 - new plugin: Ansari-Bradley two-sample test						TODO: document, make it stable
 - place internal objects .rk.rkreply and .rk.available.packages.cache into rkward package environment
-- support for preview functionality in graphing plugins					TODO: document
+- support for preview functionality in graphing plugins
 - new plugin: barplot
 - new plugin: export contents of an X11 device to several different file formats
 - plugins can now be context sensitive (e.g. work on a particular x11 device)		TODO: document

Modified: trunk/rkward/doc/en/writing_plugins_introduction.docbook
===================================================================
--- trunk/rkward/doc/en/writing_plugins_introduction.docbook	2007-02-01 20:41:17 UTC (rev 1282)
+++ trunk/rkward/doc/en/writing_plugins_introduction.docbook	2007-02-01 21:19:10 UTC (rev 1283)
@@ -41,8 +41,8 @@
      and in the FDL itself on how to use it. -->
 <legalnotice>&FDLNotice;</legalnotice>
 
-<date>2007-01-12</date>
-<releaseinfo>0.4.5.00</releaseinfo>
+<date>2007-02-01</date>
+<releaseinfo>0.4.6.00</releaseinfo>
 
 <abstract>
 <para>
@@ -833,6 +833,107 @@
 </section>
 </chapter>
 
+<chapter id="specialized_plugins">
+<title>Concepts for use in specialized plugins</title>
+<para>
+This chapter contains information on some topics that are useful only to certain classes of plugins.
+</para>
+
+<section id="preview_plots">
+	<title>Preview functionality for graphing plugins</title>
+	<para>
+A very useful feature for all plugins generating a plot / graph is to provide an automatically updating preview. To do so, you will need two things: Adding a <preview>-checkbox to your <link linkend="mainxml">GUI definition</link>, and adjusting the <link linkend="phptemplate">generated code</link> for the preview. We will deal with both in turn.
+	<para>
+	<para>
+Adding a <preview>-checkbox is simple. Just place the following somewhere in your GUI. It will take care of all the behind-the-scenes magic of creating a preview device, updaing the preview whenever the setting have changed, etc. Example:
+	<para>
+	<programlisting>
+<document>
+	[...]
+	<dialog [...]>
+		[...]
+		<preview id="preview"/>
+		[...]
+	</dialog>
+	[...]
+</document>
+	</programlisting>
+	<para>
+And that's it for the GUI definition.
+	</para>
+	<para>
+Adjusting the PHP template is a little more work. You will have to create a new function called "preview" in addition to the "preprocess", "calculate", etc. functions. This function should generate the code needed to produce the plot, and only that. Esp. no printing of headers, rk.graphics.on(), or similar calls. Below is an example of the typical pattern that you will use:
+	</para>
+	<programlisting>
+<?php
+function preprocess () {
+	// the "somepackage" is needed to create the plot
+?>
+require (somepackage)
+<? [...]
+}
+
+function calculate () {
+	// empty in this example
+}
+
+function printout () {
+	// all the real work is moved to a custom defined function doPrintout (), below
+
+	doPrintout (true);	// true in this case means: We want all the headers that should be printed in the output
+}
+
+function preview () {
+	// we call all stages of the general code. Only the printout () function need to be slightly different
+	preprocess ();
+	calculate ();
+	doPrintout (false);	// true in this case means: We want all the headers that should be printed in the output
+	cleanup ();
+}
+
+function cleanup () {
+	// empty in this example
+}
+
+function doPrintout ($final) {
+	// this function takes care of generating the code for the printout() section. If $final is set to true,
+	// it generates the full code, including headers. If $final is set to false, only the essentials will
+	// be generated.
+
+	if ($final) { ?>
+rk.header ("An example plot")
+
+rk.graph.on ()
+<	} 
+	// only the following section will be generated for $final==false
+?>
+try ({plot (5, 5)})
+<	if ($final) { ?>
+rk.graph.off ()
+	}
+<?
+}
+?>
+	</programlisting>
+	<para>
+That's it, your plugin should now be preview-enabled.
+	</para>
+</section>
+
+<section id="contextualized_plugins">
+	<title>Context-dependent plugins</title>
+
+	<section id="context_x11">
+		<title>X11 device context</title>
+	</section>
+
+	<section id="context_import">
+		<title>Import data context</title>
+	</section>
+</section>
+
+</chapter>
+
 <chapter id="pluginhelp">
 <title>Writing a help page</title>
 <para>
@@ -1390,6 +1491,16 @@
 	</varlistentry>
 	</variablelist></listitem>
 </varlistentry>
+<varlistentry>
+<term><preview></term>
+<listitem>Checkbox to toggle preview functionality (see <link linkend="preview_plots">chapter on graph previews</link>). Attributes:
+	<variablelist>
+	<varlistentry>
+	<term><label></term>
+	<listitem>Label of the box (optional, default is "Preview")</listitem>
+	</varlistentry>
+	</variablelist></listitem>
+</varlistentry>
 </variablelist>
 </section>
 
@@ -1669,6 +1780,16 @@
 	</varlistentry>
 	</variablelist></listitem>
 </varlistentry>
+<varlistentry>
+<term><preview></term>
+<listitem>Default property is "state"
+	<variablelist>
+	<varlistentry>
+	<term>state</term>
+	<listitem>Whether the preview box is checked (not necessarily whether the preview has already been shown) (boolean)</listitem>
+	</varlistentry>
+	</variablelist></listitem>
+</varlistentry>
 </variablelist>
 </section>
 

Modified: trunk/rkward/rkward/plugin/rkpreviewbox.cpp
===================================================================
--- trunk/rkward/rkward/plugin/rkpreviewbox.cpp	2007-02-01 20:41:17 UTC (rev 1282)
+++ trunk/rkward/rkward/plugin/rkpreviewbox.cpp	2007-02-01 21:19:10 UTC (rev 1283)
@@ -44,7 +44,7 @@
 
 	// create checkbox
 	QVBoxLayout *vbox = new QVBoxLayout (this, RKGlobals::spacingHint ());
-	toggle_preview_box = new QCheckBox (xml->getStringAttribute (element, "label", i18n ("Preview"), DL_WARNING), this);
+	toggle_preview_box = new QCheckBox (xml->getStringAttribute (element, "label", i18n ("Preview"), DL_INFO), this);
 	vbox->addWidget (toggle_preview_box);
 	toggle_preview_box->setChecked (preview_active);
 	connect (toggle_preview_box, SIGNAL (stateChanged (int)), this, SLOT (changedState (int)));


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


