* clf function now also works with "frame" uicontrols.
[scilab.git] / scilab / modules / graphics / help / en_US / figure_operations / clf.xml
1 <!--
2  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
3  * Copyright (C) INRIA - Serge Steer
4  * Copyright (C) INRIA - Jean-Baptiste Silvy
5  * Copyright (C) Samuel GOUGEON : update after fix of bug 7411
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <refentry xml:lang="en" xml:id="clf">
15     <refnamediv>
16         <refname>clf</refname>
17         <refpurpose>
18             Clear or reset or reset a figure or a frame uicontrol.
19         </refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Calling Sequence</title>
23         <synopsis>
24             clf([opt_job_arg])
25             
26             clf(figureHandle[, opt_job_arg])
27             clf(num[, opt_job_arg])
28             
29             clf(frameHandle[, opt_job_arg)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>figureHandle</term>
37                 <listitem>
38                     <para>A handle: the handle of the figure to clear or reset.</para>
39                 </listitem>
40             </varlistentry>
41             <varlistentry>
42                 <term>num</term>
43                 <listitem>
44                     <para>An integer value: the figure_id of the figure to clear or reset.</para>
45                 </listitem>
46             </varlistentry>
47             <varlistentry>
48                 <term>frameHandle</term>
49                 <listitem>
50                     <para>A handle: the handle of the frame to clear or reset.</para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>opt_job_arg</term>
55                 <listitem>
56                     <para>
57                         A string which specifying the job for <function>clf</function>.
58                         Its value can be <literal>"clear"</literal> (default) or <literal>"reset"</literal>.
59                     </para>
60                 </listitem>
61             </varlistentry>
62         </variablelist>
63     </refsection>
64     <refsection>
65         <title>Description</title>
66         <para>
67             The <literal>clf</literal> command can be used to reset a figure to its default
68             values and/or to delete all its children. If can also be used to delete all the children of a frame.
69         </para>
70         <variablelist>
71             <varlistentry>
72                 <term>First input argument: </term>
73                 <listitem>
74                     <variablelist>
75                         <varlistentry>
76                             <term>num</term>
77                             <listitem>
78                                 <para>
79                                     <literal>clf(num,..)</literal> clears or resets the figure with <literal>figure_id==num</literal>
80                                 </para>
81                             </listitem>
82                         </varlistentry>
83                         <varlistentry>
84                             <term>figureHandle</term>
85                             <listitem>
86                                 <para>
87                                     <literal>clf(figureHandle,..)</literal> clears or resets the figure pointed to by the handle <literal>h</literal>
88                                 </para>
89                             </listitem>
90                         </varlistentry>
91                         <varlistentry>
92                             <term>job</term>
93                             <listitem>
94                                 <para>
95                                     <literal>clf(job)</literal> clears or resets the current figure.
96                                 </para>
97                             </listitem>
98                         </varlistentry>
99                     </variablelist>
100                 </listitem>
101             </varlistentry>
102             <varlistentry>
103                 <term>Second input argument:</term>
104                 <listitem>
105                     <variablelist>
106                         <varlistentry>
107                             <term>"clear" (default)</term>
108                             <listitem>
109                                 <para>
110                                     <literal>clf(.., "clear")</literal> clears the targetted figure or frame.
111                                     <itemizedlist>
112                                         <listitem>
113                                             All its <literal>children</literal> are deleted: axes, uicontrols, menus (for figures only), ...
114                                             To prevent menus and uicontrols from being deleted from a figure, the <literal>delete(gca())</literal> command
115                                             might be used instead.
116                                         </listitem>
117                                         <listitem>
118                                             Its event handler is disabled: <literal>.event_handler_enable = "off"</literal>
119                                         </listitem>
120                                         <listitem>
121                                             The message in the status bar is cleared: <literal>.info_message = ""</literal>
122                                         </listitem>
123                                     </itemizedlist>
124                                     All other figure's properties are unchanged.
125                                 </para>
126                             </listitem>
127                         </varlistentry>
128                         <varlistentry>
129                             <term>"reset"</term>
130                             <listitem>
131                                 <para>
132                                     Used for figures only, <literal>clf(.., "reset")</literal> deletes all children of the specified figure. In addition, all figure's
133                                     properties are reset to their default values as returned by <link linkend="gdf">gdf</link>. The only exception are the
134                                     <literal>axes_size</literal>
135                                     and <literal>figure_size</literal> properties, which can not be reset if the figure
136                                     is docked with other elements.
137                                 </para>
138                             </listitem>
139                         </varlistentry>
140                     </variablelist>
141                 </listitem>
142             </varlistentry>
143         </variablelist>
144     </refsection>
145     <refsection>
146         <title>Examples</title>
147         <programlisting role="example">
148             f4=scf(4);  //creates figure with id==4 and make it the current one
149             f4.color_map = jetcolormap(64);
150             f4.figure_size = [400, 200];
151             plot2d()
152             clf(f4, "reset")
153             
154             f0=scf(0); //creates figure with id==0 and make it the current one
155             f0.color_map = hotcolormap(128); // change color map
156             t=-%pi:0.3:%pi;
157             plot3d1(t,t,sin(t)'*cos(t));
158             
159             clf() // equivalent to clf(gcf(),"clear")
160             plot3d1(t,t,sin(t)'*cos(t)); // color_map unchanged
161             
162             clf(gcf(), "reset")
163             plot3d1(t,t,sin(t)'*cos(t)); // color_map changed (back to the default one with 32 colors)
164             
165             fr = uicontrol("Style", "frame", "Position", [20 20 200 200]);
166             a=newaxes(fr);
167             plot(1:10);
168             clf(fr);
169         </programlisting>
170     </refsection>
171     <refsection role="see also">
172         <title>See Also</title>
173         <simplelist type="inline">
174             <member>
175                 <link linkend="figure_properties">figure properties</link>
176             </member>
177             <member>
178                 <link linkend="gcf">gcf</link>
179             </member>
180             <member>
181                 <link linkend="gdf">gdf</link>
182             </member>
183             <member>
184                 <link linkend="scf">scf</link>
185             </member>
186             <member>
187                 <link linkend="set">set</link>
188             </member>
189             <member>
190                 <link linkend="get">get</link>
191             </member>
192             <member>
193                 <link linkend="graphics_entities">graphics_entities</link>
194             </member>
195         </simplelist>
196     </refsection>
197     <refsection>
198         <title>History</title>
199         <revhistory>
200             <revision>
201                 <revnumber>5.5.0</revnumber>
202                 <revremark>
203                     <function>clf</function> works for all axes parents (figures and frames).
204                 </revremark>
205             </revision>
206         </revhistory>
207     </refsection>
208 </refentry>