* 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
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA - Djalel Abdemouche
5  * Copyright (C) Digiteo - 2009 - Jean-Baptiste Silvy
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"  xml:lang="en" xml:id="get">
15     <refnamediv>
16         <refname>get</refname>
17         <refpurpose>Retrieve a property value from a graphics
18             entity or an User Interface object.
19         </refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Calling Sequence</title>
23         <synopsis>h=get(prop)
24             val=get(h,prop)
25             val=get(handlePath,prop)
26             val=h.prop
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>h</term>
34                 <listitem>
35                     <para>handle, the handle of the entity to retrieve a property.
36                         <literal>h</literal> can be a vector of handles, in which case get returns
37                         the property value for all objects contained in h. <literal>h</literal> can also be <emphasis>0</emphasis> to get the root object properties.
38                     </para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>handlePath</term>
43                 <listitem>
44                     <para>
45                         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).
46                     </para>
47                     <para>
48                         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.
49                     </para>
50                 </listitem>
51             </varlistentry>
52             <varlistentry>
53                 <term>prop</term>
54                 <listitem>
55                     <para>character string name of the property.</para>
56                 </listitem>
57             </varlistentry>
58             <varlistentry>
59                 <term>val</term>
60                 <listitem>
61                     <para>value of the property.</para>
62                 </listitem>
63             </varlistentry>
64         </variablelist>
65     </refsection>
66     <refsection>
67         <title>Description</title>
68         <para>This routine can be used to retrieve the value of a specified property from a
69             graphics entity or a GUI object. In this case it is equivalent to use the dot operator on a handle.
70             For exemple, <literal>get(h,"background")</literal> is equivalent to <literal>h.background</literal>.
71         </para>
72         <para>Property names are character strings. To get the list of all existing properties
73             see <link linkend="graphics_entities">graphics_entities</link> or <link linkend="uicontrol">uicontrol</link>
74             for User Interface objects.
75         </para>
76         <para>
77             <literal>get</literal> function can be also called with only a property as argument. In this case,
78             the property must be one of the following (called with other properties names, <literal>get</literal> will return <literal>[]</literal>):
79         </para>
80         <variablelist>
81             <varlistentry>
82                 <term>current_entity or hdl</term>
83                 <listitem>
84                     <para>returns a handle on the lastly created (and still
85                         existent) entity.
86                         <literal>get('current_entity')</literal> and <literal>get('hdl')</literal> are equivalent to <link linkend="gce">gce</link>.
87                     </para>
88                 </listitem>
89             </varlistentry>
90             <varlistentry>
91                 <term>current_figure</term>
92                 <listitem>
93                     <para>returns a handle on the current graphic figure.
94                         <literal>get('current_figure')</literal> is equivalent to <link linkend="gcf">gcf</link>.
95                     </para>
96                 </listitem>
97             </varlistentry>
98             <varlistentry>
99                 <term>current_axes</term>
100                 <listitem>
101                     <para>returns a handle on the current axes entity.
102                         <literal>get('current_axes')</literal> is equivalent to <link linkend="gca">gca</link>.
103                     </para>
104                 </listitem>
105             </varlistentry>
106             <varlistentry>
107                 <term>default_figure</term>
108                 <listitem>
109                     <para>returns a handle on the default figure entity.
110                         <literal>get('default_figure')</literal> is equivalent to <link linkend="gdf">gdf</link>.
111                     </para>
112                 </listitem>
113             </varlistentry>
114             <varlistentry>
115                 <term>default_axes</term>
116                 <listitem>
117                     <para>returns a handle on the default axes entity.
118                         <literal>get('default_axes')</literal> is equivalent to <link linkend="gda">gda</link>.
119                     </para>
120                 </listitem>
121             </varlistentry>
122             <varlistentry>
123                 <term>figures_id</term>
124                 <listitem>
125                     <para>returns a row vector containing ids of all opened graphic figures.
126                         <literal>get('figures_id')</literal> is equivalent to <link linkend="winsid">winsid</link>.
127                     </para>
128                 </listitem>
129             </varlistentry>
130         </variablelist>
131     </refsection>
132     <refsection>
133         <title>Examples</title>
134         <para>
135           <programlisting role="example"><![CDATA[
136 // for graphics entities
137  clf()
138
139 // simple graphics objects
140 subplot(121);
141 x=[-.2:0.1:2*%pi]';
142 plot2d(x-2,x.^2);
143 subplot(122);
144 xrect(.2,.7,.5,.2);
145 xrect(.3,.8,.3,.2);
146 xfarc(.25,.55,.1,.15,0,64*360);
147 xfarc(.55,.55,.1,.15,0,64*360);
148 xstring(0.2,.9,"Example <<A CAR>>");
149
150 h=get("current_entity") //get the newly object created
151 h.font_size=3;
152
153 f=get("current_figure") //get the current figure
154 f.figure_size
155 f.figure_size=[700 500];
156 f.children
157 f.children(2).type
158 f.children(2).children
159 f.children(2).children.children.thickness=4;
160
161 a=get("current_axes") //get the current axes
162 a.children.type
163 a.children.foreground //get the foreground color of a set of graphics objects
164 a.children.foreground=9;
165
166 // for  User Interface objects
167 h=uicontrol('string', 'Button'); // Opens a window with a  button.
168 p=get(h,'position'); // get the geometric aspect of the button
169 disp('Button width: ' + string(p(3))); // print the width of the button
170 close(); // close figure
171 ]]></programlisting>
172         </para>
173         <para>
174         <programlisting role="example"><![CDATA[
175 // Using path
176 f = figure("dockable", "off", "menubar", "none", "toolbar", "none", "infobar_visible", "off", "tag", "mainfig");
177 frameHandle = uicontrol("parent", f, "style", "frame", "position", [200 200 190 100], "tag", "myframe");
178 btnHandle = uicontrol("parent", frameHandle, "position", [20 20 150 30], "string", "button", "tag", "example");
179
180 set("mainfig/myframe/example", "string", "complete path");
181 get("mainfig/myframe/example", "string")
182 set("mainfig/*/example", "string", "wildcard path");
183 get("mainfig/*/example", "string")
184 set("myframe/example", "string", "partial path");
185 get("myframe/example", "string")
186  ]]></programlisting>
187         </para>
188     </refsection>
189     <refsection role="see also">
190         <title>See Also</title>
191         <simplelist type="inline">
192             <member>
193                 <link linkend="uicontrol">uicontrol</link>
194             </member>
195             <member>
196                 <link linkend="root_properties">root_properties</link>
197             </member>
198             <member>
199                 <link linkend="graphics_entities">graphics_entities</link>
200             </member>
201             <member>
202                 <link linkend="set">set</link>
203             </member>
204         </simplelist>
205     </refsection>
206 </refentry>