### IDMItem

  The IDMItem class represents items in a direct manipulation. The items are commonly known as source and target items. Use this class to create source items when starting a direct manipulation on a source window, and target items when dragging over a potential target window.

  This class provides virtual functions implementing base support for direct manipulation item objects in the Open Class Library. You can create derived classes to support specific items, such as text item objects and container item objects.

  Objects of this class have the following attributes in addition to those inherited from its base class:

  - A source window handle.
  - The types of the dragged object (true and additional).
  - The rendering mechanisms and formats (RMFs) of the dragged object (native and additional).
  - The container name of the IContainerControl object which is the source of the direct manipulation operation.
  - The source name.
  - The suggested target name.
  - The item image that visually represents the item while it is being dragged.
  - The offset from the pointing device to the origin of the image for this item.
  - The source flags providing instructions on how to render an object, such as making the object copyable only or identifying the object as a container of other objects.
  - The generic IString buffer contents, which hold a various assortment of bytes that represents the item's data.

    IDMSourceRenderer and IDMTargetRenderer objects typically transfer the contents between the source and target windows. The four objects involved in the transfer of the contents (source item, source renderer, target item, and target renderer) must agree on and select a supported RMF.

    For example, IDMEFItem, IDMSourceRenderer, and IDMTargetRenderer use the item's contents to hold the source entry field text. Derived item classes can use this attribute optionally, provided the renderers they work with use the attribute in a compatible fashion.

  - The generic object pointer, which holds a pointer to any type of object.

    When you use the library-defined rendering mechanism and the process rendering format, , the object pointed to is the object being dragged. Therefore, if the target window is in the same process as the source window, the target window can access the dragged object directly.

    As with the item's contents, the source items, target items, source renderers, and target renderers must agree on the nature of the value of this field, and derived item classes (and renderer classes) can use this attribute optionally.

  - An association with a source or target drag operation object (see IDMSourceOperation or IDMTargetOperation ).
  - Associations with a selected source or target drag renderer object (see IDMSourceRenderer or IDMTargetRenderer ), which the source handler or target handler creates, respectively.

#### OS/2 Considerations

  The IDMItem class is a wrapper for the DRAGITEM structure.

### IDMItem - Member Functions and Data by Group

### Constructors & Destructor

Use these members to construct, copy, assign, and destruct objects of this class.

~IDMItem

      public:
      virtual ~IDMItem()

  This destructor decrements the drag item's reference count. The drag item will not be actually destroyed until its reference count is 0. The drag item's reference count is incremented everytime an IDMItem::Handle object is created.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

IDMItem

  Overload 1

      public:
      IDMItem(const Handle& item)

  item
    A reference to a handle of a generic drag item that is created by the Open Class Library.

  Use this constructor to construct drag items for the target of a direct manipulation. It is called by the member function, IDMItemProviderFor::provideTargetItemFor, of the drag item provider for the derived item class.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      IDMItem( IDMTargetOperation* targetOperation,
               _DRAGITEM* dragItem )

  targetOperation
    A pointer to the drag target operation object to which this drag item object is to be added.
  dragItem
    A pointer to the OS/2 Presentation Manager DRAGITEM structure that this item provides a wrapper for.

  The Open Class Library uses this constructor to construct generic drag items for the target of a direct manipulation. You do not need to call it directly.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 3

      public:
      IDMItem( IDMSourceOperation* sourceOperation,
               const IString& types,
               const unsigned long supportedOperations = unknown,
               const unsigned long attributes = none )

  sourceOperation
    A pointer to the drag source operation object to which this drag item object is to be added.
  types
    A reference to a drag item type or types. Use a comma to separate the individual types if multiple types are identified.
  supportedOperations
    Identifies the supported operations flags. Operations supported by the Open Class Library are IDMItem::copyable, IDMItem::linkable, and IDMItem::moveable. You can also specify user-defined operations.
  attributes
    Identifies item attribute flags. Attributes supported by the Open Class Library are IDMItem::none, IDMItem::open, IDMItem::reference, IDMItem::group, IDMItem::container, IDMItem::prepare, and IDMItem::removableMedia. You can also specify user-defined attributes.

  Use this constructor to construct items for the source of a direct manipulation. It is called by the member function, IDMItem::generateSourceItems.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 4

      public:
      IDMItem(const IDMItem& dragItem)

  dragItem
    A reference to a drag item object to copy.

  Use this constructor, a copy constructor, to make a copy of an existing IDMItem object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

