# HG changeset patch # User Rik # Date 1244521990 -7200 # Node ID 5183cee7a4236dff7851eca435dd188a1410ec50 # Parent 28d4a6acbf0ace4a41f48563d3c0310991706984 Update some of Advanced Plotting documentation. Updated functions delete, allchild, backend, clf, hold, and refreshdata. diff --git a/doc/ChangeLog b/doc/ChangeLog --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2009-06-07 Rik + + * interpreter/plot.txi: Update some of Advanced Plotting documentation. + Updated functions delete, allchild, backend, clf, hold, and refreshdata. + 2009-06-07 Thorsten Meyer * interpreter/container.txi: Udate documentation of container types @@ -22,11 +27,11 @@ * interpreter/oop.txi: Update docs of polynomial class, mention chained indexing. -2009-05-27 Søren Hauberg +2009-05-27 S�ren Hauberg * interpreter/errors.txi: fix 'print_usage' output. -2009-05-27 Søren Hauberg +2009-05-27 S�ren Hauberg * interpreter/bugs.txi: fix call to 'page_screen_output'. @@ -166,7 +171,7 @@ * interpreter/Makefile.in (DISTFILES): Use doc-cache instead of DOC for doc cache file. -2009-03-08 Søren Hauberg +2009-03-08 S�ren Hauberg * interpreter/stats.txi (Basic Statistical Functions): Add the 'histc' function. @@ -252,11 +257,11 @@ (DISTFILES): Add DOC nad mk_doc_cache.m to the list. * mk_doc_cache.m: New file. -2009-02-01 Søren Hauberg +2009-02-01 S�ren Hauberg * interpreter/nonlin.txi: Remove reference to 'fsolve_options'. -2009-02-01 Søren Hauberg +2009-02-01 S�ren Hauberg * interpreter/system.txi: Remove reference to 'eomdate'. @@ -272,7 +277,7 @@ * vr-idx.txi: Delete. * interpreter/Makefile.in (SUB_SOURCE): Remove it from the list. -2009-01-22 Søren Hauberg +2009-01-22 S�ren Hauberg * interpreter/func.txi: Put varargin and varargout in concept index. * interpreter/var.txi: Put ans in concept index. @@ -393,12 +398,12 @@ * interpreter/contrib.txi: correction of the mercurial example * interpreter/container.txi: minor correction of the text -2008-09-25 Søren Hauberg +2008-09-25 S�ren Hauberg * interpreter/image.txi: Update for imread and imwrite instead of loadimge and saveimage. -2008-09-24 Søren Hauberg +2008-09-24 S�ren Hauberg * interpreter/image.txi: Document imfinfo. @@ -447,7 +452,7 @@ * interpreter/numbers.txi: Document intwarning. -2008-08-06 Søren Hauberg +2008-08-06 S�ren Hauberg * interpreter/basics.txi, interpreter/errors.txi, interpreter/expr.txi, interpreter/func.txi, @@ -664,7 +669,7 @@ * refcard/refcard.tex: Update for 3.0. -2007-10-15 Søren Hauberg +2007-10-15 S�ren Hauberg * interpreter/preface.txi, interpreter/basics.txi, interpreter/strings.txi, interpreter/container.txi, @@ -696,7 +701,7 @@ 2007-10-06 John W. Eaton - * interpreter/octave.texi: Add David Bateman and Søren Hauberg as + * interpreter/octave.texi: Add David Bateman and S�ren Hauberg as authors. 2006-09-28 Henry Mollet mollet@pacbell.net @@ -728,7 +733,7 @@ * interpreter/geometry.txi: Check whether TEXINFO_QHULL is set before including certain figures. -2007-08-31 Søren Hauberg +2007-08-31 S�ren Hauberg * interpreter/nonlin.txi: Extended the example. @@ -811,7 +816,7 @@ * interpreter/interp.txi: Also change figures here. * interpreter/Makefile.in: and here. -2007-06-18 Søren Hauberg +2007-06-18 S�ren Hauberg * interpreter/optim.txi: Added some introductory text to each section. @@ -858,7 +863,7 @@ and subsections for hashing to system utilities chapter. -2007-06-12 2007-06-10 Søren Hauberg +2007-06-12 2007-06-10 S�ren Hauberg * interpreter/diffeq.txi: Note that x-dot is the derivative of x. @@ -886,7 +891,7 @@ * interpreter/Makefile.in ($(HTML_IMAGES_PNG)): Use cp instead of INSTALL_DATA to copy files to the HTML directory. -2007-05-28 Søren Hauberg +2007-05-28 S�ren Hauberg * interpreter/errors.txi: Add new sections and some more detailed descriptions on errors and warnings. @@ -894,7 +899,7 @@ interpreter/var.txi: Add references to the new sections in errors.txi. -2007-05-28 Søren Hauberg +2007-05-28 S�ren Hauberg * interpreter/io.txi: Rearrange some sections, and add a few examples. @@ -928,7 +933,7 @@ * interpreter/debug.txi, io.txi, octave.txi: Doc fixes. -2007-05-21 Søren Hauberg +2007-05-21 S�ren Hauberg * interpreter/expr.txi: Describe +=, -=, *=, and /= operators. Add new example. @@ -950,7 +955,7 @@ * interpreter/func.txi: Additional documentation for function locking, dispatch and autoloading. -2007-05-16 Søren Hauberg +2007-05-16 S�ren Hauberg * interpreter/expr.txi: Improve docs. @@ -960,7 +965,7 @@ interpreter/intro.txi, interpreter/numbers.txi, interpreter/octave.texi, interpreter/preface.txi: Doc fixes. -2007-04-18 Søren Hauberg +2007-04-18 S�ren Hauberg * interpreter/package.texi: Document "*" flag for loaded packages. @@ -1043,7 +1048,7 @@ * Makefile.in (SUB_SOURCE): Include dynamic.txi in the list. -2007-04-18 Søren Hauberg +2007-04-18 S�ren Hauberg * interpreter/package.texi: New file. * octave/texi: @include it, add it to the menus. @@ -1068,7 +1073,7 @@ * interpreter/stream.txi: Delete. * interpreter/Makefile.in (SUB_SOURCE): Remove it from the list. -2007-04-16 Søren Hauberg +2007-04-16 S�ren Hauberg * intrepreter/stmt.txi: Improve documentation of switch statement. @@ -1080,15 +1085,15 @@ * interpreter/image.txi: Update docs. -2007-04-11 Søren Hauberg +2007-04-11 S�ren Hauberg * interpreter/container.txi: Document indexing with (). -2007-04-11 Søren Hauberg +2007-04-11 S�ren Hauberg * interpreter/container.txi: Improve cell array documentation. -2007-04-09 Søren Hauberg +2007-04-09 S�ren Hauberg * interpreter/func.txi: Document varargin, varargout, and default argument values. diff --git a/doc/interpreter/plot.txi b/doc/interpreter/plot.txi --- a/doc/interpreter/plot.txi +++ b/doc/interpreter/plot.txi @@ -538,7 +538,7 @@ @item axes @cindex axes graphics object @cindex graphics object, axes -An set of axes. This object is a child of a figure object and may be a +A set of axes. This object is a child of a figure object and may be a parent of line, text, image, patch, or surface objects. @item line @@ -567,7 +567,7 @@ A three-dimensional surface. @end table -To determine whether an object is a graphics object index or a figure +To determine whether a variable is a graphics object index or a figure index, use the functions @code{ishandle} and @code{isfigure}. @DOCSTRING(ishandle) @@ -593,10 +593,11 @@ get (0) @result{} ans = @{ - type = root figure + type = root currentfigure = [](0x0) children = [](0x0) visible = on + @dots{} @} @end group @end example @@ -673,24 +674,24 @@ @DOCSTRING(drawnow) Only figures that are modified will be updated. The @code{refresh} -function can also be to force an update of the current figure, even if -it is nor modified. +function can also be used to force an update of the current figure, even if +it is not modified. @DOCSTRING(refresh) Normally, high-level plot functions like @code{plot} or @code{mesh} call @code{newplot} to initialize the state of the current axes so that the next plot is drawn in a blank window with default property settings. To -have two plots superimposed over one another, call the @code{hold} +have two plots superimposed over one another, use the @code{hold} function. For example, @example @group -hold ("on"); +hold on; x = -10:0.1:10; plot (x, sin (x)); plot (x, cos (x)); -hold ("off"); +hold off; @end group @end example diff --git a/scripts/miscellaneous/delete.m b/scripts/miscellaneous/delete.m --- a/scripts/miscellaneous/delete.m +++ b/scripts/miscellaneous/delete.m @@ -17,9 +17,13 @@ ## . ## -*- texinfo -*- -## @deftypefn {Function File} {} delete (@var{file}) -## @deftypefnx {Function File} {} delete (@var{h}) +## @deftypefn {Function File} {} delete (@var{file}) +## @deftypefnx {Function File} {} delete (@var{handle}) ## Delete the named file or graphics handle. +## +## Deleting graphics objects is the proper way to remove +## features from a plot without clearing the entire figure. +## @seealso{clf, cla} ## @end deftypefn ## Author: jwe diff --git a/scripts/plot/allchild.m b/scripts/plot/allchild.m --- a/scripts/plot/allchild.m +++ b/scripts/plot/allchild.m @@ -18,12 +18,12 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {@var{h} =} allchild (@var{handles}) -## Find all children including hidden children of an object. +## Find all children, including hidden children, of a graphics object. ## ## This function is similar to @code{get (h, "children")}, but also ## returns includes hidden objects. If @var{handles} is a scalar, -## @var{h} will be a vector, and if not, @var{h} will be a cell matrix -## with the same size as @var{handles} and each cell will contain a +## @var{h} will be a vector. Otherwise, @var{h} will be a cell matrix +## of the same size as @var{handles} and each cell will contain a ## vector of handles. ## @seealso{get, set, findall, findobj} ## @end deftypefn diff --git a/scripts/plot/backend.m b/scripts/plot/backend.m --- a/scripts/plot/backend.m +++ b/scripts/plot/backend.m @@ -21,10 +21,10 @@ ## @deftypefnx {Function File} {} backend (@var{hlist}, @var{name}) ## Change the default graphics backend to @var{name}. If the backend is ## not already loaded, it is first initialized (initialization is done -## through the execution of __init_@var{name}__). +## through the execution of @code{__init_@var{name}__}). ## -## @var{hlist} is a list of figure handles. When given, this function -## only switches the default backend for the corresponding figures. +## When called with a list of figure handles, @var{hlist}, the backend is +## changed only for the listed figures. ## @seealso{available_backends} ## @end deftypefn diff --git a/scripts/plot/clf.m b/scripts/plot/clf.m --- a/scripts/plot/clf.m +++ b/scripts/plot/clf.m @@ -17,15 +17,15 @@ ## . ## -*- texinfo -*- -## @deftypefn {Function File} {} clf () +## @deftypefn {Function File} {} clf () ## @deftypefnx {Function File} {} clf ("reset") ## @deftypefnx {Function File} {} clf (@var{hfig}) ## @deftypefnx {Function File} {} clf (@var{hfig}, "reset") -## @deftypefnx {Function File} {@var{hfig} =} clf (@dots{}) -## Delete the children of the current figure with visible handles. -## If @var{hfig} is specified and is an figure object handle, operate on it -## instead of the current figure. If the optional argument @code{"reset"} -## is specified, also delete the figure's children with hidden handles. +## 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. ## @seealso{cla, close, delete} ## @end deftypefn diff --git a/scripts/plot/hold.m b/scripts/plot/hold.m --- a/scripts/plot/hold.m +++ b/scripts/plot/hold.m @@ -17,27 +17,31 @@ ## . ## -*- texinfo -*- -## @deftypefn {Function File} {} hold @var{args} -## Tell Octave to `hold' the current data on the graph when executing -## subsequent plotting commands. This allows you to execute a series of -## plot commands and have all the lines end up on the same graph. The -## default is for each new plot command to clear the plot device first. -## For example, the command -## -## @example -## hold on -## @end example +## @deftypefn {Function File} {} hold +## @deftypefnx {Function File} {} hold @var{state} +## @deftypefnx {Function File} {} hold (@var{hax}, @dots{}) +## Toggle or set the 'hold' state of the plotting engine which determines +## whether new graphic objects are added to the plot or replace the existing +## objects. +## +## @table @code +## @item hold on +## Retain plot data and settings so that subsequent plot commands are displayed +## on a single graph. ## -## @noindent -## turns the hold state on. An argument of @code{"off"} turns the hold -## state off, and @code{hold} with no arguments toggles the current hold -## state. +## @item hold off +## Clear plot and restore default graphics settings before each new plot +## command. (default). ## -## @deftypefnx {Function File} {} hold (@var{h}, @dots{}) +## @item hold +## Toggle the current 'hold' state. +## @end table ## -## Applies to a specific axis or axes, associated with the handle(s), -## @var{h}. -## +## When given the additional argument @var{hax}, the hold state is modified +## only for the given axis handle. +## +## To query the current 'hold' state use the @code{ishold} function. +## @seealso{ishold, cla, newplot, clf} ## @end deftypefn function hold (varargin) diff --git a/scripts/plot/refreshdata.m b/scripts/plot/refreshdata.m --- a/scripts/plot/refreshdata.m +++ b/scripts/plot/refreshdata.m @@ -17,16 +17,23 @@ ## . ## -*- texinfo -*- -## @deftypefn {Function File} {} refreshdata () +## @deftypefn {Function File} {} refreshdata () ## @deftypefnx {Function File} {} refreshdata (@var{h}) -## @deftypefnx {Function File} {} refreshdata (@var{h}, @var{ws}) -## Evaluates any datasource properties of the current figure and updates -## the corresponding data. If call with one or more arguments @var{h} is -## a scalar or array of figure handles which to refresh. The data -## sources are by default evaluated in the "base" workspace but can also -## be set in the "caller" workspace. +## @deftypefnx {Function File} {} refreshdata (@var{h}, @var{workspace}) +## Evaluate any @samp{datasource} properties of the current figure and update +## the plot if the corresponding data has changed. If called with one or more +## arguments @var{h} is a scalar or array of figure handles to refresh. The +## optional second argument @var{workspace} can take the following values. ## -## An example of the use of refreshdata is +## @table @code +## @item "base" +## Evaluate the datasource properties in the base workspace. (default). +## @item "caller" +## Evaluate the datasource properties in the workspace of the function +## that called @code{refreshdata}. +## @end table +## +## An example of the use of @code{refreshdata} is: ## ## @example ## @group @@ -40,8 +47,6 @@ ## endfor ## @end group ## @end example -## -## @seealso{linkdata} ## @end deftypefn function refreshdata (h, ws) diff --git a/src/graphics.cc b/src/graphics.cc --- a/src/graphics.cc +++ b/src/graphics.cc @@ -4963,7 +4963,7 @@ DEFUN (available_backends, , , "-*- texinfo -*-\n\ @deftypefn {Built-in Function} {} available_backends ()\n\ -Returns resgistered graphics backends.\n\ +Return a cell array of registered graphics backends.\n\ @end deftypefn") { gh_manager::autolock guard; @@ -4979,9 +4979,15 @@ DEFUN (drawnow, args, , "-*- texinfo -*-\n\ -@deftypefn {Built-in Function} {} __go_drawnow__ ()\n\ -@deftypefnx {Built-in Function} {} __go_drawnow__ (@var{term}, @var{file}, @var{mono}, @var{debug_file})\n\ -Undocumented internal function.\n\ +@deftypefn {Built-in Function} {} drawnow ()\n\ +@deftypefnx {Built-in Function} {} drawnow (\"expose\")\n\ +@deftypefnx {Built-in Function} {} drawnow (@var{term}, @var{file}, @var{mono}, @var{debug_file})\n\ +Update figure windows and their children. The event queue is flushed and\n\ +any callbacks generated are executed. With the optional argument\n\ +@code{\"expose\"}, only graphic objects are updated and no other events or\n\ +callbacks are processed.\n\ +The third calling form of @code{drawnow} is for debugging and is\n\ +undocumented.\n\ @end deftypefn") { static int drawnow_executing = 0;