* Bug 15514 fixed [doc]: set() page overhauled
[scilab.git] / scilab / modules / graphics / help / pt_BR / 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: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[
197 gda().auto_clear = "off";
198 clf
199 // Example with a Plot 2D
200 x = [-.2:0.1:2*%pi]';
201 plot2d(x-.3, [sin(x-1) cos(2*x)], [1 2] );
202 a = gca();
203 p1 = a.children.children(1);
204 p2 = a.children.children(2);
205
206 // ajustando as propriedades nomeadas para os valores especificados nos objetos
207 p2.thickness = 2;
208 set(p2, "foreground",13, "polyline_style",2);
209 a.y_location = "middle";
210 a.tight_limits = "on";
211 set(a, "box","off", "sub_tics",[7 0]);
212 set(p1, "mark_mode","on", "mark_style",3);
213
214 plot2d(x-2,x.^2/20);
215 p3 = a.children(1).children;
216 set([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:
224 clf, plot2d()
225 [gcf() gca()].tag
226 set([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:
245 clf, plot()
246 curves = gce().children;
247 set([gca() ; curves], "thickness", 2);
248 curves(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[
255 f = figure("dockable", "off", "menubar", "none", "toolbar", "none", "infobar_visible", "off", "tag", "mainfig");
256 frameHandle = uicontrol("parent", f, "style", "frame", "position", [200 200 190 100], "tag", "myframe");
257 btnHandle = uicontrol("parent", frameHandle, "position", [20 20 150 30], "string", "button", "tag", "example");
258
259 set("mainfig/myframe/example", "string", "complete path");
260 get("mainfig/myframe/example", "string")
261 set("mainfig/*/example", "string", "wildcard path");
262 get("mainfig/*/example", "string")
263 set("myframe/example", "string", "partial path");
264 get("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>