operator =

  Overloaded definition of the assignment operation to handle assignments of drag items to other drag items.

  This operator increments the drag operation's reference count. The drag operation's reference count is used to manage the destruction of the respective source and target operation objects.

  Overload 1

      public:
      IDMItem& operator =(const IDMItem& item)

  item
    A reference to a drag item object to copy.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      Handle operator =(const Handle& item)

  item
    A reference to a handle of a drag item object to copy.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Attribute Flags

Use these static members to define the drag item's attribute flags.
Note: These static members represent bit masks, which are patterns of bits used to control portions of another pattern of bits. Any user-defined values must be greater than the IDMItem::removableMedia value.

container

      public:
      static const unsigned long container

  The source object is a container of other objects.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

group

      public:
      static const unsigned long group

  The source object is a group of objects.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

none

      public:
      static const unsigned long none

  No attributes are defined for the source object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

open

      public:
      static const unsigned long open

  The source object is open.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

prepare

      public:
      static const unsigned long prepare

  The source object requires preparation before it establishes a data transfer conversation.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

reference

      public:
      static const unsigned long reference

  The source object is a reference to another object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

removableMedia

      public:
      static const unsigned long removableMedia

  The source object is on removable media, or the source object cannot be recovered after a move operation.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Drag Image Support

Use these members to set and query the image for the drag item.

hasImage

      public:
      bool hasImage() const

  Returns true if the drag item has an associated image.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

image

      public:
      virtual IDMImage& image()

  Returns a reference to the drag image associated with the drag item. If a drag image is not associated with the drag item, a default drag image is created, associated with the drag item, and returned.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setImage

      public:
      virtual IDMItem& setImage(IDMImage& image)

  Sets the item's drag image.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Drop Status

Use these members to set and query the item's drop status. The drop status determines if this item can be dropped on its current target.

dropStatus

      public:
      DropIndicator dropStatus() const

  Returns the drop status for the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setDropStatus

      public:
      IDMItem& setDropStatus(DropIndicator status)

  Sets the drop status for the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Item Attributes

Use these members to set and query attributes of an item. The attributes include the source and target name, source and target window, and general container information.

attributes

      public:
      virtual unsigned long attributes() const

  Returns the attributes for the drag item. These attributes indicate the nature of the drag item object. Attributes supported by the Open Class Library are IDMItem::none, IDMItem::open, IDMItem::reference, IDMItem::group, IDMItem::container, IDMItem::prepare, and IDMItem::removableMedia.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

containerName

      public:
      virtual IString containerName() const

  Returns the source container's name. If the selected RMF is , this function returns the fully qualified path name where the file resides.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

imageOffset

      public:
      virtual ISize imageOffset() const

  Returns the offset from the pointing device's hot spot to the origin of the image for the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isContainer

      public:
      virtual bool isContainer() const

  Returns true if the drag item is a container of other objects.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isGroup

      public:
      virtual bool isGroup() const

  Returns true if the drag item is a group of objects.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isOnRemovableMedia

      public:
      virtual bool isOnRemovableMedia() const

  Returns true if the drag item is on removable media or may not be easily recovered after a move operation. Examples of removable media are the following:

  - Diskettes
  - Tapes
  - Writable optical disks
  - Removable disk drives
  - PCMCIA drives

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isOpen

      public:
      virtual bool isOpen() const

  Returns true if the drag item is open. A drag item could be considered open if it represents the following:

  - A file, and the file is currently open
  - A program that is currently running
  - A device that is currently open

  You can interpret these attributes in various ways depending upon your specialized requirements.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isReference

      public:
      virtual bool isReference() const

  Returns true if the drag item is a reference to another object. A drag item could be considered a reference if it is an alias for another object or the original object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

