5.3 DUIM-Sheets Module

choose-file

Generic function

Summary

Displays the built-in file dialog for the target platform.

Signature

choose-file #key frame owner title documentation exit-boxes name default => locator

Arguments

frame: An instance of type <frame>. Default value: #f.
owner: An instance of type <sheet>. Default value: #f.
title: An instance of type <string>.
documentation: An instance of type <string>.
direction: An instance of type one-of(#"input", #"output"). Default value: #"input".
filters: An instance of type limited(<sequence>, of: <sequence>).
exit-boxes: An instance of type <object>.
name: An instance of type <object>.
default: An instance of type <string>.

Values

locator: An instance of type <string>.

Library

duim-sheets

Module

duim-sheets

Description

Displays the built-in file dialog for the target platform, which allows the user to choose a file from any of the local or networked drives currently connected to the computer. The function returns the name of the file chosen by the user.

Figure 5.2 Typical appearance of a choose-file dialog

If the frame argument is specified, the top-level sheet of frame becomes the owner of the dialog.

Alternatively, you can specify the owner directly using the owner argument, which takes an instance of <sheet> as its value.

By default, both frame and owner are #f, meaning the dialog has no owner. You should not specify both of these values.

If you wish, you can specify a title for the dialog; this is displayed in the title bar of the frame containing the dialog.

The direction argument is used to specify whether the file chosen is being opened (that is, information in the file is loaded into the application) or saved to (that is, information in the application is being saved to a file on disk).

The filters argument lets you specify the file filters that should be offered to the user in the dialog. These filters are typically available in a drop-down list box, and let the user display only certain types of file, such as text files. Each filter is described as a sequence of strings:

The first string in the sequence is a description of the files that are displayed when this filter is chosen.
Each subsequent string is a regular expression that describes which files to display in the dialog.

For example, to specify a filter that lets the user choose to display either text files, HTML files, or Dylan source files, the following sequence should be passed to the filters argument:

#[#["Text files", "*.txt", "*.text"], 
  #["HTML files", "*.htm", "*.html"], 
  #["Dylan files", "*.dylan"]

Here, text files are defined as any file with a filename suffix of .txt or .text, HTML files have filenames with a suffix of either .htm or .html, and Dylan files have filenames with a suffix of .dylan.

The default argument is used to specify a default filename to pass to the dialog. This is a convenient way to suggest a file in which some information may be saved, or a file to be loaded into an application.

Example

The following example illustrates how you can define a class of frame that contains buttons to display both Open and Save As dialogs, using the pre-built dialog classes for your target environment.

define frame <open-save-dialog-frame> (<simple-frame>)
  pane open-file-button (frame)
    make(<menu-button>,
         label: "Open...",
         documentation: 
          "Example of standard file 'Open' dialog",
         activate-callback: 
          method (button)
          let file = choose-file(direction: #"input",
                                 owner: frame);
            if (file) frame-status-message(frame)
             := format-to-string
                  ("Opened file %s", file);
            end
          end);
  pane save-file-button (frame)
    make(<menu-button>,
         label: "Save As...",
         documentation: 
          "Example of standard file 'Save As' dialog",
         activate-callback: 
          method (button)
          let file = choose-file(direction: #"output",
                                 owner: frame);
            if (file) frame-status-message(frame)
             := format-to-string
                  ("Saved file as %s", file);
            end
          end);
end frame <open-save-dialog-frame>;