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>