changeset 17069:b2cbf369837e

stem.m, stem3.m, __stem__.m: Upgrade to use new __plt_get_axis_arg__. * scripts/plot/stem.m, scripts/plot/stem3.m: Rename tmp to htmp. Redo docstrings. * scripts/plot/private/__stem__.m: Overhaul to support new __plt_get_axis_arg__. Left in a kluge where axis is set to gca.
author Rik <rik@octave.org>
date Wed, 24 Jul 2013 23:12:46 -0700
parents 328b579e08e9
children 140d50ed8f22
files scripts/plot/private/__stem__.m scripts/plot/stem.m scripts/plot/stem3.m
diffstat 3 files changed, 67 insertions(+), 39 deletions(-) [+]
line wrap: on
line diff
--- a/scripts/plot/private/__stem__.m
+++ b/scripts/plot/private/__stem__.m
@@ -32,20 +32,20 @@
     caller = "stem";
   endif
 
-  [ax, varargin, nargin] = __plt_get_axis_arg__ (caller, varargin{:});
+  [hax, varargin, nargin] = __plt_get_axis_arg__ (caller, varargin{:});
 
   [x, y, z, dofill, llc, ls, mmc, ms, varargin] = ...
       check_stem_arg (have_z, varargin{:});
 
-  oldax = gca ();
+  oldfig = ifelse (isempty (hax), [], get (0, "currentfigure"));
   unwind_protect
-    axes (ax);
-    hold_state = get (ax, "nextplot");
-    newplot ();
+    hax = newplot (hax);
+    hold_state = get (hax, "nextplot");
+    set (hax, "nextplot", "add");
+
     h = [];
-
     nx = rows (x);
-    for i = 1: columns (x)
+    for i = 1 : columns (x)
       if (have_z)
         xt = x(:)';
         xt = [xt; xt; NaN(1, nx)](:);
@@ -60,14 +60,10 @@
         yt = [zeros(1, nx); yt; NaN(1, nx)](:);
       endif
 
-      hg  = hggroup ();
+      hg = hggroup ();
       h = [h; hg];
       args = __add_datasource__ (caller, hg, {"x", "y", "z"}, varargin{:});
 
-      if (i == 1)
-        set (ax, "nextplot", "add");
-      endif
-
       if (isempty (llc))
         lc = __next_line_color__ ();
       else
@@ -87,23 +83,23 @@
       endif
 
       if (have_z)
