IDMTargetRenderer

The IDMTargetRenderer class provides target rendering support for a direct manipulation. You can register objects of this class by using IDMRenderer::setDefaultTargetRenderer, IDMTargetHandler::addRenderer, or IDMTargetHandler::setRenderer.

The target handler selects a best-match target renderer by calling IDMTargetHandler::findRendererFor for a given drag item and invokes the rendering functions of this renderer when target rendering events occur.


IDMTargetRenderer - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


[view class]
~IDMTargetRenderer
public:
virtual ~IDMTargetRenderer()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IDMTargetRenderer


Overload 1
public:
IDMTargetRenderer()

This is the default constructor.

When this constructor is used, the renderer supports any type and all of the default target RMFs supported by the Open Class Library:

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IDMTargetRenderer( const char* rmfs, const char* type = IDM::any )

rmfs
A pointer to the RMFs string.
type
A pointer to the drag item types string. The default is any drag item type, IDM::any.

Use this function to construct objects of this class by providing rendering mechanisms and formats (RMFs) and drag item types that indicate the drag items that can be rendered by this target renderer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Renderer Specifics

Use these members to process the different rendering operations that are specific to the supported rendering mechanisms and formats.


[view class]
prepareAtSource
protected:
virtual bool prepareAtSource( IDMTargetDropEvent& event, const IDMItem::Handle& dragItem )

Sends a source prepare event to the source to request source preparation for the specified drag item. This function returns true if the source successfully completes its processing.

The Open Class Library uses this function to implement the support for the rendering mechanism and format.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
renderAtSource
protected:
virtual bool renderAtSource( IDMTargetDropEvent& event, const IDMItem::Handle& dragItem )

Sends a source render event to the source to request source rendering for the specified drag item. This function returns true if the source successfully completes its processing.

The Open Class Library uses this function to implement the support for the rendering mechanism and format.

Exception

IAccessError The render event was not sent to the source. The source window handle may be invalid.
IOutOfMemory The render event was not sent to the source. The system was unable to allocate the required memory.
IAccessError The render event was not sent to the source. The target process could not give the source process access to the shared memory buffer because the system may be out of memory or the buffer may be locked.
IAccessError The render event was not sent to the source. The source reported an error during the processing of the source render event.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
renderComplete
protected:
virtual bool renderComplete( const IDMItem::Handle& dragItem, void* pBuffer )

Called to process a render completion event for the specified drag item.

The Open Class Library uses this function to implement the support for the rendering mechanism and format.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
renderToName
protected:
virtual IString renderToName( const IDMItem::Handle& dragItem )

Provides the name of the location of the rendered data. This name could be a file name or a shared memory buffer.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Source and Target Rendering

Use these members to support the implementation of target rendering. Members that you can use to support source rendering are identified on an individual basis.

Source rendering is rendering that involves both the source and target after the drop has occurred. The data for rendering is not available when the drop occurs, so the target requests that the source make the data available. The request for data is issued for each drag item using IDMSourceRenderEvent, and possibly IDMSourcePrepareEvent. The source can notify the target when it has finished rendering each drag item using IDMTargetEndEvent. The target informs the source when it has finished rendering each drag item via IDMSourceEndEvent.
Note: The default source rendering support in the Open Class Library does not use IDMTargetEndEvent.

Target rendering, the optimal form of rendering, involves mainly the target after the drop has occurred. The data for rendering is available when the drop occurs. The target informs the source when it has finished rendering each drag item via IDMSourceEndEvent.


[view class]
canRender
public:
virtual DropIndicator canRender( const IDMItem::Handle& dragItem )

Returns true if the target renderer can render drag items with the specified attributes. This function is called for each drag item during target enter event processing.
Note: This function can be used for either source or target rendering.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
informSourceOfCompletion
public:
virtual IDMTargetRenderer& informSourceOfCompletion( const IDMItem::Handle& dragItem, IDM::RenderCompletion code = IDM::targetSuccessful )

Informs the source that the target has finished processing the data associated with the dropped item. The render completion code indicates if the target renderer successfully processed the data or if it failed.
Note: This function must be used for both source and target rendering.

Exception

IInvalidRequest The source could not be informed that the target finished processing. The drag item is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
supportsOperation
public:
virtual bool supportsOperation( const IDMItem::Handle& dragItem )

Determines if the default drag operation, which is set by the source, is supported by the drag item. If the default operation is IDMOperation::drag, the target must select an operation. If no operation is selected, the Open Class Library's default selection is IDMOperation::move.

If the default operation defined by the source is a value greater than IDMOperation::unknown, the application must define the functionality of this operation and process the operation accordingly.

When the default operation defined by the source is one of the following, the default processing verifies if the drag item supports the operation:

This function is called for each drag item during target enter event processing.
Note: This function can be used for either source or target rendering.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
targetRender
public:
virtual IDMTargetRenderer& targetRender( IDMTargetDropEvent& event, const IDMItem::Handle& dragItem )

Called when a drop event occurs for a drag item and the renderer must render the drag item. Use the rendering mechanism and format (RMF) to determine the type of rendering to implement.

This function is called for each drag item during target drop event processing.
Note: This function can be used for either source or target rendering.

Exception

IInvalidRequest The drag item was not rendered. The IDM::rfProcess rendering format can only be used if the source and the target are in the same process.
IInvalidRequest The drag item was not rendered. Source rendering of the drag item failed.
IInvalidRequest The drag item was not rendered. The rendering format is invalid.
IInvalidRequest The drag item was not rendered. The rendering mechanism is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
targetRenderComplete
public:
virtual IDMTargetRenderer& targetRenderComplete( IDMTargetEndEvent& event )

Called when the source has completed the rendering of a drag item. This function is called for each drag item during target end event processing.

This function is not used by any of the default renderers supported by the Open Class Library.
Note: This function is used for source rendering only.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
targetRenderPrepare
public:
virtual IDMTargetRenderer& targetRenderPrepare( IDMTargetDropEvent& event, const IDMItem::Handle& dragItem )

Called when the source requests that the target issue a source prepare event for a specific RMF.
Note: This function is used for source rendering only.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


IDMTargetRenderer - Inherited Member Functions and Data

Inherited Public Functions

IDMRenderer

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data