Partilhar via

Funções globais do controle composto

  • Artigo

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

hInstance
[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 retorno

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

hInstance
[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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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 retorno

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

Funções
Macros de controle de composição