home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 January / macformat-020.iso / Shareware City / Developers / apps.to.go / DTS.Lib / =Using CtlHandler.c < prev    next >
Encoding:
Text File  |  1994-05-04  |  5.1 KB  |  105 lines  |  [TEXT/MPS ]
  1. ***** CtlHandler.c usage documentation *****/
  2.  
  3. Purpose:  To simplify and standardize control handling within a window.
  4.  
  5.  
  6. This code implements the new 7.0 human-interface standards for both
  7. TextEdit and List controls.  These standards include the following features:
  8.  
  9. 1) Tabbing between TextEdit and List controls within a window.
  10. 2) Displaying what item is active.  The active TextEdit item is indicated
  11.    by either a blinking caret, or a selection range.
  12. 3) List positioning via the keyboard.  Entries on the keyboard automatically
  13.    select and display the closest List item.  Also, the up and down arrows
  14.    scroll through the list.
  15. 4) Document window scrollbars are handled.
  16. 5) Balloon help for window contents is handled (when called with a NULL event).
  17.  
  18.  
  19. The main call for handling the control events is:
  20.  
  21. short    IsCtlEvent(WindowPtr window, EventRecord *event, ControlHandle *retCtl, short *retAction);
  22.  
  23. This call handles the following:
  24.     1) Document scrolling.
  25.     2) TextEdit control events.
  26.     3) List control events.
  27.     4) Tabbing (and shirt-tabbing) between TextEdit and list controls.
  28.     5) Displaying the selected TextEdit or List control.
  29.     6) Buttons.
  30.     7) Radio buttons.
  31.     8) Check boxes.
  32.     9) Popups and other controls.
  33.    10) Balloon help for controls.
  34.  
  35. The document content is scrolled automatically.  The updateRgn is set to include the
  36. area scrolled into view and the window update procedure is automatically called.
  37.  
  38. TextEdit and List control events are completely handled.  Since the controls are just
  39. containers for TERecords or ListRecords, all other access is up to the application.
  40.  
  41. Simple buttons are simply tracked.
  42.  
  43. Radio buttons are updated to reflect the new selection.  Radio buttons are handled as
  44. families.  The refCon field holds the family number.  For any given family, there can
  45. only be one selected radio button.  When a new one is clicked on, the old selected
  46. radio button is deselected automatically.
  47.  
  48. Check boxes are simply toggled on and off, as there is no family relationship between
  49. checkboxes.
  50.  
  51. Popups are simply tracked.  To determine what the popup choice is, the popup control
  52. value will have to be retreived.
  53.  
  54. The return value of IsCtlEvent is non-zero if the event was handled.  The values are
  55. as follows:
  56.  
  57. 0x8000:                IsCtlEvent() scrolled the document.  The constant kScrollEvent is defined as
  58.                     0x8000 for this purpose.
  59. 0:                    IsCtlEvent didn't handle the event.
  60. any other value:    The control number of the control that handled the event.  Remember that
  61.                     a TextEdit control may actually consist of up to 3 controls.  There is the
  62.                     main container control for the TERecord.  There may also be 1 or 2 scrollbar
  63.                     controls that are related to the TERecord.  The control number reflects which
  64.                     control was hit.  This allows determination as to whether or not the scrollbar
  65.                     was hit.
  66.                     For TextEdit and list controls, even if a related scrollbar was hit, the
  67.                     control handle returned is the handle for the TextEdit control.
  68.  
  69. Just because a control number was returned doesn't mean that a control handle was returned.
  70. If an inactive scrollbar is clicked on, then FindControl() returns nil, instead of the
  71. control handle (really).  The control that is returned is what FindControl returns, and
  72. therefore it is possibly nil.
  73.  
  74. For TextEdit and List controls, IsCtlEvent simply calls CTEClick(), CTEKey(), CLClick() or
  75. CLKey().  The value returned as the action depends on which function was called.  The true/false
  76. returned by these functions as to whether or not the control handled the event is expanded to
  77. be the control number.  If false is returned by any of these functions, then IsCtlEvent()
  78. returns 0 for the control number.
  79.  
  80. IsCtlEvent() has no way of determining if you are actually using TextEdit or List controls.
  81. Since it has to make function calls service these controls, code may get linked into your
  82. application that you don't need.  To prevent this, IsCtlEvent() calls the appropriate
  83. functions by function pointer.  The default functions are just stub functions that return
  84. appropriate results as if there were no such controls.  This allows IsCtlEvent() to handle
  85. the case where these controls aren't used without linking in a bunch of code.
  86.  
  87. So what about the case where you DO want to use these controls?  To create one of these
  88. controls, you have to call either CTENew() or CLNew(), for TextEdit and List controls,
  89. respectively.  (Or, if you are using the AppsToGo program editor, you simply create them
  90. in a fashion similar to ResEdit.)
  91.  
  92. When CTENew() is called, it calls CTEInitialize().  CTEInitialize() replaces all
  93. of the stub function procedure pointers with pointers to the actual functions.
  94. If you call CTENew(), then CTENew() will get linked in.  Since CTENew() calls
  95. CTEInitialize(), CTEInitialize() will get linked in.  Since it references the actual
  96. code, the actual code will get linked in.  This allows you to not have to worry about
  97. specific implementations linking in too much code.  If you call it, it will link.  The
  98. above process is also done for List controls.
  99.  
  100.  
  101.  
  102. The remaining functions aren't nearly as interesting, but they can prove to be useful.
  103. See the file CtlHandler.h for a list and description of these functions.
  104.  
  105.