## Copyright (C) 2005-2011 John W. Eaton
##
## This file is part of Octave.
##
## Octave is free software; you can redistribute it and/or modify it
## under the terms of the GNU General Public License as published by
## the Free Software Foundation; either version 3 of the License, or (at
## your option) any later version.
##
## Octave is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with Octave; see the file COPYING.  If not, see
## <http://www.gnu.org/licenses/>.

## -*- texinfo -*-
## @deftypefn  {Function File} {} axes ()
## @deftypefnx {Function File} {} axes (@var{property}, @var{value}, @dots{})
## @deftypefnx {Function File} {} axes (@var{h})
## Create an axes object and return a handle to it.
## @end deftypefn

## Author: jwe

function h = axes (varargin)

  if (nargin == 0 || nargin > 1)
    ## make default axes object, and make it the current axes for the
    ## current figure.
    idx = find (strcmpi (varargin(1:2:end), "parent"), 1, "first");
    if (! isempty (idx) && length (varargin) >= 2*idx)
      cf = varargin{2*idx};
      varargin([2*idx-1, 2*idx]) = [];
    else
      cf = gcf ();
    endif
    tmp = __go_axes__ (cf, varargin{:});
    set (ancestor (cf, "figure"), "currentaxes", tmp);
  else
    ## arg is axes handle, make it the current axes for the current
    ## figure.
    tmp = varargin{1};
    if (length(tmp) == 1 && ishandle (tmp)
        && strcmp (get (tmp, "type"), "axes"))
      parent = ancestor (tmp, "figure");
      set (0, "currentfigure", parent);
      set (parent, "currentaxes", tmp);
    else
      error ("axes: expecting argument to be a scalar axes handle");
    endif

    ax = [get(tmp, "xlim") get(tmp, "ylim") get(tmp, "zlim")];
    len =length(ax);
    for i = 1:2:len
      if (ax(i) == ax(i+1))
        error ("axes: lower limit(%d) cannot equal upper limit(%d)", i, i+1);
      endif
    endfor
## code to test for axes out of range.
## the variable do_reset is used to control whether out of range
## values are reset to something in range.  
## It has not been possible to determine, paticularly for the current
## fltk backend, what values within the range of "singles" result
## in a correct plot.  For this reason the current setting (do_reset = 0)
## just issues a warning if it is likely that the plot will be incorrect.
## So far, it seems that an "out of range" plot appears as obviously
## incorrect.  This is helpful in the sense that it prevents plots that
## appear to be correct, but are not.
    do_reset = 1;
    ca=gca();
    if (strcmp (get (get (ca, "parent"), "__graphics_toolkit__"), "fltk"))
       xyzmax = realmax("single")/1e3;    ## numbers bigger than this do not plot
                                          ## correctly through FLT due to rounding
                                          ## above the max single limit.
                                          ## Plots like surf need this.   20 Apr 2011
    else
       xyzmax = realmax("double");        ## It is assumed that "double" works.
    endif
    axrange = [-xyzmax xyzmax -xyzmax xyzmax -xyzmax xyzmax];
    axoutl = ax(1:2:end) < axrange(1:2:end) ;
    axouth = ax(2:2:end) > axrange(2:2:end) ;
    for i = 1:1:len/2
      if(axoutl(i) == 1)
        ix = 2*(i-1)+1;
        warning ("axes: limit index (%i) is %g which is outside axis limit for fltk_backend.", ix, ax(ix));
        if(do_reset == 1)
          ax(ix) = axrange(ix);
        endif
      endif
    endfor
    for i = 2:1:len/2
      if(axouth(i) == 1)
        ix = 2*(i-1)+2;
        warning ("axes: limit index (%i) is  %g which is outside axis limit for fltk_backend.", ix, ax(ix));
        if(do_reset == 1)
          ax(ix) = axrange(ix);
        endif
      endif
    endfor
    if(do_reset == 1)
      axx = [get(tmp, "xlim") get(tmp, "ylim") get(tmp, "zlim")];
      if(any(ax != axx))
        if ((ax(1) != axx(1)) || (ax(2) != axx(2)))
          set (ca, "xlim", [ax(1), ax(2)]);
        endif
        if ((ax(3) != axx(3)) || (ax(4) != axx(4)))
          set (ca, "ylim", [ax(3), ax(4)]);
        endif
        if ((ax(5) != axx(5)) || (ax(6) != axx(6)))
          set (ca, "zlim", [ax(5), ax(6)]);
        endif
        warning ("axes: limits changed to: %g %g %g %g %g %g\n", ax);
      endif
    endif
  endif

  if (nargout > 0)
    h = tmp;
  endif

endfunction
