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>