home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
cset21v1.zip
/
IBMCPP
/
IBMCLASS
/
IDMITEM.HPP
< prev
next >
Wrap
C/C++ Source or Header
|
1993-10-22
|
33KB
|
652 lines
#ifndef _IDMITEM_
#define _IDMITEM_
/*******************************************************************************
* FILE NAME: idmitem.hpp *
* *
* DESCRIPTION: *
* This file contains the declaration(s) of the class(es): *
* IDMItem - Generic direct manipulation item class. *
* *
* COPYRIGHT: *
* Licensed Materials - Property of IBM *
* (C) Copyright IBM Corporation 1992, 1993 *
* All Rights Reserved *
* US Government Users Restricted Rights - Use, duplication, or *
* disclosure *
* restricted by GSA ADP Schedule Contract with IBM Corp. *
* *
*******************************************************************************/
#ifndef _IREFCNT_
#include <irefcnt.hpp>
#endif
#ifndef _IWINDOW_
#include <iwindow.hpp>
#endif
#ifndef _IDMCOMM_
#include <idmcomm.hpp>
#endif
#ifndef _ISTRING_
#include <istring.hpp>
#endif
/*----------------------------------------------------------------------------*/
/* Align classes on four byte boundary. */
/*----------------------------------------------------------------------------*/
#pragma pack(4)
/* Forward Declarations */
struct _DRAGITEM;
struct _HSTR;
class IDMSourceRenderEvent;
class IDMSourcePrepareEvent;
class IDMSourceEndEvent;
class IDMSourceDiscardEvent;
class IDMSourcePrintEvent;
class IDMTargetDropEvent;
class IDMTargetEndEvent;
class IDMSourceOperation;
class IDMTargetOperation;
class IDMOperation;
class IDMRenderer;
class IDMSourceRenderer;
class IDMTargetRenderer;
class IDMImage;
class IDMItem : public IRefCounted {
typedef IRefCounted
Inherited;
typedef IDM::DropIndicator
DropIndicator;
/*******************************************************************************
* Objects of this class represent generic items being dragged or dropped *
* during a direct manipulation operation. *
* *
* This class provides virtual functions that implement the base ICLUI support *
* for direct manipulation item objects. (Direct manipulation is also referred *
* to by the term drag/drop.) Windows create derived classes to support *
* specific drag item objects such as text item objects and container item *
* objects when an application end-user begins a direct manipulation operation. *
* *
* Objects of this class possess the following attributes in addition to *
* those inherited from its base class: *
* o Source window handle *
* o Types of the dragged object (true and additional) *
* o RMFs (Rendering Mechanisms and Formats) of the dragged object (native *
* and additional) *
* o Container name at the source of the drag *
* o Source name *
* o Suggested target name *
* o Item image which visually represents the item being dragged. *
* o Relative position of the corresponding item image in the drag pointer *
* o Source flags providing instructions on how to render an object, etc. *
* o Generic IString buffer contents to hold a various assortment of bytes *
* o Generic object pointer to hold a pointer to an object. *
* o Association with a source or target drag operation object (see *
* IDMSourceOperation or IDMTargetOperation) *
* o Association(s) with a selected source or target drag renderer object *
* see IDMSourceRenderer or IDMTargetRenderer), which are created by the *
* source handler (see IDMSourceHandler) and target handler (see *
* IDMTargetRenderer), respectively. *
* *
*******************************************************************************/
public:
/*------------------------------ IDMItem::Handle -------------------------------
| IDMItem::Handle provides access to the IDMItem objects associated with a |
| direct manipulation operation. The handle manages the references to the |
| IDMItem object and ensures that this object is not deleted until the direct |
| manipulation operation is completed. |
| |
| Use Handle to reference an item handle within this class and IDMItem::Handle |
| externally. |
| |
| The handle provides a "->" operator, which enables instances to be treated |
| just like a pointer to an IDMItem object. |
------------------------------------------------------------------------------*/
typedef IReference< IDMItem > Handle;
/*-------------------------- Constructors/Destructor ---------------------------
| You can construct generic objects of this class by providing one of the |
| following items: |
| o A pointer to the drag source operation, types, supported operations |
| and attributes |
| o A pointer to the drag target operation and drag item structure |
| o A copy constructor |
| o An item handle (for example, a copy constructor) |
------------------------------------------------------------------------------*/
IDMItem ( IDMSourceOperation *sourceOperation,
const IString &types,
const unsigned long supportedOperations = unknown,
const unsigned long attributes = none);
IDMItem ( IDMTargetOperation *targetOperation,
_DRAGITEM *dragItem );
IDMItem ( const IDMItem &dragItem );
IDMItem ( const Handle &item );
virtual
~IDMItem ( );
/*--------------------------------- Operators ---------------------------------+
| The following functions allow assignments of IDMItems: |
| operator = - Replaces the contents of an IDMItem. |
+-----------------------------------------------------------------------------*/
operator = ( const IDMItem &item );
operator = ( const Handle &item );
/*---------------------- Supported Operations Flags --------------------------
The following static members define a drag object's supported
operations flags. The valid supported operations are:
unknown - No supported drag operations are available.
copyable - The source object that is being dragged can be copied to
the specified drop location.
moveable - The source object that is being dragged can be moved to
the specified drop location.
linkable - The source object that is being dragged can be linked to
the specified object.
Note: These static members represent bit masks, patterns of characters used
to control portions of another pattern of characters. Any user defined values
must be greater than the linkable value.
------------------------------------------------------------------------------*/
static const unsigned long
unknown,
copyable,
moveable,
linkable;
/*---------------------------- Attributes Flags ------------------------------
The following static members define the drag object's attribute flags. The
valid attributes of dragged objects are:
none - No attributes are defined.
open - The source object is open
reference - The source object is a reference to another object
group - The source object is a group of objects
container - The source object is a container of other objects
prepare - The source object requires preparation before it
establishes a data transfer conversation
removableMedia - The source object is on removable media, or the source
object cannot be recovered after a move operation
Note: These static members represent bit masks, patterns of characters used
to control portions of another pattern of characters. Any user defined values
must be greater than the removableMedia value.
----------------------------------------------------------------------------*/
static const unsigned long
none,
open,
reference,
group,
container,
prepare,
removableMedia;
/*-------------------------------- Accessors -----------------------------------
| Instances of the IDMItem class have attributes that can be accessed by the |
| following functions: |
| sourceWindowHandle - Returns the handle of the source window for this |
| item. |
| sourceWindow - Returns a pointer to the source window for this |
| item. |
| containerName - Returns the source container name |
| sourceName - Returns the source object name |
| targetName - Returns the suggested target object name |
| attributes - Returns the control attributes for this item |
| supportedOperations - Returns the operations supported by this item |
| imageOffset - Returns the offset of the image origin |
| from the pointer hotspot. |
| setSourceWindowHandle - Sets the source window handle for this item. |
| setContainerName - Sets the source container name. |
| setTargetName - Sets the suggested target object "name". |
| setSourceName - Sets the source object "name". |
------------------------------------------------------------------------------*/
virtual IWindowHandle
sourceWindowHandle ( ) const;
virtual IWindow
*sourceWindow ( ) const;
virtual IString
containerName ( ) const,
sourceName ( ) const,
targetName ( ) const;
virtual unsigned long
attributes ( ) const,
supportedOperations ( ) const;
virtual ISize
imageOffset ( ) const;
IDMItem
&setSourceWindowHandle ( IWindowHandle window ),
&setContainerName ( const char *containerName ),
&setTargetName ( const char *targetName ),
&setSourceName ( const char *sourceName );
/*-------------------------------- Attributes ----------------------------------
| These functions permit the setting/testing of a variety of drag item |
| "attribute" flags: |
| isOpen - Indicates whether the dragged object is "open". |
| isReference - Indicates whether the dragged object is a |
| "reference" to another object. |
| isGroup - Indicates whether the item is a group of objects. |
| isContainer - Indicates whether the item is a container of other|
| objects. |
| isOnRemovableMedia - Indicates whether the item is on removable media |
| or cannot be recovered after a move operation. |
| requiresPreparation - Indicates whether the source requires preparation |
| prior to rendering. |
| setRequiresPreparation - Set/reset the "requiresPreparation" flag. |
| setOpen - Set/reset the "isOpen" flag. |
| setReference - Set/reset the "isReference" flag. |
| setGroup - Set/reset the "isGroup" flag. |
| setContainer - Set/reset the "isContainer" flag. |
| setOnRemovableMedia - Set/reset the "isOnRemovableMedia" flag. |
------------------------------------------------------------------------------*/
virtual Boolean
isOpen ( ) const,
isReference ( ) const,
isGroup ( ) const,
isContainer ( ) const,
isOnRemovableMedia ( ) const,
requiresPreparation ( ) const;
virtual IDMItem
&setRequiresPreparation ( Boolean requiresPrep = true ),
&setOpen ( Boolean open = true ),
&setReference ( Boolean reference = true ),
&setGroup ( Boolean group = true ),
&setContainer ( Boolean container = true ),
&setOnRemovableMedia ( Boolean onRemovableMedia = true );
/*-------------------------------- Operations ----------------------------------
| These functions permit the setting/querying of the supported direct |
| manipulation operations for this class: |
| canBeCopied - Indicates whether a copy operation is supported. |
| canBeLinked - Indicates whether a link operation is supported. |
| canBeMoved - Indicates whether a move operation is supported. |
| enableCopy - Enables or disables copy operation for the item. |
| enableLink - Enables or disables link operation for the item. |
| enableMove - Enables or disables move operation for the item. |
| supportedOperationsFor - Returns operations this item supports using the |
| specified RMFs. |
------------------------------------------------------------------------------*/
virtual Boolean
canBeCopied ( ) const,
canBeLinked ( ) const,
canBeMoved ( ) const;
virtual IDMItem
&enableCopy ( Boolean copyable = true ),
&enableLink ( Boolean linkable = true ),
&enableMove ( Boolean moveable = true );
virtual unsigned long
supportedOperationsFor ( const IString &selectedRMFs ) const;
/*------------------------------- Object Type ----------------------------------
| These functions provide means for setting/querying the "type(s)" of the |
| item: |
| trueType - Returns the "true type" of the item. |
| types - Returns all types for the item. Individual types are |
| separated by a comma. |
| hasType - Indicates whether the item supports a particular type. |
| setTrueType - Sets the "true type" of the item. |
| setTypes - Sets the types for the item. Issue setTypes("") to remove |
| all types for the item. |
| addType - Adds an additional type or types (i.e. "type1,type2") |
| removeType - Removes a type from this item. |
| replaceType - Replaces a type for this item. |
------------------------------------------------------------------------------*/
virtual IString
trueType ( ) const,
types ( ) const;
virtual Boolean
hasType ( const char *aType ) const;
virtual IDMItem
&setTrueType ( const char *aType ),
&setTypes ( const char *types ),
&addType ( const char *aType ),
&removeType ( const char *aType );
/*----------------------- Rendering Mechanisms/Formats -----------------------
| These functions provide means for querying or setting the rendering |
| mechanism and/or format of the item: |
| nativeRMF - Returns the "native" rendering mechanism and format of |
| the item. |
| nativeRM - Returns the "native" rendering mechanism of the item. |
| nativeRF - Returns the "native" rendering format of the item. |
| rmfs - Returns all rendering mechanisms and formats of the item. |
| supportsRMF - Indicates whether the item supports a specific rendering |
| mechanism and format. |
| setNativeRMF - Sets the "native" RMF to the argument type. |
| setRMFs - Sets the RMFs for the item. Issue setRMFs("") to remove |
| all RMFs for the item. |
| addRMF - Adds an additional RMF or RMFs (i.e. "<rm1,rf1>,<rm2,rf2>") |
| removeRMF - Removes a RMF from this item. |
| |
| Note: Functions that get and set RMFs use the following RMF notation: |
| "<rm1,rf1>,<rm2,rf2>" - Ordered pair form |
| "(rm1,rm2)x(rf1)" - Cross product form |
------------------------------------------------------------------------------*/
virtual IString
nativeRMF ( ) const,
nativeRM ( ) const,
nativeRF ( ) const,
rmfs ( ) const;
virtual Boolean
supportsRMF ( const IString &rmf ),
supportsRMF ( const IString &rm,
const IString &rf );
virtual IDMItem
&setNativeRMF ( const IString &rmf ),
&setNativeRMF ( const IString &rm,
const IString &rf ),
&setRMFs ( const IString &rmfs ),
&addRMF ( const IString &rmf ),
&addRMF ( const IString &rm,
const IString &rf ),
&removeRMF ( const IString &rmf ),
&removeRMF ( const IString &rm,
const IString &rf );
/*------------------- Rendering Mechanisms/Formats Utilities -----------------
| These static functions provide means for constructing/querying the rendering |
| mechanism and/or format: |
| appendRMF - Appends another rmf to an rmf string, separated by a |
| comma, if required. |
| compressRMFs - Returns a compressed version of the argument rmf |
| string with all possible cross products converted |
| to cross-product form. |
| deleteRMF - Deletes a particular rmf from an rmf string. |
| matchingRMFs - Returns the intersection of the two rmf strings. An |
| optional argument indicates that only the first |
| matching rmf is required. |
| rfForThisProcess - Returns DRF_PROCESS=pid where pid is the current |
| process identifier. |
| rfFrom - Returns the rendering format from an rmf. |
| rmfFrom - Constructs a rendering mechanism and format ordered |
| pair (i.e. "<rm,rf>"). If multiple rm's or rf's are |
| included, you should use rmfsFrom, instead. |
| rmFrom - Returns the rendering mechanism from an rmf. |
| rmfsFrom - Returns a full rmf string from either a single rmf |
| string, or separate rm/rf strings. The result will |
| have all cross-products expanded. |
------------------------------------------------------------------------------*/
static void
appendRMF ( IString &rmfs, const IString &rmf ),
deleteRMF ( IString &rmfs, const IString &rmf );
static IString
compressedRMFs ( const IString &rmfs ),
matchingRMFs ( const IString &rmfs1,
const IString &rmfs2,
Boolean firstOnly = false ),
rfForThisProcess ( ),
rfFrom ( const IString &rmf ),
rmfFrom ( const IString &rm,
const IString &rf ),
rmFrom ( const IString &rmf ),
rmfsFrom ( const IString &rmfs ),
rmfsFrom ( const IString &rm,
const IString &rf );
/*---------------------------- Selected Renderer -------------------------------
| These functions provide support to set/get the renderer that was selected |
| for this item. Also, functions are provided to set/get the rendering |
| mechanism and format (RMF) that was selected from those supported within |
| the renderer: |
| renderer - Returns the position of the selected renderer for this |
| item. |
| setRenderer - Sets the position of the selected renderer for this item. |
| selectedRMF - Returns selected RMF for this item in ordered pair |
| (i.e. "<rm,rf>") or cross product (i.e. "(rm)x(rf1,rf2)") |
| format. |
| setSelectedRMF - Sets selected RMF for this item. Expects the argument |
| to be in ordered pair or cross product format. |
------------------------------------------------------------------------------*/
unsigned
renderer ( ) const;
IString
selectedRMF ( ) const;
IDMItem
&setRenderer ( unsigned position ),
&setSelectedRMF ( const IString &rmf );
/*------------------------------- Drop Status ----------------------------------
| These functions provide support to set/get the drop status for this item: |
| dropStatus - Returns drop status for this item. |
| setDropStatus - Sets drop status for this item. |
------------------------------------------------------------------------------*/
DropIndicator
dropStatus ( ) const;
IDMItem
&setDropStatus ( DropIndicator status );
/*---------------------- Source Renderering (Callbacks) ------------------------
| These functions provide source renderering support: |
| sourceRender - Called to give the item opportunity to acquire the data |
| that will be transferred to the target. |
| sourcePrepare - Called to give the item opportunity to acquire |
| information needed by the target, perform a task |
| required by a target prior to target renderering, or |
| perform setup required by a source renderer. |
| sourceEnd - Called by the source handler when the target has informed |
| it that the target has finished processing the data that |
| was associated with the dropped item. Source cleanup for |
| the item should occur here. |
| sourceDiscard - Called by the IDMSourceRenderer::sourceDiscard() |
| function when it was indicated that the source window has |
| responsibility for discarding the item. |
| sourcePrint - Called by the IDMSourceRenderer::sourcePrint() |
| function when it was indicated that the source window has |
| responsibility for printing the item. |
------------------------------------------------------------------------------*/
virtual Boolean
sourceRender ( IDMSourceRenderEvent &event ),
sourcePrepare ( IDMSourcePrepareEvent &event ),
sourceEnd ( IDMSourceEndEvent &event ),
sourceDiscard ( IDMSourceDiscardEvent &event ),
sourcePrint ( IDMSourcePrintEvent &event );
/*---------------------- Target Rendering (Callbacks) --------------------------
| These functions provide target renderering support: |
| targetDrop - Called to give the item the opportunity to "write" the |
| data that was transferred to the target window. Target |
| cleanup for the item should occur here. |
| targetEnd - Called by the target handler when the source has informed |
| it that the source has finished rendering the data that |
| was associated with the dropped item. |
------------------------------------------------------------------------------*/
virtual Boolean
targetDrop ( IDMTargetDropEvent &event ),
targetEnd ( IDMTargetEndEvent &event );
/*---------------------------- Drag Image Support ------------------------------
| These functions provide drag image support: |
| image - Returns the drag image for this item, or 0 if none. |
| setImage - Sets or removes this item's drag image |
| hasImage - Returns true if item has an image. |
------------------------------------------------------------------------------*/
virtual IDMImage
&image ( );
virtual IDMItem
&setImage ( IDMImage &image );
Boolean
hasImage ( ) const;
/*------------------------------ Source Items ----------------------------------
| This function generates source items: |
| generateSourceItems - Generates generic items. |
------------------------------------------------------------------------------*/
static Boolean
generateSourceItems ( IDMSourceOperation *sourceOperation );
/*------------------------------ Drag Operation --------------------------------
| These functions provide access to the drag operations: |
| sourceOperation - Returns the source operation for this item, or 0 |
| if request was made by target. |
| targetOperation - Returns the target operation for this item, or 0 |
| if request was made by source. |
------------------------------------------------------------------------------*/
virtual IDMSourceOperation
*sourceOperation ( );
virtual IDMTargetOperation
*targetOperation ( );
/*---------------------------- Associated Object -------------------------------
| These functions provide read/write access to data associated with the |
| direct manipulation operation. The contents functions are used with |
| the rendering mechanism IDM::rmLibrary. The object functions are used |
| with the rendering format IDM::rfProcess: |
| contents - Returns the contents of the drag item. |
| contentsSize - Returns the size of the contents of the drag item. |
| setContents - Sets contents of the drag item. Derived class should |
| override to provide specific implementation based upon |
| characteristics of the window. |
| object - Returns the pointer to the object. |
| setObject - Sets the pointer to the object. |
------------------------------------------------------------------------------*/
virtual IString
contents ( ) const;
virtual unsigned long
contentsSize ( ) const;
virtual Boolean
setContents ( const IString &data );
virtual void
*object ( ) const;
virtual IDMItem
&setObject ( void *pointerToObject );
/*-------------------------------- Utilities -----------------------------------
| This function provides utility services used to implement this class: |
| sourceItemFor - Retrieves the source item handle based upon the target |
| item if and only if we're in the same process, and |
| the parameter is a target item. Otherwise, 0 is returned. |
------------------------------------------------------------------------------*/
static Handle
sourceItemFor ( const Handle &targetItem );
protected:
/*------------------------------- Implementation -------------------------------
| The following function/data membe provide implement features for this class: |
| generateSourceName - Generates the source name for the implementation of |
| the IDM::rfText renderering format. |
| strContents - Holds data (contents) of the drag item. This data member is |
| protected to allow derived classes to either return the |
| contents of it via the contents() function or allow the |
| object() function to return a pointer to it per a derived |
| implementation. |
------------------------------------------------------------------------------*/
IString
generateSourceName ( );
IString
strContents;
private: /*------------------------ PRIVATE ----------------------------------*/
friend class IDMSourceOperation;
friend class IDMTargetOperation;
friend class IDMSourceRenderEvent;
friend class IDMSourceRenderer;
friend class IDMTargetRenderer;
friend class IDMTargetEndEvent;
friend class IDMItemUtilities;
unsigned long
dragSupOps,
dragAttrs;
IWindowHandle
sourceWndh;
IDMImage
*pIDMImage;
ISize
sizeImageOffset;
IString
strContainerName,
strSourceName,
strTargetName,
strTypes,
strRMFs,
strSelectedRMF;
IDMSourceOperation
*pDMSrcOperation;
IDMTargetOperation
*pDMTgtOperation;
unsigned
rendererPosition;
DropIndicator
drpStatus;
void
*pObject;
_DRAGITEM
*pPMDragItem;
_DRAGITEM
*PMDragItem ( );
void
setPMDragItem ( _DRAGITEM *pDragItem );
void
asPMDragItem ( _DRAGITEM *pDragItem );
static IString
stringFromHandle (const IStringHandle& hstr);
IStringHandle
handleFromString (IString inputStr);
static IString
nextRMOrRFFrom ( const IString &rmfs,
unsigned &position );
static void
setHSTR ( unsigned long &oldHSTR,
const IStringHandle &newHSTR );
}; // IDMItem
/*----------------------------------------------------------------------------*/
/* Resume compiler default packing. */
/*----------------------------------------------------------------------------*/
#pragma pack()
#ifndef I_NO_INLINES
#include <idmitem.inl>
#endif
#endif // _IDMITEM_