IDragDropTargetFlavorHelper Class Reference

#include <IDragDropTargetFlavorHelper.h>

Inheritance diagram for IDragDropTargetFlavorHelper:

Public Types
enum	{ kDefaultIID = IID_IDRAGDROPTARGETFLAVORHELPER }

Public Member Functions
virtual DragDrop::eHelperType	GetHelperType () const =0
virtual bool16	HelperWillDoDragTracking () const =0
virtual DragDrop::TargetResponse	HandleCouldAcceptTypes (const IDragDropTarget *, DataObjectIterator *, const IDragDropSource *, const IDragDropController *) const =0
virtual bool16	DoDragEnter_PreflightDragData (IDragDropTarget *, IDragDropController *)=0
virtual void	DoDragEnter (IDragDropTarget *)=0
virtual void	DoDragWithin (IDragDropTarget *, const PMPoint &localPt)=0
virtual void	DoDragLeave (IDragDropTarget *)=0
virtual ErrorCode	ProcessDragDropCommand (IDragDropTarget *, IDragDropController *, DragDrop::eCommandType)=0
virtual PMRect	GetDragDataBounds () const =0
Public Member Functions inherited from IPMUnknown
virtual IPMUnknown *	QueryInterface (PMIID interfaceID) const =0
virtual void	AddRef () const =0
virtual void	Release () const =0

Protected Member Functions
virtual DragDrop::TargetResponse	CouldAcceptTypes (const IDragDropTarget *, DataObjectIterator *, const IDragDropSource *, const IDragDropController *) const =0

Detailed Description

The IDragDropTargetFlavorHelper interface provides extensibility for drag drop targets. Implementors of IDragDropTargetFlavorHelper should derive from CDragDropTargetFlavorHelper which provides default implementations for many of the methods described here.

Drag target extensibility requires the source be derived from CDragDropSourceTarget_Extensible. Create a new boss with an IDragDropTargetFlavorHelper implementation combined with a IK2ServiceProvider implementation that corresponds to the service ID defined by the extensible drag target.

When the framework asks an extensible drag target if could accept the drag being dragged onto it, the target then asks each of it's flavor helpers if they could accept any of the flavors in the dragged data. One helper is chosen based on it's willingness to accept the drag, and in the case of multiple helpers, prioritized by helper type and the priority of the flavor they propose to accept. The extensible target then forwards the subsequent method calls that occur during the drag to the chosen helper.

See Also

IDragDropTarget, CDragDropTargetFlavorHelper, CDragDropSourceTarget_Extensible, IK2ServiceProvider

Member Function Documentation

virtual DragDrop::TargetResponse IDragDropTargetFlavorHelper::CouldAcceptTypes ( const IDragDropTarget *  , DataObjectIterator *  , const IDragDropSource *  , const IDragDropController *    ) const

protectedpure virtual

Could this target helper accept the current drag. Override CouldAcceptTypes to report whether the helper could accept any of the promised flavors in the dragged data. CouldAcceptTypes should not attempt to examine the actual drag data, but should base it's return value only on the flavors of data available. Add kDropTargetDrawsFeedback to result if target will draw its own feedback representing the data as it moves through the target, as does the layout widget. Not to be confused with target hilighting.

Parameters

target	IN the drag drop target this helper is assisting
iter	IN iterator based access to drag items in the drag (usually just one)
source	IN the drag drop source where the drag originated, used to help determine if operation would result in a move, copy or link. (drags from external apps will have source == nil)
controller	IN drag drop controller for this operation

Returns

the action the target intends to perform (nothing, copy, move, link) plus target options for handling the drag

Implemented in CusDtLnkUIDDTargetFlavorHelper, BscDNDCustomFlavorHelper, and CDragDropTargetFlavorHelper.

virtual void IDragDropTargetFlavorHelper::DoDragEnter ( IDragDropTarget *  )

pure virtual

Respond to a drag entering the target. Implementors often override DoDragEnter when implementing non standard drag tracking behavior - especially custom drag hilighting and feedback. If information about the data is needed while tracking it can be obtained from the IDragDropController interface on the session.

Parameters

target

IN the drag drop target this helper is assisting

Precondition

only called if HelperWillDoDragTracking returns kTrue

