1######################################################################## 2## 3## Copyright (C) 2005-2021 The Octave Project Developers 4## 5## See the file COPYRIGHT.md in the top-level directory of this 6## distribution or <https://octave.org/copyright/>. 7## 8## This file is part of Octave. 9## 10## Octave is free software: you can redistribute it and/or modify it 11## under the terms of the GNU General Public License as published by 12## the Free Software Foundation, either version 3 of the License, or 13## (at your option) any later version. 14## 15## Octave is distributed in the hope that it will be useful, but 16## WITHOUT ANY WARRANTY; without even the implied warranty of 17## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18## GNU General Public License for more details. 19## 20## You should have received a copy of the GNU General Public License 21## along with Octave; see the file COPYING. If not, see 22## <https://www.gnu.org/licenses/>. 23## 24######################################################################## 25 26## -*- texinfo -*- 27## @deftypefn {} {} line () 28## @deftypefnx {} {} line (@var{x}, @var{y}) 29## @deftypefnx {} {} line (@var{x}, @var{y}, @var{z}) 30## @deftypefnx {} {} line ("xdata", @var{x}, "ydata", @var{y}) 31## @deftypefnx {} {} line ("xdata", @var{x}, "ydata", @var{y}, "zdata", @var{z}) 32## @deftypefnx {} {} line (@dots{}, @var{property}, @var{value}) 33## @deftypefnx {} {} line (@var{hax}, @dots{}) 34## @deftypefnx {} {@var{h} =} line (@dots{}) 35## Create a line object from @var{x} and @var{y} (and possibly @var{z}) and 36## insert it in the current axes. 37## 38## In the standard calling form the data @var{x}, @var{y}, and @var{z} may be 39## scalars, vectors, or matrices. In the case of matrix inputs, @code{line} 40## will attempt to orient scalars and vectors so the results can be plotted. 41## This requires that one of the dimensions of the vector match either the 42## number of rows or the number of columns of the matrix. 43## 44## In the low-level calling form (50% higher performance) where the data is 45## specified by name (@code{line ("xdata", @var{x}, @dots{})}) the data must be 46## vectors. If no data is specified (@code{line ()}) then 47## @w{@code{@var{x} == @var{y} = [0, 1]}}. 48## 49## Multiple property-value pairs may be specified for the line object, but they 50## must appear in pairs. 51## 52## If called with only @var{property}/@var{value} pairs then any unspecified 53## properties use their default values as specified on the root object. 54## 55## If the first argument @var{hax} is an axes handle, then plot into this axes, 56## rather than the current axes returned by @code{gca}. 57## 58## The optional return value @var{h} is a graphics handle (or vector of 59## handles) to the line objects created. 60## 61## Programming Note: The full list of properties is documented at 62## @ref{Line Properties}. 63## 64## The function @code{line} differs from @code{plot} in that line objects are 65## inserted in to the current axes without first clearing the plot. 66## @seealso{image, patch, rectangle, surface, text} 67## @end deftypefn 68 69function h = line (varargin) 70 71 ## Get axis argument which may be in a 'parent' PROP/VAL pair 72 [hax, varargin] = __plt_get_axis_arg__ ("line", varargin{:}); 73 74 if (isempty (hax)) 75 hax = gca (); 76 oldfig = []; 77 else 78 hax = hax(1); 79 oldfig = get (0, "currentfigure"); 80 set (0, "currentfigure", ancestor (hax, "figure")); 81 endif 82 83 unwind_protect 84 htmp = __line__ (hax, varargin{:}); 85 unwind_protect_cleanup 86 if (! isempty (oldfig)) 87 set (0, "currentfigure", oldfig); 88 endif 89 end_unwind_protect 90 91 if (nargout > 0) 92 h = htmp; 93 endif 94 95endfunction 96 97 98%!demo 99%! clf; 100%! line ([0 1], [0.8 0.8], "linestyle", "-", "color", "b"); 101%! line ([0 1], [0.6 0.6], "linestyle", "--", "color", "g"); 102%! line ([0 1], [0.4 0.4], "linestyle", ":", "color", "r"); 103%! line ([0 1], [0.2 0.2], "linestyle", "-.", "color", "k"); 104%! ylim ([0 1]); 105%! title ("line() with various linestyles"); 106%! legend ('"-"', '"--"', '":"', '"-."', 'location', 'eastoutside'); 107 108%!demo 109%! clf; 110%! x = 0:0.3:10; 111%! y1 = cos (x); 112%! y2 = sin (x); 113%! subplot (3,1,1); 114%! args = {"color", "b", "marker", "s"}; 115%! line ([x(:), x(:)], [y1(:), y2(:)], args{:}); 116%! title ("Test broadcasting for line()"); 117%! subplot (3,1,2); 118%! line (x(:), [y1(:), y2(:)], args{:}); 119%! subplot (3,1,3); 120%! line ([x(:), x(:)+pi/2], y1(:), args{:}); 121%! xlim ([0 10]); 122 123%!test 124%! hf = figure ("visible", "off"); 125%! unwind_protect 126%! h = line; 127%! assert (findobj (hf, "type", "line"), h); 128%! assert (get (h, "xdata"), [0 1], eps); 129%! assert (get (h, "ydata"), [0 1], eps); 130%! assert (get (h, "type"), "line"); 131%! assert (get (h, "color"), get (0, "defaultlinecolor")); 132%! assert (get (h, "linestyle"), get (0, "defaultlinelinestyle")); 133%! assert (get (h, "linewidth"), get (0, "defaultlinelinewidth"), eps); 134%! unwind_protect_cleanup 135%! close (hf); 136%! end_unwind_protect 137