home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / C / Snippets / Stuart's Tech Notes / Pop Up Menu CDEF / Pop Up.note < prev   
Encoding:
Text File  |  1995-06-11  |  8.7 KB  |  190 lines  |  [TEXT/KAHL]
  1. // Pop Up menu CDEF
  2. // (C) 1990-1995 Stuart Cheshire <cheshire@cs.stanford.edu>
  3. // Written after endless frustration with the one by Chris Faigle which
  4. // used to crash all the time, to whom some credit for inspiration should go.
  5.  
  6. INTRODUCTION
  7.  
  8. To use Stuart's Pop Up menu CDEF you need to
  9. 1. Paste the CDEF resource (about 3K) into your application's resource file
  10. 2. Create the menus you want to pop up, just like normal menu bar menus
  11. 3. Add Pop Up Menu Control items (CNTLs) to your dialogs
  12.  
  13. In use, the popup menu controls behave just like any other control. They
  14. automatically respond to mouse clicks, they have maximum and minimum
  15. values just like a scroll bar control, and they have a current value which
  16. your program can read with GetCtlValue or change with SetCtlValue. The
  17. minimum value of a popup menu control is 1, and the maximum value is the
  18. number of items in the menu.
  19.  
  20. There are three components to a popup menu control: The title (name) of
  21. the control, the menu that will pop up when clicked upon, and the little
  22. piece of code (the CDEF) that makes it all work.
  23.  
  24. The way you tell the Macintosh these three pieces of information is with
  25. a CNTL resource. Having created a CNTL resource (described below) which
  26. specifies the control's title, MENU, CDEF, and other sundry formatting
  27. information about how it should appear on the screen, you can then add
  28. "Control" items to your dialogs just as you would for scroll bars and
  29. other controls. When you create the "Control" item in ResEdit, enter
  30. the resource id of your CNTL resource that describes that control. Each
  31. different control in your dialog should have its own CNTL describing it,
  32. but they may share the same menus, if appropriate.
  33.  
  34. Logically, the layout of the information looks like this:
  35.  
  36.   DLOG ---> DITL
  37.             Button                ---> CDEF
  38.             Check box            /
  39.             Control -------> CNTL ---> MENU
  40.             Radio button         \
  41.             Radio button          ---> Title & other layout information
  42.             etc.
  43.  
  44. A popup menu control is displayed as two components, the title part, on
  45. the left, and the pop up menu part, on the right.
  46.                             ______________________
  47.             Control Title   | Selected Menu Item |
  48.                             ~~~~~~~~~~~~~~~~~~~~~~
  49. When these instructions talk about the width of the title, they are
  50. referring to the part on the left. When they talk about the width of
  51. the menu, they are referring to the part on the right. When they talk
  52. about the width of the control, then are referring to the total width
  53. of both parts.
  54.  
  55. CREATING THE CNTL
  56.  
  57. The fields of the CNTL resource are interpreted in the following (slightly
  58. non-standard) way:
  59.  
  60. BoundsRect: The overall size of the pop up control (both the title and the
  61.          menu). Ususally, top = 0, left = 0, bottom = 16, right = the width
  62. Value:   Initial default menu selection (ie 1 for the first menu item).
  63. Visible: TRUE or FALSE, as you wish
  64. Max:     Width of the title of the pop up menu. (Use zero for automatic size.)
  65. Min:     Resource ID of the menu to use
  66. ProcID:  CDEF resource to use. Formula is Resource ID * 16 + variation code
  67.          If this CDEF resource id is 2, ProcID should be 32 + variation code
  68. RefCon:  Resource type (optional, see below)
  69. Title:   The title string to display for this control (optional).
  70.          Note: the menu's own title is ignored. This means that you can
  71.          make a single menu containing items "slow", "medium" and "fast",
  72.          and then use that menu in multiple places in the same dialog,
  73.          with different control titles for each one, like "ship speed",
  74.          "bullet speed", "enemy speed" etc.
  75.  
  76. Variation codes:
  77. Bit 0 set if you want the menu width stretched so that the menu goes all
  78.       the way to the right edge of the control rectangle
  79. Bit 1 set for "New style" (with little arrow pointing downwards)
  80. Bit 2 set to build the menu dynamically by calling AddResMenu(RefCon)
  81. Bit 3 set to right-justify the title (only applies if contrlMax is non-zero)
  82.  
  83. SPECIAL FEATURES
  84.  
  85. * Can automatically build a pop up resource menu -- set bit 2 of the variation
  86. code and set RefCon to the resource type. Eg. set RefCon to the value 'FONT'
  87. (464F4E54 hex or 1179602516 decimal) to build a font menu.
  88.  
  89. * If you specify a contrlMin of zero, instead of reading a menu resource,
  90. the CDEF will let you create a menu programatically at runtime and then
  91. put its handle in the Control RefCon. (This is of dubious functionality,
  92. but Chris Faigle's original CDEF supported it, so I did too.)
  93.  
  94. * After reading the initialization parameters out of the Min and Max fields,
  95. they are set to 0 and the number of items in the menu, respectively. This
  96. means that SetCtlValue, GetCtlMin, and GetCtlMax calls in your program
  97. will work correctly.
  98.  
  99. * The CDEF correctly responds to calcCntlRgn calls etc. which means that
  100. you get an accurate preview when constructing your dialogs in ResEdit.
  101.  
  102. * Pop up control title is automatically highlighted when the menu is
  103. clicked on. No need to do this yourself in your program.
  104.  
  105. * Multiple CNTLs can reference the same MENU. For example, you might
  106. want to do this if your program has a dialog with three options, each
  107. of which offer the user the choice of "Small, medium, large". With most
  108. other Pop Up Menu CDEFs, you have to create three identical menus because
  109. otherwise they will crash when they dispose of the same menu three times.
  110. Since the same MENU resource can be used in multiple places, the title
  111. defined with the menu (if any) is not displayed. The title which is
  112. displayed is the control title defined in the CNTL resource.
  113.  
  114. * Supports both "command" and "option" oriented pop ups.
  115. "Option" oriented pop ups (fonts, sizes, baud rates etc.) are basically
  116. just space-saving replacements for radio button groups, so only one item
  117. from the menu may be selected at any one time, and what is displayed in
  118. the drop-shadow box is whatever the currently selected item is.
  119. "Command" oriented pop ups are menus where selecting an item from them
  120. performs some command instead of just changing the control's value.
  121. For these kind of pop ups where the control does not have any particular
  122. single "value", use SetCtlValue(theControl, 0) and the CDEF will display
  123. the menu's title in the box instead of any of the items. This is not a
  124. good way to use pop-up menus, but may be useful in certain restricted
  125. circumstances where you are otherwise contstrained and cannot make a
  126. nicer user interface. For instance, Intercon's NFS/Share software uses
  127. this technique in order to place a popup menu in the Chooser from which
  128. the user can select commands "Add host", "Delete host", "Edit host" etc.
  129.  
  130. * Disabled pop ups (HiliteControl(theControl, 255)) are correctly drawn
  131. greyed out.
  132.  
  133. * Allows alignment of columns of popup menus, including right-justification
  134. of titles if desired. For example:
  135.  
  136.   DEFAULT STYLE, "Max" is zero, for automatic sizing of titles
  137.            _________
  138. Tank Icons | Small |
  139.            ~~~~~~~~~
  140.               __________
  141. Pillbox Icons | Medium |
  142.               ~~~~~~~~~~
  143.                      ______________
  144. Refueling Base Icons | Super Huge |
  145.                      ~~~~~~~~~~~~~~
  146.  
  147.   FIXED WIDTH TITLE STYLE, "Max" is set by hand to width of widest title
  148.                      _________
  149. Tank Icons           | Small |
  150.                      ~~~~~~~~~
  151.                      __________
  152. Pillbox Icons        | Medium |
  153.                      ~~~~~~~~~~
  154.                      ______________
  155. Refueling Base Icons | Super Huge |
  156.                      ~~~~~~~~~~~~~~
  157.  
  158.   RIGHT-JUSTIFIED FIXED WIDTH TITLE STYLE,
  159.   "Max" is set by hand to width of widest title and
  160.   Bit 3 (right-justify title) of variation code is set
  161.                      _________
  162.           Tank Icons | Small |
  163.                      ~~~~~~~~~
  164.                      __________
  165.        Pillbox Icons | Medium |
  166.                      ~~~~~~~~~~
  167.                      ______________
  168. Refueling Base Icons | Super Huge |
  169.                      ~~~~~~~~~~~~~~
  170.  
  171. * Allows fixed width menus. Similarly to the right justification of titles
  172. above, if you have a column of different sized menus, setting bit 2 of the
  173. variation code tells the CDEF to extend the width of the menu up to the
  174. right edge of the control's bounding box so that all the menus appear
  175. pleasingly aligned on the screen. For example:
  176.  
  177.   RIGHT-JUSTIFIED FIXED WIDTH TITLE STYLE WITH FIXED WIDTH MENU,
  178.   "Max" is set by hand,
  179.   Bit 3 (right-justify title) and
  180.   Bit 0 (fixed-width menu) of variation code are set
  181.                      _______________
  182.           Tank Icons | Small       |
  183.                      ~~~~~~~~~~~~~~~
  184.                      _______________
  185.        Pillbox Icons | Medium      |
  186.                      ~~~~~~~~~~~~~~~
  187.                      _______________
  188. Refueling Base Icons | Super Huge  |
  189.                      ~~~~~~~~~~~~~~~
  190.