Método IOleInPlaceUIWindow::SetActiveObject (oleidl.h)

Artigo
03/01/2024

Fornece um canal direto de comunicação entre o objeto e cada uma das janelas de quadro e documento.

Sintaxe

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

Parâmetros

[in] pActiveObject

Um ponteiro para a interface IOleInPlaceActiveObject no objeto in-loco ativo.

[in] pszObjName

Um ponteiro para uma cadeia de caracteres que contém um nome que descreve o objeto que um contêiner de inserção pode usar na composição de seu título de janela. Ele poderá ser NULL se o objeto não exigir que o contêiner altere seus títulos de janela. Os contêineres devem ignorar esse parâmetro e sempre usar seu próprio nome na barra de título.

Retornar valor

Esse método retorna S_OK com êxito. Outros valores retornados possíveis incluem o seguinte.

Código de retorno	Descrição
E_UNEXPECTED	Ocorreu um erro inesperado.

Comentários

Em geral, um objeto inserido deve passar NULL para o parâmetro pszObjName (consulte Anotações para implementadores abaixo). No entanto, se você estiver trabalhando em conjunto com um contêiner que exibe o nome do objeto ativo in-loco em sua barra de título, deverá compor uma cadeia de caracteres na seguinte forma: <nome> do aplicativo – < nome >de tipo curto de objeto.

Anotações para chamadores

IOleInPlaceUIWindow::SetActiveObject é chamado pelo objeto para estabelecer um link de comunicação direta entre si e as janelas de documento e quadro.

Ao desativar, o objeto chama IOleInPlaceUIWindow::SetActiveObject, passando NULL para os parâmetros pActiveObject e pszObjName.

Um objeto deve chamar IOleInPlaceUIWindow::SetActiveObject antes de chamar IOleInPlaceFrame::SetMenu para dar ao contêiner o ponteiro para o objeto ativo. Em seguida, o contêiner usa esse ponteiro no processamento de IOleInPlaceFrame::SetMenu e para passar para OleSetMenuDescriptor.

Anotações aos implementadores

O Guia de Design da Interface do Usuário do Microsoft Windows recomenda que um contêiner in-loco ignore o parâmetro pszObjName passado nesse método. O guia diz "A barra de título não é afetada pela ativação in-loco. Ele sempre exibe o nome do contêiner de nível superior."

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	oleidl.h