Programmer 7500/MAX_PROGRAMMERS.iso/PASCAL/ULDIAL.ZIP/ULDIAL.DOC

Text File | 1990-06-25 | 10.8 KB | 256 lines

     ╔════════════════════════════════════════════════════════════════╗
     ║ Dialog Objects as Enhancements to Turbo Power OOP Professional ║
     ║               New Communications Technology, Inc.              ║
     ║                           Version 1.0                          ║
     ║                       by John Poindexter                       ║
     ║                         CIS 73717,3405                         ║
     ║                          June 25, 1990                         ║
     ║                       ┌───────┐┌────────┐                      ║
     ║                       │ Ok    ││ Cancel │                      ║
     ║                       └───────┘└────────┘                      ║
     ╚════════════════════════════════════════════════════════════════╝

The main object of this unit is DialogBox, an object to display short messages
or instructions, get user input if desired and exit using radio buttons. There
is also a timeout provision so the box can be used for temporary messages that
are to be displayed for a short period of time and then clear. The above logo
is a simulation of what you will get.

Object hierarchy:

  [Root]              [Root]                         [Root]
    DialogBox           [AbstractWindow]               [StringArray]
                          [RawWindow]                    MStringArray
                            [StackWindow]
                              [CommandWindow]
                                [AbstractSelector]
                                  EntryScreen
                                [PickList]
                                  DialogPick

DialogBox although an immediate descendant of Root contains an EntryScreenPtr
field and DialogPickPtr fields and uses MStringArray which adds a data field
and method that keep track of the maximum string length of added strings.

DialogBox has an automatic sizing feature which is the reason for making it an
immediate descendant of Root rather than EntryScreen.

The minimal statements to use DialogBox look like this:

        if not MyDialog.Init(1,30,2,20) then Exit;
        with MyDialog do
        begin
          AddMessageString('This is a test of DialogBox.');
          AddChoiceString('Ok Cancel');
          AddHeader(' My Test ', heTC);
          Process;
          Code := GetLastChoice;
          Done;
        end;

Unit ULDial uses Unit ULRoot which is included in the archive. TESTDIAL.EXE is
an interactive testing program that will give you an opportunity to try out
DialogBox. Unit ULStatus contains a status handler I use for handling errors
and general messages to the user which is based on DialogBox.

Constants.
==========
ucULDial
  Unit code for Unit ULDial.

scOk      = 0
scCancel  = 1
scRetry   = 2
scTimeOut = 99
  Status codes which may be used for exit status of DialogBox.

Variables.
==========
ULRootColorSet
  This is initialized to ULColorSet which is in ULRoot.

Miscellaneous error codes and error messages are in ULRoot.

DialogBox Methods.
==================

Declaration
  constructor Init(NumTextLines, TotalTextChars,
                   NumChoices, TotalChoiceChars: word);
Purpose
  Initialize internal data fields and allocate MStringArrays for storing
  lines of message text and choices.
Description
  NumTextLines is the maximum number of lines of text that you will want
  displayed as a message in the DialogBox.
           TotalTextChars = NumTextLines * AveLengthOfEachLine
  NumChoices is the number of radio buttons that you want. Each radio button
  displays one word from the ChoiceString.
           TotalChoiceChars = NumChoices * (AveLenghtOfEachChoice + 4)
  Since DialogBox uses a descendant of StringArrays for storing the lines of
  message Text to be displayed and the Choices, it is good practice to
  allocate your best estimate of the memory storage requirements through Init.
  However the StringArrays can reallocate if there is enough memory.
  Reallocation will fragment memory.

Declaration
  destructor Done; virtual;
Purpose
  Deallocate all memory associated with DialogBox.
Description
  This includes memory for EntryScreen, DialogPick, Text and Choice Arrays.

Declaration
  procedure Clear;
Purpose
  To set up the DialogBox for a new message and set of Choices.
Description
  This resets the Message and Choice arrays by disposing of them and then
  reallocating at the same size. The EntryScreen is also disposed and all
  DialogBox data fields reinitialized. It is useful in those situations where
  you want to keep a DialogBox initialized and just keep sending new messages
  and choices.  Using this technique limits heap fragmentation.

Declaration
  function GetLastError: word;
Purpose
  To return the last error recorded by DialogBox.
Description
  Returns the error code and resets dlLastError to 0.

Declaration
  procedure Process;
Purpose
  To activate the DialogBox in preparation for obtaining user input.
Description
  Process is a little different from other process methods in OPRO. It calls
  the method CreateBox described below to create the pick list (dlPick^) and
  the EntryScreen (dlEntry^); add the text fields, the string entry field (if
  there is one) and the window field (dlPick^). It then calls dlEntry^.Process
  and waits for an exit selection. Process uses the standard OPRO
  EntryCommands and PickCommands sets. If UseMouse is defined, as it is in
  ULDEFINE.INC, and a mouse is installed, the mouse is enabled. After an exit
  selection has been made Process also erases the DialogBox. If SetTimeOut has
  been used to set a delay time before the box is automatically erased,
  Process first calls Draw.