requiresPreparation

      public:
      virtual bool requiresPreparation() const

  Returns true if the source requires preparation before rendering. For example, the Open Class Library uses this attribute to implement a part of its shared memory RMF support.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setContainer

      public:
      virtual IDMItem& setContainer(bool container = true)

  Sets or resets the container attribute.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setContainerName

      public:
      IDMItem& setContainerName(const char* containerName)

  Sets the source container name of the item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setGroup

      public:
      virtual IDMItem& setGroup(bool group = true)

  Sets or resets the group attribute.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setOnRemovableMedia

      public:
      virtual IDMItem&
        setOnRemovableMedia( bool onRemovableMedia = true )

  Sets or resets the removable media attribute. For example, you can set this attribute to true if the object represents a file on a diskette or CD-ROM.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setOpen

      public:
      virtual IDMItem& setOpen(bool open = true)

  Sets or resets the open attribute. For example, you can set this attribute to true if the object represents a file that is currently open.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setReference

      public:
      virtual IDMItem& setReference(bool reference = true)

  Sets or resets the reference attribute. A drag item could be considered a reference if it is an alias for another object or the original object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setRequiresPreparation

      public:
      virtual IDMItem&
        setRequiresPreparation( bool requiresPrep = true )

  Sets or resets the render prepare attribute. For example, the Open Class Library uses this attribute to implement a part of its shared memory RMF support.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setSourceName

      public:
      IDMItem& setSourceName(const char* sourceName)

  Sets the source object's name.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setSourceWindowHandle

      public:
      IDMItem& setSourceWindowHandle(IWindowHandle window)

  Sets the source window handle for the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setTargetName

      public:
      IDMItem& setTargetName(const char* targetName)

  Sets the suggested target object's name.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

sourceName

      public:
      virtual IString sourceName() const

  Returns the source object's name. If the selected RMF is , this function returns the file name.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

sourceWindow

      public:
      virtual IWindow* sourceWindow() const

  Returns a pointer to the source window for the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

sourceWindowHandle

      public:
      virtual IWindowHandle sourceWindowHandle() const

  Returns the handle of the source window for the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

supportedOperations

      public:
      virtual unsigned long supportedOperations() const

  Returns the operations supported by the drag item. Operations supported by the Open Class Library are IDMItem::copyable, IDMItem::linkable, and IDMItem::moveable.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

targetName

      public:
      virtual IString targetName() const

  Returns the suggested name that the drag item object should have at the target. The target might use a different name, for example, if the suggested name is already in use at the target.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Item Contents

Use these members to set and query the contents of the item involved in a direct manipulation.

contents

      public:
      virtual IString contents() const

  Returns the data for a direct manipulation. Typically, the data is not available at the target prior to the drop. However, if your source and target are within the same process, you can use IDMItem::sourceItemFor to obtain the data within your IDMItemProvider::provideEnterSupport override, prior to the drop.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

contentsSize

      public:
      virtual unsigned long contentsSize() const

  Returns the length of the data for a direct manipulation. Typically, the data is not available at the target prior to the drop. However, if your source and target are within the same process, you can use IDMItem::sourceItemFor to obtain the data within your IDMItemProvider::provideEnterSupport override, prior to the drop.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

object

      public:
      virtual void* object() const

  Returns the pointer to the object of a direct manipulation, such as a container object. Typically, the object is not addressable at the target prior to the drop. However, if your source and target are within the same process, you can use IDMItem::sourceItemFor to obtain addressability to the object within your IDMItemProvider::provideEnterSupport override, prior to the drop.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setContents

      public:
      virtual bool setContents(const IString& data)

  Sets the data within the drag item for a direct manipulation. Use this function to set the data that is associated with the drag item. Typically, the data is not available at the target prior to the drop. However, if your source and target are within the same process, you can use IDMItem::sourceItemFor to obtain the data within your IDMItemProvider::provideEnterSupport override, prior to the drop.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setObject

      public:
      virtual IDMItem& setObject(void* pointerToObject)

  Sets the pointer to the object of a direct manipulation, such as a container object. Typically, the object is not addressable at the target prior to the drop. However, if your source and target are within the same process, you can use IDMItem::sourceItemFor to obtain addressability to the object within your IDMItemProvider::provideEnterSupport override, prior to the drop.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Item Data

These members store data for the drag item.

strContents

      protected:
      IString 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 IDMItem::contents or to allow IDMItem::object to return a pointer to it per a derived item implementation.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Item Operations

Use these members to set and query the operations supported for a drag item object.

canBeCopied

      public:
      virtual bool canBeCopied() const

  Returns true if the drag item can be copied.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

canBeLinked

      public:
      virtual bool canBeLinked() const

  Returns true if the drag item can be linked.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

canBeMoved

      public:
      virtual bool canBeMoved() const

  Returns true if the drag item can be moved.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

