home *** CD-ROM | disk | FTP | other *** search
/ Collection of Education / collectionofeducationcarat1997.iso / COMPUSCI / TOT11.ZIP / TOTDOC11.ZIP / CHAPT20.TXT < prev    next >
Text File  |  1991-02-11  |  35KB  |  799 lines
  1.                                                                        Extending
  2.                                                                            Input
  3.                                                                            Field
  4.                                                                            Types
  5.  
  6.  
  7.  
  8.          "Stay humble. Always answer the phone - no matter who else is in the
  9.          car."
  10.  
  11.                                                                      Jack Lemmon
  12.  
  13.  
  14.          One of the most used elements of the Toolkit is the full screen input
  15.          facility. If the Toolkit field types do not meet your exact needs, you
  16.          can create your own custom field types. This chapter explains how.
  17.  
  18.  
  19. The Input Object Hierarchy
  20.          The objects FormOBJ and WinFormOBJ are used to manage and control full
  21.          screen input. You may recall that the method AddItem is used to add
  22.          individual input fields to the form. AddItem accepts any of the input
  23.          fields shown in the TOTIO Object Hierarchy on page 11.5. As the diagram
  24.          illustrates, all IO objects are descended from the root object Base-
  25.          IOOBJ. If you want to create new input field objects which can be
  26.          managed by the form objects, the new objects must be descended from
  27.          BaseIOOBJ, or any object descended from BaseIOOBJ.
  28.  
  29.          The BaseIOOBJ object includes the following data and methods, which are
  30.          inherited by all descendant objects:
  31.          ItemIOOBJ = object
  32.             vBoundary: tCoords;
  33.             vHotKey: word;
  34.             vID: word;
  35.             vActive: boolean;
  36.             {methods ...}
  37.             constructor Init;
  38.             procedure   SetActiveStatus(Selectable:boolean);
  39.             function    Active:boolean;
  40.             function    GetHotKey: word;
  41.             procedure   SetHotkey(HK:word);
  42.             function    GetID: word;
  43.             procedure   SetID(ID:word);
  44.             function    Visible: boolean;                        VIRTUAL;
  45.             procedure   Display(Status:tStatus);                 VIRTUAL;
  46.             function    Select(K:word; X,Y:byte):tAction;        VIRTUAL;
  47.             function    ProcessKey(InKey:word;X,Y:byte):tAction; VIRTUAL;
  48.             function    Suspend:boolean;                         VIRTUAL;
  49.             destructor  Done;                                    VIRTUAL;
  50.          end; {ItemIOOBJ}
  51.  
  52.          Note: the BaseIOOBJ also includes signal-related methods. These are
  53.          discussed in a later section.
  54.  
  55. 20-2                                                       Extending the Toolkit
  56. --------------------------------------------------------------------------------
  57.  
  58.          The vBoundary variable identifies the (X1,Y1) and (X2,Y2) coordinates
  59.          of the field. When the user clicks the left mouse button during full-
  60.          form input, the form object scans the list of active input objects and
  61.          moves the user to the input object with coordinates corresponding to
  62.          the mouse cursor position. Any descendant field should therefore update
  63.          the vBoundary variable to indicate the physical location of the field.
  64.          The other three BaseIOOBJ variables identify the field's hotkey, ID and
  65.          whether the field is active or selectable. These variables are managed
  66.          by the BaseIOOBJ methods SetActiveStatus, Active, GetHotkey, SetHotkey,
  67.          SetID and GetID. All these methods are suitable for any field type, and
  68.          should not need modification in descendant objects. Just inherit them
  69.          and use them!
  70.  
  71.          The virtual methods, highlighted in bold, are specific to each descen-
  72.          dant object. As a minimum, any descendant objects should redefine these
  73.          bold methods -- they are the main methods called by the form object
  74.          during full-screen input.
  75.          Apart from special hotkeys and navigation control keys, all the user
  76.          input fields are visible. That is, the user can see them. As the TOTIO
  77.          Hierarchy Diagram illustrates, all visible fields are descended from
  78.          VisibleIOOBJ, which is, in turn, descended from BaseIOOBJ. In addition
  79.          to the BaseIOOBJ objects just discussed, the VisibleIOOBJ objects
  80.          inherit the following methods:
  81.  
  82.            procedure   SetLabel(Lbl:string);
  83.            procedure   SetMessage(X,Y:byte; Msg:string);
  84.            procedure   WriteMessage;
  85.            procedure   WriteLabel(Status:tStatus);               VIRTUAL;
  86.          As their names suggest, these methods are used to set and display
  87.          labels and messages. Labels are displayed to the immediate left of a
  88.          field and act as a field title. A message is the field's descriptive
  89.          text which is displayed when the user moves to the field. Under normal
  90.          circumstances you will not need to modify these methods. They are
  91.          appropriate to any field type.
  92.  
  93.  
  94.  
  95. Creating New Field Types
  96.          When you want to create a new field object, you must decide which
  97.          existing field object has the properties most closely resembling the
  98.          new field type you want to create. For example, if the field includes
  99.          data input, then you would probably create a descendant of CharIOOBJ.
  100.          However, if the field has multiple lines (like a radio button or list),
  101.          then the new object would best be a descendant of MultiLineIOOBJ. If
  102.          none of the existing fields come anywhere close, create a descendant
  103.          from VisibleIOOBJ.
  104.  
  105.  
  106.  
  107. Extending Input Field Types                                                 20-3
  108. --------------------------------------------------------------------------------
  109.  
  110.          To illustrate the principles, a new boolean object will be created.
  111.          This object will display two different options, e.g. Yes or No, True or
  112.          False, Live or Die, etc. The field will display one of the options, and
  113.          when the user presses the space bar or clicks the mouse, the field will
  114.          flip to the other option.
  115.  
  116.          Since the boolean object does not process individual character input,
  117.          and does not occupy multiple lines, the best object to descend from is
  118.          VisibleIOOBJ. The following methods are inherited from VisibleIOOBJ and
  119.          do not need to be modified:
  120.             procedure   SetActiveStatus(Selectable:boolean);
  121.             function    Active:boolean;
  122.             function    GetHotKey: word;
  123.             procedure   SetHotkey(HK:word);
  124.             function    GetID: word;
  125.             procedure   SetID(ID:word);
  126.             procedure   SetLabel(Lbl:string);
  127.             procedure   SetMessage(X,Y:byte; Msg:string);
  128.             procedure   WriteMessage;
  129.             procedure   WriteLabel(Status:tStatus);              VIRTUAL;
  130.             function    Visible: boolean;                        VIRTUAL;
  131.  
  132.          As well as replacing Init and Done, the primary inherited methods which
  133.          need to be over-written are Display, Select, Processkey and Suspend.
  134.          These four methods are called by the form object during full screen
  135.          input. Additionally, if you want the new boolean object to function
  136.          stand-alone, i.e. without being part of a form, an Activate method
  137.          should be added. Activate will display the field and process user input
  138.          until [KEYCAP] or [KEYCAP] is pressed.
  139.          In keeping with the Toolkit style, SetValue and GetValue methods should
  140.          also be added. These methods are used to set the object's default
  141.          value, i.e. which option to display when the field is activated, and to
  142.          get the user-selected value after input is complete.
  143.  
  144.          The new boolean object will need to include three data variables: the
  145.          two strings that represent the true and false settings, and a boolean
  146.          to record the object's actual value.
  147.          After all the methods and data have been included, the definition of
  148.          the