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:ns5="http://www.w3.org/1999/xhtml"
19          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20          xmlns:scilab="http://www.scilab.org" xml:id="set" xml:lang="pt">
21    <refnamediv>
22        <refname>set</refname>
23        <refpurpose>Ajusta um valor de propriedade de uma objeto entidade gráfica
24            ou de um objeto Interface do Usuário (User Interface)
25        </refpurpose>
26    </refnamediv>
27    <refsynopsisdiv>
28        <title>Seqüência de Chamamento</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>Parâmetros</title>
42        <variablelist>
43            <varlistentry>
44                <term>h</term>
45                <listitem>
46                    manipulador da entidade da qual a propriedade nomeada se
47					deseja ajustar, <literal>h</literal> pode ser um vetor de
48					manipuladores, em tal caso, serão ajustados valores de propriedades
49					para todos os objetos identificados por h
50                    <para/>
51                </listitem>
52            </varlistentry>
53            <varlistentry>
54                <term>tagsPath</term>
55                <listitem>
56                    Case-sensitive character string providing the tag or the tags-path leading
57                    to the graphic component to process.
58                    This path is made of the strings recorded in the <literal>.Tag</literal>
59                    property of the parent figure and of the chain of its children down to
60                    the target, like <literal>"figuretag"</literal> to target the figure
61                    with figure.tag=="figuretag", or <literal>"figuretag/entitytag"</literal>
62                    to target one of its children (as for an axes, a main uimenu item, a
63                    block of legends,..), or <literal>"figuretag/entity1tag/entity2tag"</literal>,
64                    etc. Wildcards can also be used for multi-paths search.
65                    <para/>
66                </listitem>
67            </varlistentry>
68            <varlistentry>
69                <term>prop, prop2, ...</term>
70                <listitem>
71                    Escalares strings : nome que não diferencia maiúsculas de minúsculas das
72                    propriedades a serem ajustadas.
73                    <para/>
74                </listitem>
75            </varlistentry>
76            <varlistentry>
77                <term>val, val2, ...</term>
78                <listitem>
79                    value to assign to the property. Its type depends on the considered property.
80                    If <varname>h</varname> and <varname>val</varname> are vectors or matrices
81                    of same size, the multiple settings are done in an element-wise way.
82                    <para/>
83                </listitem>
84            </varlistentry>
85            <varlistentry>
86                <term>fig</term>
87                <listitem>
88                    Handle of a graphical figure.
89                    <para/>
90                </listitem>
91            </varlistentry>
92            <varlistentry>
93                <term>axes</term>
94                <listitem>
95                    Handle of an axes.
96                    <para/>
97                </listitem>
98            </varlistentry>
99        </variablelist>
100    </refsection>
101    <refsection>
102        <title>Descrição</title>
103        <para>Esta rotina pode ser utilizada para se recuperar o valor de uma
104            propriedade especificada de uma entidade de gráficos ou objeto GUI. Neste
105            caso, é equivalente a se usar o operador ponto ('.') em um manipulador.
106            Por exemplo, <literal>set(h,"background",5)</literal> é equivalente a
107            <literal>h.background = 5</literal>.
108        </para>
109        <para>
110            Para obter a lista de todas as propriedade existentes ver
111            <link linkend="graphics_entities">graphics_entities</link> ou
112            <link linkend="uicontrol">uicontrol</link> para objetos de Interface do Usuário
113        </para>
114        <para/>
115        <emphasis role="bold">set(h, prop, val)</emphasis> ou
116        <emphasis role="bold">h(prop) = val</emphasis> ou
117        <emphasis role="bold">h.prop = val</emphasis>
118        <para>
119            sets the property <varname>prop</varname> of the handle <varname>h</varname> to the
120            value <varname>val.</varname>.
121        </para>
122        <para>
123            When <varname>h</varname> is a matrix of handles,
124            <itemizedlist>
125                <listitem>
126                    if <varname>val</varname> is a matrix of same size: assignments are done in a
127                    element-wise way: <literal>set(h, prop, val)</literal> sets
128                    <literal>h(1)(prop)=val(1)</literal>, <literal>h(2)(prop)=val(2)</literal>, ...,
129                    <literal>h($)(prop)=val($)</literal>.
130                    Most often, the simpler syntax <literal>h(tag) = val</literal> does it as well.
131                </listitem>
132                <listitem>
133                    otherwise: The same and whole <varname>val</varname> value (that may be scalar
134                    or not) is assigned to every <literal>h(i)(prop)</literal> component.
135                    <warning>
136                        If <varname>val</varname> is a cell array of same size as
137                        <varname>h</varname>, it is assigned as a whole as well. For instance,
138                        <literal>set([gcf() gca()], "user_data", {"Text", 1})</literal> will do
139                        <literal>gcf().user_data = {"Text", 1}, gca().user_data = {"Text", 1}</literal>,
140                        not <literal>gcf().user_data = "Text", gca().user_data = 1</literal>.
141                    </warning>
142                </listitem>
143            </itemizedlist>
144        </para>
145        <para>
146            With this syntax, <varname>prop</varname> can't be an array of property names.
147            To set multiple properties with a single call to <literal>set(..)</literal>, the
148            following syntax must be used.
149        </para>
150        <para/>
151        <emphasis role="bold">set(h, prop1,val1, prop2,val2, ..)</emphasis>
152        <para>
153            sets the property <varname>prop1</varname> of the handle(s) <varname>h</varname> to the
154            value <varname>val1</varname>, its or their property <varname>prop2</varname> to the
155            value <varname>val2</varname>, etc. If <varname>h</varname> and some
156            <varname>val#</varname> are matrices of same size, element-wise assignments are done
157            for the related <varname>prop#</varname> properties, as already described for the
158            <literal>set(h, prop, val)</literal> syntax.
159        </para>
160        <para/>
161        <emphasis role="bold">set(tagsPath, prop,val)</emphasis> or
162        <emphasis role="bold">set(tagsPath, prop,val, prop2,val2, ..)</emphasis>
163        <para>
164            Identifying the targeted component(s) to be set can be done as well through their
165            .tag property instead of their handle. This is achieved through the
166            <varname>tagsPath</varname>.
167        </para>
168        <para>
169            In case of multiple entities matching the path, only the first one is processed.
170            Conversely, finding no matching entity yields an error.
171        </para>
172        <para/>
173        <emphasis role="bold">set("current_figure", fig)</emphasis>
174        <para>
175            sets the figure of handle <varname>fig</varname> as the active figure. This syntax
176            is equivalent to <literal>scf(fig)</literal> or <literal>scf(figure_id)</literal>,
177            that are shorter and may be prefered.
178        </para>
179        <para/>
180        <emphasis role="bold">set("current_axes", axes)</emphasis>
181        <para>
182            sets the axes of handle <varname>axes</varname> as the active one. This syntax
183            is equivalent to <literal>sca(axes)</literal> that is shorter and may be prefered.
184        </para>
185        <para/>
186        <emphasis role="bold">set("current_entity", h)</emphasis>
187        <para>
188            sets the graphical component whose <literal>h(1)</literal> is the handle as the
189            current component, as returned by <literal>gce()</literal>. If <varname>h</varname>
190            is a vector of handles, other components <literal>h(2:$)</literal> are ignored.
191        </para>
192    </refsection>
193    <refsection>
194        <title>Exemplos</title>
195        <para>
196            <programlisting role="example"><![CDATA[
197gda().auto_clear = "off";
198clf
199// Example with a Plot 2D
200x = [-.2:0.1:2*%pi]';
201plot2d(x-.3, [sin(x-1) cos(2*x)], [1 2] );
202a = gca();
203p1 = a.children.children(1);
204p2 = a.children.children(2);
205
206// ajustando as propriedades nomeadas para os valores especificados nos objetos
207p2.thickness = 2;
208set(p2, "foreground",13, "polyline_style",2);
209a.y_location = "middle";
210a.tight_limits = "on";
211set(a, "box","off", "sub_tics",[7 0]);
212set(p1, "mark_mode","on", "mark_style",3);
213
214plot2d(x-2,x.^2/20);
215p3 = a.children(1).children;
216set([a p1 p2 p3], "foreground",5);
217 ]]></programlisting>
218        </para>
219        <para>
220        Com um vetor de manipuladores gráficos :
221        </para>
222        <programlisting role="example"><![CDATA[
223// With distinct element-wise inputs:
224clf, plot2d()
225[gcf() gca()].tag
226set([gcf() gca()], "tag", ["myFigure" "myAxes"]);
227[gcf() gca()].tag
228 ]]></programlisting>
229    <screen><![CDATA[
230--> [gcf() gca()].tag
231 ans  =
232!  !
233!  !
234
235--> set([gcf() gca()], "tag", ["myFigure" "myAxes"]);
236
237--> [gcf() gca()].tag
238 ans  =
239!myFigure  !
240!myAxes    !
241]]></screen>
242    <para/>
243        <programlisting role="example"><![CDATA[
244// With the same input for all recipients:
245clf, plot()
246curves = gce().children;
247set([gca() ; curves], "thickness", 2);
248curves(1:20).thickness = 1; // shorter than set(curves(1:20), "thickness", 1)
249     ]]></programlisting>
250        <para>
251            Using a tagsPath :
252        </para>
253        <para>
254        <programlisting role="example"><![CDATA[
255f = figure("dockable", "off", "menubar", "none", "toolbar", "none", "infobar_visible", "off", "tag", "mainfig");
256frameHandle = uicontrol("parent", f, "style", "frame", "position", [200 200 190 100], "tag", "myframe");
257btnHandle = uicontrol("parent", frameHandle, "position", [20 20 150 30], "string", "button", "tag", "example");
258
259set("mainfig/myframe/example", "string", "complete path");
260get("mainfig/myframe/example", "string")
261set("mainfig/*/example", "string", "wildcard path");
262get("mainfig/*/example", "string")
263set("myframe/example", "string", "partial path");
264get("myframe/example", "string")
265     ]]></programlisting>
266        </para>
267    </refsection>
268    <refsection>
269        <title>Ver Também </title>
270        <simplelist type="inline">
271            <member>
272                <link linkend="get">get</link>
273            </member>
274            <member>
275                <link linkend="scf">scf</link>
276            </member>
277            <member>
278                <link linkend="sdf">sdf</link>
279            </member>
280            <member>
281                <link linkend="sca">sca</link>
282            </member>
283            <member>
284                <link linkend="sda">sda</link>
285            </member>
286            <member>
287                <link linkend="delete">delete</link>
288            </member>
289            <member>
290                <link linkend="copy">copy</link>
291            </member>
292            <member>
293                <link linkend="move">move</link>
294            </member>
295            <member>
296                <link linkend="graphics_entities">graphics_entities</link>
297            </member>
298        </simplelist>
299    </refsection>
300    <refsection>
301        <title>Histórico</title>
302        <revhistory>
303            <revision>
304                <revnumber>5.5.0</revnumber>
305                <revremark>
306                    <itemizedlist>
307                        <listitem>
308                            First input argument can now be a path pointing to the graphic entity.
309                        </listitem>
310                        <listitem>
311                            Multiple property setting is now available at once.
312                        </listitem>
313                    </itemizedlist>
314                </revremark>
315            </revision>
316        </revhistory>
317    </refsection>
318</refentry>
319