SHSimulateDrop

This function performs a drag and drop on a given drop target.

Declaration

HRESULT 
SHSimulateDrop (
    IDropTarget *pDropTarget, 
    IDataObject *pDataObj, 
    DWORD grfKeyState, 
    POINTL *pt, 
    DWORD *pdwEffect);

Parameters

The pDropTarget argument describes an object that receives data in a drag-and-drop operation.

The pDataObj argument describes the source data.

The grfKeyState argument is a set of bit flags to describe control keys that modify the drag-and-drop.

The pt argument is the address of a structure that provides the cursor position, measured in screen coordinates. This argument can be NULL to represent the screen origin.

The pdwEffect argument is the address of a variable that provides input and receives output. On input, bits in the variable specify the permitted drop effects. On output, the variable indicates which effect applied. This argument can be NULL to imply the combination of DROPEFFECT_COPY, DROPEFFECT_MOVE and DROPEFFECT_LINK.

Return Value

The function returns zero for success, else an error code.

Behaviour

This function is a utility for calling the drop target’s methods in a reliable way to effect a transfer from the data object to the drop target. The arguments correspond closely with those of the DragEnter and Drop methods. For the supported values of the grfKeyState argument and of the variable that is addressed by the pdwEffect argument, refer to the documentation of those methods.

The function first calls the drop target’s DragEnter method. If the pt or pdwEffect arguments are NULL, the function supplies dummies.

If the DragEnter method selects DROPEFFECT_NONE as the effect it can produce, then the function abandons the drop. It calls the drop target’s DragLeave method and returns S_FALSE. The variable at pdwEffect, if provided, receives DROPEFFECT_NONE.

Otherwise, the function proceeds to the drop target’s Drop method and returns its results.

Availability

The SHSimulateDrop function is exported from SHLWAPI.DLL as ordinal 186 in version 5.00 and higher.

Though this function dates from as long ago as 1999, it was still not documented by Microsoft as late as the January 2007 edition of the Windows Vista Software Development Kit (SDK).