octave: scripts/plot/util/figure.m annotate

annotate scripts/plot/util/figure.m @ 25054:6652d3823428 stable

maint: Update copyright dates in all source files.

author	John W. Eaton <jwe@octave.org>
date	Fri, 30 Mar 2018 09:19:05 -0400
parents	a7b6502b5cb5
children	810c7df7e5e7

rev	line source
25054 6652d3823428 maint: Update copyright dates in all source files. John W. Eaton <jwe@octave.org> parents: 24551 diff changeset	1 ## Copyright (C) 1996-2018 John W. Eaton
2313 5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe] jwe parents: 2311 diff changeset	2 ##
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe] jwe parents: 2311 diff changeset	3 ## This file is part of Octave.
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe] jwe parents: 2311 diff changeset	4 ##
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 24446 diff changeset	5 ## Octave is free software: you can redistribute it and/or modify it
2313 5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe] jwe parents: 2311 diff changeset	6 ## under the terms of the GNU General Public License as published by
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 24446 diff changeset	7 ## the Free Software Foundation, either version 3 of the License, or
22755 3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22323 diff changeset	8 ## (at your option) any later version.
2313 5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe] jwe parents: 2311 diff changeset	9 ##
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe] jwe parents: 2311 diff changeset	10 ## Octave is distributed in the hope that it will be useful, but
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe] jwe parents: 2311 diff changeset	11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
22755 3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22323 diff changeset	12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
3a2b891d0b33 maint: Standardize Copyright formatting. Rik <rik@octave.org> parents: 22323 diff changeset	13 ## GNU General Public License for more details.
2313 5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe] jwe parents: 2311 diff changeset	14 ##
5ca126254d15 [project @ 1996-07-11 21:25:22 by jwe] jwe parents: 2311 diff changeset	15 ## You should have received a copy of the GNU General Public License
7016 93c65f2a5668 [project @ 2007-10-12 06:40:56 by jwe] jwe parents: 6895 diff changeset	16 ## along with Octave; see the file COPYING. If not, see
24534 194eb4bd202b maint: Update punctuation for GPL v3 license text. Rik <rik@octave.org> parents: 24446 diff changeset	17 ## <https://www.gnu.org/licenses/>.
2290 9170d297145f [project @ 1996-06-06 05:18:49 by jwe] jwe parents: diff changeset	18
3368 a4cd1e9d9962 [project @ 1999-11-20 17:22:48 by jwe] jwe parents: 3263 diff changeset	19 ## -- texinfo --
20852 516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files. Rik <rik@octave.org> parents: 20735 diff changeset	20 ## @deftypefn {} {} figure
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files. Rik <rik@octave.org> parents: 20735 diff changeset	21 ## @deftypefnx {} {} figure @var{n}
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files. Rik <rik@octave.org> parents: 20735 diff changeset	22 ## @deftypefnx {} {} figure (@var{n})
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files. Rik <rik@octave.org> parents: 20735 diff changeset	23 ## @deftypefnx {} {} figure (@dots{}, "@var{property}", @var{value}, @dots{})
516bb87ea72e 2015 Code Sprint: remove class of function from docstring for all m-files. Rik <rik@octave.org> parents: 20735 diff changeset	24 ## @deftypefnx {} {@var{h} =} figure (@dots{})
17122 eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	25 ## Create a new figure window for plotting.
eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	26 ##
eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	27 ## If no arguments are specified, a new figure with the next available number
eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	28 ## is created.
6895 76e3d985ae56 [project @ 2007-09-13 18:22:38 by jwe] jwe parents: 6780 diff changeset	29 ##
17122 eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	30 ## If called with an integer @var{n}, and no such numbered figure exists, then
eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	31 ## a new figure with the specified number is created. If the figure already
eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	32 ## exists then it is made visible and becomes the current figure for plotting.
19593 446c46af4b42 strip trailing whitespace from most source files John W. Eaton <jwe@octave.org> parents: 18730 diff changeset	33 ##
17122 eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	34 ## Multiple property-value pairs may be specified for the figure object, but
eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	35 ## they must appear in pairs.
eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	36 ##
eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	37 ## The optional return value @var{h} is a graphics handle to the created figure
eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	38 ## object.
24551 a7b6502b5cb5 doc: Add @ref from graphic object creation functions to list of graphic properties (bug #52816). Rik <rik@octave.org> parents: 24534 diff changeset	39 ##
a7b6502b5cb5 doc: Add @ref from graphic object creation functions to list of graphic properties (bug #52816). Rik <rik@octave.org> parents: 24534 diff changeset	40 ## Programming Note: The full list of properties is documented at
a7b6502b5cb5 doc: Add @ref from graphic object creation functions to list of graphic properties (bug #52816). Rik <rik@octave.org> parents: 24534 diff changeset	41 ## @ref{Figure Properties,,Figure Properties}.
17122 eaab03308c0b doc: Rewrite docstrings for most plot functions. Rik <rik@octave.org> parents: 14846 diff changeset	42 ## @seealso{axes, gcf, clf, close}
3368 a4cd1e9d9962 [project @ 1999-11-20 17:22:48 by jwe] jwe parents: 3263 diff changeset	43 ## @end deftypefn
2290 9170d297145f [project @ 1996-06-06 05:18:49 by jwe] jwe parents: diff changeset	44
6257 44c91c5dfe1d [project @ 2007-01-30 19:16:52 by jwe] jwe parents: 6046 diff changeset	45 ## Author: jwe, Bill Denney
2314 949ab8eba8bc [project @ 1996-07-12 03:58:02 by jwe] jwe parents: 2313 diff changeset	46
6257 44c91c5dfe1d [project @ 2007-01-30 19:16:52 by jwe] jwe parents: 6046 diff changeset	47 function h = figure (varargin)
3263 7d80b56e0dc8 [project @ 1999-08-20 19:10:09 by jwe] jwe parents: 3103 diff changeset	48
6257 44c91c5dfe1d [project @ 2007-01-30 19:16:52 by jwe] jwe parents: 6046 diff changeset	49 nargs = nargin;
5406 c49aec8a9080 [project @ 2005-07-08 15:25:43 by jwe] jwe parents: 5307 diff changeset	50
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	51 if (mod (nargs, 2) == 0)
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	52 f = NaN;
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	53 init_new_figure = true;
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	54 else
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	55 arg = varargin{1};
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	56 if (ischar (arg))
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	57 arg = str2double (arg);
14276 6b4bd6a86bdd figure.m: Extend to accepting command form "figure N" Rik <octave@nomad.inbox5.com> parents: 14226 diff changeset	58 endif
17838 cfe5297e0f3b figure.m: Recode to pass failing test on Mac OS X. Rik <rik@octave.org> parents: 17744 diff changeset	59 if (isscalar (arg) && isfigure (arg))
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	60 f = arg;
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	61 init_new_figure = false;
6257 44c91c5dfe1d [project @ 2007-01-30 19:16:52 by jwe] jwe parents: 6046 diff changeset	62 varargin(1) = [];
20735 418ae0cb752f Replace ++,-- with in-place operators for performance. Rik <rik@octave.org> parents: 19833 diff changeset	63 nargs -= 1;
17838 cfe5297e0f3b figure.m: Recode to pass failing test on Mac OS X. Rik <rik@octave.org> parents: 17744 diff changeset	64 elseif (isscalar (arg) && isnumeric (arg) && arg > 0 && arg == fix (arg))
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	65 f = arg;
6293 b649aa46950d [project @ 2007-02-09 21:50:40 by jwe] jwe parents: 6283 diff changeset	66 init_new_figure = true;
6257 44c91c5dfe1d [project @ 2007-01-30 19:16:52 by jwe] jwe parents: 6046 diff changeset	67 varargin(1) = [];
20735 418ae0cb752f Replace ++,-- with in-place operators for performance. Rik <rik@octave.org> parents: 19833 diff changeset	68 nargs -= 1;
6257 44c91c5dfe1d [project @ 2007-01-30 19:16:52 by jwe] jwe parents: 6046 diff changeset	69 else
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	70 error ("figure: N must be figure handle or figure number");
6257 44c91c5dfe1d [project @ 2007-01-30 19:16:52 by jwe] jwe parents: 6046 diff changeset	71 endif
3263 7d80b56e0dc8 [project @ 1999-08-20 19:10:09 by jwe] jwe parents: 3103 diff changeset	72 endif
7d80b56e0dc8 [project @ 1999-08-20 19:10:09 by jwe] jwe parents: 3103 diff changeset	73
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	74 if (rem (nargs, 2) == 1)
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	75 error ("figure: PROPERTY/VALUE arguments must be in pairs");
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	76 endif
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	77
6293 b649aa46950d [project @ 2007-02-09 21:50:40 by jwe] jwe parents: 6283 diff changeset	78 ## Check to see if we already have a figure on the screen. If we do,
b649aa46950d [project @ 2007-02-09 21:50:40 by jwe] jwe parents: 6283 diff changeset	79 ## then update it if it is different from the figure we are creating
b649aa46950d [project @ 2007-02-09 21:50:40 by jwe] jwe parents: 6283 diff changeset	80 ## or switching to.
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	81 cf = get (0, "currentfigure"); # Can't use gcf () because it calls figure()
6293 b649aa46950d [project @ 2007-02-09 21:50:40 by jwe] jwe parents: 6283 diff changeset	82 if (! isempty (cf) && cf != 0)
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	83 if (init_new_figure \|\| cf != f)
6293 b649aa46950d [project @ 2007-02-09 21:50:40 by jwe] jwe parents: 6283 diff changeset	84 drawnow ();
b649aa46950d [project @ 2007-02-09 21:50:40 by jwe] jwe parents: 6283 diff changeset	85 endif
b649aa46950d [project @ 2007-02-09 21:50:40 by jwe] jwe parents: 6283 diff changeset	86 endif
b649aa46950d [project @ 2007-02-09 21:50:40 by jwe] jwe parents: 6283 diff changeset	87
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	88 if (init_new_figure)
19029 8c648c3a2c8f figure.m: Remove obsolete hack for bug #31931 on Mac platforms. Rik <rik@octave.org> parents: 18730 diff changeset	89 f = __go_figure__ (f, varargin{:});
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	90 __add_default_menu__ (f);
23270 79122fab82ee Restore all figure settings after clf ("reset") (bug #50527). Rik <rik@octave.org> parents: 23220 diff changeset	91 __set_default_mouse_modes__ (f);
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	92 elseif (nargs > 0)
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	93 set (f, varargin{:});
2290 9170d297145f [project @ 1996-06-06 05:18:49 by jwe] jwe parents: diff changeset	94 endif
3263 7d80b56e0dc8 [project @ 1999-08-20 19:10:09 by jwe] jwe parents: 3103 diff changeset	95
24395 41cf6ee90cb6 Better handling of "handlevisibility" property (bug #52621). Pantxo Diribarne <pantxo.diribarne@gmail.com> parents: 23270 diff changeset	96 if (strcmp (get (f, "handlevisibility"), "on"))
41cf6ee90cb6 Better handling of "handlevisibility" property (bug #52621). Pantxo Diribarne <pantxo.diribarne@gmail.com> parents: 23270 diff changeset	97 set (0, "currentfigure", f);
41cf6ee90cb6 Better handling of "handlevisibility" property (bug #52621). Pantxo Diribarne <pantxo.diribarne@gmail.com> parents: 23270 diff changeset	98 endif
24446 4ca5c9f899d3 maint: Strip trailing whitespace from source files. John W. Eaton <jwe@octave.org> parents: 24395 diff changeset	99
18411 0f32b34f6ec0 figure.m: Don't make figure N visible when property explicitly set to 'off' (bug #41396) Markus Appel <masolomaster3000@googlemail.com> parents: 17838 diff changeset	100 ## When switching to figure N, make figure visible and on top of stack,
23270 79122fab82ee Restore all figure settings after clf ("reset") (bug #50527). Rik <rik@octave.org> parents: 23220 diff changeset	101 ## unless visibility is explicitly switched off.
18411 0f32b34f6ec0 figure.m: Don't make figure N visible when property explicitly set to 'off' (bug #41396) Markus Appel <masolomaster3000@googlemail.com> parents: 17838 diff changeset	102 if (! init_new_figure && ! any (strcmpi (varargin(1:2:end), "visible")
0f32b34f6ec0 figure.m: Don't make figure N visible when property explicitly set to 'off' (bug #41396) Markus Appel <masolomaster3000@googlemail.com> parents: 17838 diff changeset	103 && strcmpi (varargin(2:2:end), "off")))
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	104 set (f, "visible", "on");
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	105 endif
11349 4a3258b1448f Add default menu for fltk backend figures Kai Habel <kai.habel@gmx.de> parents: 10793 diff changeset	106
6283 7099f1ae465e [project @ 2007-02-08 08:37:00 by jwe] jwe parents: 6257 diff changeset	107 if (nargout > 0)
7099f1ae465e [project @ 2007-02-08 08:37:00 by jwe] jwe parents: 6257 diff changeset	108 h = f;
7099f1ae465e [project @ 2007-02-08 08:37:00 by jwe] jwe parents: 6257 diff changeset	109 endif
7099f1ae465e [project @ 2007-02-08 08:37:00 by jwe] jwe parents: 6257 diff changeset	110
2290 9170d297145f [project @ 1996-06-06 05:18:49 by jwe] jwe parents: diff changeset	111 endfunction
13204 be7bfd59300a Add tests for scripts/plot Kai Habel <kai.habel@gmx.de> parents: 11523 diff changeset	112
19833 9fc020886ae9 maint: Clean up m-files to follow Octave coding conventions. Rik <rik@octave.org> parents: 19697 diff changeset	113
13204 be7bfd59300a Add tests for scripts/plot Kai Habel <kai.habel@gmx.de> parents: 11523 diff changeset	114 %!test
be7bfd59300a Add tests for scripts/plot Kai Habel <kai.habel@gmx.de> parents: 11523 diff changeset	115 %! hf = figure ("visible", "off");
be7bfd59300a Add tests for scripts/plot Kai Habel <kai.habel@gmx.de> parents: 11523 diff changeset	116 %! unwind_protect
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	117 %! assert (hf, gcf);
13204 be7bfd59300a Add tests for scripts/plot Kai Habel <kai.habel@gmx.de> parents: 11523 diff changeset	118 %! assert (isfigure (hf));
18411 0f32b34f6ec0 figure.m: Don't make figure N visible when property explicitly set to 'off' (bug #41396) Markus Appel <masolomaster3000@googlemail.com> parents: 17838 diff changeset	119 %! hf2 = figure (hf, "visible", "off");
0f32b34f6ec0 figure.m: Don't make figure N visible when property explicitly set to 'off' (bug #41396) Markus Appel <masolomaster3000@googlemail.com> parents: 17838 diff changeset	120 %! assert (hf, hf2);
0f32b34f6ec0 figure.m: Don't make figure N visible when property explicitly set to 'off' (bug #41396) Markus Appel <masolomaster3000@googlemail.com> parents: 17838 diff changeset	121 %! assert (hf2, gcf);
0f32b34f6ec0 figure.m: Don't make figure N visible when property explicitly set to 'off' (bug #41396) Markus Appel <masolomaster3000@googlemail.com> parents: 17838 diff changeset	122 %! assert (isfigure (hf2));
0f32b34f6ec0 figure.m: Don't make figure N visible when property explicitly set to 'off' (bug #41396) Markus Appel <masolomaster3000@googlemail.com> parents: 17838 diff changeset	123 %! assert (get (hf2, "visible"), "off");
13204 be7bfd59300a Add tests for scripts/plot Kai Habel <kai.habel@gmx.de> parents: 11523 diff changeset	124 %! unwind_protect_cleanup
be7bfd59300a Add tests for scripts/plot Kai Habel <kai.habel@gmx.de> parents: 11523 diff changeset	125 %! close (hf);
13279 984359717d71 Use common code idiom for checking whether a double value is an integer. Rik <octave@nomad.inbox5.com> parents: 13204 diff changeset	126 %! end_unwind_protect
14363 f3d52523cde1 Use Octave coding conventions in all m-file %!test blocks Rik <octave@nomad.inbox5.com> parents: 14276 diff changeset	127
17137 603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	128 %!error <N must be figure handle or figure number> figure ({1})
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	129 %!error <N must be figure handle or figure number> figure ([1 2])
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	130 %!error <N must be figure handle or figure number> figure (-1)
603ce503babd figure.m: Overhaul function. When switching to figure N make it visible. Rik <rik@octave.org> parents: 17136 diff changeset	131 %!error <N must be figure handle or figure number> figure (1.5)

Mercurial > octave

annotate scripts/plot/util/figure.m @ 25054:6652d3823428 stable