IDropTarget::DragEnter

Other versions of this page are also available for the following:

• Windows Embedded CE 6.0 R3

8/28/2008

This method indicates whether a drop can be accepted, and, if so, the effect of the drop.

Syntax

HRESULT DragEnter(
  IDataObject* pDataObject,
  DWORD grfKeyState,
  POINTL pt,
  DWORD* pdwEffect
);

Parameters

• pDataObject
  [in] Pointer to the IDataObject interface on the data object. This data object contains the data being transferred in the drag-and-drop operation. If the drop occurs, this data object will be incorporated into the target.

• 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] On entry, pointer to the value of the pdwEffect parameter of the DoDragDrop function. On return, must contain one of the effect flags from the DROPEFFECT enumeration, which indicates what the result of the drop operation will be.

Return Value

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

• E_OUTOFMEMORY
• E_INVALIDARG
• E_UNEXPECTED

Remarks

Do not call IDropTarget::DragEnter directly; instead, the DoDragDrop function calls it to determine the effect of a drop the first time the user drags the mouse into the registered window of a drop target.

To implement IDropTarget::DragEnter, you must determine whether the target can use the data in the source data object by checking three things:

• The format and medium specified by the data object
• The input value of pdwEffect
• The state of the modifier keys

To check the format and medium, use the IDataObject pointer passed in the pDataObject parameter to call IDataObject::EnumFormatEtc so you can enumerate the FORMATETC structures that the source data object supports. Then call IDataObject::QueryGetData to determine whether the data object can render the data on the target by examining the formats and medium specified for the data object.

On entry to IDropTarget::DragEnter, the pdwEffect parameter is set to the effects given to the pdwOkEffect parameter of the DoDragDrop function. The IDropTarget::DragEnter method must choose one of these effects or disable the drop.

The following table shows modifier keys that 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

On return, the method must write the effect, one of the members of the DROPEFFECT enumeration, to the pdwEffect parameter. DoDragDrop then takes the IDropTarget::DragEnter pdwEffect parameter and writes it to its own pdwEffect parameter. Communicate the effect of the drop back to the source through DoDragDrop in the pdwEffect parameter. The DoDragDrop function then calls IDropSource::GiveFeedback so that the source application can display the appropriate visual feedback to the user through the target window.

Requirements

Header	shobjidl.h, shobjidl.idl
Library	Developer Implemented
Windows Embedded CE	Windows CE .NET 4.2 and later

See Also

Reference

IDropTarget

Other Resources

IDataObject
IDataObject::EnumFormatEtc
FORMATETC
IDataObject::QueryGetData