#include <IDragDropController.h>

Inheritance diagram for IDragDropController:

Public Types
enum	{ kDefaultIID = IID_IDRAGDROPCONTROLLER }

Public Member Functions
	IDragDropController (IPMUnknown *boss)

virtual bool16	StartDrag (IDragDropSource , IEvent e, bool16 patientUser=kFalse)=0

virtual ErrorCode	ClearDrag ()=0

virtual bool16	IsDragInProgress () const =0

virtual GSysPoint	GetDragMouseLocation () const =0

virtual bool16	IsPatientUser () const =0

virtual bool16	IsUserUsingCopyGesture () const =0

virtual bool16	DidUserUseCopyGesture () const =0

virtual bool16	DidUserUseDragChildrenGesture () const =0

virtual bool16	IsTargetSameAsSource () const =0

virtual bool16	NeedsToInternalize () const =0

virtual uint16	GetItemCount ()=0

virtual IPMDataObject *	AddDragItem (uint32 itemID)=0

virtual IPMDataObject *	GetDragItem (uint32 itemID)=0

virtual IAbortableCmdSeq *	GetCommandSequence () const =0

virtual IDataExchangeHandler *	QuerySourceHandler () const =0

virtual void	SetSourceHandler (IDataExchangeHandler *handler)=0

virtual IDataExchangeHandler *	QueryTargetHandler () const =0

virtual void	SetTargetHandler (IDataExchangeHandler *handler)=0

virtual IDataExchangeHandler *	QueryHandlerForInternalize (DataExchangeResponse &response, const PMFlavor &internalizedFlavor=kNoFlavor) const =0

virtual ErrorCode	FulfillPromise (IPMDataObject *whichItem, const ExternalPMFlavor &whichFlavor) const =0

virtual ErrorCode	ExternalizeDrag (PMFlavor whichFlavor) const =0

virtual bool16	CanInternalizeDuringTracking () const =0

virtual ErrorCode	InternalizeDrag (ExternalPMFlavor extFlavor, PMFlavor intFlavor)=0

virtual void	SetTrackingCursorFeedback (const CursorSpec &cursor)=0

virtual CursorSpec	GetDefaultTrackingCursorFeedback (DragDrop::eTargetResponse targetResponse) const =0

virtual bool16	WillTargetProvideCursorFeedback () const =0

virtual void	SuppressExternalDragHandling (bool16 doSuppress)=0

Public Member Functions inherited from CDataExchangeController
	CDataExchangeController (IPMUnknown *boss)

virtual void	ReadWrite (IPMStream *s, ImplementationID prop)

virtual void	RegisterAllHandlers ()

virtual bool16	RegisterDataHandler (ClassID dataClass)

virtual IDataExchangeHandler *	NewDataHandler (ClassID dataClass) const

virtual IDataExchangeHandler *	QueryHandler (const PMFlavor &scrapFlavor) const

virtual IDataExchangeHandler *	QueryHandler (const ExternalPMFlavor &fromFlavor, const PMFlavor &toFlavor) const

virtual void	GetInternalizeableFlavors (OrderedFlavorList &flavorList) const

virtual IDataExchangeHandler *	QueryActiveHandler () const

virtual void	SetActiveHandler (IDataExchangeHandler *activeHandler)

virtual IDataBase *	GetScrapDataBase () const

virtual ErrorCode	Initialize ()

virtual bool16	IsValid () const

virtual void	Cleanup ()

virtual void	Purge (int32 level)

void	AllowPurge ()

void	DisallowPurge ()

bool	PurgeIsAllowed () const

Additional Inherited Members
Static Public Member Functions inherited from CDataExchangeController
static void	Purge (int32 level, void *refPtr)

Protected Member Functions inherited from CDataExchangeController
virtual IDataExchangeHandler *	QueryHandlerToInternalizeData (IPMDataObject *whichItem, DataExchangeResponse &response, const PMFlavor &toFlavor) const

virtual IDataExchangeHandler *	QueryHandlerToInternalizeData (DataObjectIterator &dataIter, DataExchangeResponse &response, const PMFlavor &toFlavor) const

