                                Prompt Dialogs

                           "All is not gold that outward sheweth bright"
                                                            Lydgate

Introduction

          In Chapter 4 you learned about the message functions such as
     PromptOK and PromptYesNo. These functions make it easy to display a
     message and prompt the user to select a button. The GOLDREAD unit
     takes the feature one step further and allows the user to input
     data such as strings, integers and even select a radio button. If
     you want to prompt the user to input a single standard field type,
     you don't need to build a custom IO form, just use GOLDREAD's
     prompt functions.

     Figure 9.1 shows the PromptStr function in action.


     Figure 9.1
     The PromptStr
     dialog


A Prompt Function Summary

          List below is a summary of the prompt functions supplied in
     the GOLDREAD unit:

     PromptStr(X,Y,StrFldLen:byte;Lab,Tit:StrScreen; Default:string;
                                              Caps:boolean): string;

          Prompts the user to enter a string. If the field length is too
     long for the dialog, Gold will automatically use a scrollable
     string field. PromptStr will optionally convert all input to
     uppercase.

     PromptNum(X,Y:byte;Lab,Tit:StrScreen;Default,Min,Max:LongInt;
                                             Spin:boolean): longint;

          Prompts the user to input a whole number within the specified
     range. The field optionally displays spinners to allow the user to
     scroll through a range of numbers.

     PromptReal(X,Y:byte;Lab,Tit:StrScreen;Fmat:string;Default,
                                            Min,Max:extended): extended;

          Prompts the user to input a real number within the specified
     range. The field optionally displays spinners to allow the user to
     scroll through a range of numbers.

     PromptFixedReal(X,Y:byte;Lab,Tit:StrScreen;WLen,DP:byte;Default,
                         Min,Max,Delta:extended;Spin:boolean): extended;

          Like FixedReal except the field has a fixed decimal place.

     PromptDate(X,Y:byte;Lab,Tit:StrScreen;Fmat:gDate;Default,
                                Min,Max:Dates;Spin,Drop:boolean): Dates;

          Prompts the user to enter a date within the specified range.
     All the Gold date formats are supported. The field optionally
     displays spinners to allow the user to scroll through a range of
     numbers, as well as an optional drop down calendar.

     PromptRadio(X,Y:byte;Lab,Tit:StrScreen;Fields:string;
                                                 Default:byte): byte;

          Prompts the user to select an item from a list of up to 13
     radio button items. The radio button text for all the items is
     defined in a single string, with each option delimited by the '|'
     character.

     PromptColor(X,Y,Default:byte;Cmt,Tit:StrScreen): byte;

          Prompts the user to select a display attribute, i.e.
     background and foreground colors. This dialog is highly
     customizable. Refer to the section Prompting for Colors for more
     information.

          The user can optionally escape from these dialogs. If you need
     to know whether the user escaped, check the value of the variable
     ReadVars.LastAction, which will be set to Escaped if the user
     selects the Cancel button, or clicks on the close icon.

     Here are a few tips to help you customize the dialog's appearance:

          Window Position - Each function accepts X and Y parameters
               which identify the upper left coordinates of the dialog
               window. If X is specified as zero, the dialog will be
               horizontally centered. Similarly, if Y is specified as
               zero, the dialog will be vertically centered. You guessed
               it, if both X and Y are set to zero, the dialog will be
               automatically positioned in the middle of the display.

          Window Style - You can customize the prompt window style by
               assigning a value in the range 1 to 9 to the variable
               ReadVars.PromptStyle. At program start-up the default
               window style is set to the same style as PromptOK, i.e.
               the style specified in WinVars.PromptStyle.

          Label Position - By default, the optional field label is
               positioned to the left of the field (except for
               PromptRadio). To position the label above the field,
               simply start the label with the '^' character, e.g.
               '^Enter your name'.

          Number Ranges - The number and prompt related prompts require
               that you specify a maximum and minimum acceptable value.
               If you want the user to be able to enter any value (i.e.
               disable the range limits), specify the min and max values
               as zero.

          Controlling Gaps - The gaps or whitespace to the left and
               right of the dialog, i.e. the area between the input
               field and the window border, is controlled by the
               variable ReadVars.OutsideGap. The default value is 2. The
               gap between the buttons is similarly controlled by the
               variable ReadVars.ButtonGap, which also has a default of
               2 characters.


          Run the demo files DEMRD1.PAS through DEMRD7.PAS to see the
     prompt functions in action.

