IDropTarget::DragOver (Compact 2013)
3/28/2014
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 Value
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
Header |
shobjidl.h, |
Library |
Developer Implemented |
See Also
Reference
IDropTarget
IDropTarget::DragEnter