fig(w, h, varargin)

function handle= fig(w, h, varargin)
%{
                  Written by Dr. Phillip M. Feldman

                    Version 3.1.1   18 June, 2009

fig() opens a new figure window of specified size, creates an axes object
within the window, and applies any additional figure window properties that
are specified.  The window size may be given in units of either screen
dimensions (i.e., as fractions of the width and height of the screen) or
pixels. The calling program may also specify the color of the region inside
the axes, the color of the frame around the axes, and any parameters that
would be passed to Matlab's figure() function.

Syntax:

   handle= fig(w, h, option1, value1, ... );

All calling arguments are optional.  Arguments must be specified in pairs.
In particular, one cannot specify w without also specifying h.

- w is the window width specified either as a fraction (0 to 1) of the
screen width or in pixels (a whole number greater than or equal to 200).
The default width is 0.8.

- h is the window height specified either as a fraction (0 to 1) of the
screen height or in pixels (a whole number greater than or equal to 100).
The default height is 0.6.

Note: The units of w and h must be the same, i.e., you must not specify
one as a fraction of the screen dimension and the other in pixels.

Any arguments following w and h are option/value pairs.  The options are
always strings.  Allowed options and corresponding values are as follows:

- AxesColor specifies the color of the region inside the axes.

- BgndColor or BackgroundColor specifies the color of the frame around the
axes.

Each color specification must be an RGB 3-tuple, the name of a color
(lower-case string), or a color index (1-21).  Default colors are white.


REVISION HISTORY

Version 3.1.1, 6-18-2009:

Fixed code so that parameter name for background color can be either
'BgndColor' or 'BackgroundColor'.

Version 3.1, 5-11-2009:

- Eliminated dependence on getargs().

- Modified code to allow any parameter name/value pairs that would be
accepted by Matlab's figure() function.

- Window width and height may now be specified in units of either screen
dimensions or pixels.

Version 3.0, 4-10-2009: Did major rework of the code to:

- make use of new color management system,
- systematize the handling of calling arguments, and
- allow the user to control the initial visibility state of the window.

Version 2.3, 10-5-2007: Fixed bug (set Position was using wrong elements of
scrsz).

Version 2.2, 10-3-2007: The function now returns a handle to the newly
created figure.

Version 2.1, 9-24-2007: As per a suggestion from Andrew Brandt at the
MathWorks, I changed the function so that it sets the default axes color
rather than creating new axes with the specified color. This change was
made because with the previous version, the axes color was being lost when
a plot with logarithmic axes was created.

Version 2.0, 9-19-2007: Added second color argument, so that the user can
control not only the "background color", but also the "axes color".
%}


% Section 1: Check input arguments and assign default values if necessary.

if mod(nargin,2) ~= 0
   error('The number of calling arguments must be even.');
end

% Supply default values for optional input arguments.

if nargin == 0
   w= 0.8; h= 0.6;
end

if w > 1 & w < 200
   error('The window width must either be <= 1 or >= 200.');
end

if h > 1 & h < 100
   error('The window height must either be <= 1 or >= 100.');
end

if (w <= 1 & h > 1) | (h <= 1 & w > 1)
   error('Window width and height units must be the same.');
end

AxesColor= 'white';
BgndColor= 'white';


% Section 2: Process optional name/value pairs.

% We must work our way backwards through the list of optional arguments;
% otherwise, deletions would modify the indices of elements that have not
% yet been processed.

for i= length(varargin)-1 : -2 : 1
   if strcmpi(varargin{i},'AxesColor')
      % Save axes color:
      AxesColor= varargin{i+1};

   elseif strcmpi(varargin{i},'BgndColor') | ...
          strcmpi(varargin{i},'BackgroundColor')
      % Save axes color:
      BgndColor= varargin{i+1};

   else
      % We don't recognize this parameter name, so leave it alone.  (It
      % will be passed to figure() for processing).
      continue;
   end

   % Delete parameter name and value from varargin:
   varargin(i:i+1)= [];
end


% To allow for the possibility that a color has been specified as a string
% (color name) or as a color index (1-21), call RGB() to convert it to an
% RGB 3-tuple.  (If already an RGB 3-tuple, it will be left unchanged).

AxesColor= RGB(AxesColor);
BgndColor= RGB(BgndColor);


% Section 3: Create figure window, set its background color, size, and
% position, and apply any additional properties.

set(0, 'unit','pixels');
ScreenSize= get(0,'ScreenSize');

if w <= 1
   % Window dimensions were specified as a fraction of screen dimensions:

   winsize(1)= w * ScreenSize(3);
   winsize(2)= h * ScreenSize(4);
   winposn(1)= 0.5 * (1-w) * ScreenSize(3);
   winposn(2)= 0.5 * (1-h) * ScreenSize(4);

else
   % Window dimensions were specified in pixels:

   winsize(1)= w;
   winsize(2)= h;
   winposn(1)= 0.5 * (ScreenSize(3) - w);
   winposn(2)= 0.5 * (ScreenSize(4) - h);
end

handle= figure('Color',BgndColor);

set (handle, 'Position',[winposn(1) winposn(2) winsize(1) winsize(2)]);

% Apply any additional properties to the window:

for i= 1 : 2 : length(varargin)
   set (handle, varargin{i}, varargin{i+1});
end


% Section 4: Set the default axes color and create the axes object.

set(0,'defaultAxesColor', AxesColor);

% Create axes object:
axes;