virtual ClassID	GetScrapDocBossID () const

virtual PMString	GetScrapDBFileName () const =0

virtual IDataBase *	CreateDataBase () const =0

virtual void	ResetMagicBytes () const =0

virtual ErrorCode	InitializeScrap ()

virtual ErrorCode	RevertScrap ()

virtual void	RunNewScrapResponders ()

virtual bool16	IsClipboardExternal () const

IDataExchangeHandler *	GetActiveHandler () const

virtual IDataExchangeHandler *	QueryCachedHandler () const

virtual void	SetCachedHandler (IDataExchangeHandler *handlerToCache)

Protected Attributes inherited from CDataExchangeController
bool16	fInitialized

ErrorCode	fInitializationErrorCode

IDataBase *	fScrapDB

UID	fScrapDocID

bool16	fScrapDBFailed

IPMUnknown *	fRoot

int32	fAllowPurge

bool16	fDataHandlersRegistered

K2Vector < DataExchangeHandlerEntry >	fDataHandlers

IDataExchangeHandler *	fActiveHandler

IDataExchangeHandler *	fCachedHandler

Detailed Description

IDragDropController interface, represents the controlling entity in a drag drop operation.

IDragDropController is derived should derive from IDataExchangeController by way of the partial implementation

class CDataExchangeController. Implementations of IDragDropController provide the glue between the platform dependent

drag managers (OLE and Mac OS X) and the platform independent Drag Drop framework presented bu InDesign.

See Also: IDataExchangeController

Member Function Documentation

virtual IPMDataObject* IDragDropController::AddDragItem ( uint32 itemID )

pure virtual

Add a drag item to the current drag operation. This method is called by IDragDropSource::DoAddDragContent and should normally only be called once per drag. Exceptions would be Mac only, and only when trying to emulate the behavior of another applications drag behavior (i.e the Finder).

Parameters

itemID IN the id of the item to add (almost always 1).

Precondition: a drag must be in progress

Returns: a new drag item

Postcondition: caller must release the returned data object.

virtual bool16 IDragDropController::CanInternalizeDuringTracking ( ) const

pure virtual

Can the data in a drag be internalized during the tracking phase of a drag. This question turned out to be not so simple - in essense the answer is "Well, maybe." So these days, if you have to ask the answer is no. However if you have special knowledge of the source of the drag and of the flavor being promised and the data is simple for the source to externalize - then, maybe, you can ask for the data during tracking.

Returns: always returns kFalse

virtual ErrorCode IDragDropController::ClearDrag ( )

pure virtual

Clear the controller of any knowledge of the previous drag operation. Called by the framework in preparation to begin a new drag and also at the end of all drags started within the application.

virtual bool16 IDragDropController::DidUserUseCopyGesture ( ) const

pure virtual

Was the user using the copy gesture (option/alt key pressed) at the time the drag was started?

Precondition: a drag must be in progress

Returns: kTrue or kFalse

virtual bool16 IDragDropController::DidUserUseDragChildrenGesture ( ) const

pure virtual

Was the user using the drag children gesture (cmd key pressed) at the time the drag was started?

Precondition: a drag must be in progress

Returns: kTrue or kFalse

virtual ErrorCode IDragDropController::ExternalizeDrag ( PMFlavor whichFlavor ) const

pure virtual

A framework call that is now a no-op

Parameters

whichFlavor IN flavor to externalize

Returns: kSuccess or an error code

virtual ErrorCode IDragDropController::FulfillPromise	(	IPMDataObject *	whichItem,
		const ExternalPMFlavor &	whichFlavor
	)		const

pure virtual

Render the contents of the drag out to the platform drag manager. FulfillPromise is called by the drag drop framework in response a flavor data request from an external drop target. Internally it sets up a PMFlavorStream and calls the source handler to externalize the flavor to the stream.

Parameters

whichItem	IN the IPMDataObject representing the drag item.
whichFlavor	IN which flavor to provide data for

Precondition: a drag must be in progress

Returns: kSuccess or an error code

Implements IDataExchangeController.

virtual IAbortableCmdSeq* IDragDropController::GetCommandSequence ( ) const

