FileBrowser (leaf, event)

A FileBrowser is used for examining directories and selecting files.


Value GP
(Text, ".")

On retrieval, the value is the full pathname of the selected file, or NIL if no file is selected. When specified, the value may be absolute or relative (to the currently displayed directory), and may name a file or a directory. If a directory is specified, that directory is displayed but no file is selected, hence the new retrievable value is NIL. An initial specification, if relative, is relative to the current working directory of the application. Thus, the default initial value of ``.'' displays the current working directory.
Suffixes
(TextList)

If this property is specified, the file-browser will show only those files whose suffixes are in this list. The strings should not include the period; to include files that have no suffix, use the empty string. Example: (Suffixes "i3" "m3" "" "fv") (Directories are always shown.)
ReadOnly
(Boolean, FALSE)

If true, the browser will only accept selection or naming of files that already exist. Otherwise, user may name a new file by typing in the helper (see Helper).

Behavior
The FileBrowser displays a list of the files in the current directory, in alphabetic order. The user can select a file by clicking on its name, and activate it by double-clicking. Auto-scrolling works as for Browser. In the default setup, only activating a file generates an event. Activating a directory makes that the current directory, and changes the display to show it.
If a helper is present (see Helper), it displays the pathname of the current directory whenever the current directory is changed. The user may also type a filename in the helper, and press Return to activate it.
There are three ``states'' of selection in a FileBrowser with a Helper. After a new directory has just been set, there is no selection; the value is NIL. When the user clicks on an item in the browser, the browser has the selection, shown by a highlighted item; when the user types any character in the helper, the helper has the selection; the highlight vanishes from the browser. Thus it is possible to give a name for a file that does not yet exist, provided that ReadOnly is false. A relative pathname typed in the Helper is relative to the current directory.
We recommend using (LabelFont "fixed") for a filebrowser.
Shape
At minimum, large enough to hold its scrollbar plus the single string "XXXX" in the font being used, plus the shadow. Infinitely stretchable in both dimensions.
Notes
A Helper never generates events in its own name. It can be accessed in its own name, but this is not recommended.
OS-related errors can occur: nonexistent directory in path, current directory became inaccessible, protection violation, etc. The default reaction to these errors is just to refuse to activate anything. In such a state, GetText will return NIL. The user can get out of this state by typing an absolute pathname of a directory that is known to exist. The underlying FileBrowserVBT interface has a mechanism (the error method) whereby the client can be notified of such errors, to report them to the user appropriately.
See Also
Helper and DirMenu

It is common (and recommended) practice to combine a FileBrowser, a DirMenu, and a Helper, with activation and cancellation buttons, in an arrangment like the following, which could be used in an ``Open...'' dialog.


(ZChassis
  (VBox
    (HBox
      (Shape (Width 150) (Height 150)
        (VBox (LabelFont "fixed")
          (DirMenu (For fb))
          (Glue 6)
          (Frame Lowered (BgColor "White")
             (FileBrowser %fb ReadOnly))))
      Fill
      (Shape (Width 100)
       (VBox Fill
          (Button %open "Open")
          (Glue 10)
          (CloseButton "Cancel"))))
    (HBox
      (Shape (Width 30) (Height 16) "File:")
      (Frame Lowered (BgColor "White")
        (Helper (For fb) (Font "fixed"))))))