Mercurial > hg > octave-nkf
changeset 17064:84e000930ca5
pie.m, pie3.m: Update to use new __plt_get_axis_arg__.
* scripts/plot/pie.m, scripts/plot/pie3.m: Update to use new
__plt_get_axis_arg__. Rewrite docstring to explain "missing" slices.
author | Rik <rik@octave.org> |
---|---|
date | Wed, 24 Jul 2013 23:12:46 -0700 |
parents | f17d9a574645 |
children | 991e8a386aa3 |
files | scripts/plot/pie.m scripts/plot/pie3.m |
diffstat | 2 files changed, 56 insertions(+), 36 deletions(-) [+] |
line wrap: on
line diff
--- a/scripts/plot/pie.m +++ b/scripts/plot/pie.m @@ -18,50 +18,60 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} pie (@var{x}) -## @deftypefnx {Function File} {} pie (@var{x}, @var{explode}) +## @deftypefnx {Function File} {} pie (@dots{}, @var{explode}) ## @deftypefnx {Function File} {} pie (@dots{}, @var{labels}) -## @deftypefnx {Function File} {} pie (@var{h}, @dots{}); +## @deftypefnx {Function File} {} pie (@var{hax}, @dots{}); ## @deftypefnx {Function File} {@var{h} =} pie (@dots{}); ## Plot a 2-D pie chart. ## ## When called with a single vector argument, produce a pie chart of the ## elements in @var{x}. The size of the ith slice is the percentage that the -## element @var{x}i represents of the total sum of @var{x}. +## element @var{x}i represents of the total sum of @var{x}: +## @code{pct = @var{x}(i) / sum (@var{x})}. ## -## The variable @var{explode} is a vector of the same length as @var{x} that, -## if non-zero, "explodes" the slice from the pie chart. +## The optional input @var{explode} is a vector of the same length as @var{x} +## that, if non-zero, "explodes" the slice from the pie chart. ## ## The optional input @var{labels} is a cell array of strings of the same ## length as @var{x} specifying the label for each slice. +## +## 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 list of handles to the patch ## and text objects generating the plot. ## -## @seealso{pie3, bar, stem} +## Note: If @code{sum (@var{x}) @leq{} 1} then the elements of @var{x} are +## interpreted as percentages directly and are not normalized by @code{sum (x)}. +## Furthermore, if the sum is less than 1 then there will be a missing slice +## in the pie plot to represent the missing, unspecified percentage. +## +## @seealso{pie3, bar, hist, rose} ## @end deftypefn ## Very roughly based on pie.m from octave-forge whose author was ## Daniel Heiserer <Daniel.heiserer@physik.tu-muenchen.de> -function retval = pie (varargin) +function h = pie (varargin) - [h, varargin] = __plt_get_axis_arg__ ("pie", varargin{:}); + [hax, varargin, nargin] = __plt_get_axis_arg__ ("pie", varargin{:}); if (nargin < 1) print_usage (); - else - oldh = gca (); - unwind_protect - axes (h); - newplot (); - tmp = __pie__ ("pie", h, varargin{:}); - unwind_protect_cleanup - axes (oldh); - end_unwind_protect endif + oldfig = ifelse (isempty (hax), [], get (0, "currentfigure")); + unwind_protect + hax = newplot (hax); + htmp = __pie__ ("pie", hax, varargin{:}); + unwind_protect_cleanup + if (! isempty (oldfig)) + set (0, "currentfigure", oldfig); + endif + end_unwind_protect + if (nargout > 0) - retval = tmp; + h = htmp; endif endfunction
--- a/scripts/plot/pie3.m +++ b/scripts/plot/pie3.m @@ -19,50 +19,60 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {} pie3 (@var{x}) -## @deftypefnx {Function File} {} pie3 (@var{x}, @var{explode}) +## @deftypefnx {Function File} {} pie3 (@dots{}, @var{explode}) ## @deftypefnx {Function File} {} pie3 (@dots{}, @var{labels}) -## @deftypefnx {Function File} {} pie3 (@var{h}, @dots{}); +## @deftypefnx {Function File} {} pie3 (@var{hax}, @dots{}); ## @deftypefnx {Function File} {@var{h} =} pie3 (@dots{}); ## Plot a 3-D pie chart. ## ## Called with a single vector argument, produces a 3-D pie chart of the ## elements in @var{x}. The size of the ith slice is the percentage that the -## element @var{x}i represents of the total sum of @var{x}. +## element @var{x}i represents of the total sum of @var{x}: +## @code{pct = @var{x}(i) / sum (@var{x})}. ## -## The variable @var{explode} is a vector of the same length as @var{x} that, -## if non-zero, "explodes" the slice from the pie chart. +## The optional input @var{explode} is a vector of the same length as @var{x} +## that, if non-zero, "explodes" the slice from the pie chart. ## ## The optional input @var{labels} is a cell array of strings of the same ## length as @var{x} specifying the label for each slice. ## +## 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 list of graphics handles to the patch, ## surface, and text objects generating the plot. ## -## @seealso{pie, bar, stem} +## Note: If @code{sum (@var{x}) @leq{} 1} then the elements of @var{x} are +## interpreted as percentages directly and are not normalized by @code{sum (x)}. +## Furthermore, if the sum is less than 1 then there will be a missing slice +## in the pie plot to represent the missing, unspecified percentage. +## +## @seealso{pie, bar, hist, rose} ## @end deftypefn ## Very roughly based on pie.m from octave-forge whose author was ## Daniel Heiserer <Daniel.heiserer@physik.tu-muenchen.de> -function retval = pie3 (varargin) +function h = pie3 (varargin) - [h, varargin] = __plt_get_axis_arg__ ("pie", varargin{:}); + [hax, varargin, nargin] = __plt_get_axis_arg__ ("pie3", varargin{:}); if (nargin < 1) print_usage (); - else - oldh = gca (); - unwind_protect - axes (h); - newplot (); - tmp = __pie__ ("pie3", h, varargin{:}); - unwind_protect_cleanup - axes (oldh); - end_unwind_protect endif + oldfig = ifelse (isempty (hax), [], get (0, "currentfigure")); + unwind_protect + hax = newplot (hax); + htmp = __pie__ ("pie3", hax, varargin{:}); + unwind_protect_cleanup + if (! isempty (oldfig)) + set (0, "currentfigure", oldfig); + endif + end_unwind_protect + if (nargout > 0) - retval = tmp; + h = htmp; endif endfunction