                         Directory & File Selection

                                 "As a jewel of gold in a swines snout,
                                  so is a fair woman which is without
                                  discretion"
                                                         Proverbs 11.22

Introduction

          The GOLDDIR unit includes a set of customizable dialogs which
     perform the following duties:

          Displays a file open/close dialog with files, directories,
     drives and file masks listed  la Windows.

          Displays a multi-column list of files (and optionally
     directories/drives) allowing the user to select a file.

          Displays a Directory Selector/Changer dialog to allow the user
     to navigate around drives and directories.


Figure 6.1
The PromptFile dialog

Using PromptFile to Choose a File

     The PromptFile function in GOLDDIR is defined as follows:

     PromptFile(FullFilename:PathStr): StrScreen;

          Displays a file selection dialog allowing the user to enter an
     explicit filename or to navigate around the drives and directories
     and select a file from the list. The only parameter is a string
     that specifies the default mask/filename that will be displayed in
     the Filename field when the dialog is first displayed. If the
     string includes a path, the dialog will fill the directory and
     drive list with the specified path as the current selection.

          The function returns the fully qualified filename of the
     selected file, or a null string if the user escaped/cancelled.

          The demo file DEMDIR1.PAS shows how easily a file dialog can
     be displayed. (See figure 6.1).

Adding Custom Help

          By default, the PromptFile dialog does not include a help
     button. However, a help button will automatically appear (as if by
     magic) when you use the following procedure:

     AssignDirHelpHook(PFHook: PromptHelpHook);

          Assigns a help procedure to a PromptFile or PromptDir dialog.
     The passed procedure must be declared far and have no passed
     parameters.

          The hooked procedure will be called whenever the user selects
     the Help button. To subsequently remove the Help button, call the
     procedure RemoveDirhelpHook before displaying the dialog.

          Run DEMDIR2.PAS (or DEMDIR6.PAS) for a demonstration of the
     custom help facility.

Ensuring a File Exists

          Users can manually enter a filename in the filename field of
     the dialog, rather than selecting from the list of files. You can
     ensure the user only enters the name of an existing file by setting
     the value of DirsVars.ExistOnly to true. If the user tries to enter
     a file which does not exist, an error message is displayed and the
     user is returned to the dialog.

Customizing  the PromptFile Dialog

          By default, the PromptFile dialog is constructed as a file
     open dialog. However, the window title, button text and button
     hotkeys can all be customized to change the flavor of the dialog.
     International developers can easily change all the dialog text and
     messages to a different language.

          The DirVars record variable includes the following variables
     which influence the displayed text:

Changing the Window Title

          The following variable controls the window title, and defaults
     to 'Pick a File':

     DirVars.StrPromptFileTitle: string[60];

Changing the Buttons

          Both the text and the associated hot key of each of the three
     buttons may be changed by modifying the following variables:

     DirVars.OpenButStr: strbutton;
     DirVars.OpenHK: word;
     DirVars.CancelButStr: strbutton;
     DirVars.CancelHK: word;
     DirVars.HelpButStr: strbutton;
     DirVars.HelpHK: word;

     The defaults for these variables are as follows:

           OpenButStr := '  ~O~pen  ';
           CancelButStr := ' ~C~ancel ';
           HelpButStr := '  ~H~elp  ';
           OpenHK := 280;
           CancelHK := 302;
           HelpHK := 291;

          Run the demo DEMDIR3.PAS to see a custom Save As dialog that
     was developed by modifying the buttons and title.

Changing Error Dialogs

          When the user selects a drive which is not available or ready
     (e.g. when the user selects a floppy drive when no disk is in the
     drive), Gold displays an error dialog. The error title and text can
     be customized by modifying the following variables:

     DirVars.NotReadyTitle: string [30];
     DirVars.NotReadyMsgA: string [30];
     DirVars.NotReadyMsgB: string [60];

     The default text for these variables is as follows:

     NotReadyTitle := 'Drive not ready!';
     NotReadyMsgA := 'Cannot read drive ';
     NotReadyMsgB := 'Please insert a disk or select Cancel';

          When a user enters the name of a file which does not exist,
     and DirVars. ExistsOnly is set to true, an error is displayed. The
     error title and text can be customized by modifying the following
     variables:

     DirVars.NoExistTitle: string [30];
     DirVars.NoExistText: string [60];

     The default text for these variables is as follows:

     NoExistTitle := ' INVALID ';
     NoExistText := '||^Not a valid path or file name';

