# HG changeset patch
# User John W. Eaton <jwe@octave.org>
# Date 1318297156 14400
# Node ID 467276f9a366bc2ef0b922fc5a8c8b737c7faff8
# Parent  e84d512b2438dcaa42fe67e993bc2596b7ee2159
clf: return figure handle

* clf.m: If nargout > 0, return handle of figure window that was
cleared.

diff --git a/scripts/plot/clf.m b/scripts/plot/clf.m
--- a/scripts/plot/clf.m
+++ b/scripts/plot/clf.m
@@ -21,17 +21,19 @@
 ## @deftypefnx {Function File} {} clf ("reset")
 ## @deftypefnx {Function File} {} clf (@var{hfig})
 ## @deftypefnx {Function File} {} clf (@var{hfig}, "reset")
+## @deftypefnx {Function File} {@var{h} =} clf (@dots)
 ## Clear the current figure window.  @code{clf} operates by deleting child
 ## graphics objects with visible handles (@code{handlevisibility} = on).
 ## If @var{hfig} is specified operate on it instead of the current figure.
 ## If the optional argument @code{"reset"} is specified, all objects including
-## those with hidden handles are deleted.
+## those with hidden handles are deleted.  If an output value is
+## requested, return the handle of the figure window that was cleared.
 ## @seealso{cla, close, delete}
 ## @end deftypefn
 
 ## Author: jwe
 
-function clf (varargin)
+function retval = clf (varargin)
 
   if (nargin > 2)
     print_usage ();
@@ -74,6 +76,10 @@
   ## Delete the children.
   delete (hc);
 
+  if (nargout > 0)
+    retval = hfig;
+  endif
+
 endfunction
 
 %!test