Improve description of callback_type property in uicontrol_properties help page. 19/17019/3
Charlotte HECQUET [Tue, 11 Aug 2015 13:22:17 +0000 (15:22 +0200)]
Change-Id: I1801d891df8bdd2df8040e7daca098742f388a5b

scilab/modules/gui/help/en_US/uicontrol_properties.xml
scilab/modules/gui/help/ja_JP/uicontrol_properties.xml

index 709d272..37cec2c 100644 (file)
@@ -54,7 +54,7 @@
                 <term>Callback_Type</term>
                 <listitem>
                     <para>Scalar</para>
-                    <para>The type of callback transmitted to the uicontrol.</para>
+                    <para>The type of callback transmitted to the uicontrol (see example below).</para>
                     <itemizedlist>
                         <listitem>
                             <para>
@@ -63,7 +63,9 @@
                         </listitem>
                         <listitem>
                             <para>
-                                <literal>0</literal> or <literal>2</literal> a Scilab instruction
+                                <literal>0</literal> (by default) or <literal>2</literal> a non prioritary, interruptible Scilab instruction
+                            </para>
+                            <para>
                                 <literal>10</literal> or <literal>12</literal> a prioritary, non-interruptible Scilab instruction
                             </para>
                         </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
+    <refsection>
+        <title>Example for callback_type property</title>
+        <programlisting role="example"><![CDATA[
+function counter_start()
+    // Callback called after a click on start pushbutton
+    global Stop
+    Stop=%f;
+    while %t
+        i = evstr(get("count", "string"));
+        set("count", "string", string(i+1));
+        if Stop then
+            break
+        end
+    end
+endfunction
+
+function counter_stop()
+    // Callback called after a click on stop pushbutton
+    global Stop
+    Stop=%t
+endfunction
+
+function counter_reinit()
+    // Callback called after a click on reset pushbutton
+    Stop=%t
+    set("count", "string", "0");
+endfunction
+
+
+counter_main_fig = figure( ...
+"dockable", "off", ...
+"infobar_visible", "off", ...
+"toolbar_visible", "off", ...
+"toolbar", "none", ...
+"menubar_visible", "off", ...
+"menubar", "none", ...
+"layout", "none", ...
+"visible", "off", ...
+"resize", "off", ...
+"figure_position", [0 0], ...
+"axes_size", [400, 150], ...
+"figure_name", "Counter", ...
+"layout", "gridbag", ...
+"tag", "counter_main_figure");
+
+
+// Counter frame
+counter_frame = uicontrol(counter_main_fig, ...
+"layout", "gridbag", ...
+"style", "frame", ...
+"constraints", createConstraints("gridbag", [1, 1, 1, 1], [1, 0.5], "both"));
+
+uicontrol(counter_frame, ...
+"style", "text", ...
+"string", "Counter : ", ...
+"constraints", createConstraints("gridbag", [1, 1, 1, 1], [0.5, 1], "horizontal", "center"), ...
+"margins", [5 5 5 5], ...
+"horizontalAlignment", "center");
+
+uicontrol(counter_frame, ...
+"style", "text", ...
+"string", "0", ...
+"constraints", createConstraints("gridbag", [2, 1, 1, 1], [1, 1], "horizontal", "center"), ...
+"tag", "count", ...
+"margins", [5 5 5 5]);
+
+// Buttons frame
+buttons_frame = uicontrol(counter_main_fig, ...
+"layout", "gridbag", ...
+"style", "frame", ...
+"constraints", createConstraints("gridbag", [1, 2, 1, 1], [1, 1], "both"));
+
+// The associated callback needs to be interruptible (when clicking on stop or reset for example)
+uicontrol("parent", buttons_frame, ...
+"Style"     , "pushbutton", ...
+"String"    , "Start", ...
+"callback"  , "counter_start()", ...
+"margins", [5 5 5 5], ...
+"constraints", createConstraints("gridbag", [1, 1, 1, 1], [1, 1], "horizontal", "center"));
+
+// The associated callback needs to have priority in order to interrupt the current callback (in other words to stop the counter)
+uicontrol("parent", buttons_frame, ...
+"Style"     , "pushbutton", ...
+"String"    , "Stop", ...
+"callback"  , "counter_stop()", ...
+"callback_type", 10, ...
+"constraints", createConstraints("gridbag", [2, 1, 1, 1], [1, 1], "horizontal", "center"), ...
+"margins", [5 5 5 5]);
+
+// The same for the callback which reset the counter: it must have the priority over the callback which has started the counter
+uicontrol("parent", buttons_frame, ...
+"Style"     , "pushbutton", ...
+"String"    , "Reset", ...
+"callback"  , "counter_reinit()", ...
+"callback_type", 10, ...
+"constraints", createConstraints("gridbag", [3, 1, 1, 1], [1, 1], "horizontal", "center"), ...
+"margins", [5 5 5 5]);
+
+counter_main_fig.visible = "on";
+ ]]></programlisting>
+    </refsection>
     <refsection role="see also">
         <title>See Also</title>
         <simplelist type="inline">
         <title>History</title>
         <revhistory>
             <revision>
