IOleInPlaceUIWindow::SetActiveObject method (oleidl.h)

Provides a direct channel of communication between the object and each of the frame and document windows.

Syntax

HRESULT SetActiveObject(
  [in] IOleInPlaceActiveObject *pActiveObject,
  [in] LPCOLESTR               pszObjName
);

Parameters

[in] pActiveObject

A pointer to the IOleInPlaceActiveObject interface on the active in-place object.

[in] pszObjName

A pointer to a string containing a name that describes the object an embedding container can use in composing its window title. It can be NULL if the object does not require the container to change its window titles. Containers should ignore this parameter and always use their own name in the title bar.

Return value

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

Return code Description
E_UNEXPECTED
An unexpected error has occurred.

Remarks

Generally, an embedded object should pass NULL for the pszObjName parameter (see Notes to Implementers below). However, if you are working in conjunction with a container that does display the name of the in-place active object in its title bar, then you should compose a string in the following form: <application name> – <object short-type name>.

Notes to Callers

IOleInPlaceUIWindow::SetActiveObject is called by the object to establish a direct communication link between itself and the document and frame windows.

When deactivating, the object calls IOleInPlaceUIWindow::SetActiveObject, passing NULL for the pActiveObject and pszObjName parameters.

An object must call IOleInPlaceUIWindow::SetActiveObject before calling IOleInPlaceFrame::SetMenu to give the container the pointer to the active object. The container then uses this pointer in processing IOleInPlaceFrame::SetMenu and to pass to OleSetMenuDescriptor.

Notes to Implementers

The Microsoft Windows User Interface Design Guide recommends that an in-place container ignore the pszObjName parameter passed in this method. The guide says "The title bar is not affected by in-place activation. It always displays the top-level container's name."

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 oleidl.h

See also

IOleInPlaceFrame::SetMenu

IOleInPlaceUIWindow

OleSetMenuDescriptor