home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / PASCAL / TOTDOC.ZIP / CHAPT8.TXT < prev    next >
Encoding:
Text File  |  1991-02-11  |  16.5 KB  |  396 lines

  1.                                                                       Displaying
  2.                                                                         Messages
  3.                                                                                &
  4.                                                                          Prompts
  5.  
  6.  
  7.  
  8.  
  9.  
  10.          "As Miss America, my goal is to bring peace to the entire world and
  11.          then to get my own apartment."
  12.  
  13.                                                                         Jay Leno
  14.  
  15.  
  16.  
  17.  
  18.  
  19. Introduction
  20.  
  21.          The totMSG unit includes a variety of easy-to-use objects for display-
  22.          ing messages and prompts. A message is simply a pop-up window which is
  23.          displayed until the user presses [KEYCAP], [KEYCAP], or clicks the
  24.          mouse on the close icon/button. Similarly, a prompt is a pop-up window,
  25.          but the user must select one of the options displayed at the bottom of
  26.          the window. A prompt window can have two or three buttons. The buttons
  27.          come in two varieties: strip-buttons like the ones used in the Turbo
  28.          Pascal IDE, and box-buttons like the ones used by PC Tools and the
  29.          Norton Utilities.
  30.  
  31.  
  32.  
  33. The Object Hierarchy
  34.  
  35.          Figure 8.1 illustrates the object hierarchy for the totMSG unit. The
  36.          base (or primitive) object is BaseMessageOBJ, and all the other messag-
  37.          ing objects descend from it. You should never declare an instance of
  38.          type BaseMessageOBJ, as it is an abstract object. Use one of the
  39.          following four descendant objects:
  40.  
  41.          MessageOBJ         This is the basic message displaying object. Between
  42.                             one and twenty lines of text can be displayed in a
  43.                             moveable window. At the bottom of the window is a
  44.                             single strip-button, which defaults to the text
  45.                             "OK".  The user removes the window by clicking the
  46.                             mouse on the button or close icon, or by pressing
  47.                             [KEYCAP] or [KEYCAP].
  48.  
  49.          ButtonMessageOBJ   This object is a descendant of MessageOBJ and
  50.                             operates in the same way. The only difference is
  51.                             that the button is a box-button.
  52.  
  53.          PromptOBJ          The PromptOBJ object is descendant from the BaseMes-
  54.                             sageOBJ, and should be used when you want to prompt
  55.                             the user to choose a specific option. A message is
  56.                             displayed in a moveable window, and two or three
  57.                             strip-buttons are displayed. The user removes the
  58.                             window by clicking on one of the buttons or the
  59.                             close icon, or by pressing [KEYCAP]. The buttons can
  60.  
  61. 8-2                                                                 User's Guide
  62.  
  63. --------------------------------------------------------------------------------
  64.  
  65.                             be selected in one of three ways: clicking on the
  66.                             button, tabbing to a button and pressing [KEYCAP],
  67.                             or pressing a button hotkey.
  68.  
  69.          ButtonPromptOBJ    This objects displays box-buttons, but in all other
  70.                             aspects it operates like PromptOBJ.
  71.  
  72.  
  73.  
  74. Figure 8.1                                                             [PICTURE]
  75. Message
  76. Object Hierarchy
  77.  
  78.          This combination of objects provides you with ways of displaying
  79.          single, double and triple button messages, using strip- or box-buttons.
  80.          The decision to use strip- or box-buttons is solely cosmetic. The
  81.          strip-buttons are more "elegant", but the box-buttons are larger and
  82.          easier to select with the mouse.
  83.  
  84. Common Methods
  85.  
  86.          Since all the objects are derived from the BaseMessageOBJ, they share a
  87.          set of common methods. The following three methods can (and should) be
  88.          used with any of the messaging objects:
  89.  
  90.  
  91.          Init(Style:byte;Tit:string);
  92.  
  93.          The Init method is passed two parameters. The first is the window box
  94.          style, and the second, the window title. Refer to 5-7 for a discussion
  95.          of box styles and titles. As always, this method must be called before
  96.          any other.
  97.  
  98.  
  99.          AddLine(Str:string);
  100.  
  101.          Call this method to add a line of text to the method. For example, if
  102.          you want to display five lines of text, call AddLine five times. Up to
  103.          twenty lines of text can be displayed in a message. The text should be
  104.          no more than seventy characters long. The first line of text is always
  105.          displayed on the first line of the window, i.e. immediately below the
  106.          title. To force a space between the title and the text, call AddLine
  107.          with an empty string, e.g. AddLine('');.  Similarly, the buttons are
  108.          positioned directly below the last line of text. Just call Addline with
  109.          an empty string to force a gap between the text and the buttons. The
  110.          Toolkit automatically computes the size of the message window based on
  111.          the number of lines added, the width of the longest line, and the style
  112.          of button selected.
  113.  
  114.  
  115.          WinForm: WinFormPtr;
  116.  
  117.  
  118.  
  119. Messages & Prompts                                                           8-3
  120.  
  121. --------------------------------------------------------------------------------
  122.  
  123.          This function method returns a pointer to the Toolkit WinFormOBJ object
  124.          which is used to manage user input while the message is being dis-
  125.          played. You can use this function method to directly access the WinFor-
  126.          mOBJ methods with the following syntax: WinForm^.method. Refer to
  127.          chapter 11: Controlling User Input for a full discussion of WinFormOBJ.
  128.  
  129.  
  130.  
  131.            Note: the colors used by the message objects are derived from two
  132.            sources. The display of the window border and the message text is
  133.            controlled by the window settings used by the WinForm object.
  134.            Although this object is not discussed until chapter 11, it is
  135.            worthwhile noting that you can modify the window colors with the
  136.            following method call: WinForm^.Win^.SetColors. For example:
  137.                     MyMsg.WinForm^.Win^.SetColors(23,31,30,28);
  138.            The display color of the message buttons are controlled by the
  139.            default colors set in the global instance IOTOT. The following
  140.            method can be used to change the button colors: IOTOT^.SetColBut-
  141.            ton. For example:
  142.                     IOTOT^.SetColButton(32,46,47,46);
  143.            Refer to chapter 11 for further information.
  144.  
  145.  
  146.  
  147. 8-4                                                                 User's Guide
  148.  
  149. --------------------------------------------------------------------------------
  150.  
  151.          Done;
  152.  
  153.          This method disposes of all the memory used by the object instance, and
  154.          should always be called.
  155.  
  156.  
  157.  
  158.  
  159. Simple Messages
  160.  
  161.          The MessageOBJ and ButtonMessageOBJ objects are used for displaying
  162.          simple messages, i.e. an informational message where you don't want the
  163.          user to make a selection. The user just reads the message and removes
  164.          it.
  165.  
  166.          Both these objects include the following method:
  167.  
  168.  
  169.          Show;
  170.  
  171.          This method instructs the Toolkit to display the message window.
  172.  
  173.  
  174.          Listed below is the (by now familiar) example DEMMS1.PAS, followed by
  175.          figure 8.2 which illustrates the generated display.
  176.  
  177.          program DemoMessageOne;
  178.          {demms1 - simple message}
  179.  
  180.          Uses DOS, CRT,
  181.               totFAST, totMSG;
  182.  
  183.          Var
  184.             MsgWin : MessageOBJ;
  185.  
  186.          begin
  187.             Screen.Clear(white,'░'); {paint the screen}
  188.             with MsgWin do
  189.             begin
  190.                Init(1,' Message ');
  191.                AddLine('');
  192.                AddLine('The message unit provides a');
  193.                AddLine('very easy way of displaying');
  194.                AddLine('pop-up messages in a move-');
  195.                AddLine('able window.');
  196.                AddLine('');
  197.                Show;
  198.                Done;
  199.             end;
  200.          end.
  201.  
  202.  
  203. Figure 8.2                                                              [SCREEN]
  204. A Simple Message
  205.  
  206.  
  207.  
  208. Messages & Prompts                                                           8-5
  209.  
  210. --------------------------------------------------------------------------------
  211.  
  212.          By simply changing the instance declaration to MsgWin: ButtonMessa-
  213.          geOBJ; the message will be displayed using a box-button. The example
  214.          DEMMS2.PAS contains this simple modification, and the output is shown
  215.          in figure 8.3.
  216.  
  217.  
  218.  
  219. Figure 8.3                                                              [SCREEN]
  220. A Simple Message
  221. with a Box-Button
  222.  
  223.  
  224.  
  225.          By default, the button text is "OK", and the button has a hotkey of
  226.          "O", i.e. the user can select the button, and thereby clear the mes-
  227.          sage, by pressing [KEYCAP]. The following method provides a way of
  228.          changing the button text and hotkey:
  229.  
  230.  
  231.          SetOption(Str:string;Hotkey:word);
  232.  
  233.          This method changes the button settings. The first parameter identifies
  234.          the text to be displayed, and the second is the keycode of the hotkey
  235.          used to select the button. A code of 0 (zero) signifies no hotkey.
  236.  
  237.  
  238.  
  239.  
  240.            Note: the totIO1 unit includes a constant MaxButtonWidth which
  241.            sets the maximum button string length. By default, the maximum
  242.            string length is 30. However, it can be modified. This subject is
  243.            fully addressed in chapter 11: Controlling User Input.
  244.  
  245.  
  246.  
  247.  
  248.          Listed below is the example file DEMMS3, which is similar to
  249.          DEMMS1.PAS. The only difference is that the SetOption method was used
  250.          to change the default button settings. Notice that the "~" symbol is
  251.          used to highlight specific letters in the button text. This concept was
  252.          discussed in chapter 5: Writing to the Screen on page 5-3 (WriteHi).
  253.  
  254.  
  255.  
  256.          program DemoMessageThree;
  257.          {demms3 - using SetOption to change button text}
  258.  
  259.          Uses DOS, CRT,
  260.               totFAST, totMSG;
  261.  
  262.          Var
  263.             MsgWin : MessageOBJ;
  264.  
  265.  
  266.  
  267. 8-6                                                                 User's Guide
  268.  
  269. --------------------------------------------------------------------------------
  270.  
  271.          begin
  272.             Screen.Clear(white,'░'); {paint the screen}
  273.             with MsgWin do
  274.             begin
  275.                Init(1,' Message ');
  276.                AddLine('');
  277.                AddLine('The message unit provides a');
  278.                AddLine('very easy way of displaying');
  279.                AddLine('pop-up messages in a move-');
  280.                AddLine('able window.');
  281.                AddLine('');
  282.                SetOption(' A very ~l~ong button ',76);
  283.                Show;
  284.                Done;
  285.             end;
  286.          end.
  287.  
  288.  
  289. Figure 8.4                                                              [SCREEN]
  290. Changing the
  291. Button Text
  292.  
  293.  
  294.  
  295. Multi-Button Prompts
  296.  
  297.          The PromptOBJ and ButtonPromptOBJ objects are used for displaying mes-
  298.          sages with two or three buttons. The user removes a message by select-
  299.          ing one of the buttons.
  300.  
  301.          By default, Prompt objects have two buttons, with the text "OK" and
  302.          "Cancel". The function method Show is used to instruct the Toolkit to
  303.          display the message. This function returns a member of the enumerated
  304.          type tAction to indicate which option the user selected. The enumerated
  305.          type tAction is declared in the totIO1 unit as follows:
  306.  
  307.                   Type
  308.                   tAction = (None,NextField,PrevField,Finished,Escaped,
  309.                              Refresh,Signal,Enter,Help,Stop1,Stop2,
  310.                              Stop3,Stop4,Stop5,Stop6,Stop7,Stop8,Stop9);
  311.  
  312.          The majority of these members are for use in full screen editing
  313.          (discussed in chapter 11), and the only ones that should be used with
  314.          messaging are: Finished, Escaped, or Stop1 through Stop9. By default,
  315.          if the user selects the OK button, the member "Finished" is returned,
  316.          and if the user selects the Cancel button or presses [KEYCAP], the
  317.          member "Escaped" is returned. The syntax of the Show method is as
  318.          follows:
  319.  
  320.  
  321.          Show:tAction;
  322.  
  323.  
  324.  
  325. Messages & Prompts                                                           8-7
  326.  
  327. --------------------------------------------------------------------------------
  328.  
  329.          Displays the message window, and returns a member of the enumerated
  330.          type tAction, to indicate which button the user selected.
  331.  
  332.  
  333.          The on-disk example DEMMS4.PAS illustrates how to display a PromptOBJ
  334.          using the default button settings. The following method, SetOption,
  335.          provides a way of changing the button text and hotkeys:
  336.  
  337.  
  338.          SetOption(ID:byte; Str:StringBut;Hotkey:word;Act:tAction);
  339.  
  340.          The first parameter indicates which button you want to define, and can
  341.          have a value of 1, 2 or 3. The second parameter is the text to be
  342.          displayed in the button. The third button is a key code identifying a
  343.          hotkey which can be used to select the button. Finally, the fourth
  344.          parameter is a member of the enumerated type tAction. This is the mem-
  345.          ber which will be returned by the method Show if this button is
  346.          selected. Only use the members Finished, Escaped, or Stop1 through
  347.          Stop9, and assign a different value to each button!
  348.  
  349.  
  350.          Remember that the objects also have the methods Init, Done and AddLine
  351.          which were discussed previously. Listed below is the demo program
  352.          DEMMS5.PAS which illustrates the use of the SetOption method. Figure
  353.          8.5 illustrates the resultant display.
  354.  
  355.          program DemoMessageFive;
  356.          {demms5 - two strip-buttons with specific text}
  357.  
  358.          Uses DOS, CRT,
  359.               totFAST, totMSG, totIO1;
  360.  
  361.          Var
  362.             MsgWin : PromptOBJ;
  363.             ActionCode: tAction;
  364.  
  365.          begin
  366.             Screen.Clear(white,'░'); {paint the screen}
  367.             with MsgWin do
  368.             begin
  369.                Init(1,' Warning ');
  370.                AddLine('');
  371.                AddLine(' The file already exists on disk, and ');
  372.                AddLine(' the contents will be over-written.');
  373.                AddLine('');
  374.                SetOption(1,' ~P~roceed ',80,Finished);
  375.                SetOption(2,' ~A~bort ',65,Escaped);
  376.                ActionCode := Show;
  377.                Done;
  378.             end;
  379.          end.
  380.  
  381.  
  382.  
  383. 8-8                                                                 User's Guide
  384.  
  385. --------------------------------------------------------------------------------
  386.  
  387. Figure 8.5                                                              [SCREEN]
  388. Using PromptOBJ
  389.  
  390.  
  391.  
  392.          The message could have been generated with box-buttons simply by using
  393.          the object ButtonPromptOBJ instead of PromptOBJ - see the on-disk exam-
  394.          ple DEMMS6.PAS.
  395.  
  396.  
  397.  
  398.          The SetOption method is also the way to add a third button. Just pass a
  399.          button ID of 3 and a third button will be displayed. The listing of
  400.          DEMMS7.PAS followed by figure 8.6 illustrates this technique:
  401.  
  402.          program DemoMessageSeven;
  403.          {demms7 - three buttons}
  404.  
  405.          Uses DOS, CRT,
  406.               totFAST, totMSG, totIO1;
  407.  
  408.          Var
  409.             MsgWin : PromptOBJ;
  410.             ActionCode: tAction;
  411.  
  412.          begin
  413.             Screen.Clear(white,'░'); {paint the screen}
  414.             with MsgWin do
  415.             begin
  416.                Init(1,' Warning ');
  417.                AddLine('');
  418.                AddLine(' The file already exists on disk, and ');
  419.                AddLine(' the contents will be over-written.');
  420.                AddLine('');
  421.                SetOption(1,' ~P~roceed ',80,Finished);
  422.                SetOption(2,' ~A~bort ',65,Escaped);
  423.                SetOption(3,' ~H~elp ',72,Stop1);
  424.                ActionCode := Show;
  425.                Done;
  426.             end;
  427.          end.
  428.  
  429.  
  430.  
  431.  
  432.  
  433. Figure 8.6                                                              [SCREEN]
  434. Using Three
  435. Buttons
  436.  
  437.  
  438.  
  439.          The on-disk example DEMMS8.PAS shows how to use ButtonPromptOBJ to dis-
  440.          play three box-buttons.
  441.