uiputimfile(varargin)

function [filename, pathname, imformat] = uiputimfile(varargin)
%UIPUTIMFILE Save image file dialog box
%   [FILENAME, PATHNAME, IMFORMAT] = UIPUTIMFILE(TITLE) displays a dialog
%   box for the user to fill in and returns the filename and path strings
%   and the corresponding image file format registry information of the
%   selected file format. A successful return occurs if a valid filename is
%   specified. If an existing filename is specified or selected, a warning
%   message is displayed. The user may select Yes to use the filename or No
%   to return to the dialog to select another filename.
%
%   Parameter TITLE is a string containing the title of the dialog box.
%
%   The output variable FILENAME is a string containing the name of the
%   file selected in the dialog box. If the user presses Cancel, it is set
%   to 0.
%
%   The output variable PATHNAME is a string containing the path of the
%   file selected in the dialog box. If the user presses Cancel, it is set
%   to 0.
%
%   The output variable IMFORMAT returns the image file format registry
%   information structure from IMFORMATS. The fields in this structure are:
%  
%          ext         - A cell array of file extensions for this format
%          isa         - Function to determine if a file "IS A" certain type
%          info        - Function to read information about a file
%          read        - Function to read image data a file
%          write       - Function to write MATLAB data to a file
%          alpha       - 1 if the format has an alpha channel, 0 otherwise
%          description - A text description of the file format
%   
%   The values for the isa, info, read, and write fields must be functions
%   which are on the MATLAB search path or function handles. If the user
%   presses Cancel, it is set to 0.
%
%   [FILENAME, PATHNAME, IMFORMAT] = UIPUTIMFILE(FORMATINDEX, TITLE)
%   FORMATINDEX is an array of the IMFORMATS row indices to filter only
%   specified image formats. Note that the index is dependent on the MATLAB
%   release and OS platform.
%
%   [FILENAME, PATHNAME, IMFORMAT] = UIPUTIMFILE(TITLE, FILE)
%   [FILENAME, PATHNAME, IMFORMAT] = UIPUTIMFILE(FORMATINDEX, TITLE, FILE)
%   FILE is a string containing the name to use as the default selection.
%
%   The output variable FILENAME is a cell array of strings if multiple
%   filenames are selected. Otherwise, it is a string representing the
%   selected filename.
%
%   Examples:
%
%   [filename, pathname, imformat] = uiputimfile('Save image as');
%
%   Force BMP file:
%
%   [filename, pathname, imformat] = uiputimfile(1, 'Save image as');
%
%   FORMATINDEX=1 is used because BMP is the first entry in the IMFORMATS.
%   Or, force one of 3 BMP, GIF, and JPG files:
%
%   [filename, pathname, imformat] = uiputimfile([1 4 8], 'Save image as');
%
%   See also UIGETIMFILE, UIPUTFILE, UIGETFILE, UIGETDIR, IMFORMATS.

% Written by: Takeshi Ikuma
% Date: 11/12/2009

if isnumeric(varargin{1}) % FORMATINDEX given
   fmtidx = varargin{1}(:);
   vai = 2;
else
   vai = 1;
end

fmts = imformats;
num_entries = length(fmts);

if vai==2
   if any(isnan(fmtidx)) || any(isinf(fmtidx)) || any(fmtidx<1) || any(fmtidx>num_entries) || any(fmtidx~=floor(fmtidx))
      error('FORMATINDEX must be an array of index to IMFORMATS entry.');
   end
   fmts = fmts(unique(fmtidx)); % remove duplicates
   num_entries = length(fmts);
end

allfile = (num_entries~=1);
filterspec = cell(num_entries + allfile,2);
if allfile % if more than 1, 1st filterspec to include'em all
   [filterspec{1,1},filterspec{1,2}] = list_exts([fmts.ext],'All Supported Image Formats');
end
for k = 1:num_entries
   [filterspec{k+allfile,1},filterspec{k+allfile,2}] = list_exts(fmts(k).ext,fmts(k).description);
end
   
try
   [filename, pathname, filterindex] = uigetfile(filterspec,varargin{vai:end});
catch ME
   throwAsCaller(ME);
end

if nargout>2
   if filterindex==1 && allfile
      [p,f,e] = fileparts(filename);
      e = e(2:end); % remove the dot
      for k = 1:num_entries
         if any(strcmpi(e,fmts(k).ext))
            imformat = fmts(k);
            break;
         end
      end
   elseif filterindex==0
      imformat = 0;
   else
      imformat = fmts(filterindex-allfile);
   end
end


function [extlist,extshow] = list_exts(exts,desc)
N = length(exts);
extlist = sprintf('*.%s',exts{1});
extshow = sprintf('%s (*.%s',desc,exts{1});
for n = 2:N
   extlist = sprintf('%s;*.%s',extlist,exts{n});
   extshow = sprintf('%s, *.%s',extshow,exts{n});
end
extshow = sprintf('%s)',extshow);

% Copyright (c)2009, Takeshi Ikuma
% All rights reserved.
% 
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
% 
%     * Redistributions of source code must retain the above copyright
%     notice, this list of conditions and the following disclaimer. *
%     Redistributions in binary form must reproduce the above copyright
%     notice, this list of conditions and the following disclaimer in the
%     documentation and/or other materials provided with the distribution.
%     * Neither the name of the <ORGANIZATION> nor the names of its
%     contributors may be used to endorse or promote products derived from
%     this software without specific prior written permission.
% 
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
% IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
% THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
% PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
% CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
% PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.