Prompting for Passwords

          In some instances, you may not want the user's input to be
     echoed to the screen. For example, you may be prompting the user to
     enter a password.

          You can force the PromptStr function to echo an asterisk to
     the screen whenever a character is typed by setting the boolean
     variable ReadVars.Password to TRUE.


     The demo program DEMRD9.PAS illustrates this technique.

Prompting for Colors

          The PromptColor function is designed for applications that
     allow the end users to select their own display colors. It displays
     two lists of colors; one for the foreground and one for the
     background. A visual sample of the active selection is displayed.

          You can assign a function to display a custom visual sample by
     calling the function AssignTextSampleHook. By default, the dialog
     only allows two or three lines in which to display the sample. If
     you want more space to display the sample, change the value of the
     variable ReadVars.ColorWinDepth to reflect the total number of
     lines required in the window.

          The sample hook must be declared as a far procedure at the
     root level, and must be passed two byte parameters -- the second
     parameter being a variable. The first parameter identifies the
     active field, and the second parameter is a refresh code which
     informs Gold about which fields need to be redrawn -- either set
     the second parameter to RefreshNone or RefreshAll. These constants
     are declared in the GOLDIO unit.

          From within the hooked procedure you can ascertain the current
     values for the foreground and background by inspecting the
     variables ReadVars.ForegroundByte and ReadVars.BackgroundByte.

          Listed below is an extract of the demo file DEMRD8.PAS which
     customizes the color hook:


          {$F+}
          procedure NewTextHook(CurrentField:byte;var Refresh:byte);
          {}
          var A: byte;
          begin
             with ReadVars do
             begin
                A := Cattr(pred(ForeGroundByte),
                            pred(BackGroundByte));
                Refresh := RefreshOthers;
                case CurrentField of
                   0,1,2,3: ;
                   3: CheckBrightFlags(A);
                   else Refresh := RefreshNone;
                end;
                if Refresh = RefreshOthers then
                begin
                   Box3D(2,10,46+
                         2*Ord(not PromptStyle in [7,8]),18,
                         BlackOnCyan,WhiteOnCyan,8);
                   PartClear(5,11,43+2*Ord(not
                             PromptStyle in [7,8]),17,A,' ');
                   WriteAT(5,11,A,'Help on the Colors dialog');
                   WriteAT(5,13,A,'GOLD includes SampleHook...');
                   WriteAT(5,14,A,'permits the developer ...');
                   WriteAT(5,15,A,'to the PromptColor ....');
                end;
             end;
          end; { NewTextHook }
          {$F-}

          begin
             with ReadVars do
             begin
                ColorWinDepth := 19;
                PromptStyle := 4;
                BlinkingOn := false;
             end;
             UseCustomChars;
             MouseShow(true);
             AssignTextSampleHook(NewTextHook);
             TmpColor := PromptColor(0,4,RedOnCyan,'Pick color',
                                     'GoldRead Color Input');
             .....
          end.

          By default, the PromptColor background color list only
     includes the first 8 colors, i.e. the bright colors are excluded.
     Set the boolean variable ReadVars.Use16BgndColors variable to true
     to instruct Gold to support all 16 colors for the background field.

