IPointerInactive::OnInactiveSetCursor

Sets the mouse pointer for an inactive object. This method is called by the container on receipt of a WM_SETCURSOR method when an inactive object is under the mouse pointer.

HRESULT OnInactiveSetCursor(

LPCRECT pRectBounds,	//Object bounding rectangle
LONG x,	//Horizontal coordinate
LONG y,	//Vertical coordinate
DWORD dwMouseMsg,	//Mouse message identifier
BOOL fSetAlways	//Indicates whether object must set the mouse pointer
);

Parameter

pRectBounds

[in] The object bounding rectangle specified in client coordinate units of the containing window. This parameter tells the object its exact position and size on the screen when the WM_SETCURSOR message was received. This value is specified in units of the client’s coordinate system.

x

[in] Horizontal coordinate of mouse location in units of the client’s containing window.

y

[in] Vertical coordinate of mouse location in units of the client’s containing window.

dwMouseMsg

[in] Identifier of the mouse message for which a WM_SETCURSOR occurred.

fSetAlways

[in] If this value is TRUE, the object must set the cursor; if this value is FALSE, the object is not obligated to set the cursor, and should return S_FALSE in that case.

Return Values

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

S_OK

The mouse pointer was successfully set.

S_FALSE

The object did not set the cursor; the container should either set the cursor or call the object again with the parameter fSetAlways set to TRUE.

Remarks

The container calls this method to set the mouse pointer over an inactive object after checking the object’s activation policy by calling the IPointerInactive::GetActivationPolicy method. If the object has not requested to be activated in-place through that call, the container dispatches subsequent WM_SETCURSOR messages to the inactive object by calling OnInactiveSetCursor as long as the mouse pointer stays over the object.

To avoid rounding errors and to make the job easier on the object implementer, this method takes window coordinates in the units of its containing client window, that is, the window in which the object is displayed, instead of the usual HIMETRIC units. Thus, the same coordinates and code path can be used when the object is active and inactive. The window coordinates specify the mouse position. The bounding rectangle is also specified in the same coordinate system.

OnInactiveSetCursor takes an additional parameter (fSetAlways) indicating whether the object is obligated to set the cursor or not. Containers should first call this method with this parameter FALSE. The object may return S_FALSE to indicate that it did not set the cursor. In that case, the container should either set the cursor itself, or, if it does not wish to do this, call the OnInactiveSetCursor method again with fSetAlways being TRUE.

See Also

IPointerInactive::GetActivationPolicy