/*
   --------------------------------------------------------
   Filename.....: fileDlg.cc
   ClassName....: fileDlg
   Purpose......: API Get(Open/Save)FileName dialog
                  with some properties exposed.
   Programmer...: Rick Miller -  http://www.treturn.com/dbase
   Date.........: December 21, 2004
   Notes........: See Notes below.
   Written for..: dBASE dB2K 0.1 and newer.
   Rev. History.: See Revisions below.
   Dependencies.: VStruct32Ex.cc
                  or VStruct.cc,
                  or VStruct.prg,
                  and VStruct.h.
   Usage........: set procedure to fileDlg.cc additive
   HelpFile.....: See OPENFILENAME in win32.hlp file.
   Example:.....: See Examples below.
   SampleFile...: fileDlg.wfm.
   --------------------------------------------------------
   Notes:
   --------------------------------------------------------
      1)    file property is type "C" when not multiSelect
               or using the putFile method.
      2)    file property is type "A" when multiSelect
               and using the getFile method.
      3)    fileName property holds a fullPath filename of
               the last file selected in the dialog.
      4)    the filter property is made up of 1 or more
               filter strings concantenated together.
      5)    each filter string uses "|" or chr(124).
               between the display name and filetype.
                  example:
                     "All Files (*.*)|*.*"
      6)    each filter string can have multiple file types
               associated with a single display name.
                  example:
                     "dBASE Custom Files|*.cc;*.cfm;*.crp"
            each filetype is separated with a semicolon.
      7)    when using multiple filter strings for the
               filter property separate each filter string
               with "|" or chr(124).
                  example:
                     filterString1 + "|" + filterString2
      8)    the defExt property is added to a typed in
               filename when the typed in filename with and
               without the extension does not already exist.
      9)    property starting with a tilde "~" is protected.
      10)   method starting with "x_" is protected.
   --------------------------------------------------------
   Example 1:  getFile with 1 filetype selection.
   --------------------------------------------------------
      oDlg  =  new fileDlg()
      oDlg.filter := "Custom Class (*.cc)|*.cc"
      cFile =  oDlg.getFile("cc", "Open Custom Class File")
      oDlg.release()
   --------------------------------------------------------
   Example 2:  getFile with multiple filetype selection.
               set the initial filetype selection to cc.
   --------------------------------------------------------
      oDlg  =  new fileDlg()
      oDlg.filter := "Custom Class (*.cc)|*.cc" +;
                     "|Custom Form (*.cfm)|*.cfm"
      cFile =  oDlg.getFile("cc", "Open Custom File")
      oDlg.release()
   --------------------------------------------------------
   Example 3:  getFile with multiple file selection.
   --------------------------------------------------------
      oDlg  =  new fileDlg()
      oDlg.multiSelect  := true
      cFile =  oDlg.getFile()
      if not empty(cFile)
         ? "Selection from: " + oDlg.directory
         for i = 1 oDlg.file.size
            ? "File " + i + ":" + oDlg.file[i]
         endfor
      endif
      oDlg.release()
   --------------------------------------------------------
   Example 4:  putFile with 1 filetype selection.
   --------------------------------------------------------
      oDlg  =  new fileDlg()
      oDlg.filter := "Custom Class (*.cc)|*.cc"
      cFile =  oDlg.putFile("Save Custom Class File", "cc")
      oDlg.release()
   --------------------------------------------------------
   Example 5:  putFile with multiple filetype selection.
   --------------------------------------------------------
      oDlg  =  new fileDlg()
      oDlg.filter := "Custom Class (*.cc)|*.cc"
      oDlg.filter += "|Custom Form (*.cfm)|*.cfm"
      cFile =  oDlg.putFile("Save Custom File", "cc")
      oDlg.release()
   --------------------------------------------------------
   Properties: see OPENFILENAME in win32.hlp file for more.
   --------------------------------------------------------
      createPrompt      <bool>         true
         prompt to create a new file.
      defExt            <char>         ""
         default extension.
      directory         <char>         ""
         default directory.
      dontAddtoRecent   <bool>         false
         do not add to the most recent file list.
      file              <char/array>   ""
         array with multiSelect, char without multiSelect.
      fileMustExist     <bool>         true
         require existence of file.
      fileName          <char>         ""
         fullPath filename of last file.
      filter            <char>         "All Files (*.*)|*.*"
         what appears in the filetype list.
      forceShowHidden   <bool>         false
         show hidden or system files NT 5.??.
      hideReadOnly      <bool>         true
         hide the readOnly checkbox.
      multiSelect       <bool>         false
         allow multiple file selection.
      noChangeDir       <bool>         true
         no directory change allowed.
      noNetworkButton   <bool>         false
         hide the network button.
      openTitle         <char>         "Open File"
         dialog title with getFile().
      overWritePrompt   <bool>         true
         prompt when replacing an existing file.
      pathMustExist     <bool>         true
         require existence of directory.
      saveTitle         <char>         "Save File"
         dialog title with putFile().
   --------------------------------------------------------
   Methods:
   --------------------------------------------------------
      getFile(<char> fileType, <char> title)
         show the file open dialog.
         returns string.
      inspect()
         display object in the inspector.
      putFile(<char> title, <char> fileType)
         show the file save dialog.
         returns string.
      release()
         destroy object. close procedure files.
      reset()
         reset property values to default settings.
   --------------------------------------------------------
   Revisions:
   --------------------------------------------------------
      February 10, 2005
         1) renamed all external functions.
      December 27, 2004
         1) fixed bug in x_ValidateFiletype method.
   */