home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / cluidm.zip / idmrendr.hpp < prev    next >
Text File  |  1993-05-05  |  21KB  |  372 lines
  1. #ifndef _IDMRENDR_
  2. #define _IDMRENDR_
  3. /*******************************************************************************
  4. * FILE NAME: idmrendr.hpp                                                      *
  5. *                                                                              *
  6. * DESCRIPTION:                                                                 *
  7. *   This file contains the declaration(s) of the class(es):                    *
  8. *     IDMRenderer          - Direct manipulation renderer common base class.   *
  9. *     IDMSourceRenderer    - Source renderer.                                  *
  10. *     IDMSrcRendererHandle - Source renderer handle.                           *
  11. *     IDMTargetRenderer    - Target renderer.                                  *
  12. *     IDMTgtRendererHandle - Target renderer handle.                           *
  13. *                                                                              *
  14. * COPYRIGHT:                                                                   *
  15. *   Licensed Materials - Property of IBM                                       *
  16. *   (C) Copyright IBM Corporation 1992, 1993                                   *
  17. *   All Rights Reserved                                                        *
  18. *   US Government Users Restricted Rights - Use, duplication, or               *
  19. *   disclosure                                                                 *
  20. *   restricted by GSA ADP Schedule Contract with IBM Corp.                     *
  21. *                                                                              *
  22. * $Log:   M:/ibmclass/idrag/vcs/idmrendr.hpv  $
  23. //
  24. //   Rev 1.2   05 May 1993 16:36:00   unknown
  25. //Source Render Prepare changes
  26. //
  27. //   Rev 1.1   30 Apr 1993 11:45:40   HAGGAR
  28. //No change.
  29. //
  30. //   Rev 1.0   22 Apr 1993 10:44:08   HAGGAR
  31. //Initial revision.
  32. *******************************************************************************/
  33. #ifndef _IREFCNT_
  34.   #include <irefcnt.hpp>
  35. #endif
  36.  
  37. #ifndef _IDMEVENT_
  38.   #include <idmevent.hpp>
  39. #endif
  40.  
  41. #ifndef _ISTRING_
  42.   #include <istring.hpp>
  43. #endif
  44.  
  45. /* Forward Declarations */
  46. struct _DRAGTRANSFER;
  47. class IDMTgtItemHandle;
  48. class IDMItem;
  49. class IDMSourceItem;
  50. class IDMTargetItem;
  51.  
  52.  
  53. class IDMRenderer : public IRefCounted {
  54. typedef IRefCounted
  55.   Inherited;
  56. /*******************************************************************************
  57. * This is the common base class for the source and target direct               *
  58. * manipulation renderer classes.                                               *
  59. *                                                                              *
  60. * Objects of this class perform the "rendering" of items during direct         *
  61. * manipulation.  Such "rendering" is essentially the transfer of the dragged   *
  62. * object from the source to the target window.                                 *
  63. *                                                                              *
  64. * This class is an abstract base class that defines the common protocol of     *
  65. * source and target renderers.  The derived classes IDMSourceRenderer and      *
  66. * IDMTargetRenderer, declared below, define the specific protocol for source   *
  67. * and target renderers.                                                        *
  68. *                                                                              *
  69. * A generic renderer possesses the following attributes:                       *
  70. *   o A set of supported types.  These are the types of dragged items that     *
  71. *     this renderer can work with.                                             *
  72. *   o A set of supported rendering mechanisms and rendering formats (RMFs).    *
  73. *     These describe the various means by which this renderer can transfer     *
  74. *     the dragged object.                                                      *
  75. *                                                                              *
  76. * The operations that can be performed on objects of this class fall into      *
  77. * two basic categories:                                                        *
  78. *   o Queries as to whether the renderer can render a given item.              *
  79. *   o Requests to perform one of the basic rendering processes.                *
  80. *******************************************************************************/
  81. public:
  82.  
  83. /*------------------------ Constructor/Destructor ------------------------------
  84. | Generic objects of this class are constructed without formal parameters.     |
  85. ------------------------------------------------------------------------------*/
  86.   IDMRenderer             ( );
  87.   virtual ~IDMRenderer    ( );
  88.  
  89. /*------------------------- Supported Types and RMFs ---------------------------
  90.   These functions return the types and renderering mechanisms/formats
  91.   supported by an IDMRenderer object:
  92.     supportedTypes - Returns the types of items supported by the renderer.
  93.     supportedRMFs  - Returns the rendering mechanisms and formsts supported
  94.                      by this renderer.
  95. ------------------------------------------------------------------------------*/
  96. virtual IString
  97.   supportedTypes    ( ) const,
  98.   supportedRMFs     ( ) const;
  99.  
  100. /*--------------------------------- Testing ------------------------------------
  101.   These function permit querying of the renderer's capability to render a
  102.   given item:
  103.     canSourceRender - Returns true if the source renderer can render an
  104.                       object with a given type (or set of possible types).
  105.     canSourceRender - Returns true if the source renderer can render an
  106.                       object with a given selecte type + selected RMF +
  107.                       selected operation.
  108.     canTargetRender - Returns true if the target renderer can render an
  109.                       object with a given type + set of possible source RMFs +
  110.                       default operation.
  111. ------------------------------------------------------------------------------*/
  112. virtual Boolean
  113.   canSourceRender    ( const IString  &types ),
  114.   canSourceRender    ( const IString  &selectedType,
  115.                        const IString  &selectedRMF,
  116.                        unsigned short selectedOp ),
  117.   canTargetRender    ( const IString  &types,
  118.                        const IString  &sourceRMFs,
  119.                        unsigned short defaultOp );
  120.  
  121. /*-------------------------------- Rendering -----------------------------------
  122.   These functions are called to actually perform the rendering:
  123.     sourceRender - Called when the target renderer requests that a source
  124.                    renderer render an item.
  125.     targetRender - Called when a dragged operation is dropped on a target.
  126.     sourceRenderComplete - Called (on the target renderer) when the source
  127.                    renderer indicates it has completed a sourceRender.
  128.     renderComplete - Invoked against the target renderer when it has
  129.                    completed rendering (generates DM_ENDCONVERSATIION),
  130.                    called against the source handler when the
  131.                    DM_ENDCONVERSATION event occurs.
  132. ------------------------------------------------------------------------------*/
  133. virtual IDMRenderer
  134.  &sourceRender            ( const IDMSrcItemHandle &dragItem ),
  135.  &targetRender            ( const IDMTgtItemHandle &dragItem ),
  136.  
  137.  &sourceRenderComplete    ( const IDMSrcItemHandle &dragItem ),
  138.  
  139.  &renderComplete          ( const IDMItem &dragItem );
  140.  
  141. protected:
  142. /*------------------------- Supported Types and RMFs ---------------------------
  143.   These functions set the types and renderering mechanisms/formats
  144.   supported by an IDMRenderer object:
  145.     setSupportedTypes - Sets the types of items supported by the renderer.
  146.     setSupportedRMFs  - Sets the rendering mechanisms and formsts supported
  147.                         by this renderer.
  148. ------------------------------------------------------------------------------*/
  149. virtual IDMRenderer
  150.  &setSupportedTypes    ( const IString &aType ),
  151.  &setSupportedRMFs     ( const IString &aRMF );
  152.  
  153. private: /*------------------------ PRIVATE ----------------------------------*/
  154.  
  155. IString
  156.   strTypes,
  157.   strRMFs;
  158.  
  159. }; // class IDMRenderer
  160.  
  161.  
  162. class IDMSourceRenderer : public IDMRenderer {
  163. /*******************************************************************************
  164. * Objects of this class provide source rendering when a direct manipulation    *
  165. * operation is performed.  Instances of this class are "registered" with the   *
  166. * source handler.  The handler selects a renderer for a given drag item and    *
  167. * invokes rendering functions of the renderer when source rendering events     *
  168. * occur.                                                                       *
  169. *******************************************************************************/
  170. public:
  171. /*--------------------------------- Testing ------------------------------------
  172. | These functions are used to test whether a given item can be rendered:       |
  173. |   canRender - Returns true if the renderer can render items with the         |
  174. |               argument attribute(s).                                         |
  175. ------------------------------------------------------------------------------*/
  176. virtual Boolean
  177.   canRender    ( const IString  &types ),
  178.   canRender    ( const IString  &selectedType,
  179.                  const IString  &selectedRMF,
  180.                  unsigned short selectedOp );
  181.  
  182. /*-------------------------------- Rendering -----------------------------------
  183. | These functions are called to perform rendering operations:                  |
  184. |   renderPrepare  - Called when a "render prepare" event occurs for a drag    |
  185. |                    item to be rendered by this renderer.                     |
  186. |   render         - Called when a "render" event occurs for a drag item to    |
  187. |                    be rendered by this renderer.                             |
  188. |   renderComplete - Called when a "completion" event occurs for a drag item   |
  189. |                    to be rendered by this renderer.                          |
  190. ------------------------------------------------------------------------------*/
  191. virtual IDMSourceRenderer
  192.  &renderPrepare     ( IDMSourcePrepareEvent &event ),
  193.  &render            ( IDMSourceRenderEvent  &event ),
  194.  &renderComplete    ( const IDMSourceItem   &sourceItem,
  195.                       IDMSourceEndEvent     &event );
  196.  
  197. }; // class IDMSourceRenderer
  198.  
  199.  
  200. class IDMSrcRendererHandle : public IReference< IDMSourceRenderer > {
  201. /*******************************************************************************
  202. * Objects of this class provide access to IDMSourceRenderer objects            *
  203. * associated with a direct manipulation event.  This "handle" class manages    *
  204. * references to the IDMSourceRenderer object to ensure that it is not          *
  205. * deleted until the drag operation is completed.                               *
  206. *                                                                              *
  207. * This class provides a "->" operator that enables instances to be treated     *
  208. * just like a pointer to an IDMSourceRenderer object.                          *
  209. *                                                                              *
  210. * Example:                                                                     *
  211. *   // BUGBUG - Provide example                                                *
  212. *                                                                              *
  213. *   // IDMSrcOperationHandle providing access to the source drag operation...  *
  214. *   IDMSrcOperationHandle                                                      *
  215. *     srcOperation;                                                            *
  216. *                                                                              *
  217. *   // Process items...                                                        *
  218. *   for( int i = 0; i < srcOperation->numberOfItems(); i++ )                   *
  219. *     {                                                                        *
  220. *     IDMSrcItemHandle                                                         *
  221. *       item = srcOperation->item( i );                                        *
  222. *     // If item is C code, then this handler can accept it...                 *
  223. *     if ( item->trueType() == IDragItem::cCode )                              *
  224. *       // Note: The following line is tentative and should be amended         *
  225. *       //       per the actual drag item protocol when it is completed.       *
  226. *       item -> enableDrop();                                                  *
  227. *     }                                                                        *
  228. *                                                                              *
  229. * This class has no members.  It is essentially a synonym for the type         *
  230. * IReference< IDMSourceRenderer >.                                             *
  231. *******************************************************************************/
  232. public:
  233.   IDMSrcRendererHandle (IDMSourceRenderer *pIDMSrcRenderer);
  234.   ~IDMSrcRendererHandle ( );
  235.  
  236. /*--------------------------------- Operators ---------------------------------+
  237. | Operators defined for IDMSrcRendererHandle:                                  |
  238. |   == - Overload definition to handle comparisons of source drag item handles.|
  239. |   <  - Overload definition to handle comparisons of source drag item handles.|
  240. +-----------------------------------------------------------------------------*/
  241. Boolean
  242.   operator ==    ( const IDMSrcRendererHandle &sourceRenderer ) const,
  243.   operator <     ( const IDMSrcRendererHandle &sourceRenderer ) const;
  244.  
  245. }; // IDMSrcRendererHandle
  246.  
  247.  
  248. class IDMTargetRenderer : public IDMRenderer {
  249. /*******************************************************************************
  250.   Objects of this class provide target rendering when a direct manipulation
  251.   operation is performed.  Instances of this class are "registered" with the
  252.   target handler.  The handler selects a renderer for a given drag item and
  253.   invokes rendering functions of the renderer when target rendering events
  254.   occur.
  255. *******************************************************************************/
  256. public:
  257.  
  258. /*------------------------ Constructor/Destructor ------------------------------
  259. | Generic objects of this class are constructed without formal parameters.     |
  260. ------------------------------------------------------------------------------*/
  261.   IDMTargetRenderer     ( );
  262.   ~IDMTargetRenderer    ( );
  263.  
  264. /*--------------------------------- Testing ------------------------------------
  265. | These functions are used to test whether a given item can be rendered:       |
  266. |   canRender - Returns drop indicator per the renderers ability to render     |
  267. |               the item with the argument attributes.                         |
  268. ------------------------------------------------------------------------------*/
  269. virtual IDMSourceNotifyEvent::DropIndicator
  270.   canRender         ( const IString &aType,
  271.                       const IString &sourceRMFs,
  272.                       unsigned short defaultOp,
  273.                       const IDMTgtItemHandle dragItem );
  274.  
  275. virtual Boolean
  276.   checkOperation    ( const IDMTgtItemHandle dragItem,
  277.                       unsigned short defaultOp );
  278.  
  279. /*-------------------------------- Rendering -----------------------------------
  280. | These functions are called to perform rendering operations:                  |
  281. |   render         - Called when a "drop" event occurs for a drag item to      |
  282. |                    be rendered by this renderer.                             |
  283. |   renderComplete - Called when a "completion" event occurs for a drag item   |
  284. |                    to be rendered by this renderer.                          |
  285. ------------------------------------------------------------------------------*/
  286. virtual IDMTargetRenderer
  287.  &render            ( const IDMTgtItemHandle &dragItem,
  288.                       IDMTargetDropEvent     &dropEvent ),
  289.  &renderComplete    ( const IDMTargetItem    &targetItem,
  290.                       IDMTargetEndEvent      &event );
  291.  
  292. protected:
  293. /*------------------------------ Implementation --------------------------------
  294. | These functions provide utilities used to implement this class:              |
  295. |   sourceRender             - Send "render" event to source window to request |
  296. |                              source rendering for the argument item.         |
  297. |   sourceRenderPrepare      - Send "prepare" event to source window to request|
  298. |                              source preparation for the argument item.       |
  299. |   informSourceOfCompletion - Send "end" event to source to inform it that    |
  300. |                              rendering is completed for the argument item.   |
  301. ------------------------------------------------------------------------------*/
  302. virtual IDMTargetRenderer
  303.  &sourceRender                ( const IDMTgtItemHandle &dragItem,
  304.                                 IDMTargetDropEvent     &dropEvent ),
  305.  &sourceRenderPrepare         ( const IDMTgtItemHandle &dragItem,
  306.                                 IDMTargetDropEvent     &dropEvent ),
  307.  &informSourceOfCompletion    ( const IDMTgtItemHandle &dragItem );
  308.  
  309. private: /*------------------------ PRIVATE ----------------------------------*/
  310.  
  311. _DRAGTRANSFER *dragTransfer (const IDMTgtItemHandle &dragItem,
  312.                              IDMTargetDropEvent     &dropEvent);
  313. _DRAGTRANSFER
  314.  *pPMDragTransfer;
  315.  
  316. }; // class IDMTargetRenderer
  317.  
  318.  
  319. class IDMTgtRendererHandle : public IReference< IDMTargetRenderer > {
  320. /*******************************************************************************
  321. * Objects of this class provide access to IDMTargetRenderer objects            *
  322. * associated with a direct manipulation event.  This "handle" class manages    *
  323. * references to the IDMTargetRenderer object to ensure that it is not          *
  324. * deleted until the drag operation is completed.                               *
  325. *                                                                              *
  326. * This class provides a "->" operator that enables instances to be treated     *
  327. * just like a pointer to an IDMTargetRenderer object.                          *
  328. *                                                                              *
  329. * Example:                                                                     *
  330. *   // BUGBUG - Provide example                                                *
  331. *                                                                              *
  332. *   // IDMTgtOperationHandle providing access to the source drag operation...  *
  333. *   IDMTgtOperationHandle                                                      *
  334. *     tgtOperation;                                                            *
  335. *                                                                              *
  336. *   // Process items...                                                        *
  337. *   for( int i = 0; i < tgtOperation->numberOfItems(); i++ )                   *
  338. *     {                                                                        *
  339. *     IDMTgtItemHandle                                                         *
  340. *       item = tgtOperation->item( i );                                        *
  341. *     // If item is C code, then this handler can accept it...                 *
  342. *     if ( item->trueType() == IDragItem::cCode )                              *
  343. *       // Note: The following line is tentative and should be amended         *
  344. *       //       per the actual drag item protocol when it is completed.       *
  345. *       item -> enableDrop();                                                  *
  346. *     }                                                                        *
  347. *                                                                              *
  348. * This class has no members.  It is essentially a synonym for the type         *
  349. * IReference< IDMTargetRenderer >.                                             *
  350. *******************************************************************************/
  351. public:
  352.   IDMTgtRendererHandle (IDMTargetRenderer *pIDMTgtRenderer);
  353.   ~IDMTgtRendererHandle ( );
  354.  
  355. /*--------------------------------- Operators ---------------------------------+
  356. | Operators defined for IDMTgtRendererHandle:                                  |
  357. |   == - Overload definition to handle comparisons of target drag item handles.|
  358. |   <  - Overload definition to handle comparisons of target drag item handles.|
  359. +-----------------------------------------------------------------------------*/
  360. Boolean
  361.   operator ==    ( const IDMTgtRendererHandle &targetRenderer ) const,
  362.   operator <     ( const IDMTgtRendererHandle &targetRenderer ) const;
  363.  
  364. }; // IDMTgtRendererHandle
  365.  
  366.  
  367. #ifndef I_NO_INLINES
  368.   #include <idmrendr.inl>
  369. #endif
  370.  
  371. #endif // _IDMRENDR_
  372.