IOleInPlaceObjectWindowless::GetDropTarget

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

HRESULT GetDropTarget(
  IDropTarget** ppDropTarget   //Address of output variable that 
                               // receives the IDropTarget interface 
                               // pointer
);

Parameters

ppDropTarget: [out] Address of IDropTarget* pointer variable that receives the interface pointer to the windowless object.

Return Values

S_OK: The IDropTarget interface was successfully returned.
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.
Once 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 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 DragOver or DragEnter methods. From this point on, the container forwards all subsequent 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::DragDrop 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 DragEnter or DragOver methods. Note that an object that returns S_FALSE from DragEnter should be prepared to receive subsequent calls to DragEnter without any DragLeave in between. Indeed, if the mouse is still over the same object during the next call to the container's DragOver, the container may decide to try and call DragEnter again on the object.

Note to Callers

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

QuickInfo

  Windows NT: Use version 4.0 or later. New for OC96.
  Windows: Use Windows 95 or later. New for OC96.
  Windows CE: Unsupported.
  Header: Declared in ocidl.h.