[Classes] [Prev] [Next] [Methods]

CDragSource

Methods Index

Heritage
Description
Usage
Protected Data Members
Overrides
Public Methods
Constructor, Destructor, and Initializer Methods
Utility Methods
Mouse Event Methods
Protected Methods

CDragSource


Heritage

Superclass: CMouseHandler

Subclass: CAttachment, CViewSource


Description

CDragSource is a mouse handler used to implement "drag-and-drop" behavior.


Usage

CDragSource handles mouse events and converts them into drag-and-drop events propagated to zero or more CDragSinks. CDragSinks are objects representing an area on the screen that can receive drag-and-drop events.

CDragSource and CDragSink have a many-to-many association: a source can service zero or more sinks, and a sink can be registered with zero or more sources. This association is automatically managed: destruction of a sink automatically unregisters it with a source. In addition, destruction of a source unregisters all of its sinks and destroys those not registered with another drag source.

As a mouse handler, CDragSource ignores all events until it enters a drag-and-drop mode. It is up to the owner of the drag source to start the drag-and-drop mode by calling DoDrag(). Upon receiving this call, CDragSource starts managing mouse events by translating them into drag-and-drop events for the registered sinks. The drag-and-drop mode is automatically ended when CDragSource receives a mouse-up event.

For each drag-and-drop event, CDragSource searches its list of registered sinks for an appropriate target. The order of the search depends on the OrderPolicy of the CDragSource. When the policy is STATIC (the default), sinks are searched in the order of registration. When the order is DYNAMIC, the sinks are searched in the order defined by virtual method ShuffleSinks(). CDragSource's implementation of this method (which you may override) is to order sinks according to their window stacking order.

For an example of a CDragSource implementation which automatically enters drag-and-drop mode, see the CViewSink class.

The following example shows common usage of this class:

// Instantiate CDragSource

itsDragSource = new CDragSource();
...

// Register drag sinks with the drag source

CDragSink *aSinkOne;
CDragSink *aSinkTwo;
CDragSink *aSinkThree;
...

itsDragSource->RegisterSink(aSinkOne);
itsDragSource->RegisterSink(aSinkTwo);
itsDragSource->RegisterSink(aSinkThree, FALSE);

// FALSE as the 2nd argument for RegisterSink causes the
// drag sink being registered to be "behind" the previously
// registered drag sinks. This means the newly registered
// drag sink be the last sink to be tested for IsInSink.
//
// The default behavior (or TRUE as the 2nd argument to
// RegisterSink) is to place the newly registered drag sink
// "on top of" the previously registered drag sinks. In
// other words, the newly registered drag sink will have
// IsInSink called on it before the previously registered
// drag sinks.

...

// Start the drag with some drag data (which will be passed
// to methods.
// Also, indicate the CWindow to trap the pointer to and
// the cursor to use for dragging.

itsDragSource->DoDrag(
someDragCommand, someDragData, aWindow,
CURSOR_CROSS);

// While dragging, the registered CDragSinks will receive
// notification of enter, leave, drag, and drop on a sink
// as follows:
//
// CDragSink::DoEnter() will be called
// for a particular drag sink every time the dragging item
// "enters" the sink. The term "enters" is defined by any
// time the CDragSink::IsInSink returns TRUE when it had
// previously returned FALSE.

...

// destroy the drag source
// note that this deletes all registered sinks which are not
// shared by another CDragSource

delete itsDragSource;

Public Data Members
None


Protected Data Members

RWGDlist
(CDragSink)*
itsSinks; List of sinks registered with source
CDragSink* itsLastSink; Caches the last enetered sink
long itsDragCommand; Generated with each drag-drop event
void* itsDragData; Passed as theData of each drag-droip event
BOOLEAN itIsDragging; Internal mouse state
CURSOR itsNonDragCursor; Used while not in drag-drop mode
CWindow* itsTrappedWindow; Window passed to DoDrag method
CPoint itsLastLocation; Caches mouse lacation
OrderPolicy itsSinkOrder; Helps determine sink visit order


Overrides


Public Methods

Constructor, Destructor, and Initializer Methods

CDragSource();
CDragSource(const CDragSource& theDragSource);
CDragSource& operator=(const CDragSource& theDragSource);
virtual ~CDragSource();

Utility Methods

virtual void RegisterSink(
CDragSink *theDragSink,
BOOLEAN isInFront = TRUE);
virtual void UnregisterSink(CDragSink *theDragSink);
virtual void DoDrag(
long theDragCommand,
void* theDragData,
CWindow *theTrapWindow,
CURSOR theDragCursor = CURSOR_ARROW);

theDragCommand A command ID describing the type of data being dragged or the drag event being initiated.
theDragData A pointer to some data which should be dragged off to a sink. Sinks can use theDragCommand to determine the type of the drag data for casting purposes.
theTrapWindow This should be a pointer to the window where the drag source is registered.
theDragCursor An alternative cursor resource to use during the drag-and-drop operation.

void SetSinkOrder(OrderPolicy aPolicy);
OrderPolicy GetSinkOrder() const;

Mouse Event Methods

virtual BOOLEAN DoUp(
CPoint& theLocation,
short& theButton,
BOOLEAN& isShiftKey,
BOOLEAN& isControlKey);
virtual BOOLEAN DoDown(
CPoint& theLocation,
short& theButton,
BOOLEAN& isShiftKey,
BOOLEAN& isControlKey);
virtual BOOLEAN DoDouble(
CPoint& theLocation,
short& theButton,
BOOLEAN& isShiftKey,
BOOLEAN& isControlKey);
virtual BOOLEAN DoMove(
CPoint& theLocation,
short& theButton,
BOOLEAN& isShiftKey,
BOOLEAN& isControlKey);
Overrides of CMouseHandler mouse event methods. These methods iterate the registered sinks, calling CDragSink::IsInSink() for each, until one returns TRUE. At that point an appropriate drag-and-drop event is passed on to the sink.

virtual BOOLEAN UsesGlobalCoords(void);

Protected Methods

virtual void ShuffleSinks(void);


[Classes] [Prev] [Next] [Methods]

support@xvt.com


Visit our online help desk for tech support

Copyright © 2009, Providence Software Solutions Inc. All rights reserved.