IOleInPlaceObjectWindowless::GetDropTarget method (ocidl.h)

Article
10/13/2021

Retrieves the IDropTarget interface for an in-place active, windowless object that supports drag and drop.

Syntax

HRESULT GetDropTarget(
  [out] IDropTarget **ppDropTarget
);

Parameters

[out] ppDropTarget

A pointer to an IDropTarget pointer variable that receives the interface pointer to the windowless object.

Return value

This method returns S_OK on success. Other possible return values include the following.

Return code	Description
E_NOTIMPL	The windowless object does not support drag and drop.

Remarks

A windowed object registers its IDropTarget interface by calling the RegisterDragDrop function and supplying its window handle as a parameter. Registering its IDropTarget interface enables the object to participate in drag and drop operations. Because it does not have a window when active, a windowless object cannot register its IDropTarget interface. Therefore, it cannot directly participate in drag and drop operations without support from its container.

The following events occur during a drag and drop operation involving windowless objects:

The container registers its own IDropTarget interface through the RegisterDragDrop function.
In the container's implementation of its own IDropTarget::DragEnter or IDropTarget::DragOver methods, the container detects whether the mouse pointer just entered an embedded object.
If the object is inactive, the container calls the object's IPointerInactive::GetActivationPolicy method. The object returns the POINTERINACTIVE_ACTIVATEONDRAG flag. The container then activates the object in place. If the object was already active, the container does not have to do this step.
After the object is active, the container must then obtain the object's IDropTarget interface.
A windowless object that wishes to be a drop target still implements the IDropTarget interface, but does not register it and does not return it through calls to IUnknown::QueryInterface. Instead, the container can obtain this interface by calling the object's IOleInPlaceObjectWindowless::GetDropTarget method. The object returns a pointer to its own IDropTarget interface if it wants to participate in drag and drop operations. The container can cache this interface pointer for later use. For example, on subsequent calls to the container's IDropTarget::DragEnter or IDropTarget::DragLeave methods, the container can use the cached pointer instead of calling the object's GetDropTarget method again.
The container then calls the object's IDropTarget::DragEnter and passes the returned value for pdwEffect from its own IDropTarget::DragOver or IDropTarget::DragEnter methods. From this point on, the container forwards all subsequent IDropTarget::DragOver calls to the windowless object until the mouse leaves the object or a drop occurs on the object. If the mouse leaves the object, the container calls the object's IDropTarget::DragLeave and then releases the object's IDropTarget interface. If the drop occurs, the container forwards the IDropTarget::Drop call to the object.
Finally, the container in-place deactivates the object.

An object can return S_FALSE from its own IDropTarget::DragEnter to indicate that it does not accept any of the data formats in the data object. In that case, the container can decide to accept the data for itself and return an appropriate dwEffect from its own IDropTarget::DragEnter or IDropTarget::DragOver methods.

An object that returns S_FALSE from IDropTarget::DragEnter should be prepared to receive subsequent calls to IDropTarget::DragEnter without any IDropTarget::DragLeave in between. Indeed, if the mouse is still over the same object during the next call to the container's IDropTarget::DragOver, the container may decide to try and call IDropTarget::DragEnter again on the object.

Notes to Callers

A container can cache the pointer to the object's IDropTarget interface for later use.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	ocidl.h