Declaration
  procedure AddMessageString(Msg: string);
Purpose
  To add message strings which will be displayed as TextFields in the entry
  screen to be created.
Description
  You can add as many message strings as you want, but keep in mind that only
  those that will display on a full screen will be displayed and the lines
  will be truncated to fit in a full screen window with a border. The entry
  screen window is sized automatically as described under CreateBox. The
  maximum number of text lines that can be displayed is
  (ScreenHeight-5-NumberOfStringFieldLines). You do not have to add a message
  string if you just want the radio buttons. If you stay within the memory
  allocation specified in Init, then this is not likely to fail. Otherwise you
  should check GetLastError after adding.

Declaration
  procedure AddChoiceString(Choice: string);
Purpose
  To add exit Choices for the DialogBox.
Description
  Each word in the Choice string is displayed in a radio button box as an exit
  selection. The center row of the radio buttons is a single-choice,
  horizontal pick list. It is an error (epFatal+ecNoChoice) not to add a
  Choice string and the string may not be blank. If you stay within the memory
  allocation requirements specified in Init, this is not likely to fail.
  Otherwise you should check GetLastError after adding.
Example
  AddChoiceString('Sometimes Always Never_On_Sunday');

  This would result in the following radio buttons:
          ┌─────────────────┐┌─────────────────┐┌─────────────────┐
          │ Sometimes       ││ Always          ││ Never_On_Sunday │
          └─────────────────┘└─────────────────┘└─────────────────┘
          Choice: 1                  2                  3

Declaration
  procedure AddStringEntryField(Prompt: string; pRow, pCol: word;
                                Picture: string; fRow, fCol: word;
                                fWidth: byte; HelpIndex: word;
                                EditSt: string);
Purpose
  To add a string entry field to the DialogBox.
Description
  The use of this method is exactly the same as AddStringField in OPRO. The
  positioning of the field is adjusted in CreateBox as necessary to center the
  field just above the radio buttons. pCol and fCol are adjusted to center the
  entry field inside the box; only their difference is significant. pRow and
  fRow are only used to determine whether the prompt and the field are on the
  same line or if not, which comes first. So the difference between pRow and
  fRow is the only thing that is significant.

Declaration
  procedure AddHeader(S: string; Posn: HeaderPosType);
Purpose
  To add a header on the frame of the DialogBox.
Description
  Works just like the similar method in OPRO on the dlEntry^. It can fail
  because of insufficient memory.

Declaration
  function GetLastChoice: word;
Purpose
  Returns the number of the Choice that is selected.
Description
  The exit Choices are numbered beginning with 1 in the sequence that they
  appear in the Choice string in AddChoiceString. This should be called after
  Process to get the exit selection.

Declaration
  function GetEditedString: string;
Purpose
  Returns the edited string if AddStringEntryField has been used.
Description
  If no entry field has been added, it will always return a blank string.

Declaration
  procedure SetTimeOut(Delay: word);
Purpose
  Used to set a time out period (in milliseconds) for DialogBox.
Description
  Sometimes it is useful to display a temporary message that is on the screen
  for a fixed length of time (Delay). If the user presses a key, the timeout
  feature is overridden and the DialogBox reverts to normal key and mouse
  operation. If the DialogBox exits because of timeout, the GetLastChoice will
  return a value of scTimeOut (presently = 99).
Example
          if not MyDialog.Init(1,78,2,20) then Exit;
          with MyDialog do
          begin
            AddMessageString('Test of timeout feature.');
            AddChoiceString('Ok Cancel');
            SetTimeOut(10000);
            Process;
            Code := GetLastChoice;
            Done;
          end;

  If a key is not pressed within 10 seconds, Code = scTimeOut.
  If {Enter} is pressed, MyDialog is erased and Code = 1.
  If any other key is pressed, MyDialog reverts to normal operation.

Declaration
  function CreateBox: boolean; virtual
Purpose
  Initializes entry screen and pick list and adds fields.
Description
  Normally CreateBox is called automatically by Process; however you may call
  it separately if you want to use non-default features. If CreateBox is
  called prior to Process, then it will not be called in Process. CreateBox
  sizes the entry screen window based on the messages, choices and entry field
  that are added. The window is centered on the screen. The radio buttons are
  in the bottom three rows of the window. If an entry field is added, it is
  centered just above the radio buttons. If all goes well, it returns true.
  When CreateBox exits, all objects are initialized and ready for a call to
  Process or Draw.

Comments or suggestions are welcome.