Update figure function :
[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 the current graphic figure (window) to default values
19         </refpurpose>
20     </refnamediv>
21     <refsynopsisdiv>
22         <title>Calling Sequence</title>
23         <synopsis>
24             clf(&lt;opt_job_arg&gt;)
25             clf(h,&lt;opt_job_arg&gt;)
26             clf(num,&lt;opt_job_arg&gt;)
27         </synopsis>
28     </refsynopsisdiv>
29     <refsection>
30         <title>Arguments</title>
31         <variablelist>
32             <varlistentry>
33                 <term>h</term>
34                 <listitem>
35                     <para>a handle, the figure handle</para>
36                 </listitem>
37             </varlistentry>
38             <varlistentry>
39                 <term>num</term>
40                 <listitem>
41                     <para>a number, the figure_id</para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>&lt;opt_job_arg&gt;</term>
46                 <listitem>
47                     <para>
48                         string <literal>'clear'</literal> (default) or <literal>'reset'</literal>,
49                         specifying the job for <literal>clf</literal>. 
50                     </para>
51                 </listitem>
52             </varlistentry>
53         </variablelist>
54     </refsection>
55     <refsection>
56         <title>Description</title>
57         <para>
58             The <literal>clf</literal> command is used to reset a figure to its default
59             values and/or to delete all its children.
60         </para>
61         <variablelist>
62             <varlistentry>
63                 <term>First input argument: </term>
64                 <listitem>
65                     <variablelist>
66                         <varlistentry>
67                             <term>num</term>
68                             <listitem>
69                                 <para>
70                                     <literal>clf(num,..)</literal> clears or resets the figure with <literal>figure_id==num</literal>
71                                 </para>
72                             </listitem>
73                         </varlistentry>
74                         <varlistentry>
75                             <term>h</term>
76                             <listitem>
77                                 <para>
78                                     <literal>clf(h,..)</literal> clears or resets the figure pointed to by the handle <literal>h</literal>
79                                 </para>
80                             </listitem>
81                         </varlistentry>
82                         <varlistentry>
83                             <term>(none)</term>
84                             <listitem>
85                                 <para>
86                                     <literal>clf(..)</literal> clears or resets the current figure.
87                                                                 </para>
88                                                 </listitem>
89                                             </varlistentry>
90                                         </variablelist>
91                             </listitem>
92                         </varlistentry>
93                         <varlistentry>
94                             <term>opt_job_arg</term>
95                             <listitem>
96                                 <variablelist>
97                                     <varlistentry>
98                                         <term>'clear' (default)</term>
99                                         <listitem>
100                                             <para>
101                                                 <literal>clf(..,'clear')</literal> clears the targetted figure:
102                                                                         <itemizedlist>
103                                                                             <listitem>all its <literal>children</literal> are deleted: axes, uicontrols, menus, and others. 
104                                                                                 To prevent menus and uicontrols from being deleted, the <literal>delete(gca())</literal> command
105                                                                                 might be used instead.
106                                                                                 </listitem>
107                                                                                 <listitem>Its event handler is disabled: <literal>.event_handler_enable = "off"</literal>
108                                                                                 </listitem>
109                                                                                 <listitem>The message in the status bar is cleared: <literal>.info_message = ""</literal>
110                                                                                 </listitem>
111                                                                     </itemizedlist>
112                                                                         All other figure's properties are unchanged.
113                                 </para>
114                             </listitem>
115                         </varlistentry>
116                         <varlistentry>
117                             <term>'reset'</term>
118                             <listitem>
119                                 <para><literal>clf(..,'reset')</literal> deletes all children of the specified figure. In addition, all figure's
120             properties are reset to their default values as returned by <link linkend="gdf">gdf()</link>. The only exception are the 
121                         <literal>axes_size</literal>
122             and <literal>figure_size</literal> properties, which can not be reset if the figure
123             is docked with other elements.clears or resets the current figure.
124                                                                 </para>
125                                                         </listitem>
126                                                 </varlistentry>
127                                         </variablelist>
128                                 </listitem>
129                         </varlistentry>
130                 </variablelist>
131         </refsection>
132         <refsection>
133             <title>Examples</title>
134             <programlisting role="example"> 
135 f4=scf(4);  //creates figure with id==4 and make it the current one
136 f4.color_map = jetcolormap(64);
137 f4.figure_size = [400, 200];
138 plot2d()
139 clf(f4,'reset')
140    
141 f0=scf(0); //creates figure with id==0 and make it the current one
142 f0.color_map=hotcolormap(128); // change color map
143 t=-%pi:0.3:%pi;
144 plot3d1(t,t,sin(t)'*cos(t));
145
146 clf() // equivalent to clf(gcf(),'clear')
147 plot3d1(t,t,sin(t)'*cos(t));  // color_map unchanged
148    
149 clf(gcf(),'reset')
150 plot3d1(t,t,sin(t)'*cos(t));  // color_map changed (back to the default one with 32 colors)
151         </programlisting>
152     </refsection>
153     <refsection role="see also">
154         <title>See Also</title>
155         <simplelist type="inline">
156             <member>
157                 <link linkend="figure_properties">figure properties</link>
158             </member>
159             <member>
160                 <link linkend="gcf">gcf</link>
161             </member>
162             <member>
163                 <link linkend="gdf">gdf</link>
164             </member>
165             <member>
166                 <link linkend="scf">scf</link>
167             </member>
168             <member>
169                 <link linkend="set">set</link>
170             </member>
171             <member>
172                 <link linkend="get">get</link>
173             </member>
174             <member>
175                 <link linkend="graphics_entities">graphics_entities</link>
176             </member>
177         </simplelist>
178     </refsection>
179 </refentry>