LDragTask

LDragTask is a PowerPlant class that is used for encapsulating a single drag action initiated using the Mac OS Drag Manager.

Methods :

The methods in this class are:

LDragTask()	~LDragTask()
AddFlavors()	AddRectDragItem()
DoDrag()	DropLocationIsFinderTrash()
GetDragReference()	GetDragRegion()
InitDragTask()	MakeDragRegion()

Data Members:

The data members in this class are:

mDragRef	mDragRegion
mEventRecord

Operation :

Normally, you will use this class in conjunction with the LDragAndDrop class. To learn more information about using this class, refer to PowerPlant Advanced Topics.

Source files:

(Feature Classes)

LDragTask.h

LDragTask.cp

See also:

LDragAndDrop

LDragTask()

Purpose:

The constructors create objects from the passed-in parameters.

Access:

Public

Prototypes:

LDragTask( const EventRecord &inEventRecord );

// This constructor is for dragging a single, rectangular item

LDragTask( const EventRecord &inEventRecord,

const Rect &inItemRect,

ItemReference inItemRef,

FlavorType inFlavor,

void *inDataPtr,

Size inDataSize,

FlavorFlags inFlags );

// This constructor is for dragging an item outlined by a region

LDragTask( const EventRecord &inEventRecord,

RgnHandle inItemRgn,

ItemReference inItemRef,

FlavorType inFlavor,

void *inDataPtr,

Size inDataSize,

FlavorFlags inFlags );

These constructors have the following parameters:

const   EventRecord&	inEventRecord	A reference to the Mac OS Toolbox mouse down EventRecord.
const Rect&	inItemRect	The Rect coordinates of the drag.
ItemReference	inItemRef	A reference to the item that is in the drag.
FlavorType	inFlavor	This is the "flavor," or data type for the drag.
void*	inDataPtr	This is a pointer to the data block for the drag.
Size	inDataSize	This is the size of the data block.
FlavorFlags	inFlags	This is a value for flavor flags, defined in the Drag.h Mac OS system header.
RgnHandle	inItemRgn	This must be in global coordinates, and will not be disposed of by this class.

Remarks:

The inItemRect is in the local coordinates of the current port, so you may need to call SetPort (or FocusDraw) beforehand.

~LDragTask()

Purpose:

The destructor destroys the object.

Access:

VIrtual, Public

Prototype:

virtual ~LDragTask();

AddFlavors()

Purpose:

Add flavored items to the DragTask. If you use the short form of the LDragTask() constructor (EventRecord only), you must override this function to add items to the drag task.

Access:

Virtual, Protected

Prototype:

void AddFlavors(DragReference inDragRef );

The parameter for this method is:

DragReference

inDragRef

A reference to an item to add to the drag.

Return:

None

AddRectDragItem()

Purpose:

This is a utility method for adding a rectangular item to the drag.

Access:

Virtual, Protected

Prototype:

void AddRectDragItem( ItemReference inItemRef,

const Rect &inItemRect);

This method has the following parameters:

ItemReference	inItemRef	A reference to the item to add to the drag.
const Rect&	inItemRect	The Rect must be in Global coordinates.

Return:

None

DoDrag()

Purpose:

This method performs a drag task. This function calls other member functions to add items to the drag and build the drag region, then calls the Drag Mananger to track the drag. You will not normally override this function.

Access:

Virtual, Public

Prototype:

OSErr DoDrag(); 

None

Return:

This method returns an OSErr error code if an error occurs executing the drag. If no error occurs, the return value will be noErr.

DropLocationIsFinderTrash()

Purpose:

Return whether the drop location of the Drag is the Finder's Trash can Normally, you'll call this routine after the Drag completes to determine whether to delete the dragged items.

Access:

Public

Prototype:

Boolean DropLocationIsFinderTrash();

None

Return:

A Boolean indicating whether the drop location of the drag is the Finder's trash can.

Remarks:

Normally, you'll call this routine after the drag completes to determine whether to delete the dragged items.

GetDragReference()

Purpose:

This method returns the value of mDragRef.

Access:

Public, Inline

Prototype:

DragReference GetDragReference();

None

Return:

A DragReference containing the value of mDragRef.

GetDragRegion()

Purpose:

This method returns the value of mDragRegion.

Access:

Public, Inline

Prototype:

RgnHandle GetDragRegion(); 

None

Return:

A RgnHandle containing the value of mDragRegion.

InitDragTask()

Purpose:

This method is a private initializer for the class.

Access:

Private

Prototype:

void InitDragTask();

None

Return:

None

MakeDragRegion()

Purpose:

Build the region outlining the items to be dragged.

Access:

Virtual, Protected

Prototype:

void MakeDragRegion( DragReference inDragRef,

RgnHandle inDragRegion );

This method has the following parameters:

DragReference	inDragRef	A reference to the item in the drag.
RgnHandle	inDragRegion	The drag region for the item.

Return:

None

Remarks:

If you use the short form of the LDragTask() constructor (EventRecord only), you must override this function to specify the drag region for each item in the drag task.

mDragRef

Purpose:

This data member is the drag reference.

Access:

Protected

Prototype:

DragReference mDragRef;

mDragRegion

Purpose:

This data member is the drag region.

Access:

Protected

Prototype:

RgnHandle mDragRegion;

mEventRecord

Purpose:

This data member is the eent record, containing information about the event that just occurred.

Access:

Protected

Prototype:

const EventRecord &mEventRecord;