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>