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  * Copyright (C) INRIA - Djalel Abdemouche
   5  *
   6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   7  *
   8  * This file is hereby licensed under the terms of the GNU GPL v2.0,
   9  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  10  * This file was originally licensed under the terms of the CeCILL v2.1,
  11  * and continues to be available under such terms.
  12  * For more information, see the COPYING file which you should have received
  13  * along with this program.
  14  *
  15  -->
  16 <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="set">
  17     <refnamediv>
  18         <refname>set</refname>
  19         <refpurpose>set a property value of a graphic entity
  20             object or of a User Interface object.
  21         </refpurpose>
  22     </refnamediv>
  23     <refsynopsisdiv>
  24         <title>Syntax</title>
  25         <synopsis>
  26             set(prop,val)
  27             set(h,prop)
  28             set(h,prop,val)
  29             set(handlePath,prop,val[,prop2, val2, ..., propn, valn])
  30             h.prop=val
  31         </synopsis>
  32     </refsynopsisdiv>
  33     <refsection>
  34         <title>Arguments</title>
  35         <variablelist>
  36             <varlistentry>
  37                 <term>h</term>
  38                 <listitem>
  39                     <para>graphic handle of the entity which to set the named
  40                         property. <literal>h</literal> can be a vector of handles, in which case
  41                         set modifies the property for all entities contained in h.
  42                     </para>
  43                 </listitem>
  44             </varlistentry>
  45             <varlistentry>
  46                 <term>handlePath</term>
  47                 <listitem>
  48                     <para>
  49                         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).
  50                     </para>
  51                     <para>
  52                         Deeper hierarchy levels can also be used such as <literal>"figuretag/entity1tag/entity2tag/entityntag/entitytag"</literal>. Wildcards can also be used for multi-paths search. The first entity matching the path will be used.
  53                     </para>
  54                 </listitem>
  55             </varlistentry>
  56             <varlistentry>
  57                 <term>prop</term>
  58                 <listitem>
  59                     <para>character string, name of the property to set.</para>
  60                 </listitem>
  61             </varlistentry>
  62             <varlistentry>
  63                 <term>val</term>
  64                 <listitem>
  65                     <para>value to give to the property.</para>
  66                 </listitem>
  67             </varlistentry>
  68         </variablelist>
  69     </refsection>
  70     <refsection>
  71         <title>Description</title>
  72         <para>This routine can be used to modify the value of a specified property from a
  73             graphics entity or a GUI object. In this case it is equivalent to use the dot operator on a handle.
  74             For example, <literal>set(h,"background",5)</literal> is equivalent to <literal>h.background = 5</literal>.
  75         </para>
  76         <para>Property names are character strings. The type of the set values depends on the handle type and property.
  77         </para>
  78         <para>To get the list of all existing properties
  79             see <link linkend="graphics_entities">graphics_entities</link> or <link linkend="uicontrol">uicontrol</link>
  80             for User Interface objects.
  81         </para>
  82         <para>
  83             <literal>set</literal> function can be also called with only a property and a value as argument. In this case,
  84             the property must be one of the following:
  85         </para>
  86         <variablelist>
  87             <varlistentry>
  88                 <term>current_entity or hdl</term>
  89                 <listitem>
  90                     <para>
  91                         <literal>set('current_entity',h)</literal> or <literal>set('hdl',h)</literal> sets a new entity as current.
  92                         In this case, the value must be a graphic handle.
  93                     </para>
  94                 </listitem>
  95             </varlistentry>
  96             <varlistentry>
  97                 <term>current_figure</term>
  98                 <listitem>
  99                     <para>
 100                         <literal>set('current_figure',fig)</literal> sets a new graphic figure as current.
 101                         It is equivalent to <link linkend="scf">scf</link>. In this case, the value must be a Figure handle.
 102                     </para>
 103                 </listitem>
 104             </varlistentry>
 105             <varlistentry>
 106                 <term>current_axes</term>
 107                 <listitem>
 108                     <para>
 109                         <literal>set('current_axes',axes)</literal> sets a new axes entity as current.
 110                         It is equivalent to <link linkend="sca">sca</link>. In this case, the value must be an Axes handle.
 111                     </para>
 112                 </listitem>
 113             </varlistentry>
 114         </variablelist>
 115         <para>
 116             <literal>set</literal> can also be called with a graphic handle and property as arguments.
 117             The handle must be either a handle on the default figure or the default axes entities.
 118             The property must be <literal>"default_values"</literal>. In this case, the default entity
 119             is reset to the value it had at Scilab startup. <literal>set("default_values",h)</literal>
 120             is equivalent to <link linkend="sda">sda</link> or <link linkend="sdf">sdf</link>.
 121         </para>
 122     </refsection>
 123     <refsection>
 124         <title>Examples</title>
 125         <para>
 126             <programlisting role="example"><![CDATA[
 127 clf()
 128 set("auto_clear","off") ;
 129 // Example of a Plot 2D
 130 x=[-.2:0.1:2*%pi]';
 131 plot2d(x-.3,[sin(x-1) cos(2*x)],[1 2] );
 132 a=get("current_axes");
 133 p1=a.children.children(1);
 134 p2=a.children.children(2);
 135 // set the named properties to the specified values on the objects
 136 set(p2,"foreground",13);
 137 set(p2,"polyline_style",2);
 138 set(a,'tight_limits',"on");
 139 set(a,"box","off");
 140 set(a,"sub_tics",[ 7 0 ]);
 141 set(a,"y_location","middle")
 142 set(p2,'thickness',2);
 143 set(p1,'mark_mode',"on");
 144 set(p1,'mark_style',3);
 145 plot2d(x-2,x.^2/20);
 146 p3= a.children(1).children;
 147 set([a p1 p2 p3],"foreground",5)
 148  ]]></programlisting>
 149         </para>
 150         <para>
 151             <programlisting role="example"><![CDATA[
 152 // Using path
 153 f = figure("dockable", "off", "menubar", "none", "toolbar", "none", "infobar_visible", "off", "tag", "mainfig");
 154 frameHandle = uicontrol("parent", f, "style", "frame", "position", [200 200 190 100], "tag", "myframe");
 155 btnHandle = uicontrol("parent", frameHandle, "position", [20 20 150 30], "string", "button", "tag", "example");
 156
 157 set("mainfig/myframe/example", "string", "complete path");
 158 get("mainfig/myframe/example", "string")
 159 set("mainfig/*/example", "string", "wildcard path");
 160 get("mainfig/*/example", "string")
 161 set("myframe/example", "string", "partial path");
 162 get("myframe/example", "string")
 163  ]]></programlisting>
 164         </para>
 165     </refsection>
 166     <refsection role="see also">
 167         <title>See also</title>
 168         <simplelist type="inline">
 169             <member>
 170                 <link linkend="get">get</link>
 171             </member>
 172             <member>
 173                 <link linkend="delete">delete</link>
 174             </member>
 175             <member>
 176                 <link linkend="copy">copy</link>
 177             </member>
 178             <member>
 179                 <link linkend="move">move</link>
 180             </member>
 181             <member>
 182                 <link linkend="graphics_entities">graphics_entities</link>
 183             </member>
 184             <member>
 185                 <link linkend="uicontrol">uicontrol</link>
 186             </member>
 187         </simplelist>
 188     </refsection>
 189     <refsection>
 190         <title>History</title>
 191         <revhistory>
 192             <revision>
 193                 <revnumber>5.5.0</revnumber>
 194                 <revremark>
 195                     <itemizedlist>
 196                         <listitem>
 197                             First input argument can now be a path pointing to the graphic entity.
 198                         </listitem>
 199                         <listitem>
 200                             Multiple property setting is now available at once.
 201                         </listitem>
 202                     </itemizedlist>
 203                 </revremark>
 204             </revision>
 205         </revhistory>
 206     </refsection>
 207 </refentry>