IDropTarget::DragOver (Windows CE 5.0)

Article
09/14/2012

This method provides target feedback to the user and communicates the drop's effect to the DoDragDrop function so it can communicate the effect of the drop back to the source.

Syntax

HRESULT DragOver(  DWORD grfKeyState,  POINTL pt,  DWORD* pdwEffect);

Parameters

grfKeyState
[in] Current state of the keyboard modifier keys on the keyboard. Valid values can be a combination of any of the flags shown in the following table:

Flag	Description
MK_ALT	The user pressed the ALT key.
MK_CONTROL	The user pressed the CTRL key.
MK_LBUTTON	The user pressed the left mouse button.
MK_MBUTTON	The user pressed the middle mouse button.
MK_RBUTTON	The user pressed the right mouse button.
MK_SHIFT	The user pressed the SHIFT key.

pt
[in] POINTL structure containing the current cursor coordinates in screen coordinates.
pdwEffect
[in, out] Pointer to the current effect flag. Valid values are from the enumeration DROPEFFECT.

Return Values

This method returns S_OK if successful. Otherwise, it returns one of the following values:

E_INVALIDARG
E_OUTOFMEMORY
E_UNEXPECTED

Remarks

Do not call IDropTarget::DragOver directly. The DoDragDrop function calls this method each time the user moves the mouse across a given target window. DoDragDrop exits the loop if the drag-and-drop operation is canceled, if the user drags the mouse out of the target window, or if the drop is completed.

In implementing IDropTarget::DragOver, you must provide features similar to those in IDropTarget::DragEnter. You must also determine the effect of dropping the data on the target by examining the FORMATETC structure that defines the data object's formats and medium, along with the state of the modifier keys. The mouse position may also play a role in determining the effect of a drop.

The following table shows how modifier keys affect the result of the drop.

Key combination	User-visible feedback	DROPEFFECT value
CTRL + SHIFT	=	DROPEFFECT_LINK
CTRL	+	DROPEFFECT_COPY
No keys or SHIFT	None	DROPEFFECT_MOVE

Communicate the effect of the drop back to the source through DoDragDrop in pdwEffect. The DoDragDrop function then calls IDropSource::GiveFeedback so the source application can display the appropriate visual feedback to the user.

On entry to IDropTarget::DragOver, the pdwEffect parameter must be set to the allowed effects passed to the pdwOkEffect parameter of the DoDragDrop function. The IDropTarget::DragOver method must be able to choose one of these effects or disable the drop.

Upon return, pdwEffect is set to one of the members of the DROPEFFECT enumeration. This value is then passed to the pdwEffect parameter of DoDragDrop. The following table shows common values and their associated effects.

Value	Effect
DROPEFFECT_COPY	Copies the dragged data to the target
DROPEFFECT_LINK	Creates a link to the source data, or
DROPEFFECT_MOVE	Allows the dragged data to be permanently moved from the source application to the target.

You may also wish to provide appropriate visual feedback in the target window. There may be some target feedback already displayed from a previous call to IDropTarget::DragOver or from the initial IDropTarget::DragEnter. If this feedback is no longer appropriate, you should remove it.

For efficiency, a data object is not passed in IDropTarget::DragOver. The data object passed in the most recent call to IDropTarget::DragEnter is available and can be used.

When IDropTarget::DragOver has completed its operation, the DoDragDrop function calls IDropSource::GiveFeedback so the source application can display the appropriate visual feedback to the user.

Notes to Implementers

This function is called frequently during the DoDragDrop loop so it makes sense to optimize your implementation of the IDropTarget::DragOver method as much as possible.

Requirements

OS Versions: Windows CE .NET 4.2 and later.
Header: Shobjidl.h, Shobjidl.idl.
Link Library: Implementation dependent.

Share via