--- a/main/zenity/inst/zenity_file_selection.m	Thu Apr 01 07:59:29 2010 +0000
+++ b/main/zenity/inst/zenity_file_selection.m	Sat Apr 03 03:48:04 2010 +0000
@@ -15,22 +15,24 @@
 ## along with this program; If not, see <http://www.gnu.org/licenses/>.
 
 ## -*- texinfo -*-
-## @deftypefn  {Function File} zenity_file_selection(@var{title}, @var{option1}, ...)
-## Opens a file selection dialog.
-## The variable @var{title} sets the title of the file selection window.
-## The optional string arguments can be
+## @deftypefn  {Function File} @var{files} = zenity_file_selection(@var{title}, @var{option1}, ...)
+## Opens a file selection dialog using Zenity. The variable @var{title} sets the
+## title of the file selection window. The optional string arguments can be:
 ## @table @samp
 ## @item save
 ## The file selection dialog is a dialog for saving files.
 ## @item multiple
-## It is possible to select multiple files. @var{title}} will hold a cell array, even
-## if user selects only one file.
+## It is possible to select multiple files. @var{files} will hold a cell array,
+## even if user selects only one or no file.
 ## @item directory
-## It is possible to select only directories.
+## Activates directory-only selection.
+## @item timeout=XX
+## Specifies timeout @var{XX} in seconds after which the dialog is closed. If
+## no file is selected in the specified time, returns an empty string or cell
+## array, depending whether `multiple' was selected or not.
 ## @item Anything else
 ## The argument will be the default selected file.
 ## @end table
-## and @code{error}.
 ##
 ## @seealso{zenity_calendar, zenity_list, zenity_progress, zenity_entry, zenity_message,
 ## zenity_text_info, zenity_notification}
@@ -38,7 +40,7 @@
 
 function files = zenity_file_selection(title, varargin)
 
-  save = multiple = directory = filename = "";
+  save = multiple = directory = filename = timeout = "";
   if (nargin == 0 || isempty(title))
     title = "Select a file";
   endif
@@ -52,46 +54,62 @@
     elseif (isc && strcmpi(option, "directory"))
       directory = "--directory";
     elseif (isc)
-      filename = sprintf('--filename="%s"', varargin{i});
+      if (strfind(option, "timeout="))
+        timeout = ["--timeout=", option(strfind(option, "=")+1 : end)];
+      else
+        filename = sprintf('--filename="%s"', varargin{i});
+      endif
     else
       error("zenity_file_selection: unsupported option");
     endif
   endfor
 
-  # Separator set to "/" because it's an invalid character in most decent
-  # filesystems and so, unlikely to exist in the middle of filenames
-  # It's also the fileseparator so filenames will always already start with a
-  # '/' which is good since it can look for double '//' as separator
-  cmd = sprintf('zenity --file-selection --title="%s" --separator="/" %s %s %s %s', ...
-                 title, save, multiple, directory, filename);
+# The separator is set to "/" because it's an invalid character for filenames
+# in most filesystems and so, unlikely to exist in the middle of filenames.
+# It's also the fileseparator so filenames will always already start with a
+# '/' which is good since we can look for double '//' as separator for filepaths
+  cmd = sprintf('zenity --file-selection --title="%s" --separator="/" %s %s %s %s %s', ...
+                 title, save, multiple, directory, filename, timeout);
   [status, output] = system(cmd);
   if (status == 0)
     if (output(end) == "\n")
         output = output(1:end-1);
     endif
-    # With 'multiple', always place the output in a cell array, even if only one
-    # file is selected.
+# With 'multiple', always place the output in a cell array, even if only one
+# file is selected.
     if (multiple)
       idx = strfind(output, "//");
       if (idx)
-        files = cell(length(idx)+1,1);
-        idx   = [0, idx, length(output)];
-        for i = 1:(length(idx)-2)
-          files{i} = output((idx(i)+1):(idx(i+1)-1));
+        files = cell(length(idx)+1, 1);
+        idx   = [0, idx, length(output)+1];
+        for i = 1 : (length(idx)-1)
+          files{i}  = output( idx(i)+1 : idx(i+1)-1 );
         endfor
-        files{i+1} = output((idx(i+1)+1):idx(end));
-        return
       else
         files     = cell(1);
         files{1}  = output;
-        return
       endif
     else
       files = output;
     endif
-  elseif (status == 1 || status == -1)
-    warning("No file selected selected. Returning empty string.");
+# Exit code -1 = An unexpected error has occurred
+# Exit code  1 = The user has either pressed Cancel, or used the window
+# functions to close the dialog
+# Exit code  5 = The dialog has been closed because the timeout has been reached
+  elseif (status == 1 && multiple)
+    warning("No file selected. Returning empty cell array.");
+    files = cell(1);
+  elseif (status == 1)
+    warning("No file selected. Returning empty string.");
     files = "";
+  elseif (status == 5 && multiple)
+    warning("Timeout reached. No file selected selected. Returning empty cell array.");
+    files = cell(1);
+  elseif (status == 5)
+    warning("Timeout reached. No file selected selected. Returning empty string.");
+    files = "";
+  elseif (status == -1)
+    error("An unexpected error occurred: %s", output);
   else
     error("zenity_file_selection: %s", output);
   endif