# 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"))))))