IPointerInactive::GetActivationPolicy

Returns the present activation policy for the object. This method is called by the container on receipt of a WM_SETCURSOR or WM_MOUSEMOVE message when an inactive object is under the mouse pointer.

HRESULT GetActivationPolicy(
  DWORD* pdwPolicy   //Pointer to activation policy
);
 

Parameter

pdwPolicy
[out] Pointer to the activation policy as specified by the POINTERINACTIVE enumeration values.

Return Values

This method supports the standard return value E_FAIL, as well as the following:

S_OK
The activation policy was successfully returned.

Remarks

A container calls this method when it receives a WM_SETCURSOR or WM_MOUSEMOVE message with the mouse pointer over an inactive object that supports IPointerInactive. The object returns its activation policy through the POINTERINACTIVE enumeration values.

The object can request to be in-place activated as soon as the mouse enters it through the POINTERINACTIVE_ACTIVATEONENTRY value. An object that provides more visual feedback than simply setting the mouse pointer would use this value. For example, if the object supports special visual feedback, it must enter the active state so it can draw the visual feedback that it supports.

An object can also use this method to request activation when the mouse is dragged over them during a drag and drop operation through the POINTERINACTIVE_ACTIVATEONDRAG. See the POINTERINACTIVE enumeration for more information.

If the object returns one of these values, the container should activate the object immediately and forward the Window message that triggered the call. The object then stays active and processes subsequent messages through its own window until the container gets another WM_SETCURSOR or WM_MOUSEMOVE. At this point, the container should deactivate the object.

Note  For windowless OLE objects this mechanism is slightly different. See IOleInPlaceSiteWindowless for more information on drag and drop operations for windowless objects.

If the object returns both the POINTERINACTIVE_ACTIVATEONENTRY and the POINTERINACTIVE_DEACTIVATEONLEAVE values, the object is activated only when the mouse is over the object. If the POINTERINACTIVE_ACTIVATEONENTRY value alone is set, the object is activated once when the mouse first enters it, and it remains active.

Note to Callers

The activation policy should not be cached. The container should call this method each time the mouse enters an inactive object.

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.

See Also

IOleInPlaceSiteWindowless, POINTERINACTIVE