Create a chapter for borders help pages
[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=h.prop
26         </synopsis>
27     </refsynopsisdiv>
28     <refsection>
29         <title>Arguments</title>
30         <variablelist>
31             <varlistentry>
32                 <term>h</term>
33                 <listitem>
34                     <para>handle, the handle of the entity to retrieve a property.
35                         <literal>h</literal> can be a vector of handles, in which case get returns
36                         the property value for all objects contained in h. <literal>h</literal> can also be <emphasis>0</emphasis> to get the root object properties.
37                     </para>
38                 </listitem>
39             </varlistentry>
40             <varlistentry>
41                 <term>prop</term>
42                 <listitem>
43                     <para>character string name of the property.</para>
44                 </listitem>
45             </varlistentry>
46             <varlistentry>
47                 <term>val</term>
48                 <listitem>
49                     <para>value of the property.</para>
50                 </listitem>
51             </varlistentry>
52         </variablelist>
53     </refsection>
54     <refsection>
55         <title>Description</title>
56         <para>This routine can be used to retrieve the value of a specified property from a
57             graphics entity or a GUI object. In this case it is equivalent to use the dot operator on a handle.
58             For exemple, <literal>get(h,"background")</literal> is equivalent to <literal>h.background</literal>.
59         </para>
60         <para>Property names are character strings. To get the list of all existing properties
61             see <link linkend="graphics_entities">graphics_entities</link> or <link linkend="uicontrol">uicontrol</link>
62             for User Interface objects.
63         </para>
64         <para>
65             <literal>get</literal> function can be also called with only a property as argument. In this case,
66             the property must be one of the following (called with other properties names, <literal>get</literal> will return <literal>[]</literal>):
67         </para>
68         <variablelist>
69             <varlistentry>
70                 <term>current_entity or hdl</term>
71                 <listitem>
72                     <para>returns a handle on the lastly created (and still
73                         existent) entity.
74                         <literal>get('current_entity')</literal> and <literal>get('hdl')</literal> are equivalent to <link linkend="gce">gce</link>.
75                     </para>
76                 </listitem>
77             </varlistentry>
78             <varlistentry>
79                 <term>current_figure</term>
80                 <listitem>
81                     <para>returns a handle on the current graphic figure.
82                         <literal>get('current_figure')</literal> is equivalent to <link linkend="gcf">gcf</link>.
83                     </para>
84                 </listitem>
85             </varlistentry>
86             <varlistentry>
87                 <term>current_axes</term>
88                 <listitem>
89                     <para>returns a handle on the current axes entity.
90                         <literal>get('current_axes')</literal> is equivalent to <link linkend="gca">gca</link>.
91                     </para>
92                 </listitem>
93             </varlistentry>
94             <varlistentry>
95                 <term>default_figure</term>
96                 <listitem>
97                     <para>returns a handle on the default figure entity.
98                         <literal>get('default_figure')</literal> is equivalent to <link linkend="gdf">gdf</link>.
99                     </para>
100                 </listitem>
101             </varlistentry>
102             <varlistentry>
103                 <term>default_axes</term>
104                 <listitem>
105                     <para>returns a handle on the default axes entity.
106                         <literal>get('default_axes')</literal> is equivalent to <link linkend="gda">gda</link>.
107                     </para>
108                 </listitem>
109             </varlistentry>
110             <varlistentry>
111                 <term>figures_id</term>
112                 <listitem>
113                     <para>returns a row vector containing ids of all opened graphic figures.
114                         <literal>get('figures_id')</literal> is equivalent to <link linkend="winsid">winsid</link>.
115                     </para>
116                 </listitem>
117             </varlistentry>
118         </variablelist>
119     </refsection>
120     <refsection>
121         <title>Examples</title>
122         <programlisting role="example"><![CDATA[ 
123 // for graphics entities
124  clf()
125     
126 // simple graphics objects  
127 subplot(121);
128 x=[-.2:0.1:2*%pi]';
129 plot2d(x-2,x.^2);
130 subplot(122);
131 xrect(.2,.7,.5,.2);     
132 xrect(.3,.8,.3,.2);
133 xfarc(.25,.55,.1,.15,0,64*360);
134 xfarc(.55,.55,.1,.15,0,64*360);
135 xstring(0.2,.9,"Example <<A CAR>>");
136  
137 h=get("current_entity") //get the newly object created
138 h.font_size=3;
139  
140 f=get("current_figure") //get the current figure 
141 f.figure_size
142 f.figure_size=[700 500];
143 f.children
144 f.children(2).type
145 f.children(2).children
146 f.children(2).children.children.thickness=4; 
147  
148 a=get("current_axes") //get the current axes
149 a.children.type
150 a.children.foreground //get the foreground color of a set of graphics objects
151 a.children.foreground=9;
152
153 // for  User Interface objects
154 h=uicontrol('string', 'Button'); // Opens a window with a  button.
155 p=get(h,'position'); // get the geometric aspect of the button
156 disp('Button width: ' + string(p(3))); // print the width of the button
157 close(); // close figure
158  ]]></programlisting>
159     </refsection>
160     <refsection role="see also">
161         <title>See Also</title>
162         <simplelist type="inline">
163             <member>
164                 <link linkend="uicontrol">uicontrol</link>
165             </member>
166             <member>
167                 <link linkend="root_properties">root_properties</link>
168             </member>
169             <member>
170                 <link linkend="graphics_entities">graphics_entities</link>
171             </member>
172             <member>
173                 <link linkend="set">set</link>
174             </member>
175         </simplelist>
176     </refsection>
177 </refentry>