home *** CD-ROM | disk | FTP | other *** search
/ Power-Programmierung / CD2.mdf / c / library / dos / tvision / tfldex / tfield.doc < prev    next >
Encoding:
Text File  |  1992-01-24  |  12.5 KB  |  319 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9. TField                                                                  TFIELD.H
  10. --------------------------------------------------------------------------------
  11.     _________
  12.     | TView |
  13.     ---------
  14.         I
  15.     ____I_____
  16.     | TField |
  17.     ----------
  18.  
  19. A TField object provides a basic input line string editor. It handles keyboard
  20. input and mouse clicks and drags for block marking and a variety of line editing
  21. functions (see TField handleEvent). The selected text is deleted and then
  22. replaced by the first text input. 
  23.  
  24. Optional scrolling is provided if maxLen is greater than the x dimension
  25. (size.x).  If scrollable is True then horizontal scrolling is supported and
  26. indicated by left and right arrows.  While the scrollable variable can be
  27. directly manipulated, the function setScroll has been provided.  setScroll
  28. handles the task of automatically calling drawView when the scroll state
  29. changes.  If the programmer wants to change the scroll state directly, TField's
  30. drawView function should be called after doing so.
  31.  
  32. Text justification is supported via the justification variable.  justification
  33. can currently be either jLeft (default) or jRight.  If jRight justification is
  34. selected, any data-entry occurs from right to left (calculator style.) 
  35. setJustification handles the task of automatically calling drawView when the
  36. justification value changes.  If the programmer wants to change the
  37. justification value directly, TField's drawView function should be called after
  38. doing so.
  39.  
  40. The getData and setData member functions are available for writing and reading
  41. data strings (referenced via the data string data member) into the given record.
  42. TField::setState simplifies the redrawing of the view with appropriate colors
  43. when the state changes from or to sfActive and sfSelected.
  44.  
  45. TField can be extended to handle data types other than strings. To do so, you'll
  46. generally add additional data members and then override the constructors and the
  47. store, valid, dataSize, getData, and setData member functions. For example, to
  48. define a numeric input line, you might want it to contain minimum and maximum
  49. allowable values which will be tested by the valid function. These minimum and
  50. maximum data members would be loaded (with the load constructor) and stored on
  51. the stream.  valid would be modified to make sure the value was numeric and
  52. within range.  dataSize would be modified to include the size of the new range
  53. data members (probably sizeof(long) for each).  Oddly enough, in this example it
  54. would not be necessary to add a data member to store the numeric value itself. 
  55. It could be stored as a string value (which is already managed by TField) and
  56. converted from string to numeric value and back by getData and setData,
  57. respectively. 
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.               Data
  66.            members
  67.                                                                                 
  68.             curPos   int curPos;
  69.  
  70.                      Index to insertion point (that is, to the current cursor
  71.                      position).
  72.  
  73.                      See also: TField::selectAll
  74.  
  75.               data   char *data; 
  76.  
  77.                      The string containing the edited information. 
  78.  
  79.           firstPos   int firstPos;
  80.  
  81.                      Index to the first displayed character.
  82.  
  83.                      See also: TField::selectAll
  84.  
  85.      justification   int justification;
  86.  
  87.                      Holds the desired justification value for the field. 
  88.                      Current options are jLeft or jRight.  Default is jRight.
  89.  
  90.                      See also: TField::setJustification
  91.  
  92.             maxLen   int maxLen;
  93.  
  94.                      Maximum length allowed for string to grow (excluding the
  95.                      final 0).
  96.  
  97.                      See also: TField::dataSize
  98.  
  99.        scrollState   Boolean scrollState;
  100.  
  101.                      Flag to indicate whether scrolling is enabled or disabled. 
  102.                      Default is True (enabled).
  103.  
  104.                      See also: TField::setScroll
  105.  
  106.             selEnd   int selEnd;
  107.  
  108.                      Index to the end of the selection area (that is, to the
  109.                      last character block marked).
  110.  
  111.                      See also: TField::selectAll
  112.  
  113.           selStart   int selStart;
  114.  
  115.                      Index to the beginning of the selection area (that is, to
  116.                      the first character block marked). 
  117.  
  118.                      See also: TField::selectAll
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.             Member
  128.          functions
  129.  
  130.        constructor   TField(const TRect& bounds, int aMaxLen);
  131.  
  132.                      Creates an input box control with the given values by
  133.                      calling TView(bounds). state is then set to sfCursorVis,
  134.                      options is set to (ofSelectable | ofFirstClick), and maxLen
  135.                      is set to aMaxLen. Memory is allocated and cleared for
  136.                      aMaxlen + 1 bytes and the data data member set to point at
  137.                      this allocation.  justification is initialized to jLeft and
  138.                      scrollable is initialized to True.
  139.  
  140.        constructor   TField( StreamableInit streamableInit);           protected
  141.  
  142.                      Each streamable class needs a "builder" to allocate the
  143.                      correct memory for its objects together with the
  144.                      initialized vtable pointers. This is achieved by calling
  145.                      this constructor with an argument of type StreamableInit.
  146.                      Refer also to Chapter 8. 
  147.  
  148.                      See also: TView::TView, sfCursorVis, ofSelectable,
  149.                      ofFirstClick
  150.  
  151.         destructor   ~TField();
  152.  
  153.                      Deletes the data memory allocation, then calls ~TView to
  154.                      destroy the TField object. 
  155.  
  156.                      See also: ~TView
  157.  
  158.              build   static TStreamable *build();
  159.  
  160.                      Called to create an object in certain stream-reading
  161.                      situations.
  162.  
  163.                      See also: TStreamableClass, ipstream::readData
  164.  
  165.           dataSize   virtual ushort dataSize ();
  166.  
  167.                      Returns the size of the record for TField::getData and
  168.                      TField:: setData calls. By default, it returns maxLen + 1.
  169.                      Override this member function if you define descendants to
  170.                      handle other data types. 
  171.  
  172.                      See also: TField::getData, TField::setData 
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.               draw   virtual void draw();
  181.  
  182.                      Draws the input box and its data. The box is drawn with the
  183.                      appropriate colors depending on whether the box is
  184.                      sfFocused (that is, whether the box view owns the cursor),
  185.                      and arrows are drawn if the input string exceeds the size
  186.                      of the view (in either or both directions). Any selected
  187.                      (blockmarked) characters are drawn with the appropriate
  188.                      palette.
  189.  
  190.            getData   vlrtual void getData (void *rec);
  191.  
  192.                      Writes the number of bytes (obtained from a call to
  193.                      dataSize) from the data string to the array given by rec.
  194.                      Used with setData for a variety of applications; for
  195.                      example, temporary storage, or passing on the input string
  196.                      to other views. Override getData if you define TField
  197.                      descendants to handle non-string data types. You can also
  198.                      use getData to convert from a string to other data types
  199.                      after editing by TField. 
  200.  
  201.                      See also: TField::dataSize, TField::setData
  202.  
  203.         getPalette   vlrtual TPalette& getPalette() const;
  204.  
  205.                      Returns the default palette string, cplnputLine,
  206.                      "\x13\x13\x14\x15".
  207.  
  208.        handleEvent   void handleEvent(TEvent& event);
  209.  
  210.                      Calls TView::handleEvent, then handles all mouse and
  211.                      keyboard events if the input box is selected. This member
  212.                      function implements the standard editing capability of the
  213.                      input box.
  214.  
  215.                      Editing features include: block marking with mouse click
  216.                      and drag; block deletion; insert or overwrite control with
  217.                      automatic cursor shape change; automatic and manual
  218.                      scrolling as required (depending on relative sizes of the
  219.                      data string and size.x); manual horizontal scrolling via
  220.                      mouse clicks on the arrow icons; manual cursor movement by
  221.                      arrow, Home, and End keys (and their standard control-key
  222.                      equivalents); character and block deletion with Del and
  223.                      Ctrl-G. The view is redrawn as required and the TField data
  224.                      members are adjusted appropriately. 
  225.  
  226.                      See also: sfCursorlns, TView::handleEvent,
  227.                      TField::selectAll
  228.  
  229.               read   virtual void *read( ipstream& is);
  230.  
  231.                      Reads from the input stream is.
  232.  
  233.                      See also: TStreamableClass, TStreamable, ipstream 
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.          selectAll   void selectAll (Boolean enable);
  242.  
  243.                      Sets curPos, firstPos, and selStart to 0. If enable is set
  244.                      to True, selEnd is set to the length of the data string,
  245.                      thereby selecting the whole input line; if enable is set to
  246.                      False, selEnd is set to 0, thereby deselecting the whole
  247.                      line. Finally, the view is redrawn by calling drawView.
  248.  
  249.                      See also: TView::drawView
  250.  
  251.            setData   virtual void setData (void *rec);
  252.  
  253.                      By default, copies the number of bytes (as returned by
  254.                      dataSize) from the rec array to the data string, and then
  255.                      calls selectAll(True). This zeros curPos, firstPos, and
  256.                      selStart. Finally, drawView is called to redraw the input
  257.                      box.
  258.  
  259.                      Override setData if you define descendants to handle
  260.                      non-string data types. You also use setData to convert
  261.                      other data types to a string for editing by TField.
  262.  
  263.                      See also: TField::dataSize, TField::getData,
  264.                      TField::selectAll
  265.  
  266.   setJustification   virtual void setJustification ( int jValue );
  267.  
  268.                      Called to change the justification value.  Currently checks
  269.                      if jValue == jRight, if so it sets jValue to jRight and
  270.                      calls drawView, otherwise it sets jValue to jLeft and calls
  271.                      drawView.
  272.  
  273.                      See also: jRight, jLeft, TField::justification
  274.  
  275.          setScroll   virtual void setScroll (Boolean enable);
  276.  
  277.                      Called to enable/disable scrolling.  Sets scrollState to
  278.                      enable then calls drawView.
  279.  
  280.                      See also: TField::scrollState
  281.  
  282.           setState   virtual void setState (ushort aState, Boolean enable);
  283.  
  284.                      Called when the input box needs redrawing (for example, if
  285.                      the palette is changed) following a change of state. Calls
  286.                      TView::setState to set or clear the view's state with the
  287.                      given aState bit(s). Then if aState is sfSelected (or
  288.                      sfActive and the input box is sfSelected),
  289.                      selectAll(enable) is called (which, in turn, calls
  290.                      drawView).
  291.  
  292.                      See also: TView::setState, TField::selectAll
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.              write   virtual void write( opstream& os);
  301.  
  302.                      Writes to the output stream os.
  303.  
  304.                      See also: TStreamableClass, TStreamable, opstream
  305.  
  306. Related functions Certain operator functions are related to TField but are not
  307. member functions; see page 232 for more information.
  308.  
  309. Palette
  310. TFields use the default palette, cpField, to map onto the 19th through 21st
  311. entries in the standard dialog palette.
  312.  
  313.              1     2     3     4
  314.          ===========================
  315. cpField  || x13 | x13 | x14 | x15 ||
  316.          ===========================
  317.    Passive---^     |     |     ^---Arrow
  318.    Active-----------     ----------Selected
  319.