Merge lp:~gdesklets-desklet-team/gdesklets/develbook-control-array into lp:~gdesklets-desklet-team/gdesklets/develbook

[Joe Sapp]

Added information on using Control arrays

[lp:~gdesklets-desklet-team/gdesklets/develbook-control-array]

10. By Joe Sapp on 2010-06-18

Merged main branch

[Bjoern Koch (h.humpel)]

Looks good.

But I am just wondering if we should skip the Control IDs as we don't need them anymore:

<programlisting><![CDATA[
...
<control id="myctrl" interface="ITime" length="1"/>

<script>
 Dsp.lbl1.value = str(myctrl[0].time)
</script>
...
 ]]></programlisting>

review: Approve

=== modified file 'ChangeLog'
--- ChangeLog	2010-05-24 11:36:24 +0000
+++ ChangeLog	2010-06-18 01:30:41 +0000
@@ -14,6 +14,12 @@
 	* info.xml: updated copyright information (added missing 2009)
 	* dsp-tag-image.xml: added "saturation" attribute
 
[phone]  Joe Sapp  <[e-mail]>
+
+	* info.xml
+	* tmp.xml
+	* xibook.xml
+	* ctrl-use.xml: Added Control array information
 
 ===  0.36.2 Released   ===
 

=== modified file 'ctrl-use.xml'
--- ctrl-use.xml	2008-03-17 09:59:43 +0000
+++ ctrl-use.xml	2010-06-18 01:30:41 +0000
@@ -18,7 +18,7 @@
   ]]></programlisting>
 
   <para>The <property>id</property> attribute specifies the ID under which you
-    later want to access the control in your applet. Controls are no display
+    later want to access the control in your applet. Controls are not display
     elements, thus this ID will not be put into the
     <link linkend="script-using-dsp"><literal>Dsp</literal> namespace</link>,
     but is directly accessible.</para>
@@ -30,7 +30,7 @@
 
   <para>Controls are property-based. There are properties where you can read
     from, and properties where you can write to. You can use the
-    <application>gdesklets-shell</application> to look up the available
+    <application>gdesklets shell</application> command to look up the available
     properties of a control and their descriptions.</para>
 
   <para>By setting properties, you can e.g. change the state of a control.
@@ -64,7 +64,6 @@
 </section>
 
 
-
 <section id="ctrl-use-watch"><title>Watching Properties</title>
 
   <para>The values of properties can change from time to time. For instance,
@@ -102,4 +101,32 @@
 </section>
 
 
+<section id="ctrl-use-multiple"><title>Using Multiple Controls</title>
+
+  <para>Since controls can be considered state machines, sometimes it's useful
+    to support multiple instances of a control in a desklet. This can be done
+    by instantiating the control with the <property>length</property> property
+    explicitly set. With this set at load-time, the control will only be
+    accessible like a list and will be expandable with the 
+    <property>length</property> property. If you do not, the control may not
+    necessarily provide the <property>length</property> property, will be
+    accessible as shown above, and will not be expandable. In other words,
+    existing desklets will continue to work as they are.</para>
+
+  <programlisting><![CDATA[
+...
+<control id="myctrl" interface="ITime:9y703dqtfnv4w373caserz68r" length="1"/>
+
+<script>
+  Dsp.lbl1.value = str(myctrl[0].time)
+</script>
+...
+  ]]></programlisting>
+
+  <para>For compatibility with this feature, you should not implement a
+    <property>length</property> property in your control.</para> 
+
+</section>
+
+
 </section>

=== modified file 'info.xml'
--- info.xml	2010-05-23 23:23:27 +0000
+++ info.xml	2010-06-18 01:30:41 +0000
@@ -24,7 +24,7 @@
     </author>
   </authorgroup>
 
-  <edition>Developer's Book for gDesklets v0.36.2</edition>
+  <edition>Developer's Book for gDesklets v0.36.3(beta)</edition>
   <pubdate>2010</pubdate>
 
   <copyright>
