IDMSourceHandler

The IDMSourceHandler class processes events occurring at the source of a direct manipulation. You must add an object of this class to a window so it can support source direct manipulation. Objects of this class do not allow objects to be dropped on a window. See IDMTargetHandler for information about dropping objects on a window.
Note: An IDMSourceHandler object is added to a window if you initialize direct manipulation via the functions in Enabling Direct Manipulation.


IDMSourceHandler - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IDMSourceHandler


Overload 1
public:
IDMSourceHandler()

This is the default constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IDMSourceHandler(IContainerControl* containerControl)

containerControl
A pointer to the container control object.

Creates an object of this class using a pointer to a container control object. The constructed handler is automatically attached to the specified container.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IDMSourceHandler(IEntryField* entryField)

entryField
A pointer to the entry field object.

Creates an object of this class using a pointer to an entry field object. The constructed handler is automatically attached to the specified entry field.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IDMSourceHandler(IMultiLineEdit* multiLineEdit)

multiLineEdit
A pointer to the multiline edit object.

Creates an object of this class using a pointer to a multiline edit (MLE) object. The constructed handler is automatically attached to the specified MLE.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
IDMSourceHandler(IWindow* window)

window
A pointer to the window object.

Creates an object of this class using a pointer to an IWindow-based object that represents a control that is not supported by the default Open Class Library support for direct manipulation. These controls can be system-defined controls or custom controls. The constructed handler is automatically attached to the specified window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Dispatching

These members dispatch the various events for a direct manipulation source.


[view class]
dispatchHandlerEvent
protected:
virtual bool dispatchHandlerEvent(IEvent& event)

Overrides the default handler's dispatcher. This function processes the direct manipulation events for the source.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Event Processing

These members are dispatched in response to specific direct manipulation events for the source.


[view class]
sourceBegin
protected:
virtual bool sourceBegin( IDMSourceBeginEvent& event, bool container = true )

Called to process the start of a direct manipulation in response to the system's begin drag event. Initial processing invokes allocateOperation. Next, a pointer to the drag item provider is obtained by calling IWindow::itemProvider. Afterwards, IDMItemProvider::provideSourceItems is invoked to retrieve the items to be dragged. findRenderersFor is called to find appropriate source renderers for the items that were provided. If there are items to be dragged, IDMSourceOperation::begin is called to start the direct manipulation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sourceDiscard
protected:
virtual bool sourceDiscard(IDMSourceDiscardEvent& event)

Called to indicate that a drag item or items have been dropped on a shredder object. The source response determines what deletes the items or if the discard operation is cancelled. The default implementation dispatches IDMSourceRenderer::sourceDiscard.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

You will not receive IDMSourceDiscardEvents on AIX.

Windows Considerations

You will not receive IDMSourceDiscardEvents on Windows.


[view class]
sourceEnd
protected:
virtual bool sourceEnd(IDMSourceEndEvent& event)

Called to indicate that a given item has been processed by the target. The default implementation for this class dispatches IDMSourceRenderer::sourceEnd on the corresponding drag item object.

After all source end events are received, the IDMSourceOperation object is deleted.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
sourcePrepare
protected:
virtual bool sourcePrepare(IDMSourcePrepareEvent& event)

Called to indicate to the source that rendering is ready to start. Requests for rendering preparation are made within the source item constructors. The default implementation in this class dispatches IDMSourceRenderer::sourcePrepare on the corresponding drag item object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
sourcePrint
protected:
virtual bool sourcePrint(IDMSourcePrintEvent& event)

Called to indicate that a drag item or items have been dropped on a printer object. The source response determines who prints the items or if the operation is cancelled. The default implementation dispatches IDMSourceRenderer::sourcePrint.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


[view class]
sourceRender
protected:
virtual bool sourceRender(IDMSourceRenderEvent& event)

Called to start the rendering of a drag item by the source renderer. The default implementation for this class dispatches IDMSourceRenderer::sourceRender on the drag item object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored


Implementation

These members provide utilities used to implement this class. They are used by the Open Class Library.


[view class]
allocateOperation
protected:
virtual IDMSourceOperation::Handle allocateOperation( IDMSourceBeginEvent& event, DragImageStyle dragItemStyle ) const

Creates a new IDMSourceOperation object.

This function is called when the source handler is handling the processing of a new direct manipulation. Derived classes should override this function and return a class derived from IDMSourceOperation.

This function returns a handle to the source operation object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
findRendererFor
protected:
virtual unsigned findRendererFor( const IDMItem::Handle& item )

Finds the appropriate source renderer for the drag item. Returns the position of the renderer or 0 if a renderer cannot be found.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
findRenderersFor
protected:
virtual bool findRenderersFor( const IDMSourceOperation::Handle& sourceOperation )

Finds the appropriate source renderers for the specified source operation.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Renderer Processing

These members override the rendering functions defined in the base IDMHandler class. Use them to access the IDMSourceRenderer objects involved in a direct manipulation. Objects of this class render the drag item objects that are compatible with the rendering mechanisms and formats that the Open Class Library supports.


[view class]
addRenderer
public:
virtual IDMSourceHandler& addRenderer( const IDMSourceRenderer& newRenderer )

Adds the specified renderer to the set of candidates maintained by this handler and uses it to render objects dragged from a source window where this handler is attached. The renderer is added to the end of the renderer collection.
Note: Renderers are maintained by position, which are 1-based.

newRenderer
A reference to the renderer object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
numberOfRenderers
public:
virtual unsigned numberOfRenderers()

Returns the number of renderers associated with the source handler.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeRenderer
public:
virtual IDMSourceHandler& removeRenderer( const IDMSourceRenderer& rendererToRemove )

Removes a specified renderer from this handler.
Note: Renderers are maintained by position, which are 1-based.

rendererToRemove
A reference to the source renderer object to remove from the renderer collection.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
renderer
public:
virtual IDMSourceRenderer* renderer(unsigned position)

Returns the renderer with the specified position.
Note: Renderers are maintained by position, which are 1-based.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
replaceRenderer
public:
virtual IDMSourceHandler& replaceRenderer( unsigned position, const IDMSourceRenderer& replacement )

Replaces the given renderer with another specified renderer.
Note: Renderers are maintained by position, which are 1-based.

position
A value that represents the location of the source renderer to replace in the renderer collection.
replacement
A reference to the replacement renderer object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setRenderer
public:
virtual IDMSourceHandler& setRenderer( const IDMSourceRenderer& newRenderer )

Sets the source renderer for this handler. Removes any pre-existing source renderers.

newRenderer
A reference to the source renderer object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IDMSourceHandler - Inherited Member Functions and Data

Inherited Public Functions

IHandler
IDMHandler

Inherited Public Data

Inherited Protected Functions

IDMHandler
IHandler

Inherited Protected Data