* New way to access uicontrols using a path containing their "Tag" and their parent...

[scilab.git] / scilab / modules / graphics / help / en_US / property / get.xml

diff --git a/scilab/modules/graphics/help/en_US/property/get.xml b/scilab/modules/graphics/help/en_US/property/get.xml
index 71cb2de..a241ccd 100644 (file)
--- a/scilab/modules/graphics/help/en_US/property/get.xml
+++ b/scilab/modules/graphics/help/en_US/property/get.xml
@@ -3,11 +3,11 @@
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
  * Copyright (C) INRIA - Djalel Abdemouche
  * Copyright (C) Digiteo - 2009 - Jean-Baptiste Silvy
- * 
+ *
  * This file must be used under the terms of the CeCILL.
  * This source file is licensed as described in the file COPYING, which
  * you should have received as part of this distribution.  The terms
- * are also available at    
+ * are also available at
  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
  *
  -->
@@ -22,6 +22,7 @@
         <title>Calling Sequence</title>
         <synopsis>h=get(prop)
             val=get(h,prop)
+            val=get(handlePath,prop)
             val=h.prop
         </synopsis>
     </refsynopsisdiv>
@@ -38,6 +39,17 @@
                 </listitem>
             </varlistentry>
             <varlistentry>
+                <term>handlePath</term>
+                <listitem>
+                    <para>
+                        A character string containing a path pointing to the graphic entity. This path is made of the graphic entity <literal>"Tag"</literal> property and the <literal>"Tag"</literal> property of its parents in the graphics hierarchy under the format <literal>"figuretag/entitytag"</literal> (when the entity is the child of a figure).
+                    </para>
+                    <para>
+                        Deeper hierarchy levels can also be used such as <literal>"figuretag/entity1tag/entity2tag/entitntag/entitytag"</literal>. Wildcards can also be used for multi-paths search. The first entity matching the path will be used.
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
                 <term>prop</term>
                 <listitem>
                     <para>character string name of the property.</para>
@@ -119,32 +131,33 @@
     </refsection>
     <refsection>
         <title>Examples</title>
-        <programlisting role="example"><![CDATA[ 
+        <para>
+          <programlisting role="example"><![CDATA[
 // for graphics entities
  clf()
-    
-// simple graphics objects  
+
+// simple graphics objects
 subplot(121);
 x=[-.2:0.1:2*%pi]';
 plot2d(x-2,x.^2);
 subplot(122);
-xrect(.2,.7,.5,.2);     
+xrect(.2,.7,.5,.2);
 xrect(.3,.8,.3,.2);
 xfarc(.25,.55,.1,.15,0,64*360);
 xfarc(.55,.55,.1,.15,0,64*360);
 xstring(0.2,.9,"Example <<A CAR>>");
- 
+
 h=get("current_entity") //get the newly object created
 h.font_size=3;
- 
-f=get("current_figure") //get the current figure 
+
+f=get("current_figure") //get the current figure
 f.figure_size
 f.figure_size=[700 500];
 f.children
 f.children(2).type
 f.children(2).children
-f.children(2).children.children.thickness=4; 
- 
+f.children(2).children.children.thickness=4;
+
 a=get("current_axes") //get the current axes
 a.children.type
 a.children.foreground //get the foreground color of a set of graphics objects
@@ -155,7 +168,23 @@ h=uicontrol('string', 'Button'); // Opens a window with a  button.
 p=get(h,'position'); // get the geometric aspect of the button
 disp('Button width: ' + string(p(3))); // print the width of the button
 close(); // close figure
+]]></programlisting>
+        </para>
+        <para>
+        <programlisting role="example"><![CDATA[
+// Using path
+f = figure("dockable", "off", "menubar", "none", "toolbar", "none", "infobar_visible", "off", "tag", "mainfig");
+frameHandle = uicontrol("parent", f, "style", "frame", "position", [200 200 190 100], "tag", "myframe");
+btnHandle = uicontrol("parent", frameHandle, "position", [20 20 150 30], "string", "button", "tag", "example");
+
+set("mainfig/myframe/example", "string", "complete path");
+get("mainfig/myframe/example", "string")
+set("mainfig/*/example", "string", "wildcard path");
+get("mainfig/*/example", "string")
+set("myframe/example", "string", "partial path");
+get("myframe/example", "string")
  ]]></programlisting>
+        </para>
     </refsection>
     <refsection role="see also">
         <title>See Also</title>