@@ -39,7 +39,7 @@
   </copyright>
 
   <releaseinfo>
-    This book describes version 0.36.2 of the gDesklets platform.
+    This book describes version 0.36.3(beta) of the gDesklets platform.
   </releaseinfo>
 
   <legalnotice>

=== modified file 'tmp.xml'
--- tmp.xml	2010-05-24 11:36:24 +0000
+++ tmp.xml	2010-06-18 01:30:41 +0000
@@ -29,7 +29,7 @@
     </author>
   </authorgroup>
 
-  <edition>Developer's Book for gDesklets v0.36.2</edition>
+  <edition>Developer's Book for gDesklets v0.36.3(beta)</edition>
   <pubdate>2010</pubdate>
 
   <copyright>
@@ -44,7 +44,7 @@
   </copyright>
 
   <releaseinfo>
-    This book describes version 0.36.2 of the gDesklets platform.
+    This book describes version 0.36.3(beta) of the gDesklets platform.
   </releaseinfo>
 
   <legalnotice>
@@ -2867,7 +2867,7 @@
   ]]></programlisting>
 
   <para>The <property>id</property> attribute specifies the ID under which you
-    later want to access the control in your applet. Controls are no display
+    later want to access the control in your applet. Controls are not display
     elements, thus this ID will not be put into the
     <link linkend="script-using-dsp"><literal>Dsp</literal> namespace</link>,
     but is directly accessible.</para>
@@ -2879,7 +2879,7 @@
 
   <para>Controls are property-based. There are properties where you can read
     from, and properties where you can write to. You can use the
-    <application>gdesklets-shell</application> to look up the available
+    <application>gdesklets shell</application> command to look up the available
     properties of a control and their descriptions.</para>
 
   <para>By setting properties, you can e.g. change the state of a control.
@@ -2913,7 +2913,6 @@
 </section>
 
 
-
 <section id="ctrl-use-watch"><title>Watching Properties</title>
 
   <para>The values of properties can change from time to time. For instance,
@@ -2951,6 +2950,34 @@
 </section>
 
 
+<section id="ctrl-use-multiple"><title>Using Multiple Controls</title>
+
+  <para>Since controls can be considered state machines, sometimes it's useful
+    to support multiple instances of a control in a desklet. This can be done
+    by instantiating the control with the <property>length</property> property
+    explicitly set. With this set at load-time, the control will only be
+    accessible like a list and will be expandable with the 
+    <property>length</property> property. If you do not, the control may not
+    necessarily provide the <property>length</property> property, will be
+    accessible as shown above, and will not be expandable. In other words,
+    existing desklets will continue to work as they are.</para>
+
+  <programlisting><![CDATA[
+...
+<control id="myctrl" interface="ITime:9y703dqtfnv4w373caserz68r" length="1"/>
+
+<script>
+  Dsp.lbl1.value = str(myctrl[0].time)
+</script>
+...
+  ]]></programlisting>
+
+  <para>For compatibility with this feature, you should not implement a
+    <property>length</property> property in your control.</para> 
+
+</section>
+
+
 </section>
   <section xmlns:xi="http://www.w3.org/2001/XInclude" id="ctrl-write">
   <title>Writing Controls</title>

=== modified file 'xibook.xml'
--- xibook.xml	2010-05-23 23:23:27 +0000
+++ xibook.xml	2010-06-18 01:30:41 +0000
@@ -29,7 +29,7 @@
     </author>
   </authorgroup>
 
-  <edition>Developer's Book for gDesklets v0.36.2</edition>
+  <edition>Developer's Book for gDesklets v0.36.3(beta)</edition>
   <pubdate>2010</pubdate>
 
   <copyright>
@@ -43,7 +43,7 @@
   </copyright>
 
   <releaseinfo>
-    This book describes version 0.36.2 of the gDesklets platform.
+    This book describes version 0.36.3(beta) of the gDesklets platform.
   </releaseinfo>
 
   <legalnotice>