home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / ISELHDR.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  10KB  |  149 lines
  1. #ifndef _ISELHDR_
  2.   #define _ISELHDR_
  3. /*******************************************************************************
  4. * FILE NAME: iselhdr.hpp                                                       *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   Declaration of the class(es):                                              *
  8. *     ISelectHandler - Process a selection event for a control.                *
  9. *                                                                              *
  10. * COPYRIGHT:                                                                   *
  11. *   Licensed Materials - Property of IBM                                       *
  12. *   (C) Copyright IBM Corporation 1992, 1993                                   *
  13. *   All Rights Reserved                                                        *
  14. *   US Government Users Restricted Rights - Use, duplication, or disclosure    *
  15. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  16. *                                                                              *
  17. *******************************************************************************/
  18. #ifndef _IHANDLER_
  19.   #include <ihandler.hpp>
  20. #endif
  21. #ifndef _ICTLEVT_
  22.   #include <ictlevt.hpp>
  23. #endif
  24.  
  25. /*----------------------------------------------------------------------------*/
  26. /* Align classes on four byte boundary.                                       */
  27. /*----------------------------------------------------------------------------*/
  28. #pragma pack(4)
  29.  
  30. // Forward declarations for other classes:
  31. class IEvent;
  32.  
  33.  
  34. class ISelectHandler : public IHandler {
  35. typedef IHandler
  36.   Inherited;
  37. /*******************************************************************************
  38. * The ISelectHandler class handles the processing of item selection events,    *
  39. * including:                                                                   *
  40. *                                                                              *
  41. *   - Select                                                                   *
  42. *   - Deselect                                                                 *
  43. *   - Pressing the Enter key                                                   *
  44. *   - Double-clicking a mouse button                                           *
  45. *                                                                              *
  46. * for the following controls:                                                  *
  47. *                                                                              *
  48. *   - I3StateCheckBox                                                          *
  49. *   - ICheckBox                                                                *
  50. *   - IComboBox                                                                *
  51. *   - IContainerControl                                                        *
  52. *   - IListBox                                                                 *
  53. *   - IRadioButton                                                             *
  54. *                                                                              *
  55. * The ISelectHandler class is designed to handle events that result from a     *
  56. * user interacting with a selectable item, such as clicking a radio button.    *
  57. * An ISelectHandler should be attached to the control that generated the       *
  58. * selection event, or to the owner window of the control.  This is done by     *
  59. * passing the control window or owner window on the handleEventsFor function   *
  60. * of the ISelectHandler object.                                                *
  61. *                                                                              *
  62. * When it receives a selection event, the ISelectHandler object creates an     *
  63. * IControlEvent object and routes it to the appropriate virtual function.      *
  64. * You can override the virtual functions of ISelectHandler to supply your own  *
  65. * specialized processing of an event.  The return value from the virtual       *
  66. * functions specifies whether the IControlEvent should be passed on for        *
  67. * additional processing, as follows:                                           *
  68. *                                                                              *
  69. *   Value   Meaning                                                            *
  70. *   ---------------                                                            *
  71. *   true  - The IControlEvent object requires no additional processing and     *
  72. *           should not be passed to another handler.                           *
  73. *   false - The IControlEvent object should be passed on for additional        *
  74. *           processing, as follows:                                            *
  75. *           -- If there is a next handler for the control or window, the       *
  76. *              event is passed on to the next handler.                         *
  77. *           -- If this is the last handler for the control, the object is      *
  78. *              dispatched to the owner of the control (see IWindow::dispatch). *
  79. *           -- If this is the last handler for the owner window, the event is  *
  80. *              passed on a call to the owner window's defaultProcedure         *
  81. *              function (see IWindow::defaultProcedure).                       *
  82. *                                                                              *
  83. * Example:                                                                     *
  84. *   MyWindow::MyWindow()                                                       *
  85. *     : ...                                                                    *
  86. *   {                                                                          *
  87. *     MyRadioSelectHandler* selh = new MyRadioSelectHandler();                 *
  88. *     ...                                                                      *
  89. *     IRadioButton* rb1 = new IRadioButton(ID_RB1, this, this,                 *
  90. *                                          IRectangle(...));                   *
  91. *     IRadioButton* rb2 = new IRadioButton(ID_RB2, this, this,                 *
  92. *                                          IRectangle(...));                   *
  93. *     IRadioButton* rb3 = new IRadioButton(ID_RB3, this, this,                 *
  94. *                                          IRectangle(...));                   *
  95. *     selh->handleEventsFor(rb1);                                              *
  96. *     selh->handleEventsFor(rb2);                                              *
  97. *     selh->handleEventsFor(rb3);                                              *
  98. *     ...                                                                      *
  99. *     show();                                                                  *
  100. *   }                                                                          *
  101. *   Boolean  MyRadioSelectHandler::select(IControlEvent& evt)                  *
  102. *   {                                                                          *
  103. *     ulButtonId = evt.controlId();  // remember selected button               *
  104. *     return false;            // let another handle event also                *
  105. *   }                                                                          *
  106. *******************************************************************************/
  107. public:
  108. /*------------------------------- Constructor ----------------------------------
  109. | The only way to construct instances of this class is to use the default      |
  110. | constructor, which does not take any arguments.                              |
  111. ------------------------------------------------------------------------------*/
  112.   ISelectHandler       ( );
  113. virtual
  114.  ~ISelectHandler       ( );
  115.  
  116. protected:
  117. /*---------------------------- Event Dispatching -------------------------------
  118. | This function evaluates the event to determine if it is appropriate for      |
  119. | this handler object to process.  If it is, it calls a virtual function used  |
  120. | to process the event.                                                        |
  121. |   dispatchHandlerEvent - Calls the appropriate virtual function to process   |
  122. |                          the event.                                          |
  123. ------------------------------------------------------------------------------*/
  124. virtual Boolean
  125.   dispatchHandlerEvent ( IEvent& event );
  126.  
  127. /*------------------------ Event Processing Functions --------------------------
  128. | These functions should be supplied by a derived class in order to provide    |
  129. | processing for a selection or enter event.                                   |
  130. |   enter    - Implemented by derived classes to process an enter event.       |
  131. |   selected - Implemented by derived classes to process a selection event.    |
  132. ------------------------------------------------------------------------------*/
  133. virtual Boolean
  134.   enter                ( IControlEvent& event ),
  135.   selected             ( IControlEvent& event );
  136.  
  137. private: /*------------------------ PRIVATE ----------------------------------*/
  138. IWindowHandle
  139.   control( const IControlEvent& event ) const;
  140.  
  141. }; // ISelectHandler
  142.  
  143. /*----------------------------------------------------------------------------*/
  144. /* Resume compiler default packing.                                           */
  145. /*----------------------------------------------------------------------------*/
  146. #pragma pack()
  147.  
  148. #endif /* _ISELHDR_ */
  149.