-        h_stems = plot3 (xt, yt, zt, "color", lc, "linestyle", ls,
+        h_stems = plot3 (hax, xt, yt, zt, "color", lc, "linestyle", ls,
                          "parent", hg, x, y, z, "color", mc,
-                         "marker",  ms, "linestyle", "none",
+                         "marker", ms, "linestyle", "none",
                          "markerfacecolor", fc, "parent", hg);
 
         h_baseline = [];
       else
-        h_stems = plot (xt, yt, "color", lc, "linestyle", ls,
+        h_stems = plot (hax, xt, yt, "color", lc, "linestyle", ls,
                         "parent", hg, x(:,i), y(:, i), "color", mc, "marker",
                         ms, "linestyle", "none", "markerfacecolor",
                         fc, "parent", hg);
 
-        x_axis_range = get (ax, "xlim");
-        h_baseline = line (x_axis_range, [0, 0], "color", [0, 0, 0]);
+        x_axis_range = get (hax, "xlim");
+        h_baseline = line (hax, x_axis_range, [0, 0], "color", [0, 0, 0]);
         set (h_baseline, "handlevisibility", "off");
         set (h_baseline, "xliminclude", "off");
-        addlistener (ax, "xlim", @update_xlim);
+        addlistener (hax, "xlim", @update_xlim);
         addlistener (h_baseline, "ydata", @update_baseline);
         addlistener (h_baseline, "visible", @update_baseline);
       endif
@@ -113,7 +109,7 @@
       addproperty ("basevalue", hg, "data", 0);
       addproperty ("baseline", hg, "data", h_baseline);
 
-      if (!have_z)
+      if (! have_z)
         addlistener (hg, "showbaseline", @show_baseline);
         addlistener (hg, "basevalue", @move_baseline);
       endif
@@ -152,10 +148,17 @@
       endif
     endfor
 
+    if (! strcmp (hold_state, "add") && have_z)
+      set (hax, "view", [-37.5 30]);  # 3D view
+    endif
+    set (hax, hold_state);
+
   unwind_protect_cleanup
-    set (ax, "nextplot", hold_state);
-    axes (oldax);
+    if (! isempty (oldfig))
+      set (0, "currentfigure", oldfig);
+    endif
   end_unwind_protect
+
 endfunction
 
 function [x, y, z, dofill, lc, ls, mc, ms, newargs] = check_stem_arg (have_z, varargin)
--- a/scripts/plot/stem.m
+++ b/scripts/plot/stem.m
@@ -19,20 +19,23 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} stem (@var{y})
 ## @deftypefnx {Function File} {} stem (@var{x}, @var{y})
-## @deftypefnx {Function File} {} stem (@var{x}, @var{y}, @var{linespec})
+## @deftypefnx {Function File} {} stem (@dots{}, @var{linespec})
 ## @deftypefnx {Function File} {} stem (@dots{}, "filled")
+## @deftypefnx {Function File} {} stem (@dots{}, "@var{prop}", "@var{val}", @dots{})
+## @deftypefnx {Function File} {} stem (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} stem (@dots{})
-## Plot a stem graph from two vectors of x-y data.  If only one argument
-## is given, it is taken as the y-values and the x coordinates are taken
-## from the indices of the elements.
+## Plot a stem graph from two vectors of x-y data.
+##
+## If only one argument is given, it is taken as the y-values and the
+## x-coordinates are taken from the indices of the elements.
 ##
 ## If @var{y} is a matrix, then each column of the matrix is plotted as
 ## a separate stem graph.  In this case @var{x} can either be a vector,
 ## the same length as the number of rows in @var{y}, or it can be a
 ## matrix of the same size as @var{y}.
 ##
-## The default color is @code{"b"} (blue).  The default line style is
-## @code{"-"} and the default marker is @code{"o"}.  The line style can
+## The default color is @code{"b"} (blue), the default line style is
+## @code{"-"}, and the default marker is @code{"o"}.  The line style can
 ## be altered by the @code{linespec} argument in the same manner as the
 ## @code{plot} command.  For example,
 ##
@@ -47,6 +50,12 @@
 ## @noindent
 ## plots 10 stems with heights from 2 to 20 in red;
 ##
+## Multiple property/value pairs may be specified, but they must appear in
+## pairs.
+##
+## If the first argument @var{hax} is an axis handle, then plot into these axes,
+## rather than the current axis handle returned by @code{gca}.
+##
 ## The optional return value @var{h} is a vector of "stem series" graphics
 ## handles with one handle per column of the variable @var{y}.  The
 ## handle regroups the elements of the stem graph together as the
@@ -66,7 +75,7 @@
 ## @noindent
 ## changes the color of the second "stem series" and moves the base line
 ## of the first.
-## @seealso{bar, barh, plot}
+## @seealso{stem3, bar, hist, plot}
 ## @end deftypefn
 
 ## Author: Michel D. Schmid <michaelschmid@users.sourceforge.net>
@@ -78,10 +87,10 @@
     print_usage ();
   endif
 
-  tmp = __stem__ (false, varargin{:});
+  htmp = __stem__ (false, varargin{:});
 
   if (nargout > 0)
-    h = tmp;
+    h = htmp;
   endif
 
 endfunction
--- a/scripts/plot/stem3.m
+++ b/scripts/plot/stem3.m
@@ -19,13 +19,27 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} stem3 (@var{x}, @var{y}, @var{z})
 ## @deftypefnx {Function File} {} stem3 (@var{x}, @var{y}, @var{z}, @var{linespec})
+## @deftypefnx {Function File} {} stem3 (@dots{}, "filled")
+## @deftypefnx {Function File} {} stem3 (@dots{}, "@var{prop}", "@var{val}", @dots{})
+## @deftypefnx {Function File} {} stem3 (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} stem3 (@dots{})
-## Plot a three-dimensional stem graph and return the handles of the line
+## Plot a 3-D stem graph.
+##
+## The default color is @code{"r"} (red), the default line style is
+## @code{"-"}, and the default marker is @code{"o"}.  The line style can
+## be altered by the @code{linespec} argument in the same manner as the
+## @code{plot} command.
+##
+## Multiple property/value pairs may be specified, but they must appear in
+## pairs.
+##
+## If the first argument @var{hax} is an axis handle, then plot into these axes,
+## rather than the current axis handle returned by @code{gca}.
+##
+## The optional return value @var{h} is a vector with the handles of the line
 ## and marker objects used to draw the stems as "stem series" object.
-## The default color is @code{"r"} (red).  The default line style is
-## @code{"-"} and the default marker is @code{"o"}.
 ##
-## For example,
+## Example:
 ##
 ## @example
 ## @group
@@ -35,9 +49,11 @@
 ## @end example
 ##
 ## @noindent
-## plots 31 stems with heights from 0 to 6 lying on a circle.  Color
-## definitions with RGB-triples are not valid!
-## @seealso{stem, bar, barh, plot}
+## plots 31 stems with heights from 0 to 6 lying on a circle.
+##
+## Implementation Note: Color definitions with RGB-triples are not valid.
+##
+## @seealso{stem, bar, hist, plot}
 ## @end deftypefn
 
 function h = stem3 (varargin)
@@ -46,10 +62,10 @@
     print_usage ();
   endif
 
-  tmp = __stem__ (true, varargin{:});
+  htmp = __stem__ (true, varargin{:});
 
   if (nargout > 0)
-    h = tmp;
+    h = htmp;
   endif
 
 endfunction