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:

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.


[view 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


[view class]
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


[view class]
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.


[view class]
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


[view class]
group
public:
static const unsigned long group

The source object is a group of objects.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
none
public:
static const unsigned long none

No attributes are defined for the source object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
open
public:
static const unsigned long open

The source object is open.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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.


[view class]
hasImage
public:
bool hasImage() const

Returns true if the drag item has an associated image.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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.


[view class]
dropStatus
public:
DropIndicator dropStatus() const

Returns the drop status for the drag item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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.


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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:

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
setContainer
public:
virtual IDMItem& setContainer(bool container = true)

Sets or resets the container attribute.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setContainerName
public:
IDMItem& setContainerName(const char* containerName)

Sets the source container name of the item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setGroup
public:
virtual IDMItem& setGroup(bool group = true)

Sets or resets the group attribute.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
setSourceName
public:
IDMItem& setSourceName(const char* sourceName)

Sets the source object's name.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setSourceWindowHandle
public:
IDMItem& setSourceWindowHandle(IWindowHandle window)

Sets the source window handle for the drag item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setTargetName
public:
IDMItem& setTargetName(const char* targetName)

Sets the suggested target object's name.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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.


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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.


[view class]
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.


[view class]
canBeCopied
public:
virtual bool canBeCopied() const

Returns true if the drag item can be copied.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
canBeLinked
public:
virtual bool canBeLinked() const

Returns true if the drag item can be linked.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
canBeMoved
public:
virtual bool canBeMoved() const

Returns true if the drag item can be moved.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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


[view class]
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 <IDM::rmPrint,IDM::rfUnknown>.

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.


[view class]
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.


[view class]
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:

The default implementation of this function does nothing.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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:

The default implementation of this function does nothing.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
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.


[view class]
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


[view class]
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


[view class]
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.


[view class]
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


[view class]
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


[view class]
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


[view class]
setTrueType
public:
virtual IDMItem& setTrueType(const char* aType)

Sets the drag item's true type.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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.


[view class]
isTargetTheSource
public:
bool isTargetTheSource() const

Returns true if source and target are the same window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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.


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
nativeRF
public:
virtual IString nativeRF() const

Returns the native rendering format of the drag item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
nativeRM
public:
virtual IString nativeRM() const

Returns the native rendering mechanism of the drag item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
nativeRMF
public:
virtual IString nativeRMF() const

Returns the native RMF of the drag item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
rmfs
public:
virtual IString rmfs() const

Returns all RMFs for the drag item.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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


[view class]
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


[view class]
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.


[view class]
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


[view class]
selectedRMF
public:
IString selectedRMF() const

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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


[view class]
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: "<IDM::rmLibrary,IDM::rfText>".

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Source and Target Operation

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


[view class]
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


[view class]
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.


[view class]
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.


[view class]
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.


[view class]
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


[view class]
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


[view class]
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


[view class]
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


[view class]
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

Inherited Public Data

Inherited Protected Functions

IMRefCounted

Inherited Protected Data