home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / IHANDLER.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  10KB  |  166 lines
  1. #ifndef _IHANDLER_
  2. #define _IHANDLER_
  3. /*******************************************************************************
  4. * FILE NAME: ihandler.hpp                                                      *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   This file contains the declaration(s) of the class(es):                    *
  8. *     IHandler - Base window event handler class.                              *
  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               *
  15. *   disclosure                                                                 *
  16. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  17. *                                                                              *
  18. *******************************************************************************/
  19. #ifndef _IVBASE_
  20.   #include <ivbase.hpp>
  21. #endif
  22.  
  23. #ifndef _IEVENT_
  24.   #include <ievent.hpp>
  25. #endif
  26.  
  27. /*----------------------------------------------------------------------------*/
  28. /* Align classes on four byte boundary.                                       */
  29. /*----------------------------------------------------------------------------*/
  30. #pragma pack(4)
  31.  
  32. class IString;
  33. class IWindow;
  34.  
  35. class IHandler : public IVBase {
  36. typedef IVBase
  37.   Inherited;
  38.  
  39. /*******************************************************************************
  40. * The IHandler class is an abstract base for window event handlers.  Derived   *
  41. * classes are written to handle specific window events (Presentation Manager   *
  42. * window messages).  Windows (or the objects that create windows) add          *
  43. * instances of these handler classes to themselves by using the                *
  44. * IWindow::addHandler function.  Handlers can also be added to windows by      *
  45. * using the IHandler::handleEventsFor function.                                *
  46. *                                                                              *
  47. * Multiple handlers can be added to a given window.  The handlers are called   *
  48. * in turn until one of them indicates that further handlers are not to be      *
  49. * called.  This is achieved by the handler returning true from its             *
  50. * dispatchHandlerEvent function.  If none of the handlers returns true, then   *
  51. * the original window procedure for the underlying Presentation Manager        *
  52. * window is called.                                                            *
  53. *                                                                              *
  54. * The handler that handles a given event is also responsible for setting the   *
  55. * appropriate event result.  This is done by using the IEvent::setResult       *
  56. * function.  In general, a handler that returns true from dispatchHandlerEvent *
  57. * must call IEvent::setResult on the event passed to it.  This result will     *
  58. * be returned to the sender of the Presentation Manager message.               *
  59. *                                                                              *
  60. * Handlers can be detached from windows by using either the                    *
  61. * IWindow::removeHandler or the IHandler::stopHandlingEventsFor function.      *
  62. * Care must be taken to detach the handler from the windows it is handling     *
  63. * prior to destroying the handler object.  Typically, a window will remove     *
  64. * its handlers in its destructor.                                              *
  65. *                                                                              *
  66. * Handlers can be disabled to suppress their handling of events without        *
  67. * removing them from the window handler chain.                                 *
  68. *                                                                              *
  69. * Example:                                                                     *
  70. *   // MyControl is a control with a MyHandler attached.                       *
  71. *   class MyControl : public IControl {                                        *
  72. *   MyHandler                                                                  *
  73. *     handler;                                                                 *
  74. *   public:                                                                    *
  75. *     MyControl :: MyControl ( )                                               *
  76. *       : IControl( )                                                          *
  77. *       {                                                                      *
  78. *       this->handler.handleEventsFor( this );                                 *
  79. *       }                                                                      *
  80. *     ~MyControl ( )                                                           *
  81. *       {                                                                      *
  82. *       this->handler.stopHandlingEventsFor( this );                           *
  83. *       }                                                                      *
  84. *   };                                                                         *
  85. *******************************************************************************/
  86. public:
  87. /*----------------------------- Constructor/Destructor -------------------------
  88. | This is an abstract base class, so the constructor can only be called from   |
  89. | the constructors of derived classes.  The constructor accepts no arguments   |
  90. | and simply initializes the handler in an enabled state.                      |
  91. ------------------------------------------------------------------------------*/
  92.   IHandler();
  93.  ~IHandler();
  94. /*---------------------------- Enabling/Disabling ------------------------------
  95. | These functions deal with enabling and disabling the handler:                |
  96. |   enable    - Enables the handler, by default.  It accepts an optional       |
  97. |               Boolean argument that, when false, causes the handler to be    |
  98. |               disabled.                                                      |
  99. |   disable   - Disables the handler so that it processes no window events.    |
  100. |   isEnabled - Returns whether the handler is currently enabled.              |
  101. ------------------------------------------------------------------------------*/
  102. virtual IHandler
  103.  &enable  ( Boolean setting = true ),
  104.  &disable ( );
  105.  
  106. Boolean
  107.   isEnabled ( ) const;
  108.  
  109. /*---------------------------- Window Attachment -------------------------------
  110. | These functions permit attaching and detaching the handler object to/from    |
  111. | a given window:                                                              |
  112. |   handleEventsFor       - Attaches the handler to the argument IWindow       |
  113. |                           object.                                            |
  114. |   stopHandlingEventsFor - Detaches the handler from the argument IWindow     |
  115. |                           object.                                            |
  116. ------------------------------------------------------------------------------*/
  117. virtual IHandler
  118.  &handleEventsFor       ( IWindow *window ),
  119.  &stopHandlingEventsFor ( IWindow *window );
  120.  
  121. /*------------------------------- Diagnostics ----------------------------------
  122. |The following functions provide diagnostic information:                       |
  123. |  asString    - Returns IHandler(enabled) or IHandler(disabled).              |
  124. |  asDebugInfo - Returns diagnostic information about the handler.             |
  125. ------------------------------------------------------------------------------*/
  126. virtual IString
  127.   asString    ( ) const,
  128.   asDebugInfo ( ) const;
  129.  
  130. protected:
  131. /*------------------------------ Event Handling --------------------------------
  132. | The following functions provide information about handling events:           |
  133. |   dispatchHandlerEvent - Called (from IWindow) when a window event occurs.   |
  134. |                          A given handler should return true if dispatching   |
  135. |                          the event to other handles should not occur.  In    |
  136. |                          such cases, a result must be placed in the          |
  137. |                          argument IEvent object.                             |
  138. |   defaultProcedure     - Sends the argument IEvent object to the original    |
  139. |                          window procedure for the underlying Presentation    |
  140. |                          Manager window.                                     |
  141. ------------------------------------------------------------------------------*/
  142. virtual Boolean
  143.   dispatchHandlerEvent ( IEvent &evt ) = 0;
  144.  
  145. virtual IEventResult
  146.   defaultProcedure ( IEvent &evt );
  147.  
  148. private: /*------------------------ PRIVATE ----------------------------------*/
  149. friend IWindow;
  150. Boolean
  151.   active;
  152. unsigned
  153.   numWindows;
  154. }; // class IHandler
  155.  
  156. /*----------------------------------------------------------------------------*/
  157. /* Resume compiler default packing.                                           */
  158. /*----------------------------------------------------------------------------*/
  159. #pragma pack()
  160.  
  161. #ifndef I_NO_INLINES
  162.   #include <ihandler.inl>
  163. #endif
  164.  
  165. #endif // _IHANDLER_
  166.