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

  1.                                                                      Controlling
  2.                                                                             User
  3.                                                                            Input
  4.  
  5.  
  6.  
  7.  
  8.  
  9.          "I'm sick of writing documentation."              Bob Ainsbury
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17. Introduction
  18.  
  19.          The Toolkit includes three major units to help you prompt the user for
  20.          input: totIO1, totIO2 and totIO3. These units provide more than 20
  21.          different input objects to accommodate all of your user input needs.
  22.          Objects may be used individually to prompt a user for input, or
  23.          combined together to build a powerful input form or dialog box.
  24.  
  25.          There are objects to prompt for strings, numbers, dates, word-wrapping
  26.          memo fields, radio buttons, check boxes and lists. In the unlikely
  27.          event that there is no object type to support your specific needs, you
  28.          can create your own customized input objects.
  29.  
  30.  
  31.  
  32. Two Quick Examples
  33.  
  34.          The Toolkit form input facilities are powerful and extensive, but you
  35.          don't need to understand every feature and facility to use them! Here
  36.          are a couple of examples to prove the point.
  37.  
  38.          The following example, DEMIO1.PAS, is a simple program which prompts
  39.          the user to enter a real number.
  40.  
  41.          program DemoIOOne;
  42.          {demIO1 - single field input}
  43.  
  44.          Uses DOS, CRT,
  45.               totFAST, totIO1, totIO2;
  46.  
  47.          Var
  48.             Price: FixedRealIOOBJ;
  49.  
  50.          begin
  51.             ClrScr;
  52.             with Price do
  53.             begin
  54.                Init(35,5,8,2);
  55.                SetLabel('How much was the doppleganger? ');
  56.                SetValue(250.0);
  57.                SetMinMax(0.1,12250.0);
  58.                SetRules(EraseDefault);
  59.                Activate;
  60.                Writeln;writeln('You entered ',GetValue);
  61.  
  62. 11-2                                                                User's Guide
  63.  
  64. --------------------------------------------------------------------------------
  65.  
  66.                Done;
  67.             end;
  68.          end.
  69.  
  70.  
  71.          Let's analyze the program. At the top of the program is the declaration
  72.          of a variable called Price, which is of type FixedRealIOOBJ. All form
  73.          input fields have object names ending in "IOOBJ", which stands for
  74.          input-output object. The FixedRealIOOBJ object is for the input of real
  75.          numbers which have a fixed number of decimal places.
  76.  
  77.          In the main part of the program, only the three bold statements are
  78.          mandatory. The Init statement initializes the field. The four parame-
  79.          ters represent the (X,Y) coordinate of the first character in the
  80.          field, the number of whole digits, and the number of decimal places,
  81.          respectively. In this example, the field will be located in column 35,
  82.          row 5, with 8 significant digits, and 2 decimal places. The Activate
  83.          command instructs the Toolkit to display the field and wait for user
  84.          input. The Done method disposes of the object.
  85.  
  86.          The other statements are used to customize the field. Any input field
  87.          can have a label, and usually, the label is displayed to the immediate
  88.          left of the field. The SetLabel method assigns a label to the input
  89.          field. By default, the field will have an initial value of zero. The
  90.          SetValue method is used to assign an initial default value of 250.0. As
  91.          you may have guessed, the SetMinMax method ensures that the user inputs
  92.          a number within a specified range. Figure 11.1 shows the error message
  93.          generated by the user when an invalid number is entered. The SetRules
  94.          method instructs the Toolkit to erase the default value if the user
  95.          first presses a non-editing key, e.g. a number.
  96.  
  97.          The function method GetValue returns the value entered by the user.
  98.  
  99.  
  100.  
  101. Figure 11.1                                                             [SCREEN]
  102. Automatic Input
  103. Validation
  104.  
  105.  
  106.  
  107.          The second example, DEMIO2.PAS, shows how to combine a number of fields
  108.          into a full screen input form:
  109.  
  110.          program DemoIOTwo;
  111.          {demIO2 - full field input}
  112.  
  113.          Uses DOS, CRT,
  114.               totFAST, totIO1, totIO2;
  115.  
  116.  
  117.  
  118. Controlling User Input                                                      11-3
  119.  
  120. --------------------------------------------------------------------------------
  121.  
  122.          Var
  123.             Name: LateralIOOBJ;
  124.             Phone: PictureIOOBJ;
  125.             Price: FixedRealIOOBJ;
  126.             Keys: ControlkeysIOOBJ;
  127.             Manager: FormOBJ;
  128.             Result: tAction;
  129.  
  130.          procedure InitVars;
  131.          {}
  132.          begin
  133.             with Name do
  134.             begin
  135.                Init(35,5,20,40);
  136.                SetLabel('Vendor Name');
  137.             end;
  138.             with Phone do
  139.             begin
  140.                Init(35,7,'(###) ###-####');
  141.                SetLabel('Tel');
  142.             end;
  143.             with Price do
  144.             begin
  145.                Init(35,9,8,2);
  146.                SetLabel('Unit Price');
  147.                SetValue(250.0);
  148.                SetMinMax(0.1,12250.0);
  149.                SetRules(EraseDefault);
  150.             end;
  151.             Keys.Init;
  152.          end; {InitVars}
  153.  
  154.          begin
  155.             ClrScr;
  156.             Screen.TitledBox(15,3,65,11,76,79,78,2,' Quicky Input Demo ');
  157.             Screen.WriteCenter(25,white,'Press TAB to switch fields and
  158.                                          press ESC or F10 to end');
  159.             InitVars;
  160.             with Manager do
  161.             begin
  162.                Init;
  163.                AddItem(Keys);
  164.                AddItem(Name);
  165.                AddItem(Phone);
  166.                AddItem(Price);
  167.                Result := Go;
  168.                if Result = Finished then
  169.                   {update the database..}
  170.                else
  171.  
  172.  
  173.  
  174. 11-4                                                                User's Guide
  175.  
  176. --------------------------------------------------------------------------------
  177.  
  178.                   {call Esc routine};
  179.             end;
  180.          end.
  181.  
  182.  
  183.          In this example, there are three input fields which prompt the user to
  184.          input a name, a telephone number and a unit price. The object Keys, of
  185.          type ControlKeysIOOBJ, is used to control which keys allow the user to
  186.          switch between fields and terminate the input session. By default, the
  187.          following keys are supported [KEYCAP], [KEYCAP], [KEYCAP] and [KEYCAP].
  188.  
  189.          Every full screen input form must be controlled by a form manager of
  190.          type FormOBJ. In the example, the instance Manager is used.
  191.  
  192.          The procedure InitVars is called to initialize all the input fields
  193.          using methods similar to the ones used in the previous example. In the
  194.          body of the main program, the Manager instance is initialized, and each
  195.          of the IO objects is included in the form by calling the method AddI-
  196.          tem. Finally, the function method Go is called to instruct the Toolkit
  197.          to process user input. The method returns a member of the enumerated
  198.          type tAction, which indicates whether the user escaped or ended nor-
  199.          mally - in this case by pressing [KEYCAP].
  200.  
  201.          Figure 11.2 illustrates the output generated by this program. Note that
  202.          the first field can literally scroll, allowing the user to input data
  203.          which is longer than the visible field.
  204.  
  205.  
  206.  
  207. Figure 11.2                                                             [SCREEN]
  208. Full Screen
  209. Input
  210.  
  211.  
  212.  
  213. The Object Hierarchy
  214.  
  215.          The totIO units make extensive use of inheritance and polymorphism, and
  216.          this is reflected in the object hierarchy (see figure 11.3).
  217.  
  218.  
  219.  
  220. Controlling User Input                                                      11-5
  221.  
  222. --------------------------------------------------------------------------------
  223.  
  224. Figure 11.3
  225. totIO
  226. Object Hierarchy
  227.  
  228.  
  229.  
  230. 11-6                                                                User's Guide
  231.  
  232. --------------------------------------------------------------------------------
  233.  
  234.          At first, the object hierarchy may seem daunting, but there really
  235.          isn't much to it. Many of the objects are abstract, and these are
  236.          shaded gray in the figure. Remember that you should not create
  237.          instances of abstract objects -- use a descendant.
  238.  
  239.          All you have to decide is which object fits your input needs, and then
  240.          create an instance. For example, if you want to prompt a user for a
  241.          date, use the DateIOOBJ, or if you want to prompt for a number, choose
  242.          RealIOOBJ, FixedRealIOOBJ, or IntIOOBJ.
  243.  
  244.          It is often difficult to determine which methods are applicable to
  245.          which objects, especially with a deeply structured object hierarchy.
  246.          Part 3: Flash Cards lists, in one place, all the methods available for
  247.          each object in the IO hierarchy.
  248.  
  249.          Listed below is a brief description of each input object:
  250.  
  251.          StringIOOBJ       Basic string input. Provides methods to force the
  252.                            case of text, and to justify text when the user moves
  253.                            to another field.
  254.  
  255.          PictureIOOBJ      String input which supports a special field mask or
  256.                            picture to control input. The following special
  257.                            format characters govern input:
  258.  
  259.                            !          Forces letters to upper case
  260.                            #          Only accepts numbers
  261.                            @          Only accepts letters and punctuation
  262.                            *          Accepts any character
  263.  
  264.                            For example, the field mask '(###) ###-####' is ideal
  265.                            for US telephone numbers.
  266.  
  267.          LateralIOOBJ      String input which supports lateral scrolling. For
  268.                            example, the field width can be set to 20 characters
  269.                            wide, but the user might be allowed to enter up to 40
  270.                            characters.
  271.  
  272.          DateIOOBJ         Input of dates. The Toolkit supports eight different
  273.                            date formats, and this field will automatically
  274.                            verify that the date entered is valid, and, option-
  275.                            ally, within a specified range.
  276.  
  277.          IntIOOBJ          Whole number input. Use this object when you want to
  278.                            obtain a whole number, i.e. shortint, byte, integer,
  279.                            word, longint. Provides methods to ensure input is
  280.                            within a specified range.
  281.  
  282.          RealIOOBJ         Real number input. By using Toolkit compiler direc-
  283.                            tives (discussed on page 3.9), this object can get
  284.                            input of single, double, extended, and comp reals.
  285.                            Provides methods to ensure input is within a speci-
  286.                            fied range.
  287.  
  288.  
  289.  
  290.  
  291. Controlling User Input                                                      11-7
  292.  
  293. --------------------------------------------------------------------------------
  294.  
  295.          FixedRealIOOBJ    Like RealIOOBJ, this object is for the input of real
  296.                            numbers. The object is similar to contemporary data-
  297.                            base packages - there are a fixed number of decimal
  298.                            places, and when the user presses [KEYCAP] the cursor
  299.                            jumps to the right of the decimal place.
  300.  
  301.          HexIOOBJ          Just for the engineers, this accepts the input of
  302.                            hexadecimal numbers!
  303.  
  304.          WWArrayIOOBJ      A multi-line word-wrapping field. A one-dimensional
  305.                            string array is assigned to the field. The contents
  306.                            of the array are updated with the user's input.
  307.  
  308.          WWLinkIOOBJ       Also a multi-line word-wrapping field. A DLLOBJ
  309.                            instance is assigned to the field. The linked list is
  310.                            updated with the user's input.
  311.  
  312.          ArrayIOOBJ        A scrollable list of options from which the user may
  313.                            select one. The displayed list is based on the
  314.                            contents of a one-dimensional string array.
  315.  
  316.          LinkIOOBJ         A scrollable list based on the contents of a DLLOBJ
  317.                            instance.
  318.  
  319.          CheckIOOBJ        A check box field, where the user can check any item
  320.                            in the list.
  321.  
  322.          RadioIOOBJ        A radio button field where the user can select any
  323.                            one item in the list.
  324.  
  325.          StripIOOBJ        A "Turbo 6.0 like" button which the user can select,
  326.                            e.g. buttons for Edit, Save, Cancel, etc.
  327.  
  328.          Strip3dIOOBJ      The same as StripIOOBJ, except that a small 3-D
  329.                            shadow is drawn behind the strip.
  330.  
  331.          ButttonIOOBJ      A "Norton Utilities-like" box button.
  332.  
  333.          HotKeyIOOBJ       HotkeyIOOBJ are invisible fields, used to trap for
  334.                            special keys. For example, the key [KEYCAP] might
  335.                            terminate the input session.
  336.  
  337.          ControlKeysIOOBJ  Defines which keys are used to move between fields,
  338.                            and which keys terminate the input session.
  339.  
  340.  
  341.  
  342.          Figure 11.4 shows a not-so-useful screen which uses every input type!
  343.          The on-disk demo file DEMIO3.PAS created the display.
  344.  
  345.  
  346.  
  347.  
  348.            Note: All the display colors used by the input objects are con-
  349.            trolled by the global instance pointer IOTOT. IOTOT controls all
  350.            the common display characteristics for input fields. This makes it
  351.  
  352. 11-8                                                                User's Guide
  353.  
  354. --------------------------------------------------------------------------------
  355.  
  356.            easy to change the overall look and feel of your program, by just
  357.            changing the IOTOT values. IOTOT will be discussed in detail later
  358.            in the chapter (page 11-40).
  359.  
  360.  
  361. Figure 11.4                                                             [SCREEN]
  362. Every Field
  363. Type
  364.  
  365.  
  366.  
  367. Common Field Methods
  368.  
  369.          All the Toolkit IO objects are derived from the base object ItemIOOBJ.
  370.          This abstract object defines the following fundamental methods which
  371.          are shared by all the objects:
  372.  
  373.  
  374.          SetActiveStatus(Selectable:boolean);
  375.  
  376.          The Toolkit allows you to display fields in a form which are not always
  377.          accessible, i.e. the user cannot land the cursor on the field. Fields
  378.          which are displayed, but cannot be highlighted, are referred to as
  379.          inactive fields. By default, all fields are active, but the method
  380.          SetActiveStatus can be used to control activity status. Pass True to
  381.          activate the field, or False to deactivate it.
  382.  
  383.  
  384.          SetHotkey(HK:word);
  385.  
  386.          Every field can be optionally selected by pressing a Hotkey. You can
  387.          assign a hotkey to any field with the method SetHotKey. The passed
  388.          parameter is the Toolkit key code (refer to the table on page 6-3) that
  389.          represents the key which will activate the field. For example, the
  390.          statement SetHotKey(305) assigns the key [KEYCAP] to the object. When
  391.          the user presses [KEYCAP], the cursor will jump to this field. Be sure
  392.          to assign different hotkeys to each field. To inform the user of the
  393.          hotkey, you can use the SetLabel method with the embedded character '~'
  394.          to highlight the key, e.g. SetLabel('~N~ame');.
  395.  
  396.  
  397.          SetID(ID:word);
  398.  
  399.          By default, every field has an ID of zero. You can assign each field a
  400.          different ID with the SetID method. This ID is used to indicate the
  401.          highlighted field when a user presses a help function, or when a field
  402.          raises a signal to indicate that other fields need to be refreshed. The
  403.          topics of Help and Signals are discussed later.
  404.  
  405.  
  406.          In addition to these basic methods, all visible fields share the fol-
  407.          lowing two methods:
  408.  
  409.  
  410.  
  411. Controlling User Input                                                      11-9
  412.  
  413. --------------------------------------------------------------------------------
  414.  
  415.          SetLabel(Lbl:string);
  416.  
  417.          Every visible field can have a label. The label is usually displayed to
  418.          the immediate left of the input field. When the field is highlighted,
  419.          the label is drawn in a different color to signify that the field is
  420.          active. Use the SetLabel command to specify a string label for any
  421.          field. Note that the use of the embedded control character '~' is sup-
  422.          ported. Refer to the discussion of the Screen.WriteHi method on page
  423.          5-3 for further information.
  424.  
  425.  
  426.          SetMessage(X,Y:byte; Msg:string);
  427.  
  428.          The Toolkit can display an optional message at some location on the
  429.          screen when the field is highlighted. When the user leaves the field,
  430.          the message is erased. (Note: the old screen contents which were cov-
  431.          ered by the message are not restored.) Use the SetMessage method to
  432.          identify the location of the message and the message text.
  433.  
  434.  
  435.          Listed below is the demo program DEMIO4.PAS, which is a variation on
  436.          the program DEMIO2.PAS, discussed earlier. The usability has been
  437.          enhanced by adding informative (!) messages, and the user can jump to
  438.          the various fields by pressing hotkeys. Figure 11.5 shows the resultant
  439.          display.
  440.  
  441.          program DemoIOFour;
  442.          {demIO4 - using hotkeys, labels, and messages}
  443.  
  444.          Uses DOS, CRT,
  445.               totFAST, totIO1, totIO2;
  446.  
  447.          Var
  448.             Name: LateralIOOBJ;
  449.             Phone: PictureIOOBJ;
  450.             Price: FixedRealIOOBJ;
  451.             Keys: ControlkeysIOOBJ;
  452.             Manager: FormOBJ;
  453.             Result: tAction;
  454.  
  455.          procedure InitVars;
  456.          {}
  457.          begin
  458.             with Name do
  459.             begin
  460.                Init(35,5,20,40);
  461.                SetLabel('Vendor ~N~ame');
  462.                SetHotkey(305); {Alt-N}
  463.                SetMessage(22,11,'Enter the vendor''s name, 40 chars Max');
  464.             end;
  465.             with Phone do
  466.             begin
  467.  
  468.  
  469.  
  470. 11-10                                                               User's Guide
  471.  
  472. --------------------------------------------------------------------------------
  473.  
  474.                Init(35,7,'(###) ###-####');
  475.                SetLabel('~T~el');
  476.                SetHotkey(276); {Alt-T}
  477.                SetMessage(22,11,'Enter the vendor''s phone number');
  478.             end;
  479.             with Price do
  480.             begin
  481.                Init(35,9,8,2);
  482.                SetLabel('Unit ~P~rice');
  483.                SetHotKey(281); {Alt-P}
  484.                SetMessage(22,11,'Enter the unit price in dollars');
  485.             end;
  486.             Keys.Init;
  487.          end; {InitVars}
  488.  
  489.          begin
  490.             ClrScr;
  491.             Screen.TitledBox(15,3,65,12,76,79,78,2,' Quicky Input Demo ');
  492.             Screen.WriteCenter(25,white,'Press TAB to switched fields and press
  493.          ESC or F10 to end');
  494.             InitVars;
  495.             with Manager do
  496.             begin
  497.                Init;
  498.                AddItem(Keys);
  499.                AddItem(Name);
  500.                AddItem(Phone);
  501.                AddItem(Price);
  502.                Result := Go;
  503.                if Result = Finished then
  504.                   {update the database..}
  505.                else
  506.                   {call Esc routine};
  507.             end;
  508.          end.
  509.  
  510.  
  511.  
  512.  
  513. Figure 11.5                                                             [SCREEN]
  514. Using Labels &
  515. Messages
  516.  
  517.  
  518.  
  519. Field Types
  520.  
  521.          The Object hierarchy illustrates the interrelated nature of the totIO
  522.          objects. The objects are loosely organized into the following groups:
  523.  
  524.  
  525.  
  526. Controlling User Input                                                     11-11
  527.  
  528. --------------------------------------------------------------------------------
  529.  
  530.                 String       StringIOOBJ        (totIO2)
  531.                              PictureIOOBJ       (totIO2)
  532.                              LateralIOOBJ       (totIO2)
  533.  
  534.                 Number       IntIOOBJ           (totIO2)
  535.                              RealIOOBJ          (totIO2)
  536.                              FixedRealIOOBJ     (totIO2)
  537.                              HexIOOBJ           (totIO2)
  538.  
  539.                 Date         DateIOOBJ          (totIO2)
  540.  
  541.                 Check/Radio  CheckIOOBJ         (totIO1)
  542.                              RadioIOOBJ         (totIO1)
  543.  
  544.                 Lists        ArrayIOOBJ         (totIO2)
  545.                              LinkIOOBJ          (totIO2)
  546.  
  547.                 Wordwrap     WWArrayIOOBJ       (totIO3)
  548.                              WWLinkIOOBJ        (totIO3)
  549.  
  550.                 Buttons      StripIOOBJ         (totIO1)
  551.                              Strip3dIOOBJ       (totIO1)
  552.                              ButtonIOOBJ        (totIO1)
  553.  
  554.                 Hotkeys      HotkeyIOOBJ        (totIO1)
  555.                              ControlKeysIOOBJ   (totIO1)
  556.  
  557.  
  558.  
  559.          The objects which fall into the category of single line objects are the
  560.          String, Number and Date object groups. These objects are similar in
  561.          nature, and share the following common methods:
  562.  
  563.  
  564.          SetIns(InsOn: boolean);
  565.  
  566.          Pass True to set the field initially in insert mode, or False to be in
  567.          overtype mode.
  568.  
  569.  
  570.          SetRules(Rules:byte);
  571.  
  572.          The rules control some of the field's editing properties. The following
  573.          constants are declared in the totIO1 unit:
  574.  
  575.          NoRules         This is the default state, with no editing rules
  576.                          active.
  577.  
  578.          AllowNull       Use this rule to instruct the Toolkit to accept an
  579.                          empty or null number field, even though the SetMinMax
  580.                          method has been used to confine the acceptable input
  581.                          within a range.
  582.  
  583.          SuppressZero    This rule suppresses the display of the default field
  584.                          value in number fields, when the value is zero, i.e.
  585.                          the field is empty, rather than showing "0" or "0.0".
  586.  
  587. 11-12                                                               User's Guide
  588.  
  589. --------------------------------------------------------------------------------
  590.  
  591.          EraseDefault    When active, this rule forces the emptying of the
  592.                          field's default value, when a user highlights the field
  593.                          and presses a non-editing key.
  594.  
  595.          JumpIfFull      This rule forces the user to the next field, as soon as
  596.                          the current field is filled.
  597.  
  598.          To specify multiple rules, simply sum the rules. For example, the
  599.          following statement will enforce three of the rules:
  600.  
  601.                SetRules(AllowNull+EraseDefault+JumpIfFull);
  602.  
  603.  
  604.          SetDispChar(Ch:char);
  605.  
  606.          Normally, the key pressed by the user is displayed in the input field.
  607.          However, for security, you may want to echo a different character to
  608.          the screen. Use this method to suppress the display of the typed char-
  609.          acters. The Toolkit will use the character Ch to identify that a char-
  610.          acter has been pressed. This method is ideal for password fields. Note
  611.          that the field stores the actual typed characters, as this method only
  612.          affects the way the display is updated. Pass a character of ' ' (space)
  613.          to instruct the Toolkit to echo the typed characters.
  614.  
  615.  
  616.          SetPadChar(Pad:char);
  617.  
  618.          This method controls which character is used to pad out the empty part
  619.          of the input field. By default, the character used is defined in the
  620.          IOTOT object (discussed later).
  621.  
  622.  
  623.          With the exception of the FixedRealIOOBJ, the single line input fields
  624.          also share the following two methods:
  625.  
  626.  
  627.          SetJust(Just:tJust);
  628.  
  629.          When the user leaves the current field, the Toolkit can automatically
  630.          justify the field data. This method controls the justification. The
  631.          totSTR unit includes the declaration of an enumerated type tJust, which
  632.          has the following members:  JustLeft, JustCenter and JustRight. (Sounds
  633.          like a good name for a breakfast cereal!) By default, fields are left
  634.          justified.
  635.  
  636.  
  637.          SetCursor(Curs:tCursPos);
  638.  
  639.          Every time the user jumps to a new field, the Toolkit has to decide
  640.          where to position the cursor. This method controls the cursor position-
  641.          ing for each field. The totIO1 unit includes the declaration of an
  642.          enumerated type tJust, which has the following members: CursLeft,
  643.          CursRight and CursPrev. Use CursLeft and CursRight to force the cursor
  644.  
  645.  
  646.  
  647.  
  648. Controlling User Input                                                     11-13
  649.  
  650. --------------------------------------------------------------------------------
  651.  
  652.          to the leftmost or rightmost character position respectively. The Cur-
  653.          sPrev setting (default) instructs the Toolkit to position the cursor
  654.          where it was the last time the field was edited.
  655.  
  656.  
  657.  
  658. String Fields
  659.  
  660.          The three string field objects (StringIOOBJ, PictureIOOBJ and Lateral-
  661.          IOOBJ) are all located in the totIO2 unit. All these objects are
  662.          descended from the abstract object VisibleIOOBJ, and share the
  663.          following methods, which were described earlier:
  664.  
  665.                   SetActiveStatus(Selectable:boolean);
  666.                   SetHotkey(HK:word);
  667.                   SetID(ID:word);
  668.                   SetLabel(Lbl:string);
  669.                   SetMessage(X,Y:byte;Msg:string);
  670.                   Activate;
  671.  
  672.          In addition, the following methods are shared by all three objects:
  673.  
  674.  
  675.          SetCase(Cas:tCase);
  676.  
  677.          The totSTR unit includes the declaration of an enumerated type tCase
  678.          which has the following members: Lower, Upper, Proper and Leave. This
  679.          method can be used to control whether the Toolkit automatically adjusts
  680.          the case field string when the user leaves the field. Set the case to
  681.          Leave if you want the string to remain the same case as when it was
  682.          entered.
  683.  
  684.  
  685.          SetForceCase(On:boolean);
  686.  
  687.          The SetForceCase method is used to control whether the case of the
  688.          string input is adjusted while the user is typing in the string. Pass a
  689.          True parameter to force the case adjustment (as specified with the
  690.          method SetCase) every time a character is pressed. Pass a False parame-
  691.          ter if you want the string to be adjusted only when the user moves to
  692.          another field.
  693.  
  694.  
  695.          SetValue(Str:string);
  696.  
  697.          This method assigns a default value to the field. This value will be
  698.          displayed when the field is first displayed.
  699.  
  700.  
  701.          GetValue: string;
  702.  
  703.          This method should be called (after the user has completed the input
  704.          session) to determine which string was entered.
  705.  
  706.  
  707.  
  708.  
  709. 11-14                                                               User's Guide
  710.  
  711. --------------------------------------------------------------------------------
  712.  
  713.          Done;
  714.  
  715.          This method disposes of the memory consumed by the object, and should
  716.          be called after all user input is completed.
  717.  
  718.  
  719.  
  720. StringIOOBJ
  721.  
  722.          The StringIOOBJ is used to obtain string input from the user. The user
  723.          may enter any alphanumeric character, including upper ASCII and inter-
  724.          national characters. The only method specific to StringIOOBJ is the
  725.          important Init method. The syntax of Init is as follows:
  726.  
  727.  
  728.          Init(X,Y,FieldLen:byte);
  729.  
  730.          This method must be called first. The first two parameters indicate the
  731.          (X,Y) coordinate of the first character in the field. The third parame-
  732.          ter specifies the field length.
  733.  
  734.  
  735.  
  736. LateralIOOBJ
  737.  
  738.          The LateralIOOBJ object is very similar to StringIOOBJ, except that the
  739.          field can scroll horizontally, allowing the user to input more charac-
  740.          ters than are visible in the field. LateralIOOBJ has its own Init
  741.          method as follows:
  742.  
  743.  
  744.          Init(X,Y,Fieldlen,MaxLen:byte);
  745.  
  746.          This method must be called first. The first two parameters indicate the
  747.          (X,Y) coordinate of the first character in the field, the third parame-
  748.          ter specifies the visible field length, and the fourth parameter speci-
  749.          fies the maximum length of the input string, i.e. the scrollable field
  750.          length.
  751.  
  752.  
  753.  
  754. PictureIOOBJ
  755.  
  756.          The PictureIOOBJ object gives you character by character control of the
  757.          input data, and allows you to embed non-editable characters into the
  758.          field.
  759.  
  760.          When you initialize the object using the Init method (discussed later),
  761.          you must specify a string which represents the field picture. The pic-
  762.          ture is comprised of non-editable characters and the following four,
  763.          pre-defined, format characters:
  764.  
  765.             #     Allows the input of the characters (0-9 . -) and indicates
  766.                   that only numbers may be input.
  767.  
  768.  
  769.  
  770. Controlling User Input                                                     11-15
  771.  
  772. --------------------------------------------------------------------------------
  773.  
  774.             @     Allows only letters of the English alphabet and punctuation
  775.                   characters.
  776.  
  777.             *     Allows any character the user can find.
  778.  
  779.             !     Converts all alphabetical characters to upper case.
  780.  
  781.          Any other characters embedded in the picture are treated as fixed and
  782.          for display only.
  783.  
  784.          For example, the picture '(###) ###-####' would be used for the input
  785.          of US telephone numbers, and the picture '@@@####' might be used for a
  786.          seven character part number which comprises three letters and four dig-
  787.          its.
  788.  
  789.          The field picture is specified in the Init method as follows:
  790.  
  791.  
  792.          Init(X,Y:byte; Picture:string);
  793.  
  794.          This method must be called first. The first two parameters indicate the
  795.          (X,Y) coordinate of the first character in the field, and the third
  796.          parameter specifies the field picture.
  797.  
  798.  
  799.          Two other methods are provided to give even more control over which
  800.          characters can be input. You can either specify the characters which
  801.          are allowable, or the characters which are not allowable. The following
  802.          two methods serve this purpose:
  803.  
  804.  
  805.          SetDisAllowChar(Str:string);
  806.  
  807.          When this method is used, the Toolkit will not allow the user to input
  808.          any of the characters specified in the Str. For example, SetDisAllow-
  809.          Char('\:'); will not allow the user to input a backslash or colon,
  810.          regardless of the field picture.
  811.  
  812.  
  813.          SetAllowChar(Str:string);
  814.  
  815.          This method is the opposite of the previous one, and it is used to
  816.          identify all the characters which the Toolkit will allow the user to
  817.          enter. For example, SetAllowChar('AaBbCc0123456789'); will only allow
  818.          the user to input numbers, or the characters A, B and C.
  819.  
  820.  
  821.          Only use one or the other of these methods. If you only want to stop
  822.          the user from entering a few specific characters, use SetDisAllowChar.
  823.          On the other hand, if you only want to allow a few characters to be
  824.          input, use the SetAllowChar method.
  825.  
  826.  
  827.  
  828. 11-16                                                               User's Guide
  829.  
  830. --------------------------------------------------------------------------------
  831.  
  832.          The function method GetValue will return the condensed string excluding
  833.          the format characters. For example, a telephone number would be
  834.          returned as 10 digits with no brackets or spaces. The following method
  835.          will return the fully formatted string, including all embedded format
  836.          characters:
  837.  
  838.  
  839.          GetPicValue:string;
  840.  
  841.          Returns the string entered by the user, including all formatting char-
  842.          acters.
  843.  
  844.  
  845.  
  846.  
  847.            Note: the totStr unit includes the function PicFormat which
  848.            returns a formatted string. Refer to chapter 14: String Handling
  849.            for further information.
  850.  
  851.  
  852.  
  853.  
  854. String Field Examples
  855.  
  856.          Listed below is an extract of the demo program DEMIO5, which focuses on
  857.          string fields. Figure 11.6 shows an example of the display generated by
  858.          the full program.
  859.  
  860.          procedure InitVars;
  861.          {}
  862.          begin
  863.             with Field1 do
  864.             begin
  865.                Init(40,3,10);
  866.                SetLabel('Field 1  (StringIOOBJ)');
  867.             end;
  868.             with Field2 do
  869.             begin
  870.                Init(40,5,10);
  871.                SetLabel('Field 2  (StringIOOBJ)');
  872.                SetCase(upper);
  873.                SetValue('hello');
  874.                SetRules(EraseDefault+JumpIfFull);
  875.             end;
  876.             with Field3 do
  877.             begin
  878.                Init(40,7,15,30);
  879.                SetLabel('Field 3 (LateralIOOBJ)');
  880.             end;
  881.             with Field4 do
  882.             begin
  883.                Init(40,9,15,30);
  884.  
  885.  
  886. Controlling User Input                                                     11-17
  887.  
  888. --------------------------------------------------------------------------------
  889.  
  890.                SetLabel('Field 4 (LateralIOOBJ)');
  891.                SetCase(Upper);
  892.                SetForcecase(True);
  893.                SetCursor(CursLeft);
  894.             end;
  895.             with Field5 do
  896.             begin
  897.                Init(40,11,'(###) ###-####');
  898.                SetLabel('Field 5 (PictureIOOBJ)');
  899.             end;
  900.             with Field6 do
  901.             begin
  902.                Init(40,13,'!!!***@@@###');
  903.                SetLabel('Field 6 (PictureIOOBJ)');
  904.                SetDisAllowChar('aAbBcC123@!');
  905.                SetRules(EraseDefault);
  906.             end;
  907.             with Field7 do
  908.             begin
  909.                Init(40,15,10);
  910.                SetLabel('Field 7  (StringIOOBJ)');
  911.                SetDispChar('#');
  912.             end;
  913.          end; {InitVars}
  914.  
  915.  
  916. Figure 11.6                                                             [SCREEN]
  917. Using String
  918. Fields
  919.  
  920.  
  921.  
  922.          Don't forget that IO objects can be used individually, to prompt the
  923.          user with a single field. Listed below is the demo program DEMIO6.PAS,
  924.          which prompts the user to enter a string.
  925.  
  926.          program DemoIOSix;
  927.          {demIO6 - single string field input}
  928.  
  929.          Uses DOS, CRT,
  930.               totFAST, totIO1, totIO2, totSTR;
  931.  
  932.          var
  933.            Field: StringIOOBJ;
  934.  
  935.          begin
  936.             with Field do
  937.             begin
  938.                Init(40,5,10);
  939.                SetLabel('Field (StringIOOBJ)');
  940.                SetCase(upper);
  941.                SetValue('hello');
  942.  
  943.  
  944. 11-18                                                               User's Guide
  945.  
  946. --------------------------------------------------------------------------------
  947.  
  948.                SetRules(EraseDefault+JumpIfFull);
  949.                clrscr;
  950.                Activate;
  951.                writeln;writeln('You entered ',GetValue);
  952.                Done;
  953.             end;
  954.          end.
  955.  
  956.  
  957.  
  958.  
  959. Number Fields
  960.  
  961.          The totIO2 unit includes the following four objects for creating number
  962.          fields: IntIOOBJ, RealIOOBJ, FixedRealIOOBJ and HEXIOOBJ. All these
  963.          objects are descended from the abstract object CharIOOBJ, and share the
  964.          following methods which were described earlier:
  965.  
  966.                   SetActiveStatus(Selectable:boolean);
  967.                   SetHotkey(HK:word);
  968.                   SetID(ID:word);
  969.                   SetLabel(Lbl:string);
  970.                   SetMessage(X,Y:byte;Msg:string);
  971.                   SetIns(InsOn:boolean);
  972.                   SetRules(Rules:byte);
  973.                   SetDispChar(Ch:char);
  974.                   SetPadChar(Pad:char);
  975.                   Activate;
  976.                   Done;
  977.  
  978.  
  979.          Except for FixedRealIOOBJ, the number fields also support the following
  980.          two methods:
  981.  
  982.                   SetJust(Just:tJust);
  983.                   SetCursor(Curs:tCursPos);
  984.  
  985.  
  986.  
  987. IntIOOBJ
  988.  
  989.          The IntIOOBJ object should be used to prompt for whole numbers, i.e.
  990.          with a type of byte, word, shortint, integer and longint. The following
  991.          additional methods are supported by IntIOOBJ objects:
  992.  
  993.  
  994.          Init(X,Y,Len:byte);
  995.  
  996.          This method must be called first. The first two parameters indicate the
  997.          (X,Y) coordinate of the first character in the field. The third parame-
  998.          ter specifies the field length.
  999.  
  1000.  
  1001.          SetMinMax(Min,Max:longint);
  1002.  
  1003.  
  1004.  
  1005. Controlling User Input                                                     11-19
  1006.  
  1007. --------------------------------------------------------------------------------
  1008.  
  1009.          The Toolkit can automatically ensure that the user input falls within a
  1010.          specified range. Use the method SetMinMax to set an input range. Pass
  1011.          two zeros to turn off input validation. If the user tries to input an
  1012.          invalid value, the Toolkit displays a pop-up message explaining the
  1013.          problem (see figure 11.1), and forces the user to input a valid number.
  1014.  
  1015.  
  1016.          SetValue(Val:longint);
  1017.  
  1018.          Use this method to set an initial or default value in the field.
  1019.  
  1020.  
  1021.          GetValue: longint;
  1022.  
  1023.          This function method returns the value input by the user.
  1024.  
  1025.  
  1026.  
  1027. RealIOOBJ
  1028.  
  1029.          This object is very similar to IntIOOBJ, except that it is designed for
  1030.          the input of real numbers, i.e. numbers with one or more decimal
  1031.          places.
  1032.  
  1033.  
  1034.            Note: The Toolkit supports all the real types, i.e. real, single,
  1035.            double, extended and comp. By default, all these types are mapped
  1036.            to the base type REAL. In other words, if you declare a variable
  1037.            of type EXTENDED, the Toolkit re-maps it so that Turbo Pascal
  1038.            treats it like a basic REAL. If you do want to support all the
  1039.            additional precision reals, edit the file TOTFLAGS.INC and adjust
  1040.            the conditional defines FLOAT and FLOATEM.  Refer to page 3-9 for
  1041.            further information.
  1042.  
  1043.  
  1044.          In addition to the common methods, the following methods are supported
  1045.          by RealIOOBJ objects:
  1046.  
  1047.  
  1048.          Init(X,Y,Len:byte);
  1049.  
  1050.          This method must be called first. The first two parameters indicate the
  1051.          (X,Y) coordinate of the first character in the field. The third parame-
  1052.          ter specifies the field length.
  1053.  
  1054.  
  1055.          SetMinMax(Min,Max:extended);
  1056.  
  1057.          The Toolkit can automatically ensure that the user input falls within a
  1058.          specified range. Use the method SetMinMax to set an input range. Pass
  1059.          two zeros to suppress input validation. If the user tries to input an
  1060.          invalid value, the Toolkit displays a pop-up message explaining the
  1061.          problem (see figure 11.1), and forces the user to input a valid number.
  1062.  
  1063.  
  1064.  
  1065.  
  1066. 11-20                                                               User's Guide
  1067.  
  1068. --------------------------------------------------------------------------------
  1069.  
  1070.          SetValue(Val:extended);
  1071.  
  1072.          Use this method to set an initial or default value in the field.
  1073.  
  1074.  
  1075.          SetENotation(On:boolean);
  1076.  
  1077.          This method controls whether the user is allowed to enter the number in
  1078.          E-notation, e.g. 4.435623E+12. Pass True to allow the user to input
  1079.          E-notation, or False to disallow it.
  1080.  
  1081.  
  1082.          GetValue: extended;
  1083.  
  1084.          This function method returns the value input by the user.
  1085.  
  1086.  
  1087.  
  1088. FixedRealIOOBJ
  1089.  
  1090.          You may have used some commercial database or financial software pro-
  1091.          grams which provide special cursor control when the user is inputting
  1092.          real numbers. For example, when the user presses [KEYCAP], the cursor
  1093.          automatically jumps to the right of the fixed decimal place. The Fixe-
  1094.          dRealIOOBJ object brings this capability to the Toolkit. (The cursor
  1095.          and key reactions emulate the FoxPro database package - we liked it, so
  1096.          we copied it!)
  1097.  
  1098.          FixedRealIOOBJ objects provide the following additional methods:
  1099.  
  1100.  
  1101.          Init(X,Y,Whole,DP:byte);
  1102.  
  1103.          This method must be called first. The first two parameters indicate the
  1104.          (X,Y) coordinate of the first character in the field. The third parame-
  1105.          ter specifies the maximum number of whole numbers, and the last parame-
  1106.          ter specifies the maximum number of decimal places.
  1107.  
  1108.  
  1109.          SetMinMax(Min,Max:extended);
  1110.  
  1111.          The Toolkit can automatically ensure that the user input falls within a
  1112.          specified range. Use the method SetMinMax to set an input range. Pass
  1113.          two zeros to suppress input validation. If the user tries to input an
  1114.          invalid value, the Toolkit displays a pop-up message explaining the
  1115.          problem (see figure 11.1), and forces the user to input a valid number.
  1116.  
  1117.  
  1118.          SetValue(Val:extended);
  1119.  
  1120.          Use this method to set an initial or default value in the field.
  1121.  
  1122.  
  1123.          GetValue: extended;
  1124.  
  1125.          This function method returns the value input by the user.
  1126.  
  1127. Controlling User Input                                                     11-21
  1128.  
  1129. --------------------------------------------------------------------------------
  1130.  
  1131. HEXIOOBJ
  1132.  
  1133.          If you want a user to enter HEX numbers, HEXIOOBJ is the object for
  1134.          you. HEXIOOBJ is very similar to IntIOOBJ, with the main difference
  1135.          that HEX allows the user to input numbers and the letters A, B, C, D, E
  1136.          and F.
  1137.  
  1138.          As well as the common number methods, HEXIOOBJ supports the following
  1139.          methods:
  1140.  
  1141.  
  1142.          Init(X,Y,Len:byte);
  1143.  
  1144.          This method must be called first. The first two parameters indicate the
  1145.          (X,Y) coordinate of the first character in the field. The third parame-
  1146.          ter specifies the field length.
  1147.  
  1148.  
  1149.          SetMinMax(Min,Max:longint);
  1150.  
  1151.          The Toolkit can automatically ensure that the user input falls within a
  1152.          specified range. Use the method SetMinMax to set an input range. Pass
  1153.          two zeros to turn off input validation.
  1154.  
  1155.  
  1156.          SetValue(Val:longint);
  1157.  
  1158.          Use this method to set an initial or default value in the field.
  1159.  
  1160.  
  1161.          GetValue: longint;
  1162.  
  1163.          This function method returns the value input by the user.
  1164.  
  1165.  
  1166.  
  1167.  
  1168.            Note: in Turbo Pascal HEX numbers are preceded by a '$' character.
  1169.            For example, the following method calls have the same effect:
  1170.                               SetValue($FF);
  1171.                               SetValue(255);
  1172.  
  1173.  
  1174.  
  1175.  
  1176. Formatting Number Fields
  1177.  
  1178.          The objects IntIOOBJ, RealIOOBJ and FixedREALIOOBJ all provide optional
  1179.          formatting capabilities, which can be used to control the format of the
  1180.          displayed number when the user leaves the field, i.e. when the user is
  1181.          editing, the number is unformatted, but when the user exits the field,
  1182.          the number can be formatted in a variety of styles. For example, the
  1183.          number -123456.78 might be formatted as $123,456.78 CR.
  1184.  
  1185.          If you want formatted number fields, you must call the following
  1186.          method:
  1187.  
  1188. 11-22                                                               User's Guide
  1189.  
  1190. --------------------------------------------------------------------------------
  1191.  
  1192.          InitFormat;
  1193.  
  1194.          This method instructs the object to format the field when the user
  1195.          leaves the field.
  1196.  
  1197.  
  1198.          The totSTR unit includes the object FmtNumberOBJ, which is designed to
  1199.          format numbers. The FmtNumber object includes the following methods:
  1200.  
  1201.                   SetPrefixSuffix(P,S:char);
  1202.                   SetSign(S:tSign);
  1203.                   SetSeparators(P,T,D:char);
  1204.                   SetJustification(J:tJust);
  1205.  
  1206.  
  1207.          These methods are described in detail in chapter 14: String Handling.
  1208.          Refer to this chapter for further information.
  1209.  
  1210.          Behind the scenes, when the number method InitFormat is called, the
  1211.          Toolkit creates a private FmtNumberOBJ instance. The number method For-
  1212.          matPtr can be used to access the FmtNumberOBJ instance using the fol-
  1213.          lowing syntax:
  1214.  
  1215.                   FormatPtr^.[method]
  1216.  
  1217.          For example, the following code fragment formats an integer field with
  1218.          a '$' prefix and embedded commas.
  1219.  
  1220.                   var
  1221.                     Field: IntIOOBJ;
  1222.  
  1223.                   begin
  1224.                      with Field do
  1225.                      begin
  1226.                         Init;
  1227.                         InitFormat;
  1228.                         FormatPtr^.SetPrefixSuffix('$',#0);
  1229.                         FormatPtr^.SetSeparators(' ',',','.');
  1230.                         {...}
  1231.                      end;
  1232.                   end.
  1233.  
  1234.  
  1235.  
  1236.  
  1237. Setting the Default Format
  1238.  
  1239.          The totIO2 unit includes FmtNumberTOT, a pointer to an object instance
  1240.          of type FmtNumberOBJ. This instance defines the default formatting that
  1241.          will be applied to real and integer fields during full-screen input.
  1242.          Whenever a number field object's method InitFormat is called, the
  1243.          field's initial formats are copied from FmtNumberTOT.
  1244.  
  1245.  
  1246.  
  1247. Controlling User Input                                                     11-23
  1248.  
  1249. --------------------------------------------------------------------------------
  1250.  
  1251.          You can control each field's default value by setting FmtNumberTOT to
  1252.          specifically meet your needs, before you call the InitFormat method.
  1253.          For example, if you want all your number fields to be formatted with a
  1254.          suffix of FR, set the default with the following statement:
  1255.  
  1256.                   FmtNumberTOT.SetPrefixSuffix('','FR');
  1257.  
  1258.          All number objects initialized after this statement will assume the FR
  1259.          suffix.
  1260.  
  1261.  
  1262.  
  1263. Number Field Examples
  1264.  
  1265.          Back on the first page of this chapter you saw an example of how to
  1266.          prompt the user for a real number using FixedRealIOOBJ. Take another
  1267.          look at page 11.1 and see if the statements make more sense now!
  1268.  
  1269.          Listed below is an extract of the demo program DEMIO8.PAS which illus-
  1270.          trates how to use many of the methods discussed in this section. Figure
  1271.          11.7 shows an example of the display generated by the full program.
  1272.  
  1273.          procedure InitVars;
  1274.          {}
  1275.          begin
  1276.             with Field1 do
  1277.             begin
  1278.                Init(40,3,5);
  1279.                SetLabel('Field 1  (IntIOOBJ)');
  1280.             end;
  1281.             with Field2 do
  1282.             begin
  1283.                Init(40,5,5);
  1284.                InitFormat;
  1285.                SetLabel('Field 2  (IntIOOBJ)');
  1286.                SetValue(69);
  1287.                SetRules(EraseDefault+JumpIfFull);
  1288.             end;
  1289.             with Field3 do
  1290.             begin
  1291.                Init(40,7,10);
  1292.                SetLabel('Field 3 (RealIOOBJ)');
  1293.             end;
  1294.             with Field4 do
  1295.             begin
  1296.                Init(40,9,15);
  1297.                InitFormat;
  1298.                FormatPtr^.SetSeparators('*',',','.');
  1299.                FormatPtr^.SetPrefixSuffix('','FR');
  1300.                FormatPtr^.SetJustification(JustRight);
  1301.                SetLabel('Field 4 (RealIOOBJ)');
  1302.  
  1303.  
  1304. 11-24                                                               User's Guide
  1305.  
  1306. --------------------------------------------------------------------------------
  1307.  
  1308.                SetCursor(CursLeft);
  1309.             end;
  1310.             with Field5 do
  1311.             begin
  1312.                Init(40,11,8,2);
  1313.                SetLabel('Field 5 (FixedRealIOOBJ)');
  1314.             end;
  1315.             with Field6 do
  1316.             begin
  1317.                Init(40,13,5);
  1318.                SetLabel('Field 6  (HEXIOOBJ)');
  1319.             end;
  1320.             Keys.Init;
  1321.          end; {InitVars}
  1322.  
  1323.  
  1324.  
  1325. Figure 11.7                                                             [SCREEN]
  1326. Using Number
  1327. Fields
  1328.  
  1329.  
  1330.  
  1331. Date Fields
  1332.  
  1333.          The DateIOOBJ object is used to prompt the user to input a date. The
  1334.          Toolkit supports eight different date formats. The totDATE unit
  1335.          includes an enumerated type tDate which has the following members:
  1336.          MMDDYY, MMDDYYY, MMYY, MMYYYY, DDMMYY, DDMMYYYY, YYMMDD, YYYYMMDD.
  1337.          Whenever you work with dates, you must identify the desired date for-
  1338.          mat.
  1339.  
  1340.          Refer to chapter 13: Managing Dates for a full description of all the
  1341.          date manipulation routines which complement DateIOOBJ. There are a
  1342.          wealth of functions to convert dates to and from Julian, Gregorian and
  1343.          string formats. For example, the JultoStr and StrtoJul functions con-
  1344.          vert between Julian and string formats.
  1345.  
  1346.          DateIOOBJ is a descendant of CharIOOBJ, and inherits the following,
  1347.          previously described, methods:
  1348.  
  1349.                   SetActiveStatus(Selectable:boolean);
  1350.                   SetHotkey(HK:word);
  1351.                   SetID(ID:word);
  1352.                   SetLabel(Lbl:string);
  1353.                   SetMessage(X,Y:byte;Msg:string);
  1354.                   SetIns(InsOn:boolean);
  1355.                   SetRules(Rules:byte);
  1356.                   SetDispChar(Ch:char);
  1357.                   SetPadChar(Pad:char);
  1358.                   Activate;
  1359.                   Done;
  1360.  
  1361.  
  1362. Controlling User Input                                                     11-25
  1363.  
  1364. --------------------------------------------------------------------------------
  1365.  
  1366.          The DateIOOBJ object manipulates dates in Julian format, where dates
  1367.          are specified as longints. DateIOOBJ includes the following methods:
  1368.  
  1369.  
  1370.          Init(X,Y:byte; DateFmt:tDate);
  1371.  
  1372.          This method must be called first. The first two parameters indicate the
  1373.          (X,Y) coordinate of the first character in the field. The third parame-
  1374.          ter is a member of the enumerated type tDate, and indicates which for-
  1375.          mat of date is to be input, e.g. MMDDYY or DDMMYY.
  1376.  
  1377.  
  1378.          SetMinMax(Min,Max:longint);
  1379.  
  1380.          The Toolkit will automatically verify if proper dates are entered, i.e.
  1381.          that the month is between 1 and 12, and the days are valid for the
  1382.          specified month. The method SetMinMax can also be used to specify a
  1383.          date range. Pass two zeros to turn off input validation. If the user
  1384.          tries to input an invalid date or an out of range date, the Toolkit
  1385.          displays a pop-up message explaining the problem (see figure 11.8), and
  1386.          forces the user to input a valid number.
  1387.  
  1388.  
  1389.          SetValue(Date: longint);
  1390.  
  1391.          Use this method to set an initial or default value in the field. The
  1392.          date is passed as a Julian (longint) value.
  1393.  
  1394.  
  1395.          GetValue:longint;
  1396.  
  1397.          This function method returns the Julian date value input by the user.
  1398.  
  1399.  
  1400.  
  1401.          Listed below is the demo program DEMIO9.PAS which prompts the user for
  1402.          the input of a single date. Figure 11.8 is an example of the date
  1403.          validation performed by the Toolkit.
  1404.  
  1405.          program DemoIONine;
  1406.          {demIO9 - single date field input}
  1407.  
  1408.          Uses DOS, CRT,
  1409.               totIO1, totIO2, totDate;
  1410.  
  1411.          Var
  1412.             Birthday: DateIOOBJ;
  1413.  
  1414.          begin
  1415.             ClrScr;
  1416.             with Birthday do
  1417.             begin
  1418.                Init(35,5,MMDDYY);
  1419.                SetLabel('When is your next birthday? ');
  1420.                Activate;
  1421.  
  1422.  
  1423. 11-26                                                               User's Guide
  1424.  
  1425. --------------------------------------------------------------------------------
  1426.  
  1427.                Writeln;
  1428.                writeln('You entered the Julian date',GetValue);
  1429.                writeln('i.e. ',JultoStr(GetValue,MMDDYY));
  1430.                Done;
  1431.             end;
  1432.          end.
  1433.  
  1434.  
  1435. Figure 11.8                                                             [SCREEN]
  1436. Single Date
  1437. Input
  1438.  
  1439.  
  1440.  
  1441.          Listed below is an extract of the demo program DEMIO10.PAS which illus-
  1442.          trates how to use many of the methods discussed in this section. Figure
  1443.          11.9 shows an example of the display generated by the full program.
  1444.  
  1445.          procedure InitVars;
  1446.          {}
  1447.          begin
  1448.             with Field1 do
  1449.             begin
  1450.                Init(40,3,MMDDYY);
  1451.                SetLabel('Field 1   (MMDDYY)');
  1452.             end;
  1453.             with Field2 do
  1454.             begin
  1455.                Init(40,5,MMDDYY);
  1456.                SetLabel('Field 2   (MMDDYY)');
  1457.                SetValue(TodayInJul);
  1458.                SetRules(EraseDefault+JumpIfFull);
  1459.             end;
  1460.             with Field3 do
  1461.             begin
  1462.                Init(40,7,DDMMYYYY);
  1463.                SetLabel('Field 3 (DDMMYYYY)');
  1464.              end;
  1465.             with Field4 do
  1466.             begin
  1467.                Init(40,9,DDMMYYYY);
  1468.                SetLabel('Field 4 (DDMMYYYY)');
  1469.                SetMinMax(GregtoJul(3,1,1992),GregtoJul(3,31,1992));
  1470.                SetCursor(CursLeft);
  1471.              end;
  1472.             Keys.Init;
  1473.          end; {InitVars}
  1474.  
  1475.  
  1476.  
  1477. Controlling User Input                                                     11-27
  1478.  
  1479. --------------------------------------------------------------------------------
  1480.  
  1481. Figure 11.9                                                             [SCREEN]
  1482. Using Date
  1483. Fields
  1484.  
  1485.  
  1486.  
  1487. Check Boxes and Radio Buttons
  1488.  
  1489.          Two common elements of contemporary input forms are check boxes and
  1490.          radio buttons. Both these objects provide ways of choosing items from
  1491.          lists of options. Figure 11.10 (listed later in the section) illus-
  1492.          trates both types of objects.
  1493.  
  1494.          A check box object provides a list of options with each item having its
  1495.          own check box displayed to the left of the item, e.g. [X] Toast. Any
  1496.          number of items in the list can be selected. An item's selection status
  1497.          is toggled by hitting the [KEYCAP] or by clicking the mouse cursor on
  1498.          it. Selected items have an X in the adjacent check box.
  1499.  
  1500.          Radio buttons are similar to check boxes, except that only one item can
  1501.          be selected. When an item is selected, the previously selected item is
  1502.          deselected. The selected item has a dot in the "button" next to it,
  1503.          e.g. (.) Ham Sandwich.
  1504.  
  1505.          The Toolkit objects CheckIOOBJ and RadioIOOBJ are located in the totIO1
  1506.          unit, and are descended from VisibleIOOBJ. Both objects, therefore,
  1507.          inherit the following, previously described, methods:
  1508.  
  1509.                   SetActiveStatus(Selectable:boolean);
  1510.                   SetHotkey(HK:word);
  1511.                   SetID(ID:word);
  1512.                   SetLabel(Lbl:string);
  1513.                   SetMessage(X,Y:byte;Msg:string);
  1514.                   Activate;
  1515.                   Done;
  1516.  
  1517.  
  1518.          The objects are part of the MultLineIOOBJ object family and also
  1519.          inherit the following method:
  1520.  
  1521.  
  1522.          SetBoxOn(On:boolean);
  1523.  
  1524.          All multi-line objects can be optionally displayed in a box. By
  1525.          default, the objects are not displayed in a box. To activate the box
  1526.          display, pass a True parameter.
  1527.  
  1528.  
  1529.          Both objects share the following common methods:
  1530.  
  1531.  
  1532.          Init(X1,Y1,width,depth:byte; Title:string);
  1533.  
  1534.  
  1535.  
  1536. 11-28                                                               User's Guide
  1537.  
  1538. --------------------------------------------------------------------------------
  1539.  
  1540.          This method should be called first. The first two parameters specify
  1541.          the (X,Y) coordinate of the top left of the object. The third and
  1542.          fourth parameters specify the width and depth of the object in charac-
  1543.          ters. The width should be large enough to accommodate the longest item,
  1544.          and leave room for the box, if the box is active. The depth should be
  1545.          large enough to accommodate the title, all the items and, optionally,
  1546.          the box.
  1547.  
  1548.  
  1549.          AddItem(Str:string; HK:word; Selected:boolean);
  1550.  
  1551.          This method adds an item to the list. The first parameter specifies the
  1552.          text to be displayed - don't forget that embedded '~' characters can be
  1553.          used to highlight text (see page 5-3 for further information). The
  1554.          second parameter is an optional hot key code, which the user can press
  1555.          to jump to this item and automatically select/deselect it. Pass a value
  1556.          of zero if you don't want to specify a hotkey. The third parameter
  1557.          indicates whether the item is selected or not. You can add as many
  1558.          items as will fit in the object's initialized dimensions.
  1559.  
  1560.  
  1561.  
  1562.  
  1563.            Note: the generic method SetHotKey is used to specify the hotkey
  1564.            for the entire object. If the user presses the generic hotkey, the
  1565.            object will be selected, and the last active item will be high-
  1566.            lighted. The individual item hotkeys allow the user to both select
  1567.            the object, and immediately activate the specific item. The demo
  1568.            program DEMIO12.PAS, discussed later, illustrates hotkeys.
  1569.  
  1570.  
  1571.  
  1572.  
  1573. CheckIOOBJ
  1574.  
  1575.          CheckIOOBJ provides the following two methods for setting and checking
  1576.          the status of each item:
  1577.  
  1578.  
  1579.          SetValue(Item:byte; selected:boolean);
  1580.  
  1581.          This method is used to change the selection status of an item after it
  1582.          has been added with AddItem. The first parameter specifies the item
  1583.          number, and the second boolean parameter should be set to True to
  1584.          select the item, or false to deselect it.
  1585.  
  1586.  
  1587.          GetValue(Item:byte):boolean;
  1588.  
  1589.          This boolean function method returns True if the specified item is
  1590.          selected.
  1591.  
  1592.  
  1593.  
  1594. Controlling User Input                                                     11-29
  1595.  
  1596. --------------------------------------------------------------------------------
  1597.  
  1598. RadioIOOBJ
  1599.  
  1600.          RadioIOOBJ has the following methods for setting and checking which
  1601.          item is selected:
  1602.  
  1603.  
  1604.          SetValue(Item:byte);
  1605.  
  1606.          Only one item in a radio button object can be selected. Use this method
  1607.          (after you have added all the items) to specify which item is selected.
  1608.  
  1609.  
  1610.          GetValue:byte;
  1611.  
  1612.          This function returns the number of the selected item.
  1613.  
  1614.  
  1615.  
  1616. Examples
  1617.  
  1618.          Listed below is the demo program DEMIO11.PAS illustrating a single
  1619.          radio button field.
  1620.  
  1621.          program DemoIOEleven;
  1622.          {demIO11 - single Radio Button input}
  1623.  
  1624.          Uses DOS, CRT,
  1625.               totFAST, totINPUT, totIO1, totIO2;
  1626.  
  1627.          Var
  1628.             Bool: RadioIOOBJ;
  1629.  
  1630.          begin
  1631.             ClrScr;
  1632.             with Bool do
  1633.             begin
  1634.                Init(35,12,20,5,'Sex?');
  1635.                SetBoxOn(True);
  1636.                AddItem('~M~ale',77,true);
  1637.                AddItem('~F~emale',70,false);
  1638.                Mouse.Show;
  1639.                Activate;
  1640.                Mouse.Hide;
  1641.                gotoxy(1,20);
  1642.                if GetValue = 1 then
  1643.                   writeln('You are male!')
  1644.                else
  1645.                   writeln('Hi, I''m Bob.');
  1646.                Done;
  1647.             end;
  1648.          end.
  1649.  
  1650.  
  1651.  
  1652. 11-30                                                               User's Guide
  1653.  
  1654. --------------------------------------------------------------------------------
  1655.  
  1656.          Listed below is an extract of the demo program DEMIO12.PAS, which
  1657.          illustrates how to combine mulitiple fields in a dialog box. Figure
  1658.          11.10 shows an example of the display generated by the full program.
  1659.  
  1660.          procedure InitVars;
  1661.          {}
  1662.          begin
  1663.             with Field1 do
  1664.             begin
  1665.                Init(17,5,25,4,'Options');
  1666.                AddItem('~C~ase sensitive',67,false);
  1667.                AddItem('~W~hole words only',87,false);
  1668.                AddItem('~R~egular expression',82,false);
  1669.             end;
  1670.             with Field2 do
  1671.             begin
  1672.                Init(17,10,25,3,'Scope');
  1673.                AddItem('~G~lobal',71,true);
  1674.                AddItem('~S~elected text',83,false);
  1675.             end;
  1676.             with Field3 do
  1677.             begin
  1678.                Init(45,5,17,3,'Direction');
  1679.                AddItem('Forwar~d~',68,true);
  1680.                AddItem('~B~ackward',66,false);
  1681.             end;
  1682.             with Field4 do
  1683.             begin
  1684.                Init(45,10,17,3,'Origin');
  1685.                AddItem('~F~rom cursor',70,false);
  1686.                AddItem('~E~ntire scope',69,true);
  1687.             end;
  1688.             Keys.Init;
  1689.          end; {InitVars}
  1690.  
  1691.  
  1692. Figure 11.10                                                            [SCREEN]
  1693. A Custom
  1694. Dialog Box
  1695.  
  1696.  
  1697.  
  1698. List Fields
  1699.  
  1700.          Radio buttons allow the user to select a single item from a list.
  1701.          Sometimes, however, you may have too many items in the list to display
  1702.          all together. The ListOOBJ object family can be used to display scroll-
  1703.          able lists, and these are located in the totIO2 unit.
  1704.  
  1705.  
  1706.  
  1707. Controlling User Input                                                     11-31
  1708.  
  1709. --------------------------------------------------------------------------------
  1710.  
  1711.          ListIOOBJ is an abstract object, and you should only use the descen-
  1712.          dants ArrayIOOBJ and LinkIOOBJ. These objects display the contents of a
  1713.          string array and a DLLOBJ linked list, respectively. Both these objects
  1714.          are descendant from MultiLineIOOBJ, and inherit the following, pre-
  1715.          viously discussed, methods:
  1716.  
  1717.                   SetActiveStatus(Selectable:boolean);
  1718.                   SetHotkey(HK:word);
  1719.                   SetID(ID:word);
  1720.                   SetLabel(Lbl:string);
  1721.                   SetMessage(X,Y:byte;Msg:string);
  1722.                   SetBoxOn(On:boolean);
  1723.                   Activate;
  1724.                   Done;
  1725.  
  1726.  
  1727.          Both items share the following common Init method:
  1728.  
  1729.  
  1730.          Init(X1,Y1,width,depth:byte; Title:string);
  1731.  
  1732.          This method should be called first. The first two parameters specify
  1733.          the (X,Y) coordinate of the top left of the object. The third and
  1734.          fourth parameters specify the width and depth of the object in charac-
  1735.          ters. The width should be large enough to accommodate the longest item,
  1736.          a scroll bar (if there are too many items to display at once) and leave
  1737.          room for the box (if the box is active). The depth should be large
  1738.          enough to accommodate the title, at least one item and, optionally, the
  1739.          box.
  1740.  
  1741.  
  1742.          Having initialized the object, the next task is to call the AssignList
  1743.          method. AssignList instructs the Toolkit where to locate the data for
  1744.          the items in the list. Each object has its own AssignList method.
  1745.  
  1746.  
  1747.  
  1748. ArrayIOOBJ
  1749.  
  1750.          The Toolkit gets the contents of the list from a string array, which
  1751.          you must create separately. Having created the array, you must call the
  1752.          following method:
  1753.  
  1754.  
  1755.          AssignList(var StrArray; Total:longint; StrLength:byte);
  1756.  
  1757.          AssignList identifies the string array that will be displayed. The four
  1758.          parameters are the string array, the total number of elements in the
  1759.          array, and the length of each string in the array. The string length
  1760.          parameter must reflect the string length of the array when it was
  1761.          declared, not the maximum length of any string assigned to the array.
  1762.  
  1763.  
  1764.  
  1765. 11-32                                                               User's Guide
  1766.  
  1767. --------------------------------------------------------------------------------
  1768.  
  1769.          Listed below is the demo program DEMIO13.PAS, which illustrates how to
  1770.          build an ArrayIOOBJ field.
  1771.  
  1772.          program DemoIOThirteen;
  1773.          {demIO13 - single ArrayIOOBJ input}
  1774.  
  1775.          Uses DOS, CRT,
  1776.               totFAST, totIO1, totIO2;
  1777.  
  1778.          Var
  1779.             MyList: array[1..10] of string[20];
  1780.             ListField: ArrayIOOBJ;
  1781.  
  1782.          procedure FillArray;
  1783.          {}
  1784.          begin
  1785.             MyList[1] := 'Monitor';
  1786.             MyList[2] := 'Keyboard';
  1787.             MyList[3] := 'Mouse';
  1788.             MyList[4] := 'Light Pen';
  1789.             MyList[5] := 'Microphone';
  1790.             MyList[6] := 'LCD O/H Panel';
  1791.             MyList[7] := 'Modem';
  1792.             MyList[8] := 'Printer';
  1793.             MyList[9] := 'CD Rom';
  1794.             MyList[10] := 'Toolkit';
  1795.          end; {FillArray}
  1796.  
  1797.          begin
  1798.             ClrScr;
  1799.             FillArray;
  1800.             with ListField do
  1801.             begin
  1802.                Init(35,5,15,6,'Peripherals');
  1803.                AssignList(MyList,10,20);
  1804.                Activate;
  1805.                gotoxy(1,20);
  1806.                writeln('You chose item: ',GetValue,' - ',MyList[GetValue]);
  1807.                Done;
  1808.             end;
  1809.          end.
  1810.  
  1811.  
  1812.  
  1813.  
  1814. LinkIOOBJ
  1815.  
  1816.          This object accesses a DLLOBJ object, to determine which items to dis-
  1817.          play in the list. You must create a DLLOBJ instance, populate the list,
  1818.          and then call the following AssignList method:
  1819.  
  1820.  
  1821.  
  1822. Controlling User Input                                                     11-33
  1823.  
  1824. --------------------------------------------------------------------------------
  1825.  
  1826.          AssignList(var LinkList: DLLOBJ);
  1827.  
  1828.          This method is passed a DLLOBJ instance, or any instance of an object
  1829.          descended from DLLOBJ, e.g. StrDLLOBJ.
  1830.  
  1831.  
  1832.          Listed below is the demo program DEMIO14.PAS, which illustrates how to
  1833.          build a LinkIOOBJ field.
  1834.  
  1835.          program DemoIOFourteen;
  1836.          {demIO14 - single LinkIOOBJ input}
  1837.  
  1838.          Uses DOS, CRT,
  1839.               totFAST, totIO1, totIO2, totLINK;
  1840.  
  1841.          Var
  1842.             MyList: StrDLLOBJ;
  1843.             ListField: LinkIOOBJ;
  1844.  
  1845.          procedure FillList;
  1846.          {}
  1847.          var Retcode: integer;
  1848.          begin
  1849.             with MyList do
  1850.             begin
  1851.                Init;
  1852.                Retcode := Add('Monitor');
  1853.                Retcode := Add('Keyboard');
  1854.                Retcode := Add('Mouse');
  1855.                Retcode := Add('Light Pen');
  1856.                Retcode := Add('Microphone');
  1857.                Retcode := Add('LCD O/H Panel');
  1858.                Retcode := Add('Modem');
  1859.                Retcode := Add('Printer');
  1860.                Retcode := Add('CD Rom');
  1861.                Retcode := Add('Toolkit');
  1862.             end;
  1863.          end; {FillList}
  1864.  
  1865.          begin
  1866.             ClrScr;
  1867.             FillList;
  1868.             with ListField do
  1869.             begin
  1870.                Init(35,5,15,6,'Peripherals');
  1871.                AssignList(MyList);
  1872.                Activate;
  1873.                gotoxy(1,20);
  1874.                writeln('You chose item: ',GetValue,' - ',
  1875.                        MyList.GetStr(MyList.NodePtr(GetValue),0,0));
  1876.                Done;
  1877.  
  1878.  
  1879.  
  1880. 11-34                                                               User's Guide
  1881.  
  1882. --------------------------------------------------------------------------------
  1883.  
  1884.                MyList.Done;
  1885.             end;
  1886.          end.
  1887.  
  1888.  
  1889.  
  1890.  
  1891.          Both the examples produce identical displays, see figure 11.11 below.
  1892.  
  1893.  
  1894.  
  1895. Figure 11.11                                                            [SCREEN]
  1896. Displaying
  1897. a List
  1898.  
  1899.  
  1900.  
  1901. Word Wrapping Fields
  1902.  
  1903.          Some of the most powerful, but easy to use, form objects are the Word-
  1904.          WrapIOOBJ objects. These objects can be used to display scrollable memo
  1905.          fields. The user can type in multiple lines of text with full editing,
  1906.          and the object provides automatic word wrapping.
  1907.  
  1908.          WordWrapIOOBJ is an abstract object, and you should only use the
  1909.          descendants WWArrayIOOBJ and WWLinkIOOBJ. Like the List objects
  1910.          described in the last section, these objects display the contents of a
  1911.          string array and a DLLOBJ linked list, respectively. Both objects are
  1912.          descendant from MultiLineIOOBJ, and inherit the following, previously
  1913.          discussed, methods:
  1914.  
  1915.                   SetActiveStatus(Selectable:boolean);
  1916.                   SetHotkey(HK:word);
  1917.                   SetID(ID:word);
  1918.                   SetLabel(Lbl:string);
  1919.                   SetMessage(X,Y:byte;Msg:string);
  1920.                   SetBoxOn(On:boolean);
  1921.                   SetIns(InsOn:boolean);
  1922.                   Activate;
  1923.                   Done;
  1924.  
  1925.  
  1926.          Both items share the following common Init method:
  1927.  
  1928.  
  1929.          Init(X1,Y1,width,lines:byte; Title:string);
  1930.  
  1931.          This method should be called first. The first two parameters specify
  1932.          the (X,Y) coordinate of the top left of the object. The third parameter
  1933.          specifies the width of the object in characters, and the fourth parame-
  1934.          ter specifies the number of lines of text to display. The last parame-
  1935.          ter is an optional title.
  1936.  
  1937.  
  1938.  
  1939. Controlling User Input                                                     11-35
  1940.  
  1941. --------------------------------------------------------------------------------
  1942.  
  1943.          Having initialized the object, the next task is to call the AssignList
  1944.          method. AssignList instructs the Toolkit where to locate the data for
  1945.          the text. Each object has its own AssignList method, and these are
  1946.          explained in a later section.
  1947.  
  1948.          If you want to pre-load the field with some text, you can take advan-
  1949.          tage of the following auto-word wrapping method:
  1950.  
  1951.  
  1952.          WrapFull;
  1953.  
  1954.          This method adjusts the contents of the source data structure, i.e. the
  1955.          string array or linked list, by word wrapping the existing text. When
  1956.          you add text to the data structures you do not need to accurately word
  1957.          wrap the text, but you should make sure that there is always one space
  1958.          at the end of the line. This space separates the last word on one line
  1959.          from the first word on the next line.
  1960.  
  1961.  
  1962.          Sometimes, you may want to display a word wrap field, but not allow the
  1963.          user to edit the text. The following method controls whether editing is
  1964.          allowed:
  1965.  
  1966.  
  1967.          SetAllowEdit(On:Boolean);
  1968.  
  1969.          Pass true to enable editing (default). When editing is disabled, the
  1970.          user may still scroll the text, but it cannot be changed.
  1971.  
  1972.  
  1973.          When the word wrap fields are used on their own, i.e. by calling acti-
  1974.          vate rather than as part of a form, the user can end the input by
  1975.          pressing F10. This "end edit" key can be assigned to another key using
  1976.          the following method:
  1977.  
  1978.  
  1979.          SetEndKey(K:word);
  1980.  
  1981.          Specifies the key which will end the input session when the field is
  1982.          used individually rather than as part of a form. The default is F10.
  1983.  
  1984.  
  1985.  
  1986. WWArrayIOOBJ
  1987.  
  1988.          The Toolkit gets the text contents from a string array, which you must
  1989.          create separately. Having created the array, you must call the follow-
  1990.          ing method:
  1991.  
  1992.  
  1993.          AssignList(var StrArray; Total:longint; StrLength:byte);
  1994.  
  1995.  
  1996.  
  1997. 11-36                                                               User's Guide
  1998.  
  1999. --------------------------------------------------------------------------------
  2000.  
  2001.          AssignList identifies the string array that will be displayed. The
  2002.          three parameters are the string array, the total number of elements in
  2003.          the array, and the length of each string in the array. The string
  2004.          length parameter must reflect the string length of the array when it
  2005.          was declared, not the maximum length of any string assigned to the
  2006.          array.
  2007.  
  2008.  
  2009.  
  2010.            Note: the Toolkit is unable to extend the size of the array. You
  2011.            must, therefore, ensure the array is large enough to accommodate
  2012.            all the text the user is allowed to enter. If you want an unlim-
  2013.            ited number of lines, or you want the Toolkit to extend the lines
  2014.            used, take advantage of the WWlinkOBJ described next.
  2015.  
  2016.  
  2017.  
  2018.  
  2019.          Listed below is the demo program DEMIO15.PAS, which illustrates how to
  2020.          build an WWArrayIOOBJ field.
  2021.  
  2022.          program DemoIOFifteen;
  2023.          {demIO15 - single WWArrayIOOBJ input}
  2024.          Uses DOS, CRT,
  2025.               totFAST, totIO1, totIO3, totINPUT;
  2026.  
  2027.          Var
  2028.             MyList: array[1..10] of string[60];
  2029.             WWField: WWArrayIOOBJ;
  2030.  
  2031.          procedure FillArray;
  2032.          {}
  2033.          begin
  2034.             FillChar(MyList,sizeof(MyList),#0);
  2035.             MyList[1] := 'It seems like we have to work at innocence ';
  2036.             MyList[2] := 'and being pure, and at the same time we have ';
  2037.             MyList[3] := 'to work at being successful so that we have ';
  2038.             MyList[4] := 'an understanding as to what the rest of the ';
  2039.             MyList[5] := 'world is up to.';
  2040.             MyList[6] := '';
  2041.             MyList[7] := 'Brother Anthony Fiore';
  2042.          end; {FillArray}
  2043.  
  2044.          begin
  2045.             ClrScr;
  2046.             Screen.WriteCenter(1,15,'Press F10 to finish');
  2047.             FillArray;
  2048.             Mouse.Show;
  2049.             with WWField do
  2050.             begin
  2051.                Init(5,7,65,7,'A Quote');
  2052.                AssignList(MyList,10,60);
  2053.  
  2054.  
  2055. Controlling User Input                                                     11-37
  2056.  
  2057. --------------------------------------------------------------------------------
  2058.  
  2059.                WrapFull;
  2060.                Activate;
  2061.                gotoxy(1,20);
  2062.                Done;
  2063.             end;
  2064.             Mouse.Hide;
  2065.          end.
  2066.  
  2067.  
  2068.  
  2069. WWLinkIOOBJ
  2070.  
  2071.          This object accesses a DLLOBJ object to determine which items to dis-
  2072.          play in the list. You must create a DLLOBJ instance, populate the list,
  2073.          and then call the following AssignList method:
  2074.  
  2075.  
  2076.          AssignList(var LinkList: DLLOBJ; Max:integer);
  2077.  
  2078.          This method is passed a DLLOBJ instance, or any instance of an object
  2079.          descended from DLLOBJ, e.g. StrDLLOBJ. Max specifies the maximum number
  2080.          of lines by which the Toolkit can extend the list.
  2081.  
  2082.  
  2083.          Listed below is the demo program DEMIO16.PAS, which illustrates how to
  2084.          build a WWLinkIOOBJ field.
  2085.  
  2086.          program DemoIOSixteen;
  2087.          {demIO16 - single WWLinkIOOBJ input}
  2088.          Uses DOS, CRT,
  2089.               totFAST, totIO1, totIO3, totINPUT, totLINK;
  2090.  
  2091.          Var
  2092.             MyList: StrDLLOBJ;
  2093.             WWField: WWLinkIOOBJ;
  2094.  
  2095.          procedure FillList;
  2096.          {}
  2097.          var Retcode: integer;
  2098.          begin
  2099.             with MyList do
  2100.             begin
  2101.                init;
  2102.                Retcode := Add('It seems like we have to work at innocence ');
  2103.                Retcode := Add('and being pure, and at the same time we have ');
  2104.                Retcode := Add('to work at being successful so that we have ');
  2105.                Retcode := Add('an understanding as to what the rest of the ');
  2106.                Retcode := Add('world is up to.');
  2107.                Retcode := Add('');
  2108.                Retcode := Add('Brother Anthony Fiore');
  2109.             end;
  2110.          end; {FillList}
  2111.  
  2112.  
  2113.  
  2114. 11-38                                                               User's Guide
  2115.  
  2116. --------------------------------------------------------------------------------
  2117.  
  2118.          begin
  2119.             ClrScr;
  2120.             Screen.WriteCenter(1,15,'Press F10 to finish');
  2121.             FillList;
  2122.             Mouse.Show;
  2123.             with WWField do
  2124.             begin
  2125.                Init(5,7,65,7,'A Quote');
  2126.                AssignList(MyList,40);
  2127.                WrapFull;
  2128.                Activate;
  2129.                gotoxy(1,20);
  2130.                MyList.Done;
  2131.                Done;
  2132.             end;
  2133.             Mouse.Hide;
  2134.          end.
  2135.  
  2136.  
  2137.  
  2138.          The display generated by both of the demo programs is identical, and is
  2139.          illustrated in figure 11.12.
  2140.  
  2141.  
  2142.  
  2143. Figure 11.12                                                            [SCREEN]
  2144. A Word Wrap
  2145. Field
  2146.  
  2147.  
  2148.  
  2149. Button Fields
  2150.  
  2151.          Buttons are for use with full screen input forms. They provide a way
  2152.          for the user to invoke an event. For example, an input form may have a
  2153.          SAVE button and a CANCEL button. A button can be selected by tabbing to
  2154.          the button and pressing [KEYCAP], pressing the button hotkey, or by
  2155.          clicking the mouse cursor on the button.
  2156.  
  2157.          The Toolkit provides three button objects in the totIO1 unit: Stri-
  2158.          pIOOBJ, Strip3dIOOBJ, and ButtonIOOBJ. All three objects function iden-
  2159.          tically, and the differences are purely cosmetic. The StripIOOBJ object
  2160.          provides a single-line button, Strip3dIOOBJ is a single line button
  2161.          with a black shadow, and ButtonIOOBJ displays the button text sur-
  2162.          rounded by a box. Refer back to figure 11.4 (on page 11-8) for examples
  2163.          of each button type.
  2164.  
  2165.          All three button objects are descended from VisibleIOOBJ and share the
  2166.          following, previously described, methods:
  2167.  
  2168.  
  2169.  
  2170. Controlling User Input                                                     11-39
  2171.  
  2172. --------------------------------------------------------------------------------
  2173.  
  2174.                   SetActiveStatus(Selectable:boolean);
  2175.                   SetHotkey(HK:word);
  2176.                   SetID(ID:word);
  2177.                   SetLabel(Lbl:string);
  2178.                   SetMessage(X,Y:byte;Msg:string);
  2179.                   Done;
  2180.  
  2181.  
  2182.          While the SetLabel method is technically available, it is not normally
  2183.          used, because the button text acts as a label.
  2184.  
  2185.          The totIO1 unit includes the declaration of the enumerated type tAc-
  2186.          tion, which has the following members: None, NextField, PrevField, Fin-
  2187.          ished, Escaped, Refresh, Signal, Enter, Help, Stop1..Stop9. All these
  2188.          members are used internally by the Toolkit to control events during
  2189.          full screen input. The following members should be used with buttons:
  2190.  
  2191.               Finished       Use with buttons to indicate a standard end of a
  2192.                              form editing session, e.g. buttons like "OK",
  2193.                              "Done", "Proceed", "Save".
  2194.  
  2195.               Escaped        Use with buttons that allow the user to exit
  2196.                              without processing the edited data, e.g. buttons
  2197.                              like "Cancel", "Abort".
  2198.  
  2199.               Help           Use with a "Help" button. When selected, the
  2200.                              Toolkit will automatically invoke a context sensi-
  2201.                              tive help system (discussed later).
  2202.  
  2203.               Stop1..Stop9   These buttons function like Finished. They should
  2204.                              be used to successfully end the form edit session.
  2205.                              They are provided so that you may provide multiple
  2206.                              finished buttons. Based on which button is
  2207.                              selected, you may process the edited data differ-
  2208.                              ently. For example, you may create the following
  2209.                              three buttons:
  2210.                                       "Save & Quit"  -  Finished
  2211.                                       "Save & Edit Next" - Stop1
  2212.                                       "Save & Backup File" - Stop2
  2213.                              Whichever button is selected, the edit session will
  2214.                              end, and the FormOBJ (discussed later) will return
  2215.                              the tAction member selected.
  2216.  
  2217.  
  2218.          All three buttons share the following method:
  2219.  
  2220.  
  2221.          Init(X,Y:byte;Tit:string;Act:tAction);
  2222.  
  2223.  
  2224.  
  2225. 11-40                                                               User's Guide
  2226.  
  2227. --------------------------------------------------------------------------------
  2228.  
  2229.          This method initializes the button and must be called first. The first
  2230.          two parameters specify the upper left (X,Y) coordinate of the button.
  2231.          The third parameter is the title which will be displayed in the button.
  2232.          The title may include embedded highlight ('~') characters. The fourth
  2233.          parameter is a member of the enumerated type tAction, which indicates
  2234.          what action to take when the button is selected.
  2235.  
  2236.  
  2237.          Listed below is an extract of the program DEMIO17.PAS. This program is
  2238.          an enhancement to DEMIO12.PAS. Two buttons have been added to the dia-
  2239.          log box. Compare the display of the new program, shown in figure 11.13,
  2240.          with the button-less version in figure 11.10 (page 11-30).
  2241.  
  2242.          procedure InitVars;
  2243.          {}
  2244.          begin
  2245.             {...}
  2246.             OK.Init(23,14,'   ~O~K   ',Finished);
  2247.             OK.SetHotkey(79);
  2248.             Cancel.Init(36,14,' C~a~ncel ',Escaped);
  2249.             Cancel.SetHotkey(65);
  2250.             {...}
  2251.          end; {InitVars}
  2252.  
  2253.  
  2254.  
  2255.  
  2256. Figure 11.13                                                            [SCREEN]
  2257. 3D Strip
  2258. Buttons
  2259.  
  2260.  
  2261.  
  2262. Controlling Defaults with IOTOT
  2263.  
  2264.          One of the basic approaches in the Toolkit is to default as much as
  2265.          possible! This saves you the chore of setting dozens of parameters like
  2266.          display colors every time you want to perform a simple task. You can,
  2267.          of course, change any of the default values to meet your specific
  2268.          needs.
  2269.  
  2270.          All the colors and default settings for user input are established by
  2271.          the instance IOTOT^. IOTOT is a pointer to an object of type InputOBJ
  2272.          and is designed specifically to give you control of the input defaults.
  2273.          There are methods for setting display colors, field rules, the case of
  2274.          string input, whether the fields are initially in insert mode, and so
  2275.          on.
  2276.  
  2277.          To modify the defaults, all you have to do is call one of the IOTOT^
  2278.          methods. Before analyzing the detailed method syntax, you need to be
  2279.          aware of the wealth of colors used by the Toolkit. Most display set-
  2280.          tings require four different color attributes to be specified. The
  2281.  
  2282.  
  2283.  
  2284. Controlling User Input                                                     11-41
  2285.  
  2286. --------------------------------------------------------------------------------
  2287.  
  2288.          first two attributes are used when the field is highlighted, i.e. when
  2289.          the user is editing the field, and the second two attributes are used
  2290.          when the field is not highlighted. You may recall that the Toolkit can
  2291.          display any string in two colors using the method WriteHi (discussed on
  2292.          page 5-3). Many of the strings in the IO objects also support the two
  2293.          colors capability, e.g. field labels, button text, and check boxes.
  2294.          That is why the color setting methods need to use two colors when the
  2295.          field is highlighted, and two colors when it isn't, making a total of
  2296.          four colors for each category.
  2297.  
  2298.  
  2299.  
  2300.  
  2301.            Don't forget that the Toolkit uses a combined foreground/back-
  2302.            ground attribute to define each color. Refer to page 3.11 for
  2303.            further information.
  2304.  
  2305.  
  2306.          The following methods can be used to change the Toolkit IO defaults:
  2307.  
  2308.  
  2309.          SetColLabel(Off,OffHot,On,OnHot:byte);
  2310.  
  2311.          Specifies the display attributes for labels. The first two parameters
  2312.          specify the display attributes when the field is not highlighted. The
  2313.          first parameter is the normal attribute, and the second attribute is
  2314.          the color used after the embedded highlight character, e.g. ~. The
  2315.          third and fourth parameters specify the attributes to use when the
  2316.          field is highlighted.
  2317.  
  2318.  
  2319.          SetColButton(Off,OffHot,On,OnHot:byte);
  2320.  
  2321.          Specifies the four display attributes for button text.
  2322.  
  2323.  
  2324.          SetColGroup(Off,OffHot,On,OnHot:byte);
  2325.  
  2326.          Specifies the four color attributes to use with radio button and check
  2327.          box fields.
  2328.  
  2329.  
  2330.          SetColList(Off,OffHot,On,OnHot:byte);
  2331.  
  2332.          Specifies the four colors to use for list fields.
  2333.  
  2334.  
  2335.          SetColField(Off,On,Mask,Inactive:byte);
  2336.  
  2337.          Specifies the colors to use with standard string fields. The first
  2338.          parameter is the display color when the field is not highlighted, the
  2339.          second parameter is the color when the field is highlighted, the third
  2340.          parameter is the color to display formatting characters in PictureIOOBJ
  2341.          fields, and the fourth parameter is the default display color for any
  2342.          inactive (i.e. non-selectable) field.
  2343.  
  2344.  
  2345. 11-42                                                               User's Guide
  2346.  
  2347. --------------------------------------------------------------------------------
  2348.  
  2349.            Note: For consistency, the Toolkit does not allow you to change
  2350.            the display attributes of an individual field on an input form.
  2351.            The attributes are always derived from IOTOT at display time. You
  2352.            must use the methods SetColLabel, SetColButton, SetColGroup, Set-
  2353.            ColList, and SetColField to change the display attributes of all
  2354.            the field types in the relevant category.
  2355.  
  2356.  
  2357.  
  2358.  
  2359.  
  2360.          SetColMsg(Col:byte);
  2361.  
  2362.          Sets the color of the message which is displayed when the field is
  2363.          highlighted. Specify an attribute of zero, if you want the current
  2364.          display attribute to be used.
  2365.  
  2366.  
  2367.          SetIns(On:boolean);
  2368.  
  2369.          Controls whether the input fields are initially in insert (True) or
  2370.          overtype (False) mode.
  2371.  
  2372.  
  2373.          SetRules(Rules:byte);
  2374.  
  2375.          Sets the default field rules (refer to page 11-12 for further informa-
  2376.          tion).
  2377.  
  2378.  
  2379.          SetPadChar(Pad:char);
  2380.  
  2381.          When a field value does not entirely fill the allotted field, the
  2382.          unused characters are represented by displaying a pad character. By
  2383.          default, this value is set to a dot (ASCII characters 250). This method
  2384.          is used to change the pad character, and one of the most common alter-
  2385.          natives is a space, e.g. IOTOT^.SetPadChar(' ');.
  2386.  
  2387.  
  2388.          SetJust(Just:tJust);
  2389.  
  2390.          This method is used to set the default justification of the string
  2391.          fields (see page 11.13).
  2392.  
  2393.  
  2394.          SetCursor(Curs: tCursPos);
  2395.  
  2396.          This method controls where the cursor is positioned when an input field
  2397.          is highlighted (see page 11.13).
  2398.  
  2399.  
  2400.          SetCase(Cas:tCase);
  2401.  
  2402.          This method can be used to control whether the Toolkit automatically
  2403.          adjusts the case of any of the string field objects, when the user
  2404.          leaves the field (see page 11.13).
  2405.  
  2406. Controlling User Input                                                     11-43
  2407.  
  2408. --------------------------------------------------------------------------------
  2409.  
  2410.          SetForceCase(On:boolean);
  2411.  
  2412.          The SetForceCase method is used to control whether the case of the
  2413.          string input is adjusted while the user is typing in the string. Pass a
  2414.          True parameter to force the case adjustment (as specified with the
  2415.          method SetCase) every time a character is pressed. Pass a False parame-
  2416.          ter if you want the string to be adjusted only when the user moves to
  2417.          another field.
  2418.  
  2419.  
  2420.          The following function methods return information about the current
  2421.          default settings:
  2422.  
  2423.  
  2424.          LabelCol(Element:byte): byte;
  2425.  
  2426.          This function method returns the current attribute for displaying field
  2427.          labels. Pass a parameter with a value between 1 and 4 to indicate which
  2428.          attribute you want to determine. The parameter values represent the
  2429.          following colors:
  2430.  
  2431.               1     Not highlighted normal attribute.
  2432.               2     Not highlighted high attribute.
  2433.               3     Highlighted normal attribute.
  2434.               4     Highlighted high attribute.
  2435.  
  2436.  
  2437.          ButtonCol(Element:byte): byte;
  2438.  
  2439.          Returns the attribute byte of the Button text.
  2440.  
  2441.  
  2442.          GroupCol(Element: byte): byte;
  2443.  
  2444.          Returns the attribute byte of radio button and check box fields.
  2445.  
  2446.  
  2447.          ListCol(Element:byte): byte;
  2448.  
  2449.          Returns the attribute byte of the list fields.
  2450.  
  2451.  
  2452.          FieldCol(Element:byte): byte;
  2453.  
  2454.          Returns the attribute byte of the string fields. Pass a parameter with
  2455.          a value between 1 and 4 to indicate which attribute you want to deter-
  2456.          mine. The parameter values represent the following colors:
  2457.  
  2458.               1     Highlighted attribute.
  2459.               2     Not highlighted attribute.
  2460.               3     Attribute of mask character in picture fields.
  2461.               4     Attribute of inactive (non-selectable) fields.
  2462.  
  2463.  
  2464.          MessageCol: byte;
  2465.  
  2466.  
  2467. 11-44                                                               User's Guide
  2468.  
  2469. --------------------------------------------------------------------------------
  2470.  
  2471.          Returns the attribute used for writing the highlighted field's message.
  2472.  
  2473.  
  2474.          InputPadChar: char;
  2475.  
  2476.          Returns that character which is used to fill a field when the input is
  2477.          shorter than the field length.
  2478.  
  2479.  
  2480.          InputJust: tJust;
  2481.  
  2482.          Returns the default string justification (see page 11-13)
  2483.  
  2484.  
  2485.          InputCursorLoc: tCursPos;
  2486.  
  2487.          Returns the default cursor position (see page 11-13).
  2488.  
  2489.  
  2490.          InputCase: tCase;
  2491.  
  2492.          Returns the default case setting for string fields (see page 11-13).
  2493.  
  2494.  
  2495.          InputForceCase: boolean;
  2496.  
  2497.          Returns true if user input is forced to a specific case when each
  2498.          character is input.
  2499.  
  2500.  
  2501.          If you want to reset all the IOTOT settings back to the original Tool-
  2502.          kit defaults, all you have to do is call the SetDefaults method as
  2503.          follows:
  2504.  
  2505.                   IOTOT^.SetDefaults;
  2506.  
  2507.          By looking at the actual Toolkit code for the SetDefaults method, you
  2508.          can quickly determine the default values.
  2509.  
  2510.          procedure InputOBJ.SetDefaults;
  2511.          {}
  2512.          begin
  2513.             if Monitor^.ColorOn then {color System}
  2514.             begin
  2515.                SetColLabel(78,76,79,76);
  2516.                SetColButton(32,46,47,46);
  2517.                SetColGroup(48,62,63,62);
  2518.                SetColList(48,62,31,30);
  2519.                SetColField(48,31,23,71);
  2520.             end
  2521.             else
  2522.             begin
  2523.                SetColLabel(112,126,127,126);
  2524.                SetColButton(32,46,47,46);
  2525.                SetColGroup(48,62,63,62);
  2526.  
  2527.  
  2528. Controlling User Input                                                     11-45
  2529.  
  2530. --------------------------------------------------------------------------------
  2531.  
  2532.                SetColList(48,62,31,30);
  2533.                SetColField(48,31,23,24);
  2534.             end;
  2535.             SetColMsg(0);
  2536.             vInputPad := chr(250);
  2537.             vCase := Leave;
  2538.             vForceCase := false;
  2539.             vInputJust :=  JustLeft;
  2540.             vCursorLoc := CursPrev;
  2541.             vInsert := false;
  2542.             vRules :=  AllowNull;
  2543.          end; {InputOBJ.SetDefaults}
  2544.  
  2545.  
  2546.  
  2547. Form Management
  2548.  
  2549.          In this section, the various techniques for combining a collection of
  2550.          fields into a form will be explained. You have already learned the
  2551.          complicated stuff! All you have to do is create a FormOBJ instance and
  2552.          tell it which field object to include in the form.
  2553.  
  2554.          FormOBJ is the form manager and is located in the totIO1 unit. To build
  2555.          a form, initialize the FormOBJ instance, add the fields that will
  2556.          create the form, and instruct the Toolkit to process the user input.
  2557.          The following FormOBJ methods perform these services:
  2558.  
  2559.  
  2560.          Init;
  2561.  
  2562.          This method initializes the FormOBJ instance, and should always be
  2563.          called first.
  2564.  
  2565.  
  2566.          AddItem(var NewItem: ItemIOOBJ);
  2567.  
  2568.          This method should be called once for every field on the form. The only
  2569.          passed parameter is an object descended from ItemIOOBJ, i.e. any of the
  2570.          objects discussed so far in this chapter.
  2571.  
  2572.  
  2573.          Go:tAction;
  2574.  
  2575.          Having added all the items, call the function method Go to activate the
  2576.          form, and process the user's input. The function returns one of the
  2577.          following members of the enumerated type tAction: Finished, Escaped,
  2578.          Stop1 through Stop9. The value returned will depend on which button or
  2579.          key the user pressed. Based on the return value, you can decide how to
  2580.          process the user-entered data.
  2581.  
  2582.  
  2583.  
  2584. 11-46                                                               User's Guide
  2585.  
  2586. --------------------------------------------------------------------------------
  2587.  
  2588.          In addition to the standard user input fields, the totIO1 unit includes
  2589.          a special object, ControlKeysIOOBJ, which is used to control how the
  2590.          user moves between fields and terminates input. Every form you create
  2591.          should include a ControlKeysIOOBJ instance. ControlKeysIOOBJ objects
  2592.          provide the following three methods:
  2593.  
  2594.  
  2595.          Init;
  2596.  
  2597.          This method initializes the object and must be called first. The object
  2598.          actually provides the Toolkit with four special keys: the key to move
  2599.          on to the next field, the key to move back to the previous field, the
  2600.          key to finish the edit session, and the key to abort the edit session.
  2601.          When the ControlIOOBJ object is initialized, these keys are set to
  2602.          [KEYCAP], [KEYCAP], [KEYCAP] and [KEYCAP], respectively.
  2603.  
  2604.  
  2605.          SetKeys(Next,Prev,Fin,Esc:word);
  2606.  
  2607.          This method is used to override the default keys. The method is passed
  2608.          the four key codes which represent the keys for moving to the next
  2609.          field, moving back to the previous field, to finish editing, and to
  2610.          abort editing. For example, the statement
  2611.  
  2612.                  SetKeys(336,328,335,27);
  2613.  
  2614.          will set the keys to [KEYCAP], [KEYCAP], [KEYCAP] and [KEYCAP]. Be
  2615.          careful which keys you select. For example, if you have a word wrap
  2616.          field, you probably don't want to use the up and down arrows. Each time
  2617.          the user presses the down arrow to edit the next line, he/she will jump
  2618.          to the next field!
  2619.  
  2620.  
  2621.          Done;
  2622.  
  2623.          This should be called to dispose of the object when it is no longer
  2624.          required.
  2625.  
  2626.  
  2627.  
  2628.  
  2629.          Listed below is the example DEMIO2.PAS, which was first introduced at
  2630.          the beginning of the chapter. It shows how to use some of these basic
  2631.          FormOBJ methods. Refer back to figure 11.2 on page 11-4 to see the
  2632.          resultant output.
  2633.  
  2634.          program DemoIOTwo;
  2635.          {demIO2 - full field input}
  2636.  
  2637.          Uses DOS, CRT,
  2638.               totFAST, totIO1, totIO2;
  2639.  
  2640.  
  2641.  
  2642. Controlling User Input                                                     11-47
  2643.  
  2644. --------------------------------------------------------------------------------
  2645.  
  2646.          Var
  2647.             Name: LateralIOOBJ;
  2648.             Phone: PictureIOOBJ;
  2649.             Price: FixedRealIOOBJ;
  2650.             Keys: ControlkeysIOOBJ;
  2651.             Manager: FormOBJ;
  2652.             Result: tAction;
  2653.  
  2654.          procedure InitVars;
  2655.          {}
  2656.          begin
  2657.             with Name do
  2658.             begin
  2659.                Init(35,5,20,40);
  2660.                SetLabel('Vendor Name');
  2661.             end;
  2662.             with Phone do
  2663.             begin
  2664.                Init(35,7,'(###) ###-####');
  2665.                SetLabel('Tel');
  2666.             end;
  2667.             with Price do
  2668.             begin
  2669.                Init(35,9,8,2);
  2670.                SetLabel('Unit Price');
  2671.                SetValue(250.0);
  2672.                SetMinMax(0.1,12250.0);
  2673.                SetRules(EraseDefault);
  2674.             end;
  2675.             Keys.Init;
  2676.          end; {InitVars}
  2677.  
  2678.          begin
  2679.             ClrScr;
  2680.             Screen.TitledBox(15,3,65,11,76,79,78,2,' Quicky Input Demo ');
  2681.             Screen.WriteCenter(25,white,'Press TAB to switched fields and
  2682.                                          press ESC or F10 to end');
  2683.             InitVars;
  2684.             with Manager do
  2685.             begin
  2686.                Init;
  2687.                AddItem(Keys);
  2688.                AddItem(Name);
  2689.                AddItem(Phone);
  2690.                AddItem(Price);
  2691.                Result := Go;
  2692.                if Result = Finished then
  2693.                   {update the database..}
  2694.                else
  2695.  
  2696.  
  2697.  
  2698. 11-48                                                               User's Guide
  2699.  
  2700. --------------------------------------------------------------------------------
  2701.  
  2702.                   {call Esc routine};
  2703.             end;
  2704.          end.
  2705.  
  2706.  
  2707.  
  2708.  
  2709.          The order in which the fields are added using AddItem will be the order
  2710.          in which the user will jump from field to field. The following FormOBJ
  2711.          method can be used to control which field is highlighted when the Go
  2712.          method is called:
  2713.  
  2714.  
  2715.          SetActiveItem(ID:word);
  2716.  
  2717.          This method instructs the Toolkit on which field to highlight first.
  2718.          The only parameter is the field ID of the field to be highlighted.
  2719.          Don't forget that any field can have a unique ID by calling the method
  2720.          SetID. By default, all fields have an ID of zero.
  2721.  
  2722.  
  2723.  
  2724. Hotkey Fields
  2725.  
  2726.          By now, you should know that any field can have a hotkey assigned with
  2727.          the method SetHotKey. There is one remaining type of field that has not
  2728.          yet been discussed. Namely, HotkeyIOOBJ objects. These fields are "in-
  2729.          visible" and are used to add special Hotkeys to the form.
  2730.  
  2731.          HotkeyIOBJ objects only have the following two methods:
  2732.  
  2733.  
  2734.          Init(HK:word;Act:tAction);
  2735.  
  2736.          A HotkeyIOOBJ object has only two properties. It has a keycode, which
  2737.          represents the key that must be pressed to invoke it, and it has an
  2738.          action code of type tAction, i.e. None, NextField, PrevField, Finished,
  2739.          Escaped, Refresh, Signal, Enter, Help, Stop1..Stop9. Whenever the user
  2740.          presses the assigned hotkey, the specified action is invoked. For exam-
  2741.          ple, if you want to assign the key [KEYCAP] (in addition to [KEYCAP])
  2742.          to end the edit session, you would initialize a HotkeyIOOBJ instance as
  2743.          follows: Init(301,Finished);
  2744.  
  2745.  
  2746.          Done;
  2747.  
  2748.          This disposes of the object.
  2749.  
  2750.  
  2751.  
  2752.  
  2753. Moveable Forms
  2754.  
  2755.          The object WinFormOBJ is a descendant of FormOBJ, and provides the same
  2756.          services with one important enhancement. WinFormOBJ manages an input
  2757.  
  2758.  
  2759. Controlling User Input                                                     11-49
  2760.  
  2761. --------------------------------------------------------------------------------
  2762.  
  2763.          form on a moveable window. It is ideal for creating moveable dialog
  2764.          boxes. The Toolkit itself takes advantage of WinFormOBJ to create the
  2765.          pop-up message objects and the moveable directory dialog box.
  2766.  
  2767.          WinFormOBJ inherits the following methods from FormOBJ:
  2768.  
  2769.                   Init;
  2770.                   AddItem(var NewItem: ItemIOOBJ);
  2771.                   Done;
  2772.  
  2773.          Additionally, WinFormOBJ has a function method Win which returns a
  2774.          pointer to the MoveWinOBJ instance on which the form is built. To
  2775.          modify the window size and other properties, just call Win^.method,
  2776.          where method is any MoveWinOBJ instance.
  2777.  
  2778.          If you are going to create a window-based form using WinFormOBJ, be
  2779.          sure to create each individual field objects with relative (X,Y) coor-
  2780.          dinates. In other words, the top left of the form window will be at
  2781.          coordinates (1,1).
  2782.  
  2783.          Important Note: before calling the method Go, call the method Draw.
  2784.          This instructs the WinFormOBJ object to display the window and save the
  2785.          underlying screen contents.
  2786.  
  2787.          Refer to the on-disk example DEMIO18.PAS for a full example illustrat-
  2788.          ing the WinFormOBJ object. DEMIO18.PAS is actually an enhancement to
  2789.          the program DEMIO17.PAS, creating a text-search dialog box.
  2790.  
  2791.  
  2792.  
  2793. Determining User Input
  2794.  
  2795.          When the user has edited the form, you probably want to know what data
  2796.          was entered! First, be sure to check the tAction code returned by the
  2797.          FormOBJ method Go. This will indicate whether the user escaped, or
  2798.          really wanted the data processed.
  2799.  
  2800.          The only form input objects which update the original data source are
  2801.          the word wrapping objects WWArrayIOOBJ and WWLinkIOOBJ. The Toolkit
  2802.          automatically modifies the data passed to these objects. In all other
  2803.          cases, you should call each individual object's GetValue method to
  2804.          determine the user's input.
  2805.  
  2806.          Review the demo programs DEMIO5,8,10,13,14 to see examples of how to
  2807.          determine user input. Also, the demo programs in the last section More
  2808.          Examples! provide still further examples.
  2809.  
  2810.  
  2811.  
  2812. 11-50                                                               User's Guide
  2813.  
  2814. --------------------------------------------------------------------------------
  2815.  
  2816. Advanced Techniques
  2817.  
  2818.          For the majority of situations, you have learned all you need to know
  2819.          to master form input. However, the Toolkit provides another level of
  2820.          sophistication for developers who really want to customize their input
  2821.          forms. Although this section is called Advanced Features, it does not
  2822.          mean that these features are complicated. The only reason for separa-
  2823.          ting them into a special section is because you will probably use them
  2824.          less frequently.
  2825.  
  2826.          There follows descriptions of how to intercept every character that is
  2827.          pressed, how to validate individual fields before allowing the user to
  2828.          leave, and how to implement a help system. The concept of raising sig-
  2829.          nals between dependent fields is also introduced.
  2830.  
  2831.  
  2832.  
  2833. Intercepting Every Character Press
  2834.  
  2835.          Many of the Toolkit's units include character hooks, which provide a
  2836.          way for you to nominate a procedure or function to be called every time
  2837.          a character is pressed. This allows you to intercept each character and
  2838.          if appropriate, invoke a special routine. You can even change the value
  2839.          of the character pressed. The FormOBJ and WinFormOBJ objects also pro-
  2840.          vide a character hook facility.
  2841.  
  2842.          A character hook is an external procedure which is called every time a
  2843.          key or mouse button is pressed. To utilize the character hook facility,
  2844.          all you have to do is create a function following some specific rules,
  2845.          and then call the FormOBJ method SetCharHook to instruct the Toolkit to
  2846.          use your function.
  2847.  
  2848.          For a function to be eligible as a character hook it must adhere to the
  2849.          following rules:
  2850.  
  2851.          Rule 1     The function must be declared as a FAR function. This can be
  2852.                     achieved by preceding the function with a {$F+} compiler
  2853.                     directive, and following the function with a {$F-} direc-
  2854.                     tive. Alternatively, Turbo 6 users can use the new keyword
  2855.                     FAR following the function statement.
  2856.  
  2857.          Rule 2     The function must be declared with four passed parameters.
  2858.                     Parameter one must be a variable parameter of type word.
  2859.                     This parameter indicates which key the user just pressed,
  2860.                     and you may change the value of this parameter to return a
  2861.                     different key. The second and third parameters must be
  2862.                     variable parameters of type byte, and they represent the X
  2863.                     and Y coordinates of the mouse at the time the key was
  2864.                     pressed. The fourth parameter is a variable, and must be of
  2865.                     type word. This parameter indicates the field ID of the
  2866.                     currently active field. This field can be changed to another
  2867.                     ID if you want the user to jump to a different field.
  2868.  
  2869.  
  2870.  
  2871. Controlling User Input                                                     11-51
  2872.  
  2873. --------------------------------------------------------------------------------
  2874.  
  2875.          Rule 3     The function must return a value of type tAction. This is an
  2876.                     enumerated type which indicates to the Toolkit how to
  2877.                     proceed. The members of the enumerated type are: None,
  2878.                     NextField, PrevField, Finished, Escaped, Refresh, Signal,
  2879.                     Enter, Help, Stop1..Stop9. If you want the edit session to
  2880.                     terminate, return Finished, Escaped, or Stop1 through Stop9.
  2881.                     If you have changed, inserted, or deleted any items in the
  2882.                     visible list, return Refresh. The Toolkit will then re-
  2883.                     display the entire form contents.
  2884.  
  2885.          Rule 4     The function must be at the root level, i.e. the function
  2886.                     cannot be nested within another procedure or function.
  2887.  
  2888.          The following function declaration follows these rules:
  2889.  
  2890.                   {$F+}
  2891.                   function MyCharHook(var K:word;
  2892.                                       var X,Y: byte;
  2893.                                       var FieldID:word): tAction;
  2894.                   begin
  2895.                   ...{function statements}
  2896.                      MyCharHook := NextField;
  2897.                   end;
  2898.                   {$F-}
  2899.  
  2900.  
  2901.          The following method SetCharHook is then called to instruct the Toolkit
  2902.          to call your function every time a key is pressed:
  2903.  
  2904.  
  2905.          SetCharHook(Func:CharFunc);
  2906.  
  2907.          This method is passed the function name of a function declared using
  2908.          the rules outlined above, e.g. SetCharHook(MyCharHook);.
  2909.  
  2910.  
  2911.          Listed below is an extract from the demo program DEMIO19.PAS. This file
  2912.          is a variation on our old favorite DEMIO2.PAS. In this case, a charac-
  2913.          ter hook has been added to intercept the key [KEYCAP]. If this key is
  2914.          pressed, a message showing the current time is displayed. Notice that
  2915.          if [KEYCAP] is pressed, the hook function replaces the actual key with
  2916.          a value of 0. This stops the active field from trying to process the
  2917.          key - a zero key is ignored by the Toolkit. Finally, the hook function
  2918.          returns a value of None, indicating that the form manager does not need
  2919.          to take special action.
  2920.  
  2921.          {$F+}
  2922.          function ShowTime(var K:word; var X,Y:byte; var ID:word):tAction;
  2923.          {}
  2924.          var Msg:  MessageOBJ;
  2925.          begin
  2926.             if K = 276 then {Alt-T}
  2927.  
  2928.  
  2929.  
  2930.  
  2931. 11-52                                                               User's Guide
  2932.  
  2933. --------------------------------------------------------------------------------
  2934.  
  2935.             begin
  2936.                with Msg do
  2937.                begin
  2938.                   Init(1,'The Time M''Lord');
  2939.                   Addline('');
  2940.                   AddLine(padcenter(CurrentTime,25,' '));
  2941.                   AddLine('');
  2942.                   Show;
  2943.                   Done;
  2944.                end;
  2945.                K := 0;
  2946.             end;
  2947.             ShowTime := none;
  2948.          end; {ShowTime}
  2949.          {$F-}
  2950.  
  2951.          begin
  2952.             {...}
  2953.             with Manager do
  2954.             begin
  2955.                Init;
  2956.                AddItem(Keys);
  2957.                AddItem(Name);
  2958.                AddItem(Phone);
  2959.                AddItem(Price);
  2960.                SetCharHook(ShowTime);
  2961.                Result := Go;
  2962.                {...}
  2963.             end;
  2964.          end.
  2965.  
  2966.  
  2967.  
  2968. Validating Input
  2969.  
  2970.          As well as a character hook, the FormOBJ objects provide leave field
  2971.          and enter field hooks. These functions are called when the user tries
  2972.          to leave a field, and when the user tries to enter a field. The leave
  2973.          field hook provides a way to ensure the contents of a field are valid
  2974.          before moving to another field. The enter field hook can be used to
  2975.          take some action before entering a field, e.g. display a warning mes-
  2976.          sage, or move the user to another field if a specific condition is not
  2977.          met.
  2978.  
  2979.          Like the character hook, both field hooks must adhere to the following
  2980.          common rules:
  2981.  
  2982.          Rule 1     The function must be declared as a FAR function.
  2983.  
  2984.  
  2985.  
  2986. Controlling User Input                                                     11-53
  2987.  
  2988. --------------------------------------------------------------------------------
  2989.  
  2990.          Rule 2     The function must return a value of type tAction. This is an
  2991.                     enumerated type, which indicates to the Toolkit how to
  2992.                     proceed.
  2993.  
  2994.          Rule 3     The function must be at the root level.
  2995.  
  2996.  
  2997.  
  2998.          The hooked procedure's passed parameters are different for each hook
  2999.          type, as follows:
  3000.  
  3001.          Leave      The function must be declared with one variable passed
  3002.                     parameter of type word. This parameter represents the field
  3003.                     ID of the field the user is leaving. This parameter can be
  3004.                     changed to another field to instruct the Toolkit to jump to
  3005.                     a different field.
  3006.  
  3007.          Enter      The function must be declared with two passed parameters.
  3008.                     The first parameter is a variable parameter of type word.
  3009.                     This parameter identifies the ID of the field the user is
  3010.                     about to enter. This parameter may be modified, to instruct
  3011.                     the Toolkit to jump to a different field. The second parame-
  3012.                     ter is of type word, and it represents the ID of the field
  3013.                     the user just left.
  3014.  
  3015.          Listed below are two code sample procedures which adhere to the rules
  3016.          for leave and enter field hooks.
  3017.  
  3018.                   {$F+}
  3019.                   function MyEnterHook(var NewID:word; LastID: word):tAction
  3020.                   begin
  3021.                   ...{function statements}
  3022.                      MyEnterHook := none;
  3023.                   end;
  3024.                   {$F-}
  3025.  
  3026.                   {$F+}
  3027.                   function MyLeaveHook(var LastID: word):tAction
  3028.                   begin
  3029.                   ...{function statements}
  3030.                      MyLeaveHook := none;
  3031.                   end;
  3032.                   {$F-}
  3033.  
  3034.  
  3035.          The FormOBJ methods SetLeaveHook or SetEnterHook can then be called to
  3036.          instruct the Toolkit to call the specified function whenever a user
  3037.          tries to leave or enter a field.
  3038.  
  3039.  
  3040.  
  3041. 11-54                                                               User's Guide
  3042.  
  3043. --------------------------------------------------------------------------------
  3044.  
  3045. Context Sensitive Help
  3046.  
  3047.          The fourth category of FormOBJ user hooks is the Help hook. The Help
  3048.          hook provides a way of implementing context sensitive help into your
  3049.          form.
  3050.  
  3051.          To implement a help hook, all you have to do is create a procedure
  3052.          following some specific rules, and then call the FormOBJ method SetHel-
  3053.          pHook to instruct the Toolkit to use your function.
  3054.  
  3055.          For a function to be eligible as a character hook it must adhere to the
  3056.          following rules:
  3057.  
  3058.          Rule 1     The procedure must be declared as a FAR procedure.
  3059.  
  3060.          Rule 2     The procedure must be declared with a single passed parame-
  3061.                     ter of type word. This parameter identifies the ID of the
  3062.                     highlighted field at the time the user requested help.
  3063.  
  3064.          Rule 3     The procedure must be at the root level.
  3065.  
  3066.          The following code fragment shows a procedure which adheres to these
  3067.          rules.
  3068.  
  3069.                   {$F+}
  3070.                   function MyHelpHook(LastID: word);
  3071.                   begin
  3072.                   ...{help display statements}
  3073.                   end;
  3074.                   {$F-}
  3075.  
  3076.  
  3077.          If you go to the trouble of creating a help system, you ought to give
  3078.          the user some way of requesting help! The two best ways to add help are
  3079.          with a hotkey and with a help button. Either way is easy, and you ought
  3080.          to consider using both. The following code fragment shows how to imple-
  3081.          ment them:
  3082.  
  3083.          var
  3084.            HelpBut: Strip3dIOOBJ;
  3085.            F1key: HotkeyIOOBJ;
  3086.  
  3087.          begin
  3088.             {...}
  3089.             HelpBut.Init(34,12,'  ~H~elp  ',Help);
  3090.             HelpBut.SetHotkey(291);
  3091.             HelpBut.SetID(HelpID);
  3092.             F1Key.Init(315,Help);
  3093.             {...}
  3094.          end.
  3095.  
  3096.  
  3097.  
  3098. Controlling User Input                                                     11-55
  3099.  
  3100. --------------------------------------------------------------------------------
  3101.  
  3102.          Notice that the help button is assigned an ID of HelpID. HelpID is a
  3103.          constant defined in the totIO1 unit. The likelihood is that the user
  3104.          wants help on the highlighted field, and doesn't actually want to move
  3105.          to the help button. By assigning an object an ID of HelpID, the Toolkit
  3106.          knows not to swap to it when it is selected with a mouse button or
  3107.          hotkey.
  3108.  
  3109.          Refer to the demo program DEMIO20.PAS for a full example of how to
  3110.          implement a help system. This program is a further enhancement to the
  3111.          search dialog box demo program discussed earlier. Figure 11.14 illus-
  3112.          trates the display generated when the user asks for help.
  3113.  
  3114.  
  3115.  
  3116. Figure 11.14                                                            [SCREEN]
  3117. Add a Help
  3118. System
  3119.  
  3120.  
  3121.  
  3122. Creating Descendant Objects
  3123.  
  3124.          The FormOBJ object provides four different hooks for customizing the
  3125.          form input to meet your specific needs. If you think there may be an
  3126.          OOP way to achieve the same results you are right. You can create a
  3127.          descendent object from either FormOBJ or WinFormOBJ, and replace the
  3128.          following virtual methods:
  3129.  
  3130.          function CharTask(var K:word; var X,Y:byte;var FieldID:word):tAction;
  3131.          function LeaveTask(var FieldID:word):tAction;
  3132.          function EnterTask(var NewID:word; OldID;word):tAction;
  3133.          procedure HelpTask(ID:word);
  3134.  
  3135.          The passed parameters to these virtual methods are exactly the same as
  3136.          the ones described earlier for the hooks.
  3137.  
  3138.          Refer to chapter 9: Managing Lists page 9-32 for a comparison of hooks
  3139.          and virtual methods.
  3140.  
  3141.  
  3142.  
  3143.          In some special circumstances you will want to create fields which
  3144.          interact. A good example can be found in the Toolkit object DirWinOBJ
  3145.          (discussed in chapter 10). This object has three main fields -  a
  3146.          filename input field, a list of matching files, and a list of directo-
  3147.          ries and drives. If the user enters a new file mask, the file list
  3148.          needs to be refreshed. Similarly, if the user changes directories, the
  3149.          file list and the directory list need to be updated.
  3150.  
  3151.          The solution is for the modified field to raise a signal when changes
  3152.          need to be made to other fields. When a field raises a signal, the
  3153.          Toolkit passes the signal to every other field in turn, and each of
  3154.          these fields may itself raise signals. Every input field object has the
  3155.          following virtual methods:
  3156.  
  3157.  
  3158.  
  3159. 11-56                                                               User's Guide
  3160.  
  3161. --------------------------------------------------------------------------------
  3162.  
  3163.          procedure RaiseSignal(var TheSig:tSignal);
  3164.          procedure HandleSignal(var BaseSig:tSignal; var NewSig:tSignal);
  3165.          procedure ShutDownSignal(var BaseSig:tSignal);
  3166.  
  3167.          Refer to Part 2: Extending the Toolkit for further information about
  3168.          creating input objects which raise and handle signals.
  3169.  
  3170.  
  3171.  
  3172. More Examples!
  3173.  
  3174.          There are several additional on-disk examples included in the Toolkit.
  3175.          These examples combine many of the features described in this chapter
  3176.          to provide powerful input routines. For example, IODEM21.PAS shows how
  3177.          you might use the objects to create a database access program, and
  3178.          IODEM22.PAS illustrates how you can use PgUp and PgDn to implement a
  3179.          double input screen.
  3180.