Adding a Help Routine

          By default, the prompt dialogs do not include a help button.
     However, a help button will automatically appear when you use the
     following procedure:

     AssignReadHelpHook(PFHook: PromptHelpHook);

          Assigns a help procedure to the Prompt dialogs in GOLDREAD.
     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 RemoveReadHelpHook before displaying the dialog.

     Run DEMRD10.PAS for a demonstration of the custom help facility.

Customizing the Dialog Colors

          To customize the display colors of the prompt dialogs, use the
     GoldSetColor function to set one of the following color components:

          PromptBorder1
          PromptBorder2
          PromptTitle
          PromptBody
          PromptButtonHiHot
          PromptButtonHi
          PromptButtonNormHot
          PromptButtonNorm
          PromptButtonDefHot
          PromptButtonDef
          PromptIcons
          PromptBodyHi
          PromptNormalCmt
          PromptHiCmt
          PromptEditErase
          PromptEditNorm
          PromptEditHi

          Listed below is an extract from DEMRD11.PAS which updates all
     the prompt colors:

          procedure CustomizeColors;
          {}
          begin
             GoldSetColor(PromptBorder1,LightRedOnRed);
             GoldSetColor(PromptBorder2,LightRedOnRed);
             GoldSetColor(PromptTitle,WhiteOnRed);
             GoldSetColor(PromptBody,LightGrayOnRed);
             GoldSetColor(PromptButtonHiHot,WhiteOnMagenta);
             GoldSetColor(PromptButtonHi,YellowOnMagenta);
             GoldSetColor(PromptButtonNormHot,YellowOnMagenta);
             GoldSetColor(PromptButtonNorm,LightgrayOnMagenta);
             GoldSetColor(PromptButtonDef,LightgrayOnMagenta);
             GoldSetColor(PromptButtonDefHot,LightcyanOnMagenta);
             GoldSetColor(PromptIcons,LightcyanOnRed);
             GoldSetColor(PromptBodyHi,WhiteOnRed);
             GoldSetColor(PromptNormalCmt,YellowOnRed);
             GoldSetColor(PromptHiCmt,WhiteOnRed);
             GoldSetColor(PromptEditErase,WhiteOnGreen);
             GoldSetColor(PromptEditNorm,LightGrayOnMagenta);
             GoldSetColor(PromptEditHi,WhiteOnMagenta);
          end; { CustomizeColors }

Customizing the Button Text and Error Messages

          International developers (and developers in Louisiana) may
     want to translate the strings used in the prompt dialogs.

          The button text along with the button hotkeys use the common
     buttons declared in GOLDWIN. You can modify the default buttons by
     changing the values of the following WinVars variables (shown with
     their default assignments):

             with WinVars do
             begin
                OKButStr := '   ~O~K   ';
                OKHotKey := 280;          { Alt+O }
                CancelButStr := ' ~C~ancel ';
                CancelHotKey := 302;      { Alt+C }
                HelpButStr := '  ~H~elp  ';
                HelpHotKey := 291;
             end;

          The PromptColor function uses an additional set of strings,
     which are all defined in the ReadVars record. Listed below are the
     string variables in ReadVars along with their default values:

          BrightLabel := 'B~r~ight background';
          FGLabel := '~F~oreground';
          BGLabel := '~B~ackground';
          FGHotKey := 289;          { Alt+F }
          BGHotKey := 304;          { Alt+B }
          BrightLabelHotKey := 275; { Alt+R }
          SampleText := ' Text Text Text ';
          SampleTxtHdr := 'Sample Text';
          LowerSet := 'Black|Blue|Green|Cyan|Red|
                       Magenta|Brown|LightGray';
          UpperSet := 'DarkGray|LightBlue|LightGreen|LightCyan|
                       LightRed|LightMagenta|Yellow|White';

Error Handling

          All the prompt functions discussed in this chapter have the
     potential to fail. The most probable cause of error is a lack of
     memory to construct the window. After calling one of the functions,
     always call the function LastReadError to see whether the operation
     was successful.

