home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / IDMTGTH.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  13KB  |  227 lines
  1. #ifndef _IDMTGTH_
  2. #define _IDMTGTH_
  3. /*******************************************************************************
  4. * FILE NAME: idmtgth.hpp                                                       *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   Declaration of the class(es):                                              *
  8. *     IDMTargetHandler - Direct manipulation target window handler.            *
  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 _IDMHNDLR_
  19.   #include <idmhndlr.hpp>
  20. #endif
  21.  
  22. #ifndef _IDMTGTOP_
  23.   #include <idmtgtop.hpp>
  24. #endif
  25.  
  26. #ifndef _IDMTGTRN_
  27.   #include <idmtgtrn.hpp>
  28. #endif
  29.  
  30. /*----------------------------------------------------------------------------*/
  31. /* Align classes on four byte boundary.                                       */
  32. /*----------------------------------------------------------------------------*/
  33. #pragma pack(4)
  34.  
  35. /* Forward Declarations */
  36. class IDMTargetRenderer;
  37. class IWindow;
  38. class IEntryField;
  39. class IMultiLineEdit;
  40. class IContainerControl;
  41. class IDMTargetEnterEvent;
  42. class IDMTargetLeaveEvent;
  43. class IDMTargetDropEvent;
  44. class IDMTargetHelpEvent;
  45. class IDMTargetEndEvent;
  46.  
  47.  
  48. class IDMTargetHandler : public IDMHandler {
  49. typedef IDMHandler
  50.   Inherited;
  51. /*******************************************************************************
  52. * Objects of the IDMTargetHandler class handle events that occur in the target *
  53. * window during a direct manipulation operation.  An instance of this class    *
  54. * must be added to a window so that it can support the dropping of object(s).  *
  55. * It does not  allow objects to be dragged from a window.  See the             *
  56. * IDMSourceHandler class for information about dragging objects from a window. *
  57. *------------------------------------------------------------------------------*
  58. *                                                                              *
  59. * Two examples are provided.  Note that both achieve the same goal:            *
  60. *                                                                              *
  61. * Example 1:                                                                   *
  62. * // Create frame window object ...                                            *
  63. * IFrameWindow                                                                 *
  64. *   frame( "ICLUI Direct Manipulation Sample" );                               *
  65. *                                                                              *
  66. * // Create client entry field and entry field extension objects ...           *
  67. * IEntryField                                                                  *
  68. *   client( 0, &frame, &frame ),                                               *
  69. *   ext   ( 0, &frame, &frame );                                               *
  70. *                                                                              *
  71. * // Define target handler for the entry field ...                             *
  72. * IDMTargetHandler                                                             *
  73. *   target( &client );                                                         *
  74. *                                                                              *
  75. * // Reuse drag item provider in the extension that was instantiated           *
  76. * // for the client and configure the extension as a target handler            *
  77. * ext.setItemProvider(client.itemProvider());                                  *
  78. * target.handleEventsFor( &ext );                                              *
  79. *------------------------------------------------------------------------------*
  80. *                                                                              *
  81. * Example 2:                                                                   *
  82. * // Create frame window object ...                                            *
  83. * IFrameWindow                                                                 *
  84. *   frame( "ICLUI Direct Manipulation Sample" );                               *
  85. *                                                                              *
  86. * // Create client entry field and entry field extension objects ...           *
  87. * IEntryField                                                                  *
  88. *   client( 0, &frame, &frame ),                                               *
  89. *   ext   ( 0, &frame, &frame );                                               *
  90. *                                                                              *
  91. * // Enable both entry fields to allow dropping of text ...                    *
  92. * IDMHandler::enableDropOn( &client );                                         *
  93. * IDMHandler::enableDropOn( &ext );                                            *
  94. *                                                                              *
  95. *******************************************************************************/
  96. public:
  97. /*------------------------ Constructor/Destructor ------------------------------
  98. | You can construct objects of this class by providing one of the following    |
  99. | items:                                                                       |
  100. |   o A pointer to an IWindow object                                           |
  101. |   o A pointer to an entry field                                              |
  102. |   o A pointer to an MLE                                                      |
  103. |   o A pointer to an container control                                        |
  104. |   o No arguments                                                             |
  105. |                                                                              |
  106. | Note:  If any of the first 4 constructors are used, this handler will        |
  107. |        automatically be attached to the specified window.                    |
  108. ------------------------------------------------------------------------------*/
  109.   IDMTargetHandler     ( IWindow           *window );
  110.  
  111.   IDMTargetHandler     ( IEntryField       *entryField );
  112.  
  113.   IDMTargetHandler     ( IMultiLineEdit    *multiLineEdit );
  114.  
  115.   IDMTargetHandler     ( IContainerControl *containerControl );
  116.  
  117.   IDMTargetHandler     ( );
  118.  
  119. virtual
  120.   ~IDMTargetHandler    ( );
  121.  
  122. /*--------------------------------- Overrides ----------------------------------
  123. | The following functions override the rendering functions defined in the      |
  124. | base IDMHandler class.  They provide a means of accessing the                |
  125. | IDMTargetRenderer objects involved in the direct manipulation operation      |
  126. | described by instances of this class.  These objects will be used to handle  |
  127. | the rendering of dropped objects that are compatible with the supported      |
  128. | renderering mechanisms and formats:                                          |
  129. |   numberOfRenderers - Returns the number of renderers                        |
  130. |   renderer          - Returns the renderer with the given position           |
  131. |   replaceRenderer   - Replaces a given IDMTargetRenderer with another        |
  132. |   addRenderer       - Adds another IDMTargetRenderer to this target          |
  133. |                       operation                                              |
  134. |   removeRenderer    - Removes an IDMTargetRenderer from this target          |
  135. |                       operation                                              |
  136. |   setRenderer       - Sets the renderer for this target operation  Removes   |
  137. |                       any existing renderers.                                |
  138. |                                                                              |
  139. | Note: Renderers are maintained positionally, which is 1-based.               |
  140. ------------------------------------------------------------------------------*/
  141. virtual unsigned
  142.   numberOfRenderers  ( );
  143.  
  144. virtual IDMTargetRenderer
  145.  *renderer           ( unsigned                position );
  146.  
  147. virtual IDMTargetHandler
  148.  &replaceRenderer    ( unsigned                position,
  149.                        const IDMTargetRenderer &replacement ),
  150.  &addRenderer        ( const IDMTargetRenderer &newRenderer ),
  151.  &removeRenderer     ( const IDMTargetRenderer &rendererToRemove ),
  152.  &setRenderer        ( const IDMTargetRenderer &newRenderer );
  153.  
  154.  
  155. protected:
  156. /*------------------------------ Event Handling --------------------------------
  157. | The following functions are dispatched in response to specific direct        |
  158. | manipulation target events:                                                  |
  159. |                                                                              |
  160. |   targetEnter    - Called when dragged objects enter the target window       |
  161. |   targetLeave    - Called when the dragged objects leave the target window   |
  162. |   targetDrop     - Called when the dragged objects are dropped on the        |
  163. |                    target window                                             |
  164. |   targetHelp     - Called when the user requests help while dragging an      |
  165. |                    object over the target window                             |
  166. |   targetEnd      - Called when the source renderer has completed the         |
  167. |                    rendering of a specific dragged object, and it            |
  168. |                    posts this event.  Not used by the default renderers.     |
  169. ------------------------------------------------------------------------------*/
  170. virtual Boolean
  171.   targetEnter    ( IDMTargetEnterEvent  &event ),
  172.  
  173.   targetLeave    ( IDMTargetLeaveEvent  &event ),
  174.   targetDrop     ( IDMTargetDropEvent   &event ),
  175.   targetHelp     ( IDMTargetHelpEvent   &event ),
  176.  
  177.   targetEnd      ( IDMTargetEndEvent    &event );
  178.  
  179. /*------------------------------ Implementation --------------------------------
  180. | The following utility functions are used to implement the behavior of        |
  181. | this class:                                                                  |
  182. |   allocateOperation - Creates an instance of the IDMTargetOperation class    |
  183. |                       and returns a pointer to it.                           |
  184. |   findRenderersFor  - Called to find the appropriate target renderers        |
  185. |                       for the operation.                                     |
  186. |   findRendererFor   - Called to find the appropriate target renderer         |
  187. |                       for the item.  Returns the position of the renderer,   |
  188. |                       0 if none found.                                       |
  189. ------------------------------------------------------------------------------*/
  190. virtual IDMTargetOperation::Handle
  191.   allocateOperation    ( IDMTargetEnterEvent &event ) const;
  192.  
  193. virtual Boolean
  194.   findRenderersFor   ( const IDMTargetOperation::Handle &targetOperation );
  195.  
  196. virtual unsigned
  197.   findRendererFor    ( const IDMItem::Handle            &item );
  198.  
  199. /*-------------------------------- Overrides -----------------------------------
  200. | This class overrides the following inherited dispatchHandlerEvent function,  |
  201. | which handles drag target events.                                            |
  202. ------------------------------------------------------------------------------*/
  203. virtual Boolean
  204.   dispatchHandlerEvent ( IEvent &event );
  205.  
  206.  
  207. private: /*------------------------ PRIVATE ----------------------------------*/
  208. Boolean
  209.   isContainerControl(IWindow *pCtrlWin);
  210.  
  211. virtual IDMHandler
  212.  &replaceRenderer ( unsigned          position,
  213.                     const IDMRenderer &replacement ),
  214.  &addRenderer     ( const IDMRenderer &newRenderer ),
  215.  &removeRenderer  ( unsigned          position ),
  216.  &removeRenderer  ( const IDMRenderer &rendererToRemove ),
  217.  &setRenderer     ( const IDMRenderer &newRenderer );
  218.  
  219. }; // IDMTargetHandler
  220.  
  221. /*----------------------------------------------------------------------------*/
  222. /* Resume compiler default packing.                                           */
  223. /*----------------------------------------------------------------------------*/
  224. #pragma pack()
  225.  
  226. #endif // _IDMTGTH_
  227.