home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cset21v1.zip / IBMCPP / IBMCLASS / IDMPROV.HPP < prev    next >
C/C++ Source or Header  |  1993-10-22  |  12KB  |  200 lines
  1. #ifndef _IDMPROV_
  2. #define _IDMPROV_
  3. /*******************************************************************************
  4. * FILE NAME: idmprov.hpp                                                       *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   This file contains the declaration(s) of the class(es):                    *
  8. *     IDMItemProvider    - Base class used to provide drag items.              *
  9. *     IDMItemProviderFor - Template defining item provider class for           *
  10. *                          typical IDMItem derived classes.                    *
  11. *                                                                              *
  12. * COPYRIGHT:                                                                   *
  13. *   Licensed Materials - Property of IBM                                       *
  14. *   (C) Copyright IBM Corporation 1992, 1993                                   *
  15. *   All Rights Reserved                                                        *
  16. *   US Government Users Restricted Rights - Use, duplication, or               *
  17. *   disclosure                                                                 *
  18. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  19. *                                                                              *
  20. *******************************************************************************/
  21. #ifndef _IVBASE_
  22.   #include <ivbase.hpp>
  23. #endif
  24.  
  25. #ifndef _IDMSRCOP_
  26.   #include <idmsrcop.hpp>
  27. #endif
  28.  
  29. #ifndef _IDMITEM_
  30.   #include <idmitem.hpp>
  31. #endif
  32.  
  33. /*----------------------------------------------------------------------------*/
  34. /* Align classes on four byte boundary.                                       */
  35. /*----------------------------------------------------------------------------*/
  36. #pragma pack(4)
  37.  
  38. /* Forward declarations */
  39. class IDMTargetEnterEvent;
  40. class IDMTargetLeaveEvent;
  41. class IDMTargetHelpEvent;
  42.  
  43.  
  44. class IDMItemProvider : public IVBase {
  45. typedef IVBase
  46.   Inherited;
  47. /*******************************************************************************
  48. * Objects of this class provide application-specific direct manipulation       *
  49. * behavior to windows and controls.  The responsibilities of such objects      *
  50. * include:                                                                     *
  51. *   o providing source/target items (as described)                             *
  52. *   o providing help when requested while a dragged object is positioned       *
  53. *     over a window                                                            *
  54. *   o providing application-defined checking when a dragged object is          *
  55. *     moved over or exits a window; for example, to draw target emphasis       *
  56. *   o setting the default operation appropriate to the window over which       *
  57. *     the object is dragged                                                    *
  58. *                                                                              *
  59. * When the source handler detects that a direct manipulation operation is      *
  60. * being initiated from one of its windows, it calls the provideSourceItems     *
  61. * function.                                                                    *
  62. *                                                                              *
  63. * When items enter a potential target, generic IDMItem objects are created     *
  64. * to represent them.  Next , the target handler will call provideTargetItemFor *
  65. * (once for each item) to give a derived IDMItemProvider class the             *
  66. * opportunity to replace the generic IDMItem objects with objects of some      *
  67. * IDMItem derived class that provides application-specific behavior.           *
  68. *                                                                              *
  69. * See also the template class, IDMItemProviderFor, which can be used to        *
  70. * generate a derived IDMItemProvider class for your IDMItem derived classes.   *
  71. *******************************************************************************/
  72. public:
  73. /*------------------------- Constructors/Destructor ----------------------------
  74. | No arguments are needed to construct objects of this class.                  |
  75. ------------------------------------------------------------------------------*/
  76.   IDMItemProvider     ( );
  77.  
  78. virtual
  79.   ~IDMItemProvider    ( );
  80.  
  81. /*--------------------------- Drag Item Provision ------------------------------
  82. | These functions define the linkage between the drag item provider and the    |
  83. | actual items:                                                                |
  84. |                                                                              |
  85. |   provideSourceItems   - Gives the provider an opportunity to attach IDMItem |
  86. |                          (or derived class) objects to the argument          |
  87. |                          IDMSourceOperation object.                          |
  88. |   provideTargetItemFor - Gives the provider an opportunity to replace        |
  89. |                          generic IDMItem objects with a derived class.       |
  90. |   provideLeaveSupport  - Gives the provider an opportunity to provide        |
  91. |                          support for the target leave event.                 |
  92. |   provideEnterSupport  - Gives the provider an opportunity to provide        |
  93. |                          support for the target enter event.                 |
  94. |   provideHelpFor       - Gives the provider an opportunity to provide        |
  95. |                          window-specific drop help.                          |
  96. ------------------------------------------------------------------------------*/
  97. virtual Boolean
  98.   provideSourceItems     ( const IDMSourceOperation::Handle &sourceOperation ),
  99.   provideEnterSupport    ( IDMTargetEnterEvent              &event ),
  100.   provideLeaveSupport    ( IDMTargetLeaveEvent              &event ),
  101.   provideHelpFor         ( IDMTargetHelpEvent               &event );
  102.  
  103. virtual IDMItem::Handle
  104.   provideTargetItemFor   ( const IDMItem::Handle            &dragItem );
  105.  
  106. protected:
  107. private: /*------------------------ PRIVATE ----------------------------------*/
  108. }; // class IDMItemProvider
  109.  
  110.  
  111. template < class T >
  112. class IDMItemProviderFor : public IDMItemProvider {
  113. typedef IDMItemProvider
  114.   Inherited;
  115. /*******************************************************************************
  116. * This is a template class that can be used to generate an IDMItemProvider     *
  117. * derived class for your derived IDMItem classes.                              *
  118. *                                                                              *
  119. * This class is derived from IDMItemProvider.  It will override the key        *
  120. * functions of the class and dispatch static functions of your IDMItem         *
  121. * derived class specified as the template argument.                            *
  122. *                                                                              *
  123. * provideSourceItems will call the static generateSourceItems function of      *
  124. * your IDMItem derived class.                                                  *
  125. *                                                                              *
  126. * provideTargetItemFor will create a new instance of your IDMItem derived      *
  127. * class.  This requires that your class provide a constructor that accepts     *
  128. * as argument a const IDMItem::Handle &.  This argument will be a handle to    *
  129. * the generic IDMItem that the target handler will have created.               *
  130. *                                                                              *
  131. * If you need to override additional IDMItemProvider functions (such as        *
  132. * provideHelpFor, provideEnterSupport, and so on), then you can derive         *
  133. * your item provider class from this template class.                           *
  134. *                                                                              *
  135. * For example:                                                                 *
  136. *                                                                              *
  137. *  class MyItem : public IDMItem {                                             *
  138. *  // Your item class stuff, including...                                      *
  139. *    MyItem ( const IDMItem::Handle &genericItem );                            *
  140. *  static Boolean                                                              *
  141. *    generateSourceItems( IDMSourceOperation *pSrcOp );                        *
  142. *  };                                                                          *
  143. *                                                                              *
  144. *  class MyItemProvider : public IDMItemProviderFor< MyItem > {                *
  145. *  public:                                                                     *
  146. *  // Other item provider functions...                                         *
  147. *  virtual Boolean                                                             *
  148. *    provideHelpFor( IDMTargetHelpEvent &helpEvent );                          *
  149. *  };                                                                          *
  150. *                                                                              *
  151. *******************************************************************************/
  152. public:
  153. /*------------------------- Constructors/Destructor ----------------------------
  154. | No arguments are needed to construct objects of this class.                  |
  155. ------------------------------------------------------------------------------*/
  156.   IDMItemProviderFor     ( ) {}
  157.  
  158. virtual
  159.   ~IDMItemProviderFor    ( ) {}
  160.  
  161.  
  162. /*--------------------------- Drag Item Provision ------------------------------
  163.   These functions are overrides of key IDMItemProvider functions which are
  164.   required to implement this template class:
  165.  
  166.   provideSourceItems   - This function is overridden in this class to delegate
  167.                          the request to the generateSourceItems static member
  168.                          function of the template argument class.  That
  169.                          function should create appropriate source items and
  170.                          add them to the argument operation.
  171.   provideTargetItemFor - This function is overridden in this class to create
  172.                          a new instance of the template argument class,
  173.                          constructed from the generic target item passed to
  174.                          this function.  This means that the template argument
  175.                          class must provide a constructor that accepts as
  176.                          argument a const IDMItem::Handle &.
  177. ------------------------------------------------------------------------------*/
  178. virtual Boolean
  179.   provideSourceItems   ( const IDMSourceOperation::Handle &sourceOperation )
  180. {
  181.   return( T::generateSourceItems( sourceOperation ) );
  182. }
  183.  
  184. virtual IDMItem::Handle
  185.   provideTargetItemFor ( const IDMItem::Handle &dragItem )
  186. {
  187.   return( (IDMItem::Handle)new T( dragItem ) );
  188. }
  189.  
  190. protected:
  191. private: /*------------------------ PRIVATE ----------------------------------*/
  192. }; // class IDMItemProviderFor
  193.  
  194. /*----------------------------------------------------------------------------*/
  195. /* Resume compiler default packing.                                           */
  196. /*----------------------------------------------------------------------------*/
  197. #pragma pack()
  198.  
  199. #endif //_IDMPROV_
  200.