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