octave_packages/m/plot/uigetfile.m

   1 ## Copyright (C) 2010-2012 Kai Habel
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {[@var{fname}, @var{fpath}, @var{fltidx}] =} uigetfile ()
  21 ## @deftypefnx {Function File} {[@dots{}] =} uigetfile (@var{flt})
  22 ## @deftypefnx {Function File} {[@dots{}] =} uigetfile (@var{flt}, @var{dialog_name})
  23 ## @deftypefnx {Function File} {[@dots{}] =} uigetfile (@var{flt}, @var{dialog_name}, @var{default_file})
  24 ## @deftypefnx {Function File} {[@dots{}] =} uigetfile (@dots{}, "Position", [@var{px} @var{py}])
  25 ## @deftypefnx {Function File} {[@dots{}] =} uigetfile (@dots{}, "MultiSelect", @var{mode})
  26 ##
  27 ## Open a GUI dialog for selecting a file.  It returns the filename @var{fname},
  28 ## the path to this file @var{fpath}, and the filter index @var{fltidx}.
  29 ## @var{flt} contains a (list of) file filter string(s) in one of the following
  30 ## formats:
  31 ##
  32 ## @table @asis
  33 ## @item "/path/to/filename.ext"
  34 ## If a filename is given then the file extension is extracted and used as
  35 ## filter.  In addition, the path is selected as current path and the filename
  36 ## is selected as default file.  Example: @code{uigetfile ("myfun.m")}
  37 ##
  38 ## @item A single file extension "*.ext"
  39 ## Example: @code{uigetfile ("*.ext")}
  40 ##
  41 ## @item A 2-column cell array
  42 ## containing a file extension in the first column and a brief description
  43 ## in the second column.
  44 ## Example: @code{uigetfile (@{"*.ext", "My Description";"*.xyz",
  45 ## "XYZ-Format"@})}
  46 ##
  47 ## The filter string can also contain a semicolon separated list of filter
  48 ## extensions.
  49 ## Example: @code{uigetfile (@{"*.gif;*.png;*.jpg", "Supported Picture
  50 ## Formats"@})}
  51 ## @end table
  52 ##
  53 ## @var{dialog_name} can be used to customize the dialog title.
  54 ## If @var{default_file} is given then it will be selected in the GUI dialog.
  55 ## If, in addition, a path is given it is also used as current path.
  56 ##
  57 ## The screen position of the GUI dialog can be set using the "Position" key
  58 ## and a 2-element vector containing the pixel coordinates.
  59 ## Two or more files can be selected when setting the "MultiSelect" key to "on".
  60 ## In that case @var{fname} is a cell array containing the files.
  61 ## @end deftypefn
  62
  63 ## Author: Kai Habel
  64
  65 function [retfile, retpath, retindex] = uigetfile (varargin)
  66
  67   defaulttoolkit = get (0, "defaultfigure__graphics_toolkit__");
  68   funcname = ["__uigetfile_", defaulttoolkit, "__"];
  69   functype = exist (funcname);
  70   if (! __is_function__ (funcname))
  71     funcname = "__uigetfile_fltk__";
  72     if (! __is_function__ (funcname))
  73       error ("uigetfile: fltk graphics toolkit required");
  74     elseif (! strcmp (defaulttoolkit, "gnuplot"))
  75       warning ("uigetfile: no implementation for toolkit `%s', using `fltk' instead",
  76                defaulttoolkit);
  77     endif
  78   endif
  79
  80   if (nargin > 7)
  81     error ("uigetfile: number of input arguments must be less than eight");
  82   endif
  83
  84   defaultvals = {cell(0, 2),         # File Filter
  85                  "Open File",        # Dialog Title
  86                  "",                 # Default file name
  87                  [240, 120],         # Dialog Position (pixel x/y)
  88                  "off",              # MultiSelect on/off
  89                  pwd};               # Default directory
  90
  91   outargs = cell (6, 1);
  92   for i = 1 : 6
  93     outargs{i} = defaultvals{i};
  94   endfor
  95
  96   idx1 = idx2 = [];
  97   if (length (varargin) > 0)
  98     for i = 1 : length (varargin)
  99       val = varargin{i};
 100       if (ischar (val))
 101         if (strncmpi (val, "multiselect", 11))
 102           idx1 = i;
 103         elseif (strncmpi (val, "position", 8))
 104           idx2 = i;
 105         endif
 106       endif
 107     endfor
 108   endif
 109
 110   stridx = [idx1, idx2, 0];
 111   if (length (stridx) > 1)
 112     stridx = min (stridx(1 : end - 1));
 113   endif
 114
 115   args = varargin;
 116   if (stridx)
 117     args = varargin(1 : stridx - 1);
 118   endif
 119
 120   len = length (args);
 121   if (len > 0)
 122     file_filter = args{1};
 123     [outargs{1}, outargs{3}, defdir] = __file_filter__ (file_filter);
 124     if (length (defdir) > 0)
 125       outargs{6} = defdir;
 126     endif
 127   else
 128     outargs{1} = __file_filter__ (outargs{1});
 129   endif
 130
 131   if (len > 1)
 132     if (ischar (args{2}))
 133       if (length (args{2}) > 0)
 134         outargs{2} = args{2};
 135       endif
 136     elseif (! isempty (args{2}))
 137       print_usage ();
 138     endif
 139   endif
 140
 141   if (len > 2)
 142     if (ischar (args{3}))
 143       [fdir, fname, fext] = fileparts (args{3});
 144       if (length (fdir) > 0)
 145         outargs{6} = fdir;
 146       endif
 147       if (length (fname) > 0 || length (fext) > 0)
 148         outargs{3} = strcat (fname, fext);
 149       endif
 150     elseif (! isempty (args{3}))
 151       print_usage ();
 152     endif
 153   endif
 154
 155   if (stridx)
 156     ## we have string arguments ("position" or "multiselect")
 157
 158     ## check for even number of remaining arguments, prop/value pair(s)
 159     if (rem (nargin - stridx + 1, 2))
 160       error ("uigetfile: expecting property/value pairs");
 161     endif
 162
 163     for i = stridx : 2 : nargin
 164       prop = varargin{i};
 165       val = varargin{i + 1};
 166       if (strncmp (tolower (prop), "position", 8))
 167         if (ismatrix (val) && length(val) == 2)
 168           outargs{4} = val;
 169         else
 170           error ("uigetfile: expecting 2-element vector for position argument");
 171         endif
 172       elseif (strncmp (tolower (prop), "multiselect", 11))
 173         if (ischar (val))
 174           outargs{5} = tolower (val);
 175         else
 176           error ("uigetfile: expecting string argument (on/off) for multiselect");
 177         endif
 178       else
 179         error ("uigetfile: unknown argument");
 180       endif
 181     endfor
 182   endif
 183
 184   [retfile, retpath, retindex] = feval (funcname, outargs{:});
 185
 186 endfunction
 187
 188 %!demo
 189 %! uigetfile({"*.gif;*.png;*.jpg", "Supported Picture Formats"})
 190
 191 ## Remove from test statistics.  No real tests possible.
 192 %!test
 193 %! assert (1);