enableCopy

      public:
      virtual IDMItem& enableCopy(bool copyable = true)

  Enables or disables the copy operation for the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

enableLink

      public:
      virtual IDMItem& enableLink(bool linkable = true)

  Enables or disables the link operation for the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

enableMove

      public:
      virtual IDMItem& enableMove(bool moveable = true)

  Enables or disables the move operation for the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

supportedOperationsFor

      public:
      virtual unsigned long
        supportedOperationsFor( const IString& selectedRMFs ) const

  Returns the operations that this item supports using the specified rendering mechanisms and formats (RMFs). This function determines what operation is performed on this item using the selected RMFs. For example, you can designate a printer object as the target and make its default operation a copy rather than a move based upon the RMF of &lt;IDM::rmPrint,IDM::rfUnknown&gt;.

  The default implementation of this function calls the member function IDMItem::supportedOperations and returns its result.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Item Rendering

Use these members for item-specific rendering of the data.

sourceDiscard

      public:
      virtual bool sourceDiscard(IDMSourceDiscardEvent& event)

  Implements item-specific rendering when the operating system issues a discard request. Derived classes must override this function if the item adds the IDM::rmDiscard rendering mechanism to its RMFs. This function needs to delete the object that the item represents.

  The default implementation of this function does nothing.

Supported Platforms

  Windows | OS/2 | AIX
  Ignored | Yes | Ignored

OS/2 Considerations

  The discard request is issued by the Workplace Shell when the item is dropped on a shredder object.

sourceEnd

      public:
      virtual bool sourceEnd(IDMSourceEndEvent& event)

  Implements item-specific rendering when source or target rendering of the item has finished. This function is called when the target notifies the source that it has finished rendering the item.

  Derived classes should override this function to accomplish any of the following:

  - Perform any special cleanup before the direct manipulation ends
  - Fulfill other requirements imposed by a nondefault renderer

  The default implementation of this function does nothing.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

sourcePrepare

      public:
      virtual bool sourcePrepare(IDMSourcePrepareEvent& event)

  Implements item-specific rendering when source rendering is used to render the item. Override this function in your derived item class if you use a nondefault renderer that supports source rendering and the renderer requires item-specific processing, and if source preparation is a required part of the rendering.

  Derived classes should override this function to accomplish any of the following:

  - To creation a secondary thread to perform the source rendering.
  - To determine the size of a shared memory buffer. Do this if you want to implement your own shared memory RMF.
  - To fulfill other requirements imposed by the nondefault renderer.

  The default implementation of this function does nothing.

Supported Platforms

  Windows | OS/2 | AIX
  Ignored | Yes | Ignored

sourcePrint

      public:
      virtual bool sourcePrint(IDMSourcePrintEvent& event)

  Implements item-specific rendering when the operating system issues a print request. Derived classes must override this function if the item adds the IDM::rmPrint rendering mechanism to its RMFs. This function needs to print the object that the item represents.

  The default implementation of this function does nothing.

Supported Platforms

  Windows | OS/2 | AIX
  Ignored | Yes | Ignored

OS/2 Considerations

  The print request is issued by the Workplace Shell when the item is dropped on a printer object.

sourceRender

      public:
      virtual bool sourceRender(IDMSourceRenderEvent& event)

  Implements item-specific rendering when source rendering is used to render the item. Override this function in your derived item class if you use a nondefault renderer that supports source rendering and the renderer requires item specific processing.

  The default implementation of this function does nothing.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Ignored

targetDrop

      public:
      virtual bool targetDrop(IDMTargetDropEvent& event)

  Implements item-specific rendering when the item is dropped on a target. Derived classes must override this function to process the data that is transferred to the target window as a result of target rendering.

  If source rendering is not used, or if source rendering is performed but not in a secondary thread, target cleanup should occur in this function.

  The default implementation of this function does nothing.
  Note: If multiple items are dropped, this function is called once for each item. The items are processed in the reverse order in which they were added to the source operation in the member function, IDMItem::generateSourceItems.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

