Funções globais do controle composto
Essas funções fornecem suporte para a criação de caixas de diálogo e para criar, hospedar e licenciar controles ActiveX.
Importante
As funções listadas na tabela a seguir não podem ser usadas em aplicativos que são executados no Windows Runtime.
| Função | Descrição |
|---|---|
| AtlAxDialogBox | Cria uma caixa de diálogo modal a partir de um modelo de caixa de diálogo fornecido pelo usuário. A caixa de diálogo resultante pode conter controles ActiveX. |
| AtlAxCreateDialog | Cria uma caixa de diálogo sem modo a partir de um modelo de caixa de diálogo fornecido pelo usuário. A caixa de diálogo resultante pode conter controles ActiveX. |
| AtlAxCreateControl | Cria um controle ActiveX, inicializa-o e hospeda-o na janela especificada. |
| AtlAxCreateControlEx | Cria um controle ActiveX, inicializa-o, hospeda-o na janela especificada e recupera um ponteiro (ou ponteiros) de interface pelo controle. |
| AtlAxCreateControlLic | Cria um controle ActiveX licenciado, inicializa-o e hospeda-o na janela especificada. |
| AtlAxCreateControlLicEx | Cria um controle ActiveX licenciado, inicializa-o, hospeda-o na janela especificada e recupera um ponteiro de interface (ou ponteiros) do controle. |
| AtlAxAttachControl | Anexa um controle criado anteriormente à janela especificada. |
| AtlAxGetHost | Usado para obter um ponteiro de interface direta para o contêiner para uma janela especificada (se houver), de acordo com seu identificador. |
| AtlAxGetControl | Usado para obter um ponteiro de interface direto para o controle dentro de uma janela especificada (se houver), dado o identificador. |
| AtlSetChildSite | Inicializa o IUnknown do site filho. |
| AtlAxWinInit | Inicializa o código de hospedagem para objetos AxWin. |
| AtlAxWinTerm | Cancela a inicialização do código de hospedagem para objetos AxWin. |
| AtlGetObjectSourceInterface | Recupera informações sobre a interface padrão de origem de um objeto. |
Requisitos
Cabeçalho: atlhost.h
AtlAxDialogBox
Cria uma caixa de diálogo modal a partir de um modelo de caixa de diálogo fornecido pelo usuário.
ATLAPI_(int) AtlAxDialogBox(
HINSTANCE hInstance,
LPCWSTR lpTemplateName,
HWND hWndParent,
DLGPROC lpDialogProc,
LPARAM dwInitParam);
Parâmetros
hInstância
[in] Identifica uma instância do módulo cujo arquivo executável contém o modelo da caixa de diálogo.
lpTemplateName
[in] Identifica o modelo da caixa de diálogo. Esse parâmetro é o ponteiro para uma cadeia de caracteres com término nulo que especifica o nome do modelo da caixa de diálogo ou é um valor inteiro que especifica o identificador de recurso do modelo da caixa de diálogo. Se o parâmetro especificar um identificador de recurso, a palavra de alta ordem deverá ser zero e a palavra de baixa ordem deverá conter o identificador. Você pode usar a macro MAKEINTRESOURCE para criar esse valor.
hWndParent
[in] Identifica a janela à qual a caixa de diálogo pertence.
lpDialogProc
[in] Aponta para o procedimento da caixa de diálogo. Para saber mais sobre o procedimento da caixa de diálogo, confira DialogProc.
dwInitParam
[in] Especifica o valor a ser passado para a caixa de diálogo no parâmetro lParam da mensagem WM_INITDIALOG.
Valor de Devolução
Um dos valores HRESULT padrão.
Comentários
Para usar AtlAxDialogBox com um modelo de diálogo que contém um controle ActiveX, especifique uma cadeia de caracteres CLSID, APPID ou URL válida como o campo text da seção CONTROL do recurso de diálogo, junto com "AtlAxWin80" como o campo class name na mesma seção. O seguinte demonstra como uma seção CONTROL válida pode ser:
CONTROL "{04FE35E9-ADBC-4f1d-83FE-8FA4D1F71C7F}", IDC_TEST,
"AtlAxWin80", WS_GROUP | WS_TABSTOP, 0, 0, 100, 100
Para obter mais informações sobre como editar scripts de recursos, confira Como criar recursos. Para obter mais informações sobre instruções de definição de recurso de controle, confira Parâmetros de controle comuns no SDK do Windows: SDK Tools.
Para obter mais informações sobre caixas de diálogo em geral, confira DialogBox e CreateDialogParam no SDK do Windows.
AtlAxCreateDialog
Cria uma caixa de diálogo sem modo a partir de um modelo de caixa de diálogo fornecido pelo usuário.
ATLAPI_(HWND) AtlAxCreateDialog(
HINSTANCE hInstance,
LPCWSTR lpTemplateName,
HWND hWndParent,
DLGPROC lpDialogProc,
LPARAM dwInitParam);
Parâmetros
hInstância
[in] Identifica uma instância do módulo cujo arquivo executável contém o modelo da caixa de diálogo.
lpTemplateName
[in] Identifica o modelo da caixa de diálogo. Esse parâmetro é o ponteiro para uma cadeia de caracteres com término nulo que especifica o nome do modelo da caixa de diálogo ou é um valor inteiro que especifica o identificador de recurso do modelo da caixa de diálogo. Se o parâmetro especificar um identificador de recurso, a palavra de alta ordem deverá ser zero e a palavra de baixa ordem deverá conter o identificador. Você pode usar a macro MAKEINTRESOURCE para criar esse valor.
hWndParent
[in] Identifica a janela à qual a caixa de diálogo pertence.
lpDialogProc
[in] Aponta para o procedimento da caixa de diálogo. Para saber mais sobre o procedimento da caixa de diálogo, confira DialogProc.
dwInitParam
[in] Especifica o valor a ser passado para a caixa de diálogo no parâmetro lParam da mensagem WM_INITDIALOG.
Valor de Devolução
Um dos valores HRESULT padrão.
Comentários
A caixa de diálogo resultante pode conter controles ActiveX.
Confira CreateDialog e CreateDialogParam no SDK do Windows.
AtlAxCreateControl
Cria um controle ActiveX, inicializa-o e hospeda-o na janela especificada.
ATLAPI AtlAxCreateControl(
LPCOLESTR lpszName,
HWND hWnd,
IStream* pStream,
IUnknown** ppUnkContainer);
Parâmetros
lpszName
Um ponteiro para uma cadeia de caracteres a ser passada para o controle. Deve ser formatado de uma das seguintes formas:
Um ProgID como
"MSCAL.Calendar.7"Um CLSID como
"{8E27C92B-1264-101C-8A2F-040224009C02}"Uma URL como
"<https://www.microsoft.com>"Uma referência a um documento ativo, como
"file://\\\Documents\MyDoc.doc"Um fragmento de HTML, como
"MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"Observação
"MSHTML:"deve preceder o fragmento HTML para que ele seja designado como sendo um fluxo MSHTML.
hWnd
[in] Identificador para a janela à qual o controle será anexado.
pStream
[in] Um ponteiro para um fluxo que é usado para inicializar as propriedades do controle. Pode ser NULL.
ppUnkContainer
[out] O endereço de um ponteiro que receberá o IUnknown do contêiner. Pode ser NULL.
Valor de Devolução
Um dos valores HRESULT padrão.
Comentários
Essa função global fornece o mesmo resultado que chamar AtlAxCreateControlEx(lpszName, hWnd, pStream, NULL, NULL, NULL, NULL);.
Para criar um controle ActiveX licenciado, confira AtlAxCreateControlLic.
AtlAxCreateControlEx
Cria um controle ActiveX, inicializa-o e hospeda-o na janela especificada. Um ponteiro de interface e um coletor de eventos para o novo controle também podem ser criados.
ATLAPI AtlAxCreateControlEx(
LPCOLESTR lpszName,
HWND hWnd,
IStream* pStream,
IUnknown** ppUnkContainer,
IUnknown** ppUnkControl,
REFIID iidSink = IID_NULL,
IUnknown* punkSink = NULL);
Parâmetros
lpszName
Um ponteiro para uma cadeia de caracteres a ser passada para o controle. Deve ser formatado de uma das seguintes formas:
Um ProgID como
"MSCAL.Calendar.7"Um CLSID como
"{8E27C92B-1264-101C-8A2F-040224009C02}"Uma URL como
"<https://www.microsoft.com>"Uma referência a um documento ativo, como
"file://\\\Documents\MyDoc.doc"Um fragmento de HTML, como
"MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"Observação
"MSHTML:"deve preceder o fragmento HTML para que ele seja designado como sendo um fluxo MSHTML.
hWnd
[in] Identificador para a janela à qual o controle será anexado.
pStream
[in] Um ponteiro para um fluxo que é usado para inicializar as propriedades do controle. Pode ser NULL.
ppUnkContainer
[out] O endereço de um ponteiro que receberá o IUnknown do contêiner. Pode ser NULL.
ppUnkControl
[out] O endereço de um ponteiro que receberá o IUnknown do controle criado. Pode ser NULL.
iidSink
O identificador de interface de uma interface de saída no objeto contido.
punkSink
Um ponteiro para a interface IUnknown do objeto coletor a ser conectado ao ponto de conexão especificado pelo iidSink no objeto contido depois que o objeto contido foi criado com êxito.
Valor de Devolução
Um dos valores HRESULT padrão.
Comentários
AtlAxCreateControlEx é semelhante a AtlAxCreateControl, mas também permite que você receba um ponteiro de interface para o controle recém-criado e configure um coletor de eventos para receber eventos disparados pelo controle.
Para criar um controle ActiveX licenciado, confira AtlAxCreateControlLicEx.
AtlAxCreateControlLic
Cria um controle ActiveX licenciado, inicializa-o e hospeda-o na janela especificada.
ATLAPI AtlAxCreateControlLic(
LPCOLESTR lpszName,
HWND hWnd,
IStream* pStream,
IUnknown** ppUnkContainer,
BSTR bstrLic = NULL);
Parâmetros
lpszName
Um ponteiro para uma cadeia de caracteres a ser passada para o controle. Deve ser formatado de uma das seguintes formas:
Um ProgID como
"MSCAL.Calendar.7"Um CLSID como
"{8E27C92B-1264-101C-8A2F-040224009C02}"Uma URL como
"<https://www.microsoft.com>"Uma referência a um documento ativo, como
"file://\\\Documents\MyDoc.doc"Um fragmento de HTML, como
"MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"Observação
"MSHTML:"deve preceder o fragmento HTML para que ele seja designado como sendo um fluxo MSHTML.
hWnd
Identificador para a janela à qual o controle será anexado.
pStream
Um ponteiro para um fluxo que é usado para inicializar as propriedades do controle. Pode ser NULL.
ppUnkContainer
O endereço de um ponteiro que receberá o IUnknown do contêiner. Pode ser NULL.
bstrLic
O BSTR que contém a licença para o controle.
Valor de Devolução
Um dos valores HRESULT padrão.
Exemplo
Confira Hospedagem de Controles ActiveX usando o AXHost da ATL para obter um exemplo de como usar AtlAxCreateControlLic.
AtlAxCreateControlLicEx
Cria um controle ActiveX licenciado, inicializa-o e hospeda-o na janela especificada. Um ponteiro de interface e um coletor de eventos para o novo controle também podem ser criados.
ATLAPI AtlAxCreateControlLicEx(
LPCOLESTR lpszName,
HWND hWnd,
IStream* pStream,
IUnknown** ppUnkContainer,
IUnknown** ppUnkControl,
REFIID iidSink = IID_NULL,
IUnknown* punkSink = NULL,
BSTR bstrLic = NULL);
Parâmetros
lpszName
Um ponteiro para uma cadeia de caracteres a ser passada para o controle. Deve ser formatado de uma das seguintes formas:
Um ProgID como
"MSCAL.Calendar.7"Um CLSID como
"{8E27C92B-1264-101C-8A2F-040224009C02}"Uma URL como
"<https://www.microsoft.com>"Uma referência a um documento ativo, como
"file://\\\Documents\MyDoc.doc"Um fragmento de HTML, como
"MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"Observação
"MSHTML:"deve preceder o fragmento HTML para que ele seja designado como sendo um fluxo MSHTML.
hWnd
Identificador para a janela à qual o controle será anexado.
pStream
Um ponteiro para um fluxo que é usado para inicializar as propriedades do controle. Pode ser NULL.
ppUnkContainer
O endereço de um ponteiro que receberá o IUnknown do contêiner. Pode ser NULL.
ppUnkControl
[out] O endereço de um ponteiro que receberá o IUnknown do controle criado. Pode ser NULL.
iidSink
O identificador de interface de uma interface de saída no objeto contido.
punkSink
Um ponteiro para a interface IUnknown do objeto coletor a ser conectado ao ponto de conexão especificado pelo iidSink no objeto contido depois que o objeto contido foi criado com êxito.
bstrLic
O BSTR que contém a licença para o controle.
Valor de Devolução
Um dos valores HRESULT padrão.
Comentários
AtlAxCreateControlLicEx é semelhante a AtlAxCreateControlLic, mas também permite que você receba um ponteiro de interface para o controle recém-criado e configure um coletor de eventos para receber eventos disparados pelo controle.
Exemplo
Confira Hospedagem de Controles ActiveX usando o AXHost da ATL para obter um exemplo de como usar AtlAxCreateControlLicEx.
AtlAxAttachControl
Anexa um controle criado anteriormente à janela especificada.
ATLAPI AtlAxAttachControl(
IUnknown* pControl,
HWND hWnd,
IUnknown** ppUnkContainer);
Parâmetros
pControle
[in] Um ponteiro para o IUnknown do controle.
hWnd
[in] Identificador para a janela à qual o controle será hospedado.
ppUnkContainer
[out] Um ponteiro para um ponteiro para o IUnknown do objeto de contêiner.
Valor de Devolução
Um dos valores HRESULT padrão.
Comentários
Use AtlAxCreateControlEx e AtlAxCreateControl para criar e anexar simultaneamente um controle.
Observação
O objeto de controle que está sendo anexado deve ser inicializado corretamente antes de chamar AtlAxAttachControl.
AtlAxGetHost
Obtém um ponteiro de interface direta para o contêiner para uma janela especificada (se houver), de acordo com seu identificador.
ATLAPI AtlAxGetHost(HWND h, IUnknown** pp);
Parâmetros
h
[in] Um identificador para a janela que está hospedando o controle.
pp
[out] O IUnknown do contêiner do controle.
Valor de Devolução
Um dos valores HRESULT padrão.
AtlAxGetControl
Obtém um ponteiro de interface direta para o controle contido em uma janela especificada de acordo com seu identificador.
ATLAPI AtlAxGetControl(HWND h, IUnknown** pp);
Parâmetros
h
[in] Um identificador para a janela que está hospedando o controle.
pp
[out] O IUnknown do controle que está sendo hospedado.
Valor de Devolução
Um dos valores HRESULT padrão.
AtlSetChildSite
Chame essa função para definir o site do objeto filho do IUnknown do objeto pai.
HRESULT AtlSetChildSite(IUnknown* punkChild, IUnknown* punkParent);
Parâmetros
punkChild
[in] Um ponteiro para a interface IUnknown do filho.
punkParent
[in] Um ponteiro para a interface IUnknown do pai.
Valor de Devolução
Um valor HRESULT padrão.
AtlAxWinInit
Essa função inicializa o controle do ATL que hospeda o código registrando as classes de janela "AtlAxWin80" e "AtlAxWinLic80" mais algumas mensagens personalizadas da janela.
ATLAPI_(BOOL) AtlAxWinInit();
Valor de Devolução
Não zero se a inicialização do código de hospedagem de controle foi bem-sucedida. Caso contrário, FALSE.
Comentários
Essa função deve ser chamada antes de usar a API de hospedagem do controle ATL. Após uma chamada para essa função, a classe de janela "AtlAxWin" pode ser usada em chamadas para CreateWindow ou CreateWindowEx, conforme descrito no SDK do Windows.
AtlAxWinTerm
Essa função cancela a inicialização do controle do ATL que hospeda o código através do cancelamento do registro das classes de janela "AtlAxWin80" e "AtlAxWinLic80".
inline BOOL AtlAxWinTerm();
Valor de Devolução
Sempre retorna TRUE.
Comentários
Essa função simplesmente chama UnregisterClass, conforme descrito no SDK do Windows.
Chame essa função para limpar depois que todas as janelas de host existentes tiverem sido destruídas se você tiver chamado AtlAxWinInit e não precisar mais criar janelas de host. Se você não chamar essa função, o registro da classe de janela será cancelado automaticamente quando o processo for encerrado.
AtlGetObjectSourceInterface
Chame essa função para recuperar informações sobre a interface padrão de origem de um objeto.
ATLAPI AtlGetObjectSourceInterface(
IUnknown* punkObj,
GUID* plibid,
IID* piid,
unsigned short* pdwMajor,
unsigned short* pdwMinor);
Parâmetros
punkObj
[in] Um ponteiro para o objeto para o qual as informações devem ser retornadas.
plibid
[out] Um ponteiro para o LIBID da biblioteca de tipos que contém a definição da interface de origem.
piid
[out] Um ponteiro para a ID de interface da interface de origem padrão do objeto.
pdwMajor
[out] Um ponteiro para o número de versão principal da biblioteca de tipos que contém a definição da interface de origem.
pdwMinor
[out] Um ponteiro para o número de versão secundário da biblioteca de tipos que contém a definição da interface de origem.
Valor de Devolução
Um valor HRESULT padrão.
Comentários
AtlGetObjectSourceInterface pode fornecer a ID da interface da interface de origem padrão, juntamente com o LIBID e os números de versão principal e secundária da biblioteca de tipos que descrevem essa interface.
Observação
Para que essa função recupere com êxito as informações solicitadas, o objeto representado pelo punkObj deve implementar IDispatch (e retornar informações de tipo por meio IDispatch::GetTypeInfo) além disso, ele também deve implementar ou IProvideClassInfo2IPersist. As informações de tipo para a interface de origem devem estar na mesma biblioteca de tipos que as informações de tipo para IDispatch.
Exemplo
O exemplo a seguir mostra como você pode definir uma classe de coletor de eventos, CEasySinkque reduz o número de argumentos de modelo para os quais você pode passar para IDispEventImpl o bare essentials. EasyAdvise e EasyUnadvise usam AtlGetObjectSourceInterface para inicializar os membros IDispEventImpl antes de chamar DispEventAdvise ou DispEventUnadvise.
template <UINT nID, class T>
class CEasySink : public IDispEventImpl<nID, T>
{
public:
HRESULT EasyAdvise(IUnknown* pUnk)
{
AtlGetObjectSourceInterface(pUnk,
&m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum);
return DispEventAdvise(pUnk, &m_iid);
}
HRESULT EasyUnadvise(IUnknown* pUnk)
{
AtlGetObjectSourceInterface(pUnk,
&m_libid, &m_iid, &m_wMajorVerNum, &m_wMinorVerNum);
return DispEventUnadvise(pUnk, &m_iid);
}
};
Confira também
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de