Implemented in CDragDropTargetFlavorHelper.

virtual bool16 IDragDropTargetFlavorHelper::DoDragEnter_PreflightDragData ( IDragDropTarget *  , IDragDropController *    )

pure virtual

Give helper a chance to "preflight" the data contained in a drag. This method is called during CDragDropTarget_Extensible::HandleDoDragEnter. Preflighting is not recommended, but can be necessary if type acceptance is insufficient. Since the data in external drags will have to be internalized, the data should not be re-internalized in ProcessDragDropCommand, below.

Parameters

target	IN the drag drop target this helper is assisting
controller	IN drag drop controller for this operation

Returns

kTrue to indicate that the drag should proceed, kFalse otherwise.

Implemented in CDragDropTargetFlavorHelper.

virtual void IDragDropTargetFlavorHelper::DoDragLeave ( IDragDropTarget *  )

pure virtual

Respond to a drag leaving the target. Implementors often override DoDragLeave when implementing non standard drag behavior - especially custom drag hilighting and feedback.

Parameters

target

IN the drag drop target this helper is assisting

Precondition

only called if HelperWillDoDragTracking returns kTrue

Implemented in CDragDropTargetFlavorHelper.

virtual void IDragDropTargetFlavorHelper::DoDragWithin ( IDragDropTarget *  , const PMPoint &  localPt  )

pure virtual

Respond to a drag moving over and within the target. Implementors often override DoDragWithin when implementing non standard drag behavior - especially custom drag feedback.

Parameters

target	IN the drag drop target this helper is assisting
localPt	IN coordinates of the cursor in local target coordinates.

Precondition

only called if HelperWillDoDragTracking returns kTrue

Implemented in CDragDropTargetFlavorHelper.

virtual PMRect IDragDropTargetFlavorHelper::GetDragDataBounds ( ) const

pure virtual

Return the bounds of the item(s) being dragged. The bounds are provided to all IDropTargetCallbacks registered on the target of the drag.

Precondition

only called if HelperWillDoDragTracking returns kTrue

Returns

dragged item bounds

Implemented in CDragDropTargetFlavorHelper.

virtual DragDrop::eHelperType IDragDropTargetFlavorHelper::GetHelperType ( ) const

pure virtual

Return the type or priority of the helper. This is used to resolve conflicts that can arise when more than one target flavor helper is capable of accepting the drag data. The presence of multiple helpers is not a conflict, a conflict would arise when one helper wants to replace or augment what another helper already does.

Returns

helper type appropriate for this helper. Use DragDrop::kDefaultHelper by default.

Implemented in CDragDropTargetFlavorHelper.

virtual DragDrop::TargetResponse IDragDropTargetFlavorHelper::HandleCouldAcceptTypes ( const IDragDropTarget *  , DataObjectIterator *  , const IDragDropSource *  , const IDragDropController *    ) const

pure virtual

INTERNAL_USE_ONLY. An implementation of this method is provided in CDragDropTargetFlavorHelper. Subclasses should not override this method; see the protected variant below.

Implemented in CDragDropTargetFlavorHelper.

virtual bool16 IDragDropTargetFlavorHelper::HelperWillDoDragTracking ( ) const

pure virtual

Does the helper want to do its own drag dracking? Id kTrue is returned, the helper will receive DoDragEnter, DoDragWithin, and DoDragLeave calls.

Returns

kTrue if the helper wants to do its own tracking

Implemented in CDragDropTargetFlavorHelper.

virtual ErrorCode IDragDropTargetFlavorHelper::ProcessDragDropCommand ( IDragDropTarget *  , IDragDropController *  , DragDrop::eCommandType    )

pure virtual

Create and process (or schedule) the commands needed to complete the drop operation. Normally called on the drop target, this method is also called on sources when the original data needs to be deleted, as in a drag to the trash.

Parameters

target	IN the drag drop target this helper is assisting
controller	IN drag drop controller for this operation
commandType	IN which operation to perform (targets will only receive kDragMove or kDrop)

Returns

success or failure of the drop

Implemented in CusDtLnkUIDDTargetFlavorHelper, BscDNDCustomFlavorHelper, and CDragDropTargetFlavorHelper.