home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1995 January / macformat-020.iso / Shareware City / Developers / apps.to.go / DTS.Lib / =Using ListControl.c < prev    next >
Encoding:
Text File  |  1994-05-04  |  4.4 KB  |  106 lines  |  [TEXT/MPS ]
  1. ***** ListControl.c usage documentation *****/
  2.  
  3. Purpose:  To simplify List handling within a window.
  4.  
  5. Implementing a List control does the following:
  6.  
  7. 1) Makes using lists in a non-dialog window easier.
  8. 2) The List is automatically associated with the window, since
  9.    it is in the window's control list.
  10. 4) Updating of the List is much simpler, since all that is
  11.    necessary is to draw the control (or all the window's controls with
  12.    a DrawControls call).
  13. 5) What isn't handled automatically by tracking the control can be handled
  14.    with a direct call.  There are simple calls to handle List events.
  15. 6) When you close the window, the ListRecord is disposed of.
  16.    (This automatic disposal can easily be defeated.)
  17.  
  18.  
  19.  
  20. To create a List control, you only need a single call.  For example:
  21.  
  22.     list = CLNew(rViewCtl,            /* Resource ID of view control for List control. */
  23.                  true,                /* Initially visible.                             */
  24.                  &viewRect,            /* View rect of list.                             */
  25.                  numRows,            /* Number of rows to create List with.             */
  26.                  numCols,            /* Number of columns to create List with.         */
  27.                  cellHeight,
  28.                  cellWidth,
  29.                  theLProc,            /* Custom List procedure resource ID.             */
  30.                  window,            /* Window to hold List control.                     */
  31.                  clHScroll | blBrdr | clActive);    /* Horizontal scrollbar, active List. */
  32.  
  33. The various choices for the List control are defined as follows:
  34.  
  35. #define clHScroll        0x0002
  36. #define clVScroll        0x0008
  37. #define clActive        0x0020
  38. #define clShowActive    0x0040
  39. #define clKeyPos        0x0080
  40. #define clTwoStep        0x0100
  41. #define clHasGrow        0x0200
  42. #define clDrawIt        0x8000
  43.  
  44. clHScroll:            Create a list that includes a horizontal scrollbar.
  45. clVScroll:            Create a list that includes a vertical scrollbar.
  46. clActive:            Make this the initially active control for the window.
  47. clShowActive:        When the control is active, show that it is by drawing a selection
  48.                     border around the control.  This is the new 7.0 human-interface
  49.                     method of showing which control is active.  (It also works in system 6.)
  50. clKeyPos:            Allow list positioning, based on user keypresses.  This assumes that
  51.                     the list is alphabetized so that key presses for location make sense.
  52.                     If typing by the user is fast enough, multiple characters will be
  53.                     used for the positioning.
  54. clTwoStep:            When using IsCtlEvent(), you may want the initial click on a List
  55.                     control to just select the control, or you may wish the click to start
  56.                     tracking in addition to selecting the control.  The tracking is
  57.                     considered the second step.  By setting this bit, you indicate that you
  58.                     want control selection and item selection to be a 2-step process.
  59.                     Setting this bit means that it will take 2 separate clicks by the
  60.                     user to select an item in the list if the list is inactive.
  61. clHasGrow:            This makes sure that there is space for the growIcon if the list
  62.                     has a scrollbar.  If the list occupies an entire window, then if there
  63.                     is only one scrollbar, the scrollbar has to be shrunk to make room
  64.                     for the growIcon.  The List Manager supposedly has this ability, but
  65.                     it doesn't work.  The List control manages it correctly.
  66. clDrawIt:            This is a List manager flag that is needed for the LNew() call.
  67.  
  68.  
  69. If the CLNew call succeeds, you then have a List control in your
  70. window.  It will be automatically disposed of when you close the window.
  71. If you don't want this to happen, then you can detach it from the
  72. view control which owns it.  To do this, you would to the following:
  73.  
  74.     viewCtl = CLViewFromList(theListHndl);
  75.     if (viewCtl) SetCRefCon(viewCtl, nil);
  76.  
  77. The view control keeps a reference to the List record in the refCon.
  78. If the refCon is cleared, then the view control does nothing.  So, all that
  79. is needed to detach a List record from a view control is to set the
  80. view control's refCon nil.  Now if you close the window, you will still
  81. have the List record.
  82.  
  83.  
  84. To remove a List control completely from a window, just dispose of the view
  85. control that holds the List record.  To do this, just do something like the below:
  86.  
  87.     DisposeControl(CLViewFromList(theListHndl));
  88.  
  89. This completely disposes of the List control.
  90.  
  91.  
  92. Events for the List record are handled nearly automatically.  Just make the
  93. following call:
  94.  
  95.     CLEvent(window, eventPtr, &action);
  96.  
  97. If the event was handled, true is returned.  If the event is false, then the
  98. event doesn't belong to a List control, and further processing of the event
  99. should be done.
  100.  
  101.  
  102.  
  103. For a complete list of the List control functions and their descriptions,
  104. see the file ListControl.h.
  105.  
  106.