FileBrowser - browse and/or select file names

SYNOPSIS

       #include <InterViews/filebrowser.h>

DESCRIPTION

       FileBrowser  is  a StringBrowser that displays file names.
       In addition  to  the  standard  StringBrowser  constructor
       parameters,  the FileBrowser constructor takes a directory
       name as an argument.  The  FileBrowser  scans  the  corre-
       sponding  directory,  appending the file names to its list
       of strings.  FileBrowser lets the user choose a file name,
       and the application queries the FileBrowser for the chosen
       file.

PUBLIC OPERATIONS

       FileBrowser(ButtonState*, const char* dir, int  rows,  int
              cols, boolean uniqueSel, int highlight, const char*
              done)
       FileBrowser(const  char*  name,  ButtonState*,  const
              char*, int, int, boolean, int, const char*)
              Create  a new FileBrowser object.  The ButtonState,
              rows, cols, uniqueSel, highlight,  done,  and  name
              parameters have semantics identical to those of the
              corresponding StringBrowser  parameters.   The  dir
              parameter  specifies  the  directory  to search for
              file names.  Internally, FileBrowser  prepends  dir
              to  relative path specifications in operations that
              require them, thus avoiding a chdir(2).

       boolean IsADirectory(const char*)
              Return whether or not the given relative path  cor-
              responds to a valid directory.

       boolean SetDirectory(const char* newdir)
              Change  the  search  directory  to  newdir  if that
              directory is accessible.  The function returns true
              if successful.

       const char* GetDirectory()
              Return the name of the search directory.

       const char* ValidDirectories(const char* path)
              Given  a  path string, return the largest substring
              (starting from the beginning of path)  that  repre-
              sents a valid path.  The substring is returned in a
              static buffer and should be copied before use.

       const char* Normalize(const char* path)
              Return a normalized version of path with all spuri-
              ous  slashes,  dots,  and  tildes interpreted.  The
              normalized path is returned in a static buffer  and
              Return  the  ith  string as it appears in the File-
              Browser.  This function prepends the search  direc-
              tory  to  the string, normalizes the concatenation,
              and returns the result.

       void RereadDirectory()
              Rescan the current directory without  updating  the
              FileBrowser's appearance.

       virtual void Update()
              Rescan  the  current directory and update the File-
              Browser's appearance to reflect any changes in  the
              set of files it should display.

       void SetTextFilter(const char*)
       void SetDirectoryTextFilter(const char*)
       void SetModeFilter(int)
       void SetDirectoryModeFilter(int)
              By  default, FileBrowser displays all the files and
              directories  it  finds  in  the  search  directory.
              These  functions  provide  some  control  over  the
              entries that FileBrowser  displays.   SetTextFilter
              specifies  a regular expression (see Regexp(3I)) to
              match against file  names.   SetDirectoryTextFilter
              serves a similar role for directory names.  SetMod-
              eFilter and SetDirectoryModeFilter specify the mode
              (see chmod(1)) that displayed files and directories
              should have.  Only files and directories that match
              both  the  regular  expression  and  the  mode will
              appear in the FileBrowser.   Passing  nil  for  the
              regular  expression  or 0 for the mode restores the
              default behavior.

PROTECTED OPERATIONS

       void UpdateStrings()
              Explicitly update the FileBrowser's  appearance  to
              reflect  any  changes in the set of files it should
              display without rescanning the directory.

       virtual boolean Acceptable(const char*)
              Return whether the given file name is an acceptable
              name.   By  default, files that conform to the text
              or mode filter specifications are acceptable.  Only
              acceptable   files  will  be  displayed  by  Updat-
              eStrings.

SEE ALSO

       Interactor(2I), Button(3I), StringBrowser(3I), Regexp(3I),
       chmod(1)