pure virtual

Get the command sequence encompassing the current drag. This command sequence is necessary for two-part move operations where the drag results in data being removed from the source and added to the target.

Returns: command sequence, or nil if a drag is not in progress.

virtual CursorSpec IDragDropController::GetDefaultTrackingCursorFeedback ( DragDrop::eTargetResponse targetResponse ) const

pure virtual

Allows a drop target to get the default cursor that would otherwise be used while tracking.

Parameters

targetResponse IN specify the target response for which the cursor is needed

Precondition: a drag must be in progress

Returns: the default cursor matching the supplied target response

virtual IPMDataObject* IDragDropController::GetDragItem ( uint32 itemID )

pure virtual

Retrieve a particular drag item from the current drag

Parameters

itemID IN the id of the item to retriver (almost always 1).

Precondition: a drag must be in progress

Returns: a pointer the drag item

virtual GSysPoint IDragDropController::GetDragMouseLocation ( ) const

pure virtual

Get the location of the drag. GetDragMouseLocation actually the location of the drag cursor as maintained by the platform drag manager. As such this is the location of the mouse at the start of the last callback from the platform drag manager into the Drag Drop framework. When doing drag tracking this location should be used rather than the actual current mouse location since some lag may be involved.

Returns: location of the drag cursor in global (screen) coordinates

virtual uint16 IDragDropController::GetItemCount ( )

pure virtual

How many drag items are in the current drag? Multiple drag items is strictly a Mac only concept. On Windows there is only one drag item which might contain multiple pieces of data (i.e. files or pageitems). On the Mac, multiple drag items are supported because some external applications present their data this way (i.e. in a multi-file drag the Finder uses a drag item to represent each file dragged). The DragDrop framework attempts to hide this fact as much as possible but it does appear in various places.

Precondition: a drag must be in progress

Returns: how many items are in the drag (might be zero for an internal drag with no data added yet)

virtual ErrorCode IDragDropController::InternalizeDrag	(	ExternalPMFlavor	extFlavor,
		PMFlavor	intFlavor
	)

pure virtual

Render the contents of the platform drag manager into an internal data format. Usually called from IDragDropTarget::ProcessDragDropCommands or, occasionally for internal drags, from IDragDropTarget::DoDragEnter

Parameters

extFlavor	IN specify which external flavor should be used for the conversion, or kNoExternalFlavor to let the data exchange handler decide which one to use.
intFlavor	IN specify which internal flavor you would like the data to end up in, or kNoFlavor to let the framework decide.

Precondition: a drag must be in progress

Returns: kSuccess or an error code

virtual bool16 IDragDropController::IsDragInProgress ( ) const

pure virtual

Ask the controller if a drag operation is in progress. For drags started within this application, IsDragInProgress will remain true until the platform drag manager completes the entire drag operation. However, for drags that begin in another application, IsDragInProgress will only be true while the drag is actually over one of this applications target windows.

Returns: kTrue if a drag is in progress

virtual bool16 IDragDropController::IsPatientUser ( ) const

pure virtual

Was the drag started in patient user more?

Precondition: a drag must be in progress

Returns: kTrue for patient user mode

virtual bool16 IDragDropController::IsTargetSameAsSource ( ) const

pure virtual

Description

Precondition: a drag must be in progress

Returns: kTrue of the drag source and drop target exist and are on the same boss.

virtual bool16 IDragDropController::IsUserUsingCopyGesture ( ) const

pure virtual

Is the user currently using the copy gesture (option/alt key pressed)?

Returns: kTrue for patient user mode

virtual bool16 IDragDropController::NeedsToInternalize ( ) const

pure virtual

Is data from an external drag, or data in a non-native format, waiting to be converted to an internally supported format? This method can be useful for clients that would like to peek at the drag data if it has already been internalized, or is already in a native (internal) format. Internalizing can be expensive (think import or place gun) and should not be called to generate user feedback (i.e. menu enabling, drag feedback)

Precondition: a drag must be in progress

Returns: kTrue if the data in the drag needs to be converted.

Implements CDataExchangeController.