targetEnd

      public:
      virtual bool targetEnd(IDMTargetEndEvent& event)

  Implements item-specific rendering when the item is dropped on a target. Derived classes must override this function when a nondefault source renderer renders the data on a secondary thread. The override function must process the data that is transferred to the target window as a result of the source rendering. Target cleanup should also occur in the override function.

  The source renderer informs the target that it has finished by calling IDMSourceRenderer::informTargetOfCompletion. The call to this function is unique because the source actually posts an event to inform the target that it is finished; thus, this function is called asynchronously.

  Ensure that there is no overlap between this function or IDMItem::targetDrop, since this could mean that two processes are processing the same object. Results may be unpredictable.

  The default implementation of this function does nothing.
  Note: If multiple items are dropped, this function is called once for each item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Item Types

Use these members to set and query the drag item's types. Use a type or types to uniquely identify drag items that represent objects, such as container objects and bitmaps.

addType

      public:
      virtual IDMItem& addType(const char* aType)

  Adds one or more additional types to the drag item. Use this function in a derived class' constructor to add the type or types supported by the derived class.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

hasType

      public:
      virtual bool hasType(const char* aType) const

  Returns true if the drag item supports the specified type.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

removeType

      public:
      virtual IDMItem& removeType(const char* aType)

  Removes the specified type from the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setTrueType

      public:
      virtual IDMItem& setTrueType(const char* aType)

  Sets the drag item's true type.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setTypes

      public:
      virtual IDMItem& setTypes(const char* types)

  Sets the drag item's types. The following line of code removes all of the types for the drag item:

      setTypes("");

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

trueType

      public:
      virtual IString trueType() const

  Returns the true type of the drag item. For example, if the object is a text file, the type is IDM::plainText. If the file is an icon, the type is IDM::icon.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

types

      public:
      virtual IString types() const

  Returns all of the drag item's supported types. Individual types are separated by a comma. IDM::Type contains a list of the Open Class Library's defined types.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Item Utilities

Use these members to provide miscellaneous utility services for a drag item.

isTargetTheSource

      public:
      bool isTargetTheSource() const

  Returns true if source and target are the same window.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

sourceItemFor

      public:
      static Handle sourceItemFor(const Handle& targetItem)

  Retrieves the source item's handle based upon the handle of the target item. The source and target must be in the same process. Otherwise, 0 is returned.

  Use this function to access the source item. You can obtain the source item's data via IDMItem::contents, and you can obtain addressability to the associated object via IDMItem::object.

Exception

  IAccessError | The source item handle could not be retrieved. The query of the process and thread identifier failed. The window handle may have been invalid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

tokenForWPSObject

      public:
      unsigned long tokenForWPSObject() const

  Returns the token for the Workplace Shell object. Use the OBJECT_FOR_PREC macro to convert the token into a WPObject pointer.
  Note: The application using the token must be shell-enabled or OBJECT_FOR_PREC traps.

Supported Platforms

  Windows | OS/2 | AIX
  No | Yes | No

### Rendering Mechanisms and Formats

Use these members to create, delete, manipulate, set, and query the rendering mechanisms and formats (RMFs) for a drag item.

addRMF

  Adds one or more RMFs to the drag item.

  Overload 1

      public:
      virtual IDMItem&
        addRMF( const IString& rm,
                const IString& rf )

  rm
    A reference to the rendering mechanism string.
  rf
    A reference to the rendering format string.

  The RMFs string that is added is created from separate rendering mechanism and rendering format strings. Both strings can have multiple values that must be separated with commas.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      virtual IDMItem& addRMF(const IString& rmf)

  rmf
    A reference to the RMFs string.
  The RMFs string must be in either the ordered-pair format, "", or cross-product format, "(rm)x(rf1,rf2)".

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

appendRMF

      public:
      static void appendRMF(IString& rmfs, const IString& rmf)

  Appends the RMF string, rmf, to the RMFs string, rmfs, and separates the two strings by a comma. Both strings must be in either the ordered-pair format, "", or cross-product format, "(rm)x(rf1,rf2)".

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

compressedRMFs

      public:
      static IString compressedRMFs(const IString& rmfs)

  Returns a compressed version of the RMFs string with all possible cross products converted to cross-product form. The cross-product form is "(rm)x(rf1,rf2)", where rm represents the rendering mechanism and rf1 and rf2 represent the rendering formats.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

deleteRMF

      public:
      static void deleteRMF(IString& rmfs, const IString& rmf)

  Deletes the RMF string, rmf, from the RMFs string, rmfs. Both strings must be in either the ordered-pair format, "", or cross-product format, "(rm)x(rf1,rf2)".

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

