1########################################################################
2##
3## Copyright (C) 2010-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  {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile ()
28## @deftypefnx {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt})
29## @deftypefnx {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt}, @var{dialog_name})
30## @deftypefnx {} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uiputfile (@var{flt}, @var{dialog_name}, @var{default_file})
31## Open a GUI dialog for selecting a file.
32##
33## @var{flt} contains a (list of) file filter string(s) in one of the following
34## formats:
35##
36## @table @asis
37## @item @qcode{"/path/to/filename.ext"}
38## If a filename is given the file extension is extracted and used as filter.
39## In addition the path is selected as current path in the dialog and the
40## filename is selected as default file.  Example: @code{uiputfile ("myfun.m")}
41##
42## @item @qcode{"*.ext"}
43## A single file extension.
44## Example: @code{uiputfile ("*.ext")}
45##
46## @item @code{@{"*.ext", "My Description"@}}
47## A 2-column cell array containing the file extension in the 1st column and
48## a brief description in the 2nd column.
49## Example: @code{uiputfile (@{"*.ext","My Description";"*.xyz",
50## "XYZ-Format"@})}
51## @end table
52##
53## The filter string can also contain a semicolon separated list of filter
54## extensions.
55## Example: @code{uiputfile (@{"*.gif;*.png;*.jpg",
56## "Supported Picture Formats"@})}
57##
58## @var{dialog_name} can be used to customize the dialog title.
59## If @var{default_file} is given it is preselected in the GUI dialog.
60## If, in addition, a path is given it is also used as current path.
61##
62## @var{fname} and @var{fpath} return the chosen name and path, respectively.
63## @var{fltidx} is the index in the list of filter extensions @var{flt} that
64## was selected.
65##
66## @seealso{uigetfile, uigetdir}
67## @end deftypefn
68
69function [retfile, retpath, retindex] = uiputfile (varargin)
70
71  if (nargin > 3)
72    print_usage ();
73  endif
74
75  ## Preset default values
76  outargs = {cell(0, 2),     # File Filter
77             "Save File",    # Dialog Title
78             "",             # Default filename
79             [240, 120],     # Dialog Position (pixel x/y)
80             "create",
81             pwd};           # Default directory
82
83  if (nargin > 0)
84    [outargs{1}, outargs{3}, defdir] = __file_filter__ ("uiputfile",
85                                                        varargin{1});
86    if (! isempty (defdir))
87      outargs{6} = defdir;
88    endif
89  else
90    outargs{1} = __file_filter__ ("uiputfile", outargs{1});
91  endif
92
93  if (nargin > 1)
94    if (ischar (varargin{2}))
95      outargs{2} = varargin{2};
96    elseif (! isempty (varargin{2}))
97      print_usage ();
98    endif
99  endif
100
101  if (nargin > 2)
102    if (ischar (varargin{3}))
103      if (isfolder (varargin{3}))
104        fdir = varargin{3};
105        fname = fext = "";
106      else
107        [fdir, fname, fext] = fileparts (varargin{3});
108      endif
109      if (! isempty (fdir))
110        outargs{6} = fdir;
111      endif
112      if (! isempty (fname) || ! isempty (fext))
113        outargs{3} = [fname fext];
114      endif
115    elseif (! isempty (varargin{3}))
116      print_usage ();
117    endif
118  endif
119
120  if (__event_manager_enabled__ ())
121    [retfile, retpath, retindex] = __event_manager_file_dialog__ (outargs{:});
122  else
123    funcname = __get_funcname__ (mfilename ());
124    [retfile, retpath, retindex] = feval (funcname, outargs{:});
125  endif
126
127  ## Append extension to the name if it isn't already added.
128  if (ischar (retfile))
129    [~, ~, ext] = fileparts (retfile);
130    if (isempty (ext))
131      ext = outargs{1}{retindex};
132      ext = strrep (ext, "*", "");
133      if (! strcmp (ext, '.'))
134        [~, ~, ext] = fileparts (ext);  # paranoid checking of extension
135        retfile = [retfile ext];
136      endif
137    endif
138  endif
139
140endfunction
141
142
143%!demo
144%! uiputfile ({'*.gif;*.png;*.jpg', 'Supported Picture Formats'});
145
146## Remove from test statistics.  No real tests possible.
147%!assert (1)
148