home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / IFOCSHDR.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  9KB  |  141 lines
  1. #ifndef _IFOCSHDR_
  2.   #define _IFOCSHDR_
  3. /*******************************************************************************
  4. * FILE NAME: ifocshdr.hpp                                                      *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   Declaration of the class(es):                                              *
  8. *     IFocusHandler - Process a focus change 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 IFocusHandler : public IHandler {
  35. typedef IHandler
  36.   Inherited;
  37. /*******************************************************************************
  38. * The IFocusHandler class handles the processing of focus change events for    *
  39. * the following controls:                                                      *
  40. *                                                                              *
  41. *   - IContainerControl                                                        *
  42. *   - IEntryField                                                              *
  43. *   - IListBox                                                                 *
  44. *   - IMultiLineEdit                                                           *
  45. *   - IProgressIndicator                                                       *
  46. *   - ISlider                                                                  *
  47. *   - ISpinButton                                                              *
  48. *                                                                              *
  49. * The IFocusHandler class is designed to handle events that occur when a       *
  50. * control gains or loses the input focus, such as when the user tabs to or     *
  51. * from an entry field.  The IFocusHandler object should be attached to the     *
  52. * control that will be getting or losing the input focus, or to the owner      *
  53. * window of the control.  You can do this by passing the control or owner      *
  54. * window on the handleEventsFor function of the IFocusHandler object.          *
  55. *                                                                              *
  56. * When it receives a focus change event, the IFocusHandler object constructs   *
  57. * an IControlEvent object and routes it to the appropriate virtual function.   *
  58. * These virtual functions allow you to supply your own specialized processing  *
  59. * of the event.  The return values from the virtual functions specify whether  *
  60. * the IControlEvent should be passed on for additional processing, as follows: *
  61. *                                                                              *
  62. *   Value   Meaning                                                            *
  63. *   ---------------                                                            *
  64. *   true  - The IControlEvent requires no additional processing and should     *
  65. *           not be passed to another handler.                                  *
  66. *   false - The IControlEvent should be passed to the next handler for         *
  67. *           additional processing, as follows:                                 *
  68. *           -- If there is another handler for the control or window, the      *
  69. *              IControlEvent is passed on to the next handler.                 *
  70. *           -- If this is the last handler for the control, the IControlEvent  *
  71. *              is dispatched to the owner of the control.                      *
  72. *              (See IWindow::dispatch.)                                        *
  73. *           -- If this is the last handler for the owner window, the           *
  74. *              IControlEvent is passed on a call to the owner window's         *
  75. *              defaultProcedure function.  (See IWindow::defaultProcedure.)    *
  76. *                                                                              *
  77. * Example:                                                                     *
  78. *   MyWindow::MyWindow()   // inherits from IFrame, IFocusHandler              *
  79. *     : ...                                                                    *
  80. *   {                                                                          *
  81. *     ((IFocusHandler*)this)->handleEventsFor(this);                           *
  82. *     ...                                                                      *
  83. *     IEntryField* ef = new IEntryField(ID_EF, this, this, IRectangle(...));   *
  84. *     IStaticText* stxtHelp = new IStaticText(ID_STXTHELP, this, this,         *
  85. *                                             IRectangle(...));                *
  86. *     ...                                                                      *
  87. *     show();                                                                  *
  88. *   }                                                                          *
  89. *   Boolean  MyWindow::gotFocus(IControlEvent& evt)                            *
  90. *   {                    // provide quick help for current owned control       *
  91. *     if (evt.controlId() == ID_EF)                                            *
  92. *     {                        // entry field gaining focus                    *
  93. *        stxtHelp->setText("Please give your full name.");                     *
  94. *     }                                                                        *
  95. *     ...                                                                      *
  96. *     else                                                                     *
  97. *     {                        // some other control                           *
  98. *        stxtHelp->setText(" ");  // no help for this one                      *
  99. *     }                                                                        *
  100. *     ...                                                                      *
  101. *     return false;            // let another handle event also                *
  102. *   }                                                                          *
  103. *******************************************************************************/
  104. public:
  105. /*-------------------------- Constructor/Destructor ----------------------------
  106. | The only way to construct instances of this class is to use the default      |
  107. | constructor, which does not take any arguments.                              |
  108. | ----------------------------------------------------------------------------*/
  109.   IFocusHandler        ( );
  110. virtual
  111.  ~IFocusHandler        ( );
  112.  
  113. protected:
  114. /*---------------------------- Event Dispatching -------------------------------
  115. | This function evaluates the event to determine if it is appropriate for      |
  116. | this handler object to process.  If it is, this function calls the virtual   |
  117. | function used to process the event.                                          |
  118. |   dispatchHandlerEvent - Calls the gotFocus or lostFocus function, as        |
  119. |                          appropriate.                                        |
  120. ------------------------------------------------------------------------------*/
  121. virtual Boolean
  122.   dispatchHandlerEvent ( IEvent& event );
  123.  
  124. /*----------------------------- Event Processing -------------------------------
  125. | These functions should be supplied by a derived class to process a focus     |
  126. | change event.                                                                |
  127. |   gotFocus  - Implemented by derived classes to process a focus gain event.  |
  128. |   lostFocus - Implemented by derived classes to process a focus loss event.  |
  129. ------------------------------------------------------------------------------*/
  130. virtual Boolean
  131.   gotFocus             ( IControlEvent& event ),
  132.   lostFocus            ( IControlEvent& event );
  133. }; // IFocusHandler
  134.  
  135. /*----------------------------------------------------------------------------*/
  136. /* Resume compiler default packing.                                           */
  137. /*----------------------------------------------------------------------------*/
  138. #pragma pack()
  139.  
  140. #endif /* _IFOCSHDR_ */
  141.