* Bug 15514 fixed [doc]: set() page overhauled
[scilab.git] / 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>