IOleInPlaceSiteWindowless::SetCapture method

Enables an in-place active, windowless object to capture all mouse messages.

Syntax


HRESULT SetCapture(
  [in] BOOL fCapture
);

Parameters

fCapture [in]

If TRUE, the container should capture the mouse for the object. If FALSE, the container should release mouse capture for the object.

Return value

This method returns S_OK if the mouse capture was successfully granted to the object. If called to release the mouse capture, this method must not fail. Other possible return values include the following.

Return codeDescription
S_FALSE

Mouse capture was denied to the object.

 

Remarks

A windowless object captures the mouse input, by calling IOleInPlaceSiteWindowless::SetCapture with TRUE on its site object. The container can deny mouse capture, in which case this method returns S_FALSE. If the capture is granted, the container must set the Windows mouse capture to its own window and dispatch any subsequent mouse message to the object, regardless of whether the mouse cursor position is over this object or not.

The object can later release mouse capture by calling IOleInPlaceSiteWindowless::SetCapture with FALSE on its site object. The capture can also be released because of an external event, such as the ESC key being pressed. In this case, the object is notified by a WM_CANCELMODE message that the container dispatches along with the keyboard focus.

Containers should dispatch all mouse messages, including WM_SETCURSOR, to the windowless OLE object that has captured the mouse. If no object has captured the mouse, the container should dispatch the mouse message to the object under the mouse cursor.

The container dispatches these window messages by calling IOleInPlaceObjectWindowless::OnWindowMessage on the windowless object. The windowless object can return S_FALSE to this method to indicate that it did not process the mouse message. Then, the container should perform the default behavior for the message by calling the DefWindowProc function. For WM_SETCURSOR, the container can either set the cursor itself or do nothing.

Objects can also use IOleInPlaceSiteWindowless::OnDefWindowMessage to invoke the default message processing from the container. In the case of the WM_SETCURSOR message, this allows an object to take action if the container does not set the cursor.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

OCIdl.h

IDL

OCIdl.idl

IID

IID_IOleInPlaceSiteWindowless is defined as 922EADA0-3424-11CF-B670-00AA004CD6D8

See also

IOleInPlaceSiteWindowless
IOleInPlaceSiteWindowless::OnDefWindowMessage

 

 

Show: