PLT MrLib: Graphical Libraries Manual

10.1 `path-dialog%`

Superclass: dialog%

The path-dialog% class implements a platform-independent file/directory dialog. The dialog is the same as the dialog under X for MrEd's get-file, put-file, get-directory, and get-file-list procedures, but considerable extra functionality is available through the class.

(new path-dialog% [(label _)] [(message _)] [(parent _)] [(directory _)] [(filename _)] [(put? _)] [(dir? _)] [(existing? _)] [(new? _)] [(multi? _)] [(can-mkdir? _)] [(filters _)] [(show-file? _)] [(show-dir? _)] [(ok? _)] [(guard _)]) -> path-dialog% object
   label = #f : string (up to 200 characters) or #f
   message = #f : string (up to 200 characters) or #f
   parent = #f : frame% or dialog% object or #f
   directory = #f : path or #f
   filename = #f : path or #f
   put? = #f : boolean
   dir? = #f : boolean
   existing? = (not put?) : boolean
   new? = #f : boolean
   multi? = #f : boolean
   can-mkdir? = put? : boolean
   filters = #t : list of (list filter-name filter-glob), #f, or #t
   show-file? = #f : path-to-boolean procedure or #f
   show-dir? = #f : path-to-boolean procedure or #f
   ok? = #f : path-to-boolean procedure or #f
   guard = #f : procedure or #f

The label argument is the dialog's title string. If label is #f, the default is based on other field values.

The message argument is a prompt message to show at the top of the dialog. If it is #f, no prompt line.

The parent argument is the parent frame or dialog, if any, for this dialog.

The directory argument specifies the dialog's initial directory. If it is #f, the initial directory is the last directory that was used by the user (or the current directory on first use).

The filename argument provides an initial filename text, if any.

If put? is true, the dialog operates in choose-file-to-write mode (and warn the user if choosing an existing name).

If dir? is true, the dialog operates in directory-choice mode.

If existing? is true, the use must choose an existing file.

If new? is true, the user must choose a non-existant path. Providing both new? and existing? as true triggers an exception.

If multi? is true, the dialog allows selection of multiple paths.

If can-mkdir? is true, the dialog includes a button for the user to create a new directory.

The filters argument is one of:
- (list-of (list filter-name filter-glob)) -- a list of pattern names (e.g., ``Scheme Files'') and glob patterns (e.g., "*.scm;*.ss"). Any list (including an empty list) enables a filter box for the user to enter glob patterns, and the given list of choices is available in a combo-box drop-down menu. Glob patterns are the usual Unix ones (see glob->regexp), and a semicolon can be used to allow multiple patterns.
- #f -- no patterns and no filter input box.
- #t -- use a generic ``All'' filter, which is ``*.*'' on Windows and ``*'' on other platforms.
The show-file? predicate is used to filter file paths that are shown in the dialog. The predicate is applied to the file name as a string while the current-directory parameter is set. This predicate is intended to be a lightweight filter for choosing which names to display.

The show-dir? predicate is similar, but for directories instead of files.

The ok? predicate is used in a similar fashion to the show-file? and show-dir? predicate, but it is used to determine whether the OK button should be enabled when a file or directory is selected (so it need not be as lightweight as the other predicates).

The guard procedure is a generic verifier for the dialog's final result, as produced by the run method. It receives the result that is about to be returned (which can be a list in a multi-selection dialog), and can return a different value (any value) instead. If it throws an exception, an error dialog is shown, and the dialog interaction continues (so it can be used to verify results without dismissing the dialog). This procedure can also raise void, in which case the dialog remains without an error message.

Methods
run

10.1 path-dialog%

10.1 `path-dialog%`