Customizing PromptFile Colors

          If (for some inexplicable reason) you have the urge to change
     the default colors used in the file dialog, read on. If you are not
     familiar with Gold's Tint system, read the section Customizing
     Display Colors in Chapter 3 before proceeding.

          When changing the colors, it helps to realize that the dialog
     is actually an IO form (yes we use our own tools) and many of the
     colors are modified by altering the default IO colors.

          Listed below is an extract from the demo file DEMDIR4.PAS
     which customizes every component of the dialog:

     procedure CustomizeColors;
     {}
     begin
        {first the window border}
        GoldSetColor(IOWinTitle,WhiteonMagenta);
        GoldSetColor(IOWinIcons,GreenonMagenta);
        GoldSetColor(IOWinBorder1,YellowonMagenta);
        GoldSetColor(IOWinBody,YellowonMagenta);
        {now the buttons}
        GoldSetColor(IOButtonNormHot,WhiteOnBlue);
        GoldSetColor(IOButtonNorm,YellowOnBlue);
        GoldSetColor(IOButtonHiHot,WhiteonRed);
        GoldSetColor(IOButtonHi,YellowOnRed);
        {now the list fields}
        GoldSetColor(ListHi1,WhiteOnRed);
        GoldSetColor(ListNorm1,LightcyanOnBlue);
        GoldSetColor(ListScrollBarHi,LightcyanOnBlue);
        {and finally the messages}
        GoldSetColor(IOLabelNorm,CyanOnMagenta);
        GoldSetColor(IOLabelHi,LightcyanOnMagenta);
     end; { CustomizeColors }

Using PromptDir to Choose a Directory

          If you want to get the user to select a directory, use
     PromptDir as follows:

     PromptDir(FullFilename:PathStr;Cmt:StrScreen): StrScreen;

          Displays a directory selection dialog allowing the user to
     navigate around the drives and directories and select a path. The
     first parameter is a string that specifies the default path that
     will be selected when the dialog is first displayed. The second
     parameter is an optional comment which will be inserted at the top
     of the dialog. If the user escapes, a null string is returned,
     otherwise the selected directory (fully-qualified) is returned.

          Like PromptFile, PromptDir supports a custom help button when
     the procedure AssignDirHelpHook is used to assign a custom help
     procedure.

          Run the demos DEMDIR3.PAS and DEMDIR4.PAS to see PromptDir in
     action. (See Figure 6.2)

Customizing  the PromptDir Dialog

          The window title, button text and button hotkeys can all be
     customized to change the flavor of the dialog. International
     developers can easily change all the dialog text and messages to a
     different language.

          The DirVars record variable includes the following variables
     which influence the displayed text:

Changing the Window Title

          The following variable controls the window title and defaults
     to 'Change directory' :

     DirVars.StrPromptDirTitle : string[60];

     Figure 6.2
     The PromptDir dialog


Changing the Buttons

          Both the text and the associated hot key of each of the three
     buttons may be changed by modifying the following variables:

     DirVars.OKButStr: strButton;
     DirVars.OKHK: word;
     DirVars.CancelButStr: strbutton;
     DirVars.CancelHK: word;
     DirVars.HelpButStr: strbutton;
     DirVars.HelpHK: word;

     The defaults for these variables are as follows:

           OKButStr := '   ~O~K   ';
           CancelButStr := ' ~C~ancel ';
           HelpButStr := '  ~H~elp  ';
           OKHK := 280;
           CancelHK := 302;
           HelpHK := 291;

          The error text for error dialogs can be changed in the manner
     described in the section Changing Error Dialogs on page 6-3.

Customizing PromptDir Colors

          The technique for customizing the PromptDir colors is similar
     to PromptFile (discussed earlier). Listed below is an extract of
     the demo program DEMDIR7.PAS which assigns custom colors to the
     dialog.

     procedure CustomizeColors;
     {}
     begin
        {first the window border}
        GoldSetColor(IOWinTitle,WhiteonMagenta);
        GoldSetColor(IOWinIcons,GreenonMagenta);
        GoldSetColor(IOWinBorder1,YellowonMagenta);
        GoldSetColor(IOWinBody,YellowonMagenta);
        {now the buttons}
        GoldSetColor(IOButtonNormHot,WhiteOnBlue);
        GoldSetColor(IOButtonNorm,YellowOnBlue);
        GoldSetColor(IOButtonHiHot,WhiteonRed);
        GoldSetColor(IOButtonHi,YellowOnRed);
        {now the list fields}
        GoldSetColor(ListHi1,WhiteOnRed);
        GoldSetColor(ListNorm1,LightcyanOnBlue);
        GoldSetColor(ListScrollBarHi,LightcyanOnBlue);
        {and finally the messages}
        GoldSetColor(IOLabelNorm,CyanOnMagenta);
        GoldSetColor(IOLabelHi,LightcyanOnMagenta);
     end; { CustomizeColors }

