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