matchingRMFs

      public:
      static IString
        matchingRMFs( const IString& rmfs1,
                      const IString& rmfs2,
                      bool firstOnly = false )

  Returns the intersection of the two RMF strings. Both strings must be in either the ordered-pair format, "", or cross-product format, "(rm)x(rf1,rf2)".

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

nativeRF

      public:
      virtual IString nativeRF() const

  Returns the native rendering format of the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

nativeRM

      public:
      virtual IString nativeRM() const

  Returns the native rendering mechanism of the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

nativeRMF

      public:
      virtual IString nativeRMF() const

  Returns the native RMF of the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

removeRMF

  Removes an RMF from the drag item.

  Overload 1

      public:
      virtual IDMItem& removeRMF(const IString& rmf)

  rmf
    A reference to the RMF string.

  The RMF string must be in either the ordered-pair format, "", or cross-product format, "(rm)x(rf1,rf2)".

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      virtual IDMItem&
        removeRMF( const IString& rm,
                   const IString& rf )

  rm
    A reference to the rendering mechanism string.
  rf
    A reference to the rendering format string.

  rm and rf must represent a single rendering mechanism and a single rendering format, respectively. Multiple rendering mechanisms or rendering formats are not supported.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

rfForThisProcess

      public:
      static IString rfForThisProcess()

  Returns the string, DRF_PROCESS=pid, where pid is the ASCII representation of the process identifier (ID). Use this function to create the process rendering format.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

rfFrom

      public:
      static IString rfFrom(const IString& rmf)

  Returns the rendering format from the specified RMF string. The RMF string must be in either the ordered-pair format, "", or cross-product format, "(rm)x(rf1,rf2)".

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

rmfFrom

      public:
      static IString
        rmfFrom( const IString& rm,
                 const IString& rf )

  Creates a rendering mechanism and format (RMF)-ordered pair: "". rm and rf must represent a single rendering mechanism and a single rendering format, respectively. Multiple rendering mechanisms or rendering formats are not supported.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

rmFrom

      public:
      static IString rmFrom(const IString& rmf)

  Returns the rendering mechanism from the specified RMF string. The RMF string must be in either the ordered-pair format, "", or cross-product format, "(rm)x(rf1,rf2)".

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

rmfs

      public:
      virtual IString rmfs() const

  Returns all RMFs for the drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

rmfsFrom

  Returns an RMFs string.

  Overload 1

      public:
      static IString
        rmfsFrom( const IString& rm,
                  const IString& rf )

  rm
    A reference to the rendering mechanism string.
  rf
    A reference to the rendering format string.

  The RMFs string is created from separate rendering mechanism and rendering format strings. Both strings can have multiple values that must be separated with commas. The RMFs string is returned in the ordered-pair format.

  The following line of code illustrates passing multiple values:

        IDMItem::rmfsFrom( "rm1,rm2", "rf1,rf2" );

  The RMFs string returned from the sample line of code in the ordered-pair format is ",,,".

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      static IString rmfsFrom(const IString& rmfs)

  rmfs
    A reference to the RMFs string.

  The RMFs string is created from the specified RMFs string. Use this version of the function to expand a cross-product form into ordered pairs.

  The following line of code illustrates a cross-product form:

        IDMItem::rmfsFrom( "(rm1)x(rf1,rf2)" );

  The RMFs string returned from the sample line of code is ",".

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setNativeRMF

  Sets the native RMF to the specified value.

  Overload 1

      public:
      virtual IDMItem&
        setNativeRMF( const IString& rm,
                      const IString& rf )

  rm
    A reference to the rendering mechanism string.
  rf
    A reference to the rendering format string.

  rm and rf must represent a single rendering mechanism and a single rendering format, respectively. Multiple rendering mechanisms or rendering formats are not supported.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      virtual IDMItem& setNativeRMF(const IString& rmf)

  rmf
    A reference to the RMF string.

  rmf must represent a single RMF in the ordered-pair format, "". Multiple RMFs are not supported.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setRMFs

      public:
      virtual IDMItem& setRMFs(const IString& rmfs)

  Sets the new RMFs for the drag item. Use the following line of code to remove all of the RMFs for the item:

        setRMFs( "" );

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