Using FileList to a Choose File

          FileList takes advantage of Gold's list management tools and
     displays a list of files in a multi-column list (see Figure 6.3).

     Run the demo file DEMDIR8.PAS to see FileList in action.

          To display a file list in a stretchable window call FileList
     which is defined as follows:

     FileList(FullFilename:PathStr; Tit:StrScreen): StrScreen;

          Displays a list of files in a list window. The first string
     parameter identifies the filemask. If the string includes a path,
     the path will be the start-up directory when the window is first
     displayed. The second parameter is an optional title.

          The function returns the fully-qualified filename of the
     selected file, or a null string if the user escaped.

     Figure 6.3
     The FileList window


          FileList can display multiple file masks in a single list. All
     you have to do is specify multiple filemasks in the Fullfilename
     parameter. Try passing the string '*.pas *.asm *.inc'. You can
     still specify a full-qualified path on the first mask, e.g.
     'c:\stuff\*.pas *.asm *.inc'. This technique will also work with
     the PromptFile command.

Sorting the File List

          DirVars includes the boolean variable SortByName. If this
     variable is set to TRUE (the default being FALSE), Gold will sort
     the files in name order.

Changing Informational Text

          Information about the highlighted file is displayed in a two
     line panel at the bottom of the window (see figure 7-2). The
     DirVars record variable includes the following variables which
     influence the text displayed in the panel:

     DirVars.ParentStr: string[30];

          The string displayed when the highlight bar is on the '..'
     file. The default string is 'Parent directory'.

     DirVars.SubDirStr: string[30];

          The string which is a prefix to a sub-directory name when a
     sub-directory is highlighted. The default string is 'Sub
     directory'.

     DirVars.RootStr: string[30];

          The string displayed when the highlight bar is on the
     '\ (root)' file. The default string is 'Root directory'.

     DirVars.NoFilesStr: string[30];

          The string displayed when no matching files are encountered in
     the active directory.

     DirVars.RootNameStr: string[12];

          The "filename" of the list entry which, when selected, jumps
     the user to the root of the active drive. The default name is '\
     (root)'.

     DirVars.DriveStr: string[20];

          The string which is a prefix to a drive letter when a drive is
     highlighted. The default string is 'Drive'.

     DirVars.SortingStr: string[30];

          The message string which is displayed at the top-left of the
     list window when Gold is sorting the filename list. The default
     string is 'Sorting files...'.

          Run the demos DEMDIR8.PAS through DEMDIR11.PAS for examples of
     customizing the FileList display.

Customizing the FileList Display Colors

          The display colors used by FileList are controlled by setting
     the defaults in GOLDTINT. The demo file DEMDIR12.PAS illustrate how
     to customize all the display colors used by FileList. Listed below
     is an extract from this demo file:

     procedure CustomizeColors;
     {}
     begin
        {first the window border}
        GoldSetColor(ListTitle,WhiteonMagenta);
        GoldSetColor(ListIcons,LightgrayOnMagenta);
        GoldSetColor(ListBorder1,YellowonMagenta);
        GoldSetColor(ListBorder2,BlackonMagenta);
        GoldSetColor(ListNorm1,BlackonMagenta);
        {now the list fields}
        GoldSetColor(ListNorm1,YellowOnMagenta);  {files}
        GoldSetColor(ListHi1,WhiteOnCyan);
        GoldSetColor(ListNorm2,WhiteOnMagenta);
        {directories and drives}
        GoldSetColor(ListHi2,BlackOnCyan);
        GoldSetColor(ListScrollBarHi,LightgrayOnMagenta);
        {now the file info}
        GoldSetColor(DirListInfo,LightgrayonMagenta);
     end; { CustomizeColors }


Error Handling

          All the directory and file displaying functions discussed in
     this chapter have the potential to fail. For example, there may be
     insufficient memory to display all the files. After calling one of
     the functions, always call the function LastDirError to see if the
     operation was successful.

          One final note. If you want to display a list of files and
     allow the user to select multiple files, create a custom list using
     the RunList command. This technique is explained in Chapter 14 and
     can be viewed in the demo file DEMLS4.PAS.
