home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / IKEYHDR.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  12KB  |  172 lines
  1. #ifndef _IKEYHDR_
  2.   #define _IKEYHDR_
  3. /*******************************************************************************
  4. * FILE NAME: ikeyhdr.hpp                                                       *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   Declaration of the class(es):                                              *
  8. *     IKeyboardHandler - Process a keyboard event for a window.                *
  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 _IKEYEVT_
  22.   #include <ikeyevt.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 IKeyboardHandler : public IHandler {
  35. typedef IHandler
  36.   Inherited;
  37. /*******************************************************************************
  38. * Instances of the IKeyboardHandler class can be used to process all types of  *
  39. * keyboard events.  These events include:                                      *
  40. *   - Key presses and releases                                                 *
  41. *   - Character code, hardware scan code, and virtual key events               *
  42. *   - Single- or double-byte characters.                                       *
  43. *                                                                              *
  44. * An IKeyboardHandler object can be attached to any kind of window.  While     *
  45. * the control or window with the input focus will be the first to receive a    *
  46. * keyboard event, any event that is passed on for additional processing is     *
  47. * dispatched to the owner window of the focus window.                          *
  48. *                                                                              *
  49. * A keyboard event continues to travel up the owner window chain until either  *
  50. * a handler stops it or the key is processed by the window itself.  As a       *
  51. * result, an IKeyboardHandler object should not stop the processing of any     *
  52. * key events that it does not understand because the key has the potential of  *
  53. * being handled by any window in the owner chain, such as the frame window.    *
  54. *                                                                              *
  55. * When an IKeyboardHandler object receives a keyboard event, the               *
  56. * IKeyboardHandler object creates an IKeyboardEvent object and routes it to    *
  57. * the following virtual functions as appropriate:                              *
  58. *                                                                              *
  59. *   scanCodeKeyPress  - For key press events with a scan code value.           *
  60. *   virtualKeyPress   - For key press events with a virtual key value.         *
  61. *   characterKeyPress - For key press events with a character code value.      *
  62. *   key               - For any and all key events.                            *
  63. *                                                                              *
  64. * You should override one or more virtual functions to supply your own         *
  65. * processing of a keyboard event.  If any of the above virtual functions       *
  66. * indicates that the key event requires no additional processing, the key      *
  67. * event is not passed to any additional virtual functions of the               *
  68. * IKeyboardHandler object, and it is not passed on to any other handlers.      *
  69. * The return value from a virtual function is intrepreted as follows:          *
  70. *                                                                              *
  71. *   Value   Meaning                                                            *
  72. *   ---------------                                                            *
  73. *   true  - The IKeyboardEvent requires no additional processing and should    *
  74. *           not be passed on to another handler.                               *
  75. *   false - The IKeyboardEvent should be passed on for additional processing   *
  76. *           when the following situations occur:                               *
  77. *           -- If the key event is appropriate for another virtual function    *
  78. *              in the IKeyboardHandler, the key event is passed to that        *
  79. *              virtual function.  (The virtual functions are called in the     *
  80. *              order listed above.)                                            *
  81. *           -- If there is another handler for the window, the event is        *
  82. *              passed on to the next handler.                                  *
  83. *           -- If this is the last handler for a window, the event is passed   *
  84. *              on a call to the window's defaultProcedure function.  (See      *
  85. *              IWindow::defaultProcedure.)  This could result in the event     *
  86. *              being dispatched to the window's owner window, where the        *
  87. *              processing of the keyboard event starts again.                  *
  88. *                                                                              *
  89. * Example:                                                                     *
  90. *   MyWindow::MyWindow()                                                       *
  91. *     : ...                                                                    *
  92. *   {                                                                          *
  93. *     MyNumericKeyHandler* keyhNumeric = new MyNumericKeyHandler();            *
  94. *     ...                                                                      *
  95. *     IEntryField* efNum = new IEntryField(ID_EF, this, this, IRectangle(...));*
  96. *     keyhNumeric->handleEventsFor(efNum);                                     *
  97. *     ...                                                                      *
  98. *     show();                                                                  *
  99. *   }                                                                          *
  100. *   Boolean  MyNumericKeyHandler::characterKeyPress(IKeyboardEvent& kbdevt)    *
  101. *   {                                                                          *
  102. *     Boolean bRc = true;         // assume non-numeric key                    *
  103. *     IString strChar = keyevt.mixedCharacter();                               *
  104. *     if (strChar.length() == 1)                                               *
  105. *     {                           // single-byte character                     *
  106. *        switch (keyevt.character())                                           *
  107. *        {                                                                     *
  108. *           case '0':                                                          *
  109. *           ...                                                                *
  110. *           case '9':                                                          *
  111. *           {                     // let cases for 0 - 9 fall through to here  *
  112. *              bRc = false;       // let this valid key go through             *
  113. *              break;                                                          *
  114. *           }                                                                  *
  115. *           default:                                                           *
  116. *              break;                                                          *
  117. *        }                                                                     *
  118. *     }                                                                        *
  119. *     if (bRc == true)                                                         *
  120. *     {                           // not 0 - 9                                 *
  121. *        DosBeep(50, 50);         // inform the user and eat the key           *
  122. *     }                                                                        *
  123. *     return bRc;                                                              *
  124. *   }                                                                          *
  125. *******************************************************************************/
  126. public:
  127. /*------------------------ Constructor/Destructor ------------------------------
  128. | The only way to construct instances of this class is to use the default      |
  129. | constructor, which does not take any arguments.                              |
  130. ------------------------------------------------------------------------------*/
  131.   IKeyboardHandler     ( );
  132. virtual
  133.  ~IKeyboardHandler     ( );
  134.  
  135. protected:
  136. /*---------------------------- Event Dispatching -------------------------------
  137. | This function evaluates the event to determine if it is appropriate for      |
  138. | this handler object to process.  If it is, this function calls the virtual   |
  139. | function used to process the event.                                          |
  140. |   dispatchHandlerEvent - Calls the appropriate virtual function or           |
  141. |                          functions to process a keyboard event.              |
  142. ------------------------------------------------------------------------------*/
  143. virtual Boolean
  144.   dispatchHandlerEvent ( IEvent& event );
  145.  
  146. /*----------------------------- Event Processing -------------------------------
  147. | At least one of these functions should be supplied by a derived class to     |
  148. | process a keyboard event (note that some events can be routed to more than   |
  149. | one of these virtual functions):                                             |
  150. |   scanCodeKeyPress  - Implemented by derived classes to handle scan code     |
  151. |                       key presses.                                           |
  152. |   virtualKeyPress   - Implemented by derived classes to handle virtual key   |
  153. |                       presses.                                               |
  154. |   characterKeyPress - Implemented by derived classes to handle character     |
  155. |                       key presses.                                           |
  156. |   key               - Implemented by derived classes to handle any and all   |
  157. |                       unprocessed key events.                                |
  158. ------------------------------------------------------------------------------*/
  159. virtual Boolean
  160.   scanCodeKeyPress     ( IKeyboardEvent& event ),
  161.   virtualKeyPress      ( IKeyboardEvent& event ),
  162.   characterKeyPress    ( IKeyboardEvent& event ),
  163.   key                  ( IKeyboardEvent& event );
  164. }; // IKeyboardHandler
  165.  
  166. /*----------------------------------------------------------------------------*/
  167. /* Resume compiler default packing.                                           */
  168. /*----------------------------------------------------------------------------*/
  169. #pragma pack()
  170.  
  171. #endif /* _IKEYHDR_ */
  172.