supportsRMF

  Returns true if the item supports the specified RMFs.

  Overload 1

      public:
      virtual bool
        supportsRMF( const IString& rm,
                     const IString& rf )

  rm
    A reference to the rendering mechanism string.
  rf
    A reference to the rendering format string.

  Both strings can have multiple values that must be separated with commas.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      virtual bool supportsRMF(const IString& rmf)

  rmf
    A reference to the RMFs string.

  The RMFs string can be either in the cross-product format, "(rm)x(rf1,rf2)" or the ordered-pair format, ",".

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Selected Renderer

Use these members to set and query the renderer that is selected for the drag item.

renderer

      public:
      unsigned renderer() const

  Returns the position of the selected renderer for this drag item.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

selectedRMF

      public:
      IString selectedRMF() const

  Returns the selected rendering mechanism and format (RMF) for this item in an ordered-pair format, such as: "&lt;IDM::rmLibrary,IDM::rfText&gt;".

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setRenderer

      public:
      IDMItem& setRenderer(unsigned position)

  Sets the selected renderer for the drag item. The function's argument is the relative position of the specified renderer within the source or target handler's collection of renderers.
  Note: This function should only be called by the source or target handler.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setSelectedRMF

      public:
      IDMItem& setSelectedRMF(const IString& rmf)

  Sets the selected rendering mechanism and format (RMF) for this drag item. The function's argument must be an ordered-pair format, such as: "&lt;IDM::rmLibrary,IDM::rfText&gt;".

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Source and Target Operation

Use these members to access the source and target operation objects.

sourceOperation

      public:
      virtual IDMSourceOperation* sourceOperation()

  Returns a pointer to the source operation for the drag item. If the item represents a target item, 0 is returned.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

targetOperation

      public:
      virtual IDMTargetOperation* targetOperation()

  Returns a pointer to the target operation for the drag item. If the item represents a source item, 0 is returned.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Source Items

Use these members to access and manipulate source items involved in a direct manipulation.

generateSourceItems

      public:
      static bool
        generateSourceItems( IDMSourceOperation* sourceOperation )

  Generates generic drag items. This function is called by the implementation of IDMItemProvider::provideSourceItems in the template class IDMItemProviderFor. This arrangement is designed to permit you to implement all of your application-specific behavior in a single class derived from IDMItem or one of its derivatives. The corresponding drag item provider object is constructed using the IDMItemProviderFor template with your derived item class.

  The default implementation of this function in this class creates generic IDMItem objects and adds them to the source operation. If you use the IDMItemProviderFor template class and you have defined a derived item class, you must implement IDMItem::generateSourceItems in your derived item class. In your implementation, create one or more objects of your derived item class and call IDMOperation::addItem to add the objects to the source operation.
  Note: Use the sourceOperation parameter to access IDMOperation::addItem.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Source Name

These members generate the source name when the IDM::rfText-rendering format is used.

generateSourceName

      protected:
      IString generateSourceName()

  Use this function to generate the source name for the implementation of the IDM::rfText-rendering format.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Supported Operations Flags

Use these static members to define the supported operations of the drag item.
Note: These static members represent bit masks, patterns of bits used to control portions of another pattern of bits. Any user-defined values must be greater than the IDMItem::linkable value.

copyable

      public:
      static const unsigned long copyable

  The source object can be copied to the specified target.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

linkable

      public:
      static const unsigned long linkable

  The source object can be linked to the specified target.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

moveable

      public:
      static const unsigned long moveable

  The source object can be moved to the specified target.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

unknown

      public:
      static const unsigned long unknown

  No supported drag operations are available.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IDMItem - Type Definitions

Handle

      typedef ICountedPointerTo < IDMItem > Handle

  IDMItem::Handle provides access to the IDMItem objects associated with a direct manipulation. The handle manages the references to the IDMItem object and ensures that the object is not destructed until the direct manipulation is completed.

  Use Handle to reference an item handle within this class and IDMItem::Handle externally.

  To convert an IDMItem::Handle to an IDMItem pointer, use the ICountedPointerTo::getAlias() function.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IDMItem - Inherited Member Functions and Data

#### Inherited Public Functions

  IMRefCounted

  -     void addRef()

  -     unsigned long count() const

  -     void removeRef()

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IMRefCounted

  -     virtual ~IMRefCounted()

  -     IMRefCounted()

  -     IMRefCounted(const IMRefCounted&)

  -     IMRefCounted& operator =(const IMRefCounted&)

#### Inherited Protected Data

  - None