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