virtual IDataExchangeHandler* IDragDropController::QueryHandlerForInternalize	(	DataExchangeResponse &	response,
		const PMFlavor &	internalizedFlavor = `kNoFlavor`
	)		const

pure virtual

Determine which data exchange handler could best handle the data in a drag. By passing a specific internal flavor, you are asking if the data in the drag can be converted into that flavor. By passing kNoFlavor, the controller will instead find the first handler which recognizes the data in the drag, regardless of the flavor of object it creates.

Parameters

response	OUT response from the data exchange handler
internalizedFlavor	IN the preferred internal flavor (native format) if data needs to be converted.

Precondition: a drag must be in progress

Returns: the handler (if any) that can provide the requested conversion.

Implements CDataExchangeController.

virtual IDataExchangeHandler* IDragDropController::QuerySourceHandler ( ) const

pure virtual

Retrieve the data exchange handler used to add data to the drag. There will always be a source handler for drags started within the application, but there will not be a source handler for drag started externally.

Precondition: a drag must be in progress

Returns: data exchange handler used when data was added to the drag, or nil for externally initiated drags.

virtual IDataExchangeHandler* IDragDropController::QueryTargetHandler ( ) const

pure virtual

Retrieve the data exchange handler requested by the drop target in the current drag. There may not be a target handler, it is not a requirement that the drop target sets a target handler.

Precondition: a drag must be in progress

Returns: data exchange handler requested by the drop target (possibly nil), or nil for externally completed drags.

virtual void IDragDropController::SetSourceHandler ( IDataExchangeHandler * handler )

pure virtual

Set the data exchange handler used by source for the current drag. Should be called from in IDragDropSource::DoAddDragContent or IDragDropSourceContentHelper::DoAddDragContent.

Parameters

handler IN the handler

Postcondition: should be called only once per drag

virtual void IDragDropController::SetTargetHandler ( IDataExchangeHandler * handler )

pure virtual

Set the data exchange handler used by target for the current drop. Called from IDragDropTarget::ProcessDragDropCommand or IDragDropTargetFlavorHelper::DoAddDragContent. It is a good think to set SetTargetHandler prior to checking NeedsToInternalize() and Internalize() as the presence of this information can help in the internalization process.

Precondition: a drag must be in progress

Parameters

handler IN the handler

virtual void IDragDropController::SetTrackingCursorFeedback ( const CursorSpec & cursor )

pure virtual

Allows a drop target to set the cursor while tracking. Targets should call SetTrackingCursorFeedback during the tracking phase DoDragEnter, DoDragWithin, DoDragLeave

Parameters

cursor IN the cursor to be shown

Precondition: a drag must be in progress

virtual bool16 IDragDropController::StartDrag	(	IDragDropSource *	,
		IEvent *	e,
		bool16	patientUser = `kFalse`
	)

pure virtual

Ask the controller to begin a drag operation.

Parameters

source	IN the drag source that will provide data for the drag
e	IN event that should initiate the drag (used for mouse location and modifier keys)
patientUser	IN whether or not the drag should happen in "patient user" mode. Typically this means the user is willing to wait a bit for better drag feedback (i.e. drag the real item vs drag an outline)

Precondition: a drag must not already be in progress

Returns: whether or not the drag succeeded

Postcondition: upon return, the drag will have completed for better or worse

virtual void IDragDropController::SuppressExternalDragHandling ( bool16 doSuppress )

pure virtual

Suppress external drag handling. During certain critical sections (EventAvail, PreviewModalDialogs, ProgressBar, CommandProcessing) we have to refuse drag messages for drags initiated outside InDesign to avoid getting messages out of order as well as avoiding re-entrancy in the command processor. Don't call this method directly, use stack based class below to guarantee balance.

Parameters

doSuppress IN kTrue to suppress drag handling, kFalse to restore it

virtual bool16 IDragDropController::WillTargetProvideCursorFeedback ( ) const

pure virtual

Allows framework to see if the target will be providing cursor feedback while tracking - FRAMEWORK USE ONLY.

Precondition: a drag must be in progress

Returns: kTrue if the target will provide cursor feedback.

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation