scilab/modules/graphics/help/en_US/property/set.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!--
   3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
   4  *
   5  * Copyright (C) INRIA - Djalel Abdemouche
   6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   7  * Copyright (C) 2019 - Samuel GOUGEON
   8  *
   9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  11  * This file was originally licensed under the terms of the CeCILL v2.1,
  12  * and continues to be available under such terms.
  13  * For more information, see the COPYING file which you should have received
  14  * along with this program.
  15  *
  16  -->
  17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
  19           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
  20           xml:lang="en" xml:id="set">
  21     <refnamediv>
  22         <refname>set</refname>
  23         <refpurpose>
  24             set properties of some graphic objects or uimenus or uicontrol interactive components
  25         </refpurpose>
  26     </refnamediv>
  27     <refsynopsisdiv>
  28         <title>Syntax</title>
  29         <synopsis>
  30             set(h, prop,val)            // h(prop) = val,  h.prop = val
  31             set(h, prop,val, prop2,val2, ..)
  32             set(tagsPath, prop,val)
  33             set(tagsPath, prop,val, prop2,val2, ..)
  34
  35             set('current_figure', fig)  // scf(fig)
  36             set('current_axes', axes)   // sca(axes)
  37             set('current_entity', h)
  38         </synopsis>
  39     </refsynopsisdiv>
  40     <refsection>
  41         <title>Arguments</title>
  42         <variablelist>
  43             <varlistentry>
  44                 <term>h</term>
  45                 <listitem>
  46                     Handle of the graphic entity whose properti(es) must be set.
  47                     <literal>h</literal> can be a vector of handles. In this case, set(..) modifies
  48                     the property for all <literal>h</literal> components.
  49                     <para/>
  50                 </listitem>
  51             </varlistentry>
  52             <varlistentry>
  53                 <term>tagsPath</term>
  54                 <listitem>
  55                     Case-sensitive character string providing the tag or the tags-path leading
  56                     to the graphic component to process.
  57                     This path is made of the strings recorded in the <literal>.Tag</literal>
  58                     property of the parent figure and of the chain of its children down to
  59                     the target, like <literal>"figuretag"</literal> to target the figure
  60                     with figure.tag=="figuretag", or <literal>"figuretag/entitytag"</literal>
  61                     to target one of its children (as for an axes, a main uimenu item, a
  62                     block of legends,..), or <literal>"figuretag/entity1tag/entity2tag"</literal>,
  63                     etc. Wildcards can also be used for multi-paths search.
  64                     <para/>
  65                 </listitem>
  66             </varlistentry>
  67             <varlistentry>
  68                 <term>prop, prop2, ...</term>
  69                 <listitem>
  70                     Scalar characters strings: Case-insensitive name of the properties to set.
  71                     <para/>
  72                 </listitem>
  73             </varlistentry>
  74             <varlistentry>
  75                 <term>val, val2, ...</term>
  76                 <listitem>
  77                     value to assign to the property. Its type depends on the considered property.
  78                     If <varname>h</varname> and <varname>val</varname> are vectors or matrices
  79                     of same size, the multiple settings are done in an element-wise way.
  80                     <para/>
  81                 </listitem>
  82             </varlistentry>
  83             <varlistentry>
  84                 <term>fig</term>
  85                 <listitem>
  86                     Handle of a graphical figure.
  87                     <para/>
  88                 </listitem>
  89             </varlistentry>
  90             <varlistentry>
  91                 <term>axes</term>
  92                 <listitem>
  93                     Handle of an axes.
  94                     <para/>
  95                 </listitem>
  96             </varlistentry>
  97         </variablelist>
  98     </refsection>
  99     <refsection>
 100         <title>Description</title>
 101         <para>
 102             This function can be used to modify the value of a specified property from a graphics
 103             entity or a GUI object. In this case it is equivalent to use the dot operator on a handle.
 104             For example, <literal>set(h,"background",5)</literal> is equivalent to
 105             <literal>h.background = 5</literal>.
 106         </para>
 107         <para>
 108             To get the list of all existing properties, please see the pages of
 109             <link linkend="graphics_entities">graphics_entities</link> or
 110             <link linkend="uicontrol_properties">uicontrol_properties</link> for User Interface
 111             objects.
 112         </para>
 113         <para/>
 114         <emphasis role="bold">set(h, prop, val)</emphasis> or
 115         <emphasis role="bold">h(prop) = val</emphasis> or
 116         <emphasis role="bold">h.prop = val</emphasis>
 117         <para>
 118             sets the property <varname>prop</varname> of the handle <varname>h</varname> to the
 119             value <varname>val.</varname>.
 120         </para>
 121         <para>
 122             When <varname>h</varname> is a matrix of handles,
 123             <itemizedlist>
 124                 <listitem>
 125                     if <varname>val</varname> is a matrix of same size: assignments are done in a
 126                     element-wise way: <literal>set(h, prop, val)</literal> sets
 127                     <literal>h(1)(prop)=val(1)</literal>, <literal>h(2)(prop)=val(2)</literal>, ...,
 128                     <literal>h($)(prop)=val($)</literal>.
 129                     Most often, the simpler syntax <literal>h(tag) = val</literal> does it as well.
 130                 </listitem>
 131                 <listitem>
 132                     otherwise: The same and whole <varname>val</varname> value (that may be scalar
 133                     or not) is assigned to every <literal>h(i)(prop)</literal> component.
 134                     <warning>
 135                         If <varname>val</varname> is a cell array of same size as
 136                         <varname>h</varname>, it is assigned as a whole as well. For instance,
 137                         <literal>set([gcf() gca()], "user_data", {"Text", 1})</literal> will do
 138                         <literal>gcf().user_data = {"Text", 1}, gca().user_data = {"Text", 1}</literal>,
 139                         not <literal>gcf().user_data = "Text", gca().user_data = 1</literal>.
 140                     </warning>
 141                 </listitem>
 142             </itemizedlist>
 143         </para>
 144         <para>
 145             With this syntax, <varname>prop</varname> can't be an array of property names.
 146             To set multiple properties with a single call to <literal>set(..)</literal>, the
 147             following syntax must be used.
 148         </para>
 149         <para/>
 150         <emphasis role="bold">set(h, prop1,val1, prop2,val2, ..)</emphasis>
 151         <para>
 152             sets the property <varname>prop1</varname> of the handle(s) <varname>h</varname> to the
 153             value <varname>val1</varname>, its or their property <varname>prop2</varname> to the
 154             value <varname>val2</varname>, etc. If <varname>h</varname> and some
 155             <varname>val#</varname> are matrices of same size, element-wise assignments are done
 156             for the related <varname>prop#</varname> properties, as already described for the
 157             <literal>set(h, prop, val)</literal> syntax.
 158         </para>
 159         <para/>
 160         <emphasis role="bold">set(tagsPath, prop,val)</emphasis> or
 161         <emphasis role="bold">set(tagsPath, prop,val, prop2,val2, ..)</emphasis>
 162         <para>
 163             Identifying the targeted component(s) to be set can be done as well through their
 164             .tag property instead of their handle. This is achieved through the
 165             <varname>tagsPath</varname>.
 166         </para>
 167         <para>
 168             In case of multiple entities matching the path, only the first one is processed.
 169             Conversely, finding no matching entity yields an error.
 170         </para>
 171         <para/>
 172         <emphasis role="bold">set("current_figure", fig)</emphasis>
 173         <para>
 174             sets the figure of handle <varname>fig</varname> as the active figure. This syntax
 175             is equivalent to <literal>scf(fig)</literal> or <literal>scf(figure_id)</literal>,
 176             that are shorter and may be prefered.
 177         </para>
 178         <para/>
 179         <emphasis role="bold">set("current_axes", axes)</emphasis>
 180         <para>
 181             sets the axes of handle <varname>axes</varname> as the active one. This syntax
 182             is equivalent to <literal>sca(axes)</literal> that is shorter and may be prefered.
 183         </para>
 184         <para/>
 185         <emphasis role="bold">set("current_entity", h)</emphasis>
 186         <para>
 187             sets the graphical component whose <literal>h(1)</literal> is the handle as the
 188             current component, as returned by <literal>gce()</literal>. If <varname>h</varname>
 189             is a vector of handles, other components <literal>h(2:$)</literal> are ignored.
 190         </para>
 191     </refsection>
 192     <refsection>
 193         <title>Examples</title>
 194         <para>
 195             <programlisting role="example"><![CDATA[
 196 gda().auto_clear = "off";
 197 clf
 198 // Example with a Plot 2D
 199 x = [-.2:0.1:2*%pi]';
 200 plot2d(x-.3, [sin(x-1) cos(2*x)], [1 2] );
 201 a = gca();
 202 p1 = a.children.children(1);
 203 p2 = a.children.children(2);
 204
 205 // set the named properties to the specified values on the objects
 206 p2.thickness = 2;
 207 set(p2, "foreground",13, "polyline_style",2);
 208 a.y_location = "middle";
 209 a.tight_limits = "on";
 210 set(a, "box","off", "sub_tics",[7 0]);
 211 set(p1, "mark_mode","on", "mark_style",3);
 212
 213 plot2d(x-2,x.^2/20);
 214 p3 = a.children(1).children;
 215 set([a p1 p2 p3], "foreground",5);
 216          ]]></programlisting>
 217         </para>
 218         <para>
 219         With a vector of handles:
 220         </para>
 221         <programlisting role="example"><![CDATA[
 222 // With distinct element-wise inputs:
 223 clf, plot2d()
 224 [gcf() gca()].tag
 225 set([gcf() gca()], "tag", ["myFigure" "myAxes"]);
 226 [gcf() gca()].tag
 227      ]]></programlisting>
 228         <screen><![CDATA[
 229 --> [gcf() gca()].tag
 230  ans  =
 231 !  !
 232 !  !
 233
 234 --> set([gcf() gca()], "tag", ["myFigure" "myAxes"]);
 235
 236 --> [gcf() gca()].tag
 237  ans  =
 238 !myFigure  !
 239 !myAxes    !
 240 ]]></screen>
 241         <para/>
 242         <programlisting role="example"><![CDATA[
 243 // With the same input for all recipients:
 244 clf, plot()
 245 curves = gce().children;
 246 set([gca() ; curves], "thickness", 2);
 247 curves(1:20).thickness = 1; // shorter than set(curves(1:20), "thickness", 1)
 248      ]]></programlisting>
 249         <para>
 250             Using a tagsPath :
 251         </para>
 252         <para>
 253         <programlisting role="example"><![CDATA[
 254 f = figure("dockable", "off", "menubar", "none", "toolbar", "none", "infobar_visible", "off", "tag", "mainfig");
 255 frameHandle = uicontrol("parent", f, "style", "frame", "position", [200 200 190 100], "tag", "myframe");
 256 btnHandle = uicontrol("parent", frameHandle, "position", [20 20 150 30], "string", "button", "tag", "example");
 257
 258 set("mainfig/myframe/example", "string", "complete path");
 259 get("mainfig/myframe/example", "string")
 260 set("mainfig/*/example", "string", "wildcard path");
 261 get("mainfig/*/example", "string")
 262 set("myframe/example", "string", "partial path");
 263 get("myframe/example", "string")
 264      ]]></programlisting>
 265         </para>
 266     </refsection>
 267     <refsection role="see also">
 268         <title>See also</title>
 269         <simplelist type="inline">
 270             <member>
 271                 <link linkend="get">get</link>
 272             </member>
 273             <member>
 274                 <link linkend="scf">scf</link>
 275             </member>
 276             <member>
 277                 <link linkend="sdf">sdf</link>
 278             </member>
 279             <member>
 280                 <link linkend="sca">sca</link>
 281             </member>
 282             <member>
 283                 <link linkend="sda">sda</link>
 284             </member>
 285             <member>
 286                 <link linkend="delete">delete</link>
 287             </member>
 288             <member>
 289                 <link linkend="copy">copy</link>
 290             </member>
 291             <member>
 292                 <link linkend="move">move</link>
 293             </member>
 294             <member>
 295                 <link linkend="graphics_entities">graphics_entities</link>
 296             </member>
 297         </simplelist>
 298     </refsection>
 299     <refsection>
 300         <title>History</title>
 301         <revhistory>
 302             <revision>
 303                 <revnumber>5.5.0</revnumber>
 304                 <revremark>
 305                     <itemizedlist>
 306                         <listitem>
 307                             First input argument can now be a path pointing to the graphic entity.
 308                         </listitem>
 309                         <listitem>
 310                             Multiple property setting is now available at once.
 311                         </listitem>
 312                     </itemizedlist>
 313                 </revremark>
 314             </revision>
 315         </revhistory>
 316     </refsection>
 317 </refentry>