+                <revnumber>6.0.0</revnumber>
+                <revremark>
+                    <para>
+                        By default, callback_type property is now interruptible but non prioritary.
+                    </para>
+                </revremark>
+            </revision>
+            <revision>
                 <revnumber>5.5.0</revnumber>
                 <revremark>
                     <para>
index 21ce532..2781d64 100644 (file)
@@ -67,7 +67,7 @@
                 <term>Callback_Type</term>
                 <listitem>
                     <para>Scalar</para>
-                    <para>The type of callback transmitted to the uicontrol.</para>
+                    <para>The type of callback transmitted to the uicontrol (see example below).</para>
                     <itemizedlist>
                         <listitem>
                             <para>
@@ -76,7 +76,9 @@
                         </listitem>
                         <listitem>
                             <para>
-                                <literal>0</literal> or <literal>2</literal> a Scilab instruction
+                                <literal>0</literal> (by default) or <literal>2</literal> a non prioritary, interruptible Scilab instruction
+                            </para>
+                            <para>
                                 <literal>10</literal> or <literal>12</literal> a prioritary, non-interruptible Scilab instruction
                             </para>
                         </listitem>
             </varlistentry>
         </variablelist>
     </refsection>
+    <refsection>
+        <title>Example for callback_type property</title>
+        <programlisting role="example"><![CDATA[
+function counter_start()
+    // Callback called after a click on start pushbutton
+    global Stop
+    Stop=%f;
+    while %t
+        i = evstr(get("count", "string"));
+        set("count", "string", string(i+1));
+        if Stop then
+            break
+        end
+    end
+endfunction
+
+function counter_stop()
+    // Callback called after a click on stop pushbutton
+    global Stop
+    Stop=%t
+endfunction
+
+function counter_reinit()
+    // Callback called after a click on reset pushbutton
+    Stop=%t
+    set("count", "string", "0");
+endfunction
+
+
+counter_main_fig = figure( ...
+"dockable", "off", ...
+"infobar_visible", "off", ...
+"toolbar_visible", "off", ...
+"toolbar", "none", ...
+"menubar_visible", "off", ...
+"menubar", "none", ...
+"layout", "none", ...
+"visible", "off", ...
+"resize", "off", ...
+"figure_position", [0 0], ...
+"axes_size", [400, 150], ...
+"figure_name", "Counter", ...
+"layout", "gridbag", ...
+"tag", "counter_main_figure");
+
+
+// Counter frame
+counter_frame = uicontrol(counter_main_fig, ...
+"layout", "gridbag", ...
+"style", "frame", ...
+"constraints", createConstraints("gridbag", [1, 1, 1, 1], [1, 0.5], "both"));
+
+uicontrol(counter_frame, ...
+"style", "text", ...
+"string", "Counter : ", ...
+"constraints", createConstraints("gridbag", [1, 1, 1, 1], [0.5, 1], "horizontal", "center"), ...
+"margins", [5 5 5 5], ...
+"horizontalAlignment", "center");
+
+uicontrol(counter_frame, ...
+"style", "text", ...
+"string", "0", ...
+"constraints", createConstraints("gridbag", [2, 1, 1, 1], [1, 1], "horizontal", "center"), ...
+"tag", "count", ...
+"margins", [5 5 5 5]);
+
+// Buttons frame
+buttons_frame = uicontrol(counter_main_fig, ...
+"layout", "gridbag", ...
+"style", "frame", ...
+"constraints", createConstraints("gridbag", [1, 2, 1, 1], [1, 1], "both"));
+
+// The associated callback needs to be interruptible (when clicking on stop or reset for example)
+uicontrol("parent", buttons_frame, ...
+"Style"     , "pushbutton", ...
+"String"    , "Start", ...
+"callback"  , "counter_start()", ...
+"margins", [5 5 5 5], ...
+"constraints", createConstraints("gridbag", [1, 1, 1, 1], [1, 1], "horizontal", "center"));
+
+// The associated callback needs to have priority in order to interrupt the current callback (in other words to stop the counter)
+uicontrol("parent", buttons_frame, ...
+"Style"     , "pushbutton", ...
+"String"    , "Stop", ...
+"callback"  , "counter_stop()", ...
+"callback_type", 10, ...
+"constraints", createConstraints("gridbag", [2, 1, 1, 1], [1, 1], "horizontal", "center"), ...
+"margins", [5 5 5 5]);
+
+// The same for the callback which reset the counter: it must have the priority over the callback which has started the counter
+uicontrol("parent", buttons_frame, ...
+"Style"     , "pushbutton", ...
+"String"    , "Reset", ...
+"callback"  , "counter_reinit()", ...
+"callback_type", 10, ...
+"constraints", createConstraints("gridbag", [3, 1, 1, 1], [1, 1], "horizontal", "center"), ...
+"margins", [5 5 5 5]);
+
+counter_main_fig.visible = "on";
+ ]]></programlisting>
+    </refsection>
     <refsection role="see also">
         <title>参照</title>
         <simplelist type="inline">
         <title>履歴</title>
         <revhistory>
             <revision>
+                <revnumber>6.0.0</revnumber>
+                <revremark>
+                    <para>
+                        By default, callback_type property is now interruptible but non prioritary.
+                    </para>
+                </revremark>
+            </revision>
+            <revision>
                 <revnumber>5.5.0</revnumber>
                 <revremark>
                     <para>