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>