home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / IMNITEM.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  21KB  |  379 lines
  1. #ifndef _IMNITEM_
  2.   #define _IMNITEM_
  3. /******************************************************************************
  4. * FILE NAME: imnitem.hpp                                                      *
  5. *                                                                             *
  6. * DESCRIPTION:                                                                *
  7. *    Declaration of the class:                                                *
  8. *      IMenuItem - is a data class used to represent a menu item.             *
  9. *                                                                             *
  10. * COPYRIGHT:                                                                  *
  11. *   Licensed Materials - Property of IBM                                      *
  12. *   (c) Copyright IBM Corporation 1992, 1993                                  *
  13. *   US Government Users Restricted Rights - Use duplication                   *
  14. *   or disclosure restricted by GSA ADP Schedule Contract                     *
  15. *   with IBM Corp.                                                            *
  16. *                                                                             *
  17. *******************************************************************************/
  18. #ifndef _IBASE_
  19.   #include <ibase.hpp>
  20. #endif
  21. #ifndef _IHANDLE_
  22.   #include <ihandle.hpp>
  23. #endif
  24. #ifndef _ISTRING_
  25.   #include <istring.hpp>
  26. #endif
  27. #ifndef _IBITFLAG_
  28.   #include <ibitflag.hpp>
  29. #endif
  30.  
  31. /*----------------------------------------------------------------------------*/
  32. /* Align classes on four byte boundary.                                       */
  33. /*----------------------------------------------------------------------------*/
  34. #pragma pack(4)
  35.  
  36. // Forward declarations for other classes
  37. class IResourceId;
  38. class IMenu;
  39. class ISubmenu;
  40.  
  41. class IMenuItem : public IBase {
  42. typedef IBase
  43.   Inherited;
  44. /******************************************************************************
  45. * The IMenuItem class is a data class used to present the menu item           *
  46. * structure.  This class provides style objects, attribute objects, and       *
  47. * functions to set and query the menu item.  These functions do not affect    *
  48. * the menu unless the IMenu add or set functions are invoked with the         *
  49. * instance of the menu item.                                                  *
  50. *                                                                             *
  51. * An IMenuItem can be constructed and added to the menu by using the IMenu or *
  52. * ISubmenu member functions.  You can also use the IMenu::menuItem function   *
  53. * to query an existing item in a menu, and subsequently change the item's     *
  54. * style and attribute, and reset the menu item.                               *
  55. *                                                                             *
  56. * NOTE: A menu item ID does not have to be unique.  However, if an operation  *
  57. *       such as IMenu::checked is invoked using the ID, the first menu item   *
  58. *       that has the ID will be acted upon.                                   *
  59. ******************************************************************************/
  60. public:
  61. /*-------------------------------- Styles --------------------------------------
  62. |  The following are the valid menu-item styles:                               |
  63. |                                                                              |
  64. |    classDefaultStyle  - This style is a static variable that is set to       |
  65. |                         noStyle.                                             |
  66. |    split              - The menu item starts in a new row or column.  This   |
  67. |                         style cannot be used with splitWithSeparator or      |
  68. |                         buttonSeparator.                                     |
  69. |    splitWithSeparator - The menu item starts in a new row or column with a   |
  70. |                         line drawn to separate it.  This style cannot be     |
  71. |                         used with split or buttonSeparator.                  |
  72. |    buttonSeparator    - A line is drawn to separate the menu item.  The      |
  73. |                         user cannot use cursor movement keys to get to it.   |
  74. |                         This style cannot be used with split or              |
  75. |                         splitWithSeparator.                                  |
  76. |    postSystemCommand  - The menu item generates a system command message     |
  77. |                         that can be handled by                               |
  78. |                         ICommandHandler::systemCommand.  This style cannot   |
  79. |                         be used with postHelp.                               |
  80. |    postHelp           - The menu item generates a help message that is       |
  81. |                         issued to the previous focus window.  Therefore,     |
  82. |                         the postHelp style works just like a Help push       |
  83. |                         button.  This style cannot be used with              |
  84. |                         postSystemCommand.                                   |
  85. |    unavailable        - Sets unavailable-state emphasis for a menu item.     |
  86. |    drawItem           - Allows applications to draw the menu item.           |
  87. |    separator          - Specifies that the menu item is a separator          |
  88. |    noStyle            - Specifies that no style applies to the menu item.    |
  89. |                                                                              |
  90. |  The following functions provide a means of getting and setting the default  |
  91. |  style for this class:                                                       |
  92. |                                                                              |
  93. |    defaultStyle    - Returns the current default style.  This is the same    |
  94. |                      as classDefaultStyle unless setDefaultStyle has been    |
  95. |                      called.                                                 |
  96. |    setDefaultStyle - Sets the default style for all subsequent menu items.   |
  97. ------------------------------------------------------------------------------*/
  98. INESTEDBITFLAGCLASSDEF0(Style, IMenuItem);
  99. static const Style
  100.   classDefaultStyle,
  101.  
  102.   split,                   //mutually exclusive
  103.   splitWithSeparator,
  104.   buttonSeparator,
  105.  
  106.   postSystemCommand,      //mutually exclusive
  107.   postHelp,
  108.  
  109.   separator,             // mutually exclusive
  110.   drawItem,
  111.  
  112.   unavailable,
  113.   noStyle;
  114.  
  115. static Style
  116.   defaultStyle ( );
  117.  
  118. static void
  119.   setDefaultStyle ( const Style &aStyle );
  120.  
  121. /*------------------------------ Attributes ------------------------------------
  122. |  The following are the valid menu item attributes.  All attributes are set   |
  123. |  independent of each other.                                                  |
  124. |                                                                              |
  125. |    classDefaultAttribute - This attribute is a static variable that is set   |
  126. |                            to noAttribute.                                   |
  127. |    noDismiss             - If a menu item in a submenu is chosen, the        |
  128. |                            submenu remains displayed.                        |
  129. |    framed                - Encloses the menu item in a box.                  |
  130. |    checked               - Displays a check mark to the left of the menu     |
  131. |                            item when it is selected.  The check mark is      |
  132. |                            removed when the item is de-selected.             |
  133. |    disabled              - Displays the menu item with unavailable-state     |
  134. |                            emphasis, which means it cannot be selected.      |
  135. |    highlighted           - Displays the menu item with selected-state        |
  136. |                            emphasis.                                         |
  137. |    noAttribute           - Specifies that no attribute applies to the menu   |
  138. |                            item.                                             |
  139. |                                                                              |
  140. | The following functions provide a means of getting and setting the default   |
  141. | attributes for this class:                                                   |
  142. |                                                                              |
  143. |   defaultAttribute    - Returns the current default attribute.  This is      |
  144. |                         the same as classDefaultAttribute unless             |
  145. |                         setDefaultAttribute has been called.                 |
  146. |   setDefaultAttribute - Sets the default attribute for all subsequent menu   |
  147. |                         items.                                               |
  148. ------------------------------------------------------------------------------*/
  149. INESTEDBITFLAGCLASSDEF0(Attribute, IMenuItem);
  150.  
  151. static const Attribute
  152.   classDefaultAttribute,
  153.   noDismiss,
  154.   framed,
  155.   checked,
  156.   disabled,
  157.   highlighted,
  158.   noAttribute;
  159.  
  160. static Attribute
  161.   defaultAttribute ( );
  162.  
  163. static void
  164.   setDefaultAttribute ( const Attribute &aAttribute );
  165.  
  166. /*----------------------- Constructors and Destructor --------------------------
  167. |  You can only construct an instance of this class by creating a default      |
  168. |  menu item.  This constructor creates an instance of IMenuItem with the      |
  169. |  specified styles and attributes.                                            |
  170. |                                                                              |
  171. |  In most cases you will need to perform at least one of the "set" functions  |
  172. |  on the menu item before it can be added to a menu.  For example, if you     |
  173. |  want a bit-map menu item, you would first construct the IMenuItem and then  |
  174. |  call one of the setBitmap functions to specify the bit map to be used for   |
  175. |  display purposes.                                                           |
  176. |                                                                              |
  177. |  After construction, IMenuItems that have the separator or drawItem styles   |
  178. |  can be added to a menu without having to call any of the "set" functions.   |
  179. ------------------------------------------------------------------------------*/
  180.   IMenuItem  ( unsigned long       itemId,
  181.                const Style         &style     = defaultStyle(),
  182.                const Attribute     &attribute = defaultAttribute());
  183.  
  184.   ~IMenuItem();
  185. /*---------------------------- Enumerations ------------------------------------
  186. | The following enumerations provide a means of setting the style of           |
  187. | instances of this class:                                                     |
  188. |   LayoutType  - This enumeration is used to define the placement and layout  |
  189. |                 of the menu item.  The valid values are:                     |
  190. |                   splitLayout              - Starts the menu item in a new   |
  191. |                                              row or column.                  |
  192. |                   splitWithSeparatorLayout - Starts the menu item in a new   |
  193. |                                              row or column with a line       |
  194. |                                              drawn to separate it.           |
  195. |                   buttonSeparatorLayout    - Separates the menu item and     |
  196. |                                              does not allow cursor movement  |
  197. |                                              to it.                          |
  198. |                   normalLayout             - Specifies that no style         |
  199. |                                              applies.                        |
  200. |                                                                              |
  201. |   CommandType - This enumeration is used to define the type of event to      |
  202. |                 generate when the menu item is selected.  The valid values   |
  203. |                 are:                                                         |
  204. |                   command       - Generates an ICommandHandler::command      |
  205. |                                   event.                                     |
  206. |                   systemCommand - Generates an                               |
  207. |                                   ICommandHandler::systemCommand event.      |
  208. |                   helpCommand   - Generates a help message.                  |
  209. ------------------------------------------------------------------------------*/
  210. enum LayoutType {
  211.   normalLayout,
  212.   splitLayout,
  213.   splitWithSeparatorLayout,
  214.   buttonSeparatorLayout
  215. };
  216.  
  217. enum CommandType {
  218.   command,
  219.   systemCommand,
  220.   helpCommand
  221. };
  222.  
  223. /*---------------------- Set/Change Style and Attribute ------------------------
  224. | The following functions can be used to set menu item styles:                 |
  225. |                                                                              |
  226. |   setLayout      - Defines the menu item placement and layout.               |
  227. |   setCommand     - Specifies what event to generate when the menu item is    |
  228. |                    selected.                                                 |
  229. |   setSeparator   - Makes the menu item a separator.                          |
  230. |   setSelectable  - Enables the menu item for selection.                      |
  231. |   setDrawItem    - Generates a draw item event to allow the application to   |
  232. |                    draw the menu item.                                       |
  233. |   setNoDismiss   - Forces the menu item to remain visible when selected.     |
  234. |   setFramed      - Draws a box to enclose the menu item.                     |
  235. |   setChecked     - Displays a check mark to the left of the menu item when   |
  236. |                    it is selected.  The check mark is removed when the item  |
  237. |                    is de-selected.                                           |
  238. |   setDisabled    - Displays the menu item with unavailable-state emphasis,   |
  239. |                    which means it cannot be selected.                        |
  240. |   setHighlighted - Displays the menu item with selected-state emphasis.      |
  241. ------------------------------------------------------------------------------*/
  242. IMenuItem
  243.   &setLayout      ( LayoutType  aValue ),
  244.   &setCommand     ( CommandType aValue ),
  245.   &setSeparator   ( ),
  246.   &setSelectable  ( Boolean     selectable  = true ),
  247.   &setDrawItem    ( Boolean     drawItem    = true ),
  248.   &setNoDismiss   ( Boolean     noDismiss   = true ),
  249.   &setFramed      ( Boolean     framed      = true ),
  250.   &setChecked     ( Boolean     checked     = true ),
  251.   &setDisabled    ( Boolean     disabled    = true ),
  252.   &setHighlighted ( Boolean     highlighted = true );
  253.  
  254. /*--------------------Query/Test Style and Attribute ---------------------------
  255. | The following functions can be used to query or test for a specific style    |
  256. | or attribute:                                                                |
  257. |   layoutType    - Returns the menu item placement and layout.                |
  258. |   commandType   - Returns the event the menu item will generate when         |
  259. |                   selected.                                                  |
  260. |   isSelectable  - Returns true if the menu item is selectable.               |
  261. |   isSeparator   - Returns true if the separator style is set.                |
  262. |   isDrawItem    - Returns true if the drawItem style is set.                 |
  263. |   isNoDismiss   - Returns true if the noDismiss attribute is set.            |
  264. |   isFramed      - Returns true if the framed attribute is set.               |
  265. |   isChecked     - Returns true if the checked attribute is set.              |
  266. |   isDisabled    - Returns true if the disabled attribute is set.             |
  267. |   isHighlighted - Returns true if the highlighted attribute is set.          |
  268. ------------------------------------------------------------------------------*/
  269. LayoutType
  270.   layoutType  ( ) const;
  271. CommandType
  272.   commandType ( ) const;
  273.  
  274. Boolean
  275.   isSelectable  ( ) const,
  276.   isDrawItem    ( ) const,
  277.   isSeparator   ( ) const,
  278.   isNoDismiss   ( ) const,
  279.   isFramed      ( ) const,
  280.   isChecked     ( ) const,
  281.   isDisabled    ( ) const,
  282.   isHighlighted ( ) const;
  283.  
  284. /*---------------------Set and Change Menu Item ------------------------------
  285. | The following functions can be used to set and change menu item content.   |
  286. |   setText          - Sets the text to be displayed.                        |
  287. |   setBitmap        - Sets the bit map to be displayed.  The implementation |
  288. |                      that uses an unsigned long argument is the same as    |
  289. |                      IResourceId.  It is provided to resolve ambiguity.    |
  290. |   setIndex         - Sets the menu item ordinal position in its submenu.   |
  291. |   setSubmenuHandle - Sets the menu item submenu window handle.  When       |
  292. |                      selected, the menu item will now display the menu     |
  293. |                      specified by the menuHandle argument as a cascaded    |
  294. |                      submenu.                                              |
  295. ----------------------------------------------------------------------------*/
  296. IMenuItem
  297.   &setText      ( const char*         newText ),
  298.   &setText      ( const IResourceId   &textResId ),
  299.  
  300.   &setBitmap    ( const IBitmapHandle &menuItem ),
  301.   &setBitmap    ( const IResourceId   &bitmapResId ),
  302.   &setBitmap    ( unsigned long       bitmapResId ),
  303.  
  304.   &setIndex     ( long                index  = atEnd()),
  305.  
  306.   &setSubmenuHandle ( const IWindowHandle &menuHandle );
  307.  
  308.  
  309. /*--------------------- Accessor -----------------------------------------------
  310. | The following functions can be used to query the menu item content.          |
  311. |   id            - Returns the ID associated with the menu item.              |
  312. |   style         - Returns an unsigned long representing the menu item's      |
  313. |                   style.                                                     |
  314. |   attribute     - Returns an unsigned long representing the menu item's      |
  315. |                   attributes.                                                |
  316. |   index         - Returns the ordinal position of the menu item in its       |
  317. |                   submenu.                                                   |
  318. |   text          - Returns an IString that represents the text to be          |
  319. |                   displayed.                                                 |
  320. |   bitmap        - Returns the bit-map handle of the item.                    |
  321. |   submenuHandle - Returns the submenu window handle for the item.            |
  322. ------------------------------------------------------------------------------*/
  323. unsigned long
  324.   id            ( ) const,
  325.   style         ( ) const,
  326.   attribute     ( ) const;
  327. long
  328.   index         ( ) const;
  329. IString
  330.   text          ( ) const;
  331. IBitmapHandle
  332.   bitmap        ( ) const;
  333. IWindowHandle
  334.   submenuHandle ( ) const;
  335.  
  336. /*-------------------------- Set Style/Attribute  ------------------------------
  337. | The following member functions are used to set the menu item's style         |
  338. | and attributes:                                                              |
  339. |   setStyle     - Sets the menu item's style from an unsigned long.           |
  340. |   setAttribute - Sets the menu item's attributes from an unsigned long.      |
  341. ------------------------------------------------------------------------------*/
  342. IMenuItem
  343.   &setStyle     ( unsigned long newStyle ),
  344.   &setAttribute ( unsigned long newAttribute );
  345.  
  346. /*----------------------- Private -----------------------------------*/
  347. private:
  348. friend class IMenu;
  349. static Style
  350.   currentDefaultStyle;
  351. static Attribute
  352.   currentDefaultAttribute;
  353. static long
  354.   atEnd ( );
  355. IString
  356.   strClItemText;
  357. long
  358.   iPosition;
  359. unsigned long
  360.   afStyle,
  361.   afAttribute,
  362.   itemId;
  363. IWindowHandle
  364.   hwndSubmenu;
  365. IBitmapHandle
  366.   hBitmapHandle;
  367. };
  368.  
  369. /*----------------------------------------------------------------------------*/
  370. /* Resume compiler default packing.                                           */
  371. /*----------------------------------------------------------------------------*/
  372. #pragma pack()
  373.  
  374. #ifndef I_NO_INLINES
  375.   #include <imnitem.inl>
  376. #endif
  377.  
  378. #endif  /* _IMNITEM_ */
  379.