  ------------------------------------------------------------------------
  FilePick unit                             by Sebastian Groeneveld (2000)
  ------------------------------------------------------------------------

  Usage
  =====

  Add the following line to your program:

  $INCLUDE "FilePick.inc"


  Public routines
  ===============

  FUNCTION FilePick(       StartFolder  AS STRING , _
                     BYVAL FileMask     AS STRING , _
                     BYVAL Flags        AS INTEGER )   AS STRING


  StartFolder AS STRING
      This variable contains the path to start with. This variable may
      contain a long filename when running under Win9x. If the specified
      directory does not exist, the current directory is used.

      The variable is changed to the short filename of the last browsed
      directory.

  BYVAL FileMask AS STRING
      This variable determines what files are shown. It cannot later be
      changed by the user, so it is often best to set this to "*.*"

  BYVAL Flags AS INTEGER
      You can allow or prevent the user to perform certain tasks, like
      changing a directory, and renaming or deleting a file. To help you
      with using this variable there are some useful constants, specifying
      the related bit. The following help text explains what happens when
      you SET the corresponding bit:

      %AllowChangeDir = 0
         The user can browse other folders than the one specified in
         StartFolder.

      %AllowDelete = 1
         The user can delete files with the DEL key (confirmation is
         automatically displayed).

      %AllowRename = 2
         The user can rename files with the INS key.

      %ShowReadOnly = 3
         Files with the readonly attribute are also shown in the directory
         listing. You want to clear this bit if you're prompting the user
         for a file to write to.

      %ShowHidden = 4
         Hidden (and system) files are also shown in the directory listing.
         It's best not to combine this option with %AllowDelete or
         %AllowRename.

      %ShowLFN = 5
         A wider window layout is used, and long filenames are displayed.
         This only works when running under Win95 or Win98 (no, not under
         Win2K or WinNT), but there's no harm in setting this bit when
         running in any other OS.

      %ReturnLFN = 6
         FilePick will return the selected filename in long filename format.
         This only works when running under Win95 or Win98 (no, not under
         Win2K or WinNT), but there's no harm in setting this bit when
         running in any other OS.

      %EnableMouse = 7
         The user can use the mouse to select a file or change the directory.
         If no mouse is present, this option is ignored.



  Remarks
  =======

      * When renaming a file, the user can specify a long filename when
        running under Win9x, whether the option %ShowLFN is used or not.

      * When the current path name becomes too long to fit in the top of
        the window, part of it is removed (from the middle).

      * When file or path names in long filename format are too long to
        fit in the window, they are truncated in the middle. So the
        extension of a file will always be visible.

      * A very useful combination is setting bit %ShowLFN and clearing
        bit %ReturnLFN. This is because you often want to show the long
        filenames if possible, but want to know the short filename of
        the selected file, because then you can use it for other powerbasic
        (DOS-based) functions, like OPEN, NAME or KILL.

      * Both the background and the cursor location are stored before the
        file selection window is displayed, and are restored when leaving
        the function.

      * You can only use the flag constants by setting bits, and not by
        adding them together. So the following function call would NOT
        give the desired results:

          'Not working example
          FileName = FilePick( StartDir, FileMask, %ShowLFN + %ReturnLFN )

      * If a drive is not ready when the user selects it (eg. floppy
        drive), an error message is displayed for a short time and the
        previous directory is used. It seems that a CD-ROM drive never
        generates such an error when there's no disc in the drive. In
        that case an empty file and directory list is shown.

      * A list of active drive letters is automatically detected.


  Example
  =======

  $DIM ALL
  $INCLUDE "FilePick.inc"

  DIM StartDir  AS STRING
  DIM FileMask  AS STRING
  DIM Flags     AS INTEGER
  DIM FileName  AS STRING

  BIT SET Flags, %AllowChangeDir
  BIT SET Flags, %AllowRename
  BIT SET Flags, %ShowLFN
  BIT SET Flags, %EnableMouse

  StartDir = "C:\program files"
  FileMask = "*.*"

  FileName = FilePick( StartDir, FileMask, Flags )

  IF LEN(FileName) THEN
      PRINT "You picked "; FileName
  ELSE
      PRINT "You pressed Escape."
  END IF