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>