Funções Globais de Controlo Composto

Estas funções fornecem suporte para criar caixas de diálogo e para criar, hospedar e licenciar controlos ActiveX.

Requerimentos

Cabeçalho: atlhost.h

AtlAxDialogBox

Cria uma caixa de diálogo modal a partir de um modelo de diálogo fornecido pelo utilizador.

ATLAPI_(int) AtlAxDialogBox(
    HINSTANCE hInstance,
    LPCWSTR lpTemplateName,
    HWND hWndParent,
    DLGPROC lpDialogProc,
    LPARAM dwInitParam);

Parâmetros

hInstance
[dentro] Identifica uma instância do módulo cujo ficheiro executável contém o modelo da caixa de diálogo.

lpTemplateName
[dentro] Identifica o modelo da caixa de diálogo. Este parâmetro é ou o ponteiro para uma cadeia de caracteres terminada por 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 sua palavra de ordem superior deve ser zero e a palavra de ordem baixa deve conter o identificador. Podes usar o macro MAKEINTRESOURCE para criar este valor.

hWndParent
[dentro] Identifica a janela que detém a caixa de diálogo.

lpDialogProc
[dentro] Aponta para o procedimento da caixa de diálogo. Para mais informações sobre o procedimento da caixa de diálogo, consulte DialogProc.

dwInitParam
[dentro] Especifica o valor a passar para a caixa de diálogo no parâmetro lParam da mensagem WM_INITDIALOG.

Valor de retorno

Um dos valores padrão do HRESULT.

Observações

Para usar AtlAxDialogBox com um modelo de diálogo que contenha um controlo ActiveX, especifique um CLSID, APPID ou cadeia de URL válido como campo de texto da secção CONTROL do recurso de diálogo, juntamente com "AtlAxWin80" como campo de nome da classe na mesma secção. O seguinte demonstra como pode ser uma secção CONTROL válida:

CONTROL    "{04FE35E9-ADBC-4f1d-83FE-8FA4D1F71C7F}", IDC_TEST,
    "AtlAxWin80", WS_GROUP | WS_TABSTOP, 0, 0, 100, 100

Para mais informações sobre a edição de scripts de recursos, veja Como: Criar Recursos. Para mais informações sobre instruções de definição de recursos de controlo, consulte Parâmetros Comuns de Controlo no Windows SDK: Ferramentas SDK.

Para mais informações sobre caixas de diálogo em geral, consulte DialogBox e CreateDialogParam no SDK do Windows.

AtlAxCreateDialog

Cria uma caixa de diálogo sem modos a partir de um modelo de diálogo fornecido pelo utilizador.

ATLAPI_(HWND) AtlAxCreateDialog(
    HINSTANCE hInstance,
    LPCWSTR lpTemplateName,
    HWND hWndParent,
    DLGPROC lpDialogProc,
    LPARAM dwInitParam);

Parâmetros

hInstance
[dentro] Identifica uma instância do módulo cujo ficheiro executável contém o modelo da caixa de diálogo.

lpTemplateName
[dentro] Identifica o modelo da caixa de diálogo. Este parâmetro é ou o ponteiro para uma cadeia de caracteres terminada por 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 sua palavra de ordem superior deve ser zero e a palavra de ordem baixa deve conter o identificador. Podes usar o macro MAKEINTRESOURCE para criar este valor.

hWndParent
[dentro] Identifica a janela que detém a caixa de diálogo.

lpDialogProc
[dentro] Aponta para o procedimento da caixa de diálogo. Para mais informações sobre o procedimento da caixa de diálogo, consulte DialogProc.

dwInitParam
[dentro] Especifica o valor a passar para a caixa de diálogo no parâmetro lParam da mensagem WM_INITDIALOG.

Valor de retorno

Um dos valores padrão do HRESULT.

Observações

A caixa de diálogo resultante pode conter controlos ActiveX.

Veja CreateDialog e CreateDialogParam no SDK do Windows.

AtlAxCreateControl

Cria um controlo ActiveX, inicializa-o e aloja-o na janela especificada.

ATLAPI AtlAxCreateControl(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer);

Parâmetros

lpszName
Um apontador para uma string a ser passada ao controlo. 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 seja designado como um fluxo MSHTML.

hWnd
[dentro] Pega na janela onde o comando será acoplado.

pStream
[dentro] Um ponteiro para um fluxo que é usado para inicializar as propriedades do controlo. Pode ser NULL.

ppUnkContainer
[fora] O endereço de um ponteiro que irá receber o IUnknown do contentor. Pode ser NULL.

Valor de retorno

Um dos valores padrão do HRESULT.

Observações

Esta função global dá-te o mesmo resultado que chamar AtlAxCreateControlEx(lpszName, hWnd, pStream, NULL, NULL, NULL, NULL);.

Para criar um controlo ActiveX licenciado, consulte AtlAxCreateControlLic.

AtlAxCreateControlEx

Cria um controlo ActiveX, inicializa-o e aloja-o na janela especificada. Também podem ser criados um ponteiro de interface e um sumidouro de eventos para o novo controlo.

ATLAPI AtlAxCreateControlEx(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer,
    IUnknown** ppUnkControl,
    REFIID iidSink = IID_NULL,
    IUnknown* punkSink = NULL);

Parâmetros

lpszName
Um apontador para uma string a ser passada ao controlo. 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 seja designado como um fluxo MSHTML.

hWnd
[dentro] Pega na janela onde o comando será acoplado.

pStream
[dentro] Um ponteiro para um fluxo que é usado para inicializar as propriedades do controlo. Pode ser NULL.

ppUnkContainer
[fora] O endereço de um ponteiro que irá receber o IUnknown do contentor. Pode ser NULL.

ppUnkControl
[fora] O endereço de um ponteiro que irá receber o IUnknown do controlo criado. Pode ser NULL.

iidSink
O identificador de interface de saída de uma interface de saída no objeto contido.

punkSink
Um ponteiro para a IUnknown interface do objeto sink a ser ligado ao ponto de ligação especificado por iidSink no objeto contido após o objeto contido ter sido criado com sucesso.

Valor de retorno

Um dos valores padrão do HRESULT.

Observações

AtlAxCreateControlEx é semelhante ao AtlAxCreateControl , mas também permite receber um ponteiro de interface para o controlo recém-criado e configurar um dissipador de eventos para receber os eventos disparados pelo controlo.

Para criar um controlo ActiveX licenciado, consulte AtlAxCreateControlLicEx.

AtlAxCreateControlLic

Cria um controlo ActiveX licenciado, inicializa-o e aloja-o na janela especificada.

ATLAPI AtlAxCreateControlLic(
    LPCOLESTR lpszName,
    HWND hWnd,
    IStream* pStream,
    IUnknown** ppUnkContainer,
    BSTR bstrLic = NULL);

Parâmetros

lpszName
Um apontador para uma string a ser passada ao controlo. 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 seja designado como um fluxo MSHTML.

hWnd
Pega na janela onde o comando será acoplado.

pStream
Um ponteiro para um fluxo que é usado para inicializar as propriedades do controlo. Pode ser NULL.

ppUnkContainer
O endereço de um ponteiro que irá receber o IUnknown do contentor. Pode ser NULL.

bstrLic
O BSTR contém a licença para o controlo.

Valor de retorno

Um dos valores padrão do HRESULT.

Example

Consulte Hospedagem de Controlos ActiveX Usando ATL AXHost para um exemplo de como usar AtlAxCreateControlLic.

AtlAxCreateControlLicEx

Cria um controlo ActiveX licenciado, inicializa-o e aloja-o na janela especificada. Também podem ser criados um ponteiro de interface e um sumidouro de eventos para o novo controlo.

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 apontador para uma string a ser passada ao controlo. 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 seja designado como um fluxo MSHTML.

hWnd
Pega na janela onde o comando será acoplado.

pStream
Um ponteiro para um fluxo que é usado para inicializar as propriedades do controlo. Pode ser NULL.

ppUnkContainer
O endereço de um ponteiro que irá receber o IUnknown do contentor. Pode ser NULL.

ppUnkControl
[fora] O endereço de um ponteiro que irá receber o IUnknown do controlo criado. Pode ser NULL.

iidSink
O identificador de interface de saída de uma interface de saída no objeto contido.

punkSink
Um ponteiro para a IUnknown interface do objeto sink a ser ligado ao ponto de ligação especificado por iidSink no objeto contido após o objeto contido ter sido criado com sucesso.

bstrLic
O BSTR contém a licença para o controlo.

Valor de retorno

Um dos valores padrão do HRESULT.

Observações

AtlAxCreateControlLicEx é semelhante ao AtlAxCreateControlLic , mas também permite receber um ponteiro de interface para o controlo recém-criado e configurar um dissipador de eventos para receber os eventos disparados pelo controlo.

Example

Consulte Hospedagem de Controlos ActiveX Usando ATL AXHost para um exemplo de como usar AtlAxCreateControlLicEx.

AtlAxAttachControl

Anexa um controlo previamente criado à janela especificada.

ATLAPI AtlAxAttachControl(
    IUnknown* pControl,
    HWND hWnd,
    IUnknown** ppUnkContainer);

Parâmetros

pControl
[dentro] Um indicador para o IUnknown do controlo.

hWnd
[dentro] Handle para a janela que vai alojar o controlo.

ppUnkContainer
[fora] Um ponteiro para um ponteiro para o IUnknown do objeto contentor.

Valor de retorno

Um dos valores padrão do HRESULT.

Observações

Use o AtlAxCreateControlEx e o AtlAxCreateControl para criar e anexar simultaneamente um controlo.

AtlAxGetHost

Obtém um ponteiro de interface direto para o contentor para uma janela especificada (se existir), dado o seu handle.

ATLAPI AtlAxGetHost(HWND h, IUnknown** pp);

Parâmetros

h
[dentro] Uma maçaneta para a janela que está a alojar o controlo.

pp
[fora] O IUnknown do contentor do controlo.

Valor de retorno

Um dos valores padrão do HRESULT.

AtlAxGetControl

Obtém um ponteiro de interface direto para o controlo contido dentro de uma janela especificada, dado o seu handle.

ATLAPI AtlAxGetControl(HWND h, IUnknown** pp);

Parâmetros

h
[dentro] Uma maçaneta para a janela que está a alojar o controlo.

pp
[fora] O IUnknown do controlo que está a ser alojado.

Valor de retorno

Um dos valores padrão do HRESULT.

AtlSetChildSite

Chame esta função para definir o sítio do objeto filho para o IUnknown do objeto pai.

HRESULT AtlSetChildSite(IUnknown* punkChild, IUnknown* punkParent);

Parâmetros

punkChild
[dentro] Um apontador para a IUnknown interface da criança.

punkParent
[dentro] Um ponteiro para a IUnknown interface do pai.

Valor de retorno

Um valor HRESULT padrão.

AtlAxWinInit

Esta função inicializa o código de alojamento de controlo da ATL ao registar as classes de janela "AtlAxWin80" e "AtlAxWinLic80", além de algumas mensagens de janela personalizadas.

ATLAPI_(BOOL) AtlAxWinInit();

Valor de retorno

Não nulo se a inicialização do código de alojamento de controlo fosse bem-sucedida; caso contrário, FALSO.

Observações

Esta função deve ser chamada antes de usar a API de alojamento de controlo ATL. Após uma chamada a esta função, a classe janela "AtlAxWin" pode ser usada em chamadas para CreateWindow ou CreateWindowEx, conforme descrito no SDK do Windows.

AtlAxWinTerm

Esta função desativa o código de alojamento de controlo do ATL ao desregistar as classes de janela "AtlAxWin80" e "AtlAxWinLic80 ".

inline BOOL AtlAxWinTerm();

Valor de retorno

Retorna sempre VERDADEIRO.

Observações

Esta função simplesmente chama o UnregisterClass conforme descrito no SDK do Windows.

Chame esta função para limpar depois de todas as janelas do host existentes terem sido destruídas se ligou para o AtlAxWinInit e já não precisar de criar janelas do host. Se não chamar esta função, a classe janela será automaticamente desregistada quando o processo terminar.

AtlGetObjectSourceInterface

Chame esta função para recuperar informação sobre a interface de origem padrão de um objeto.

ATLAPI AtlGetObjectSourceInterface(
    IUnknown* punkObj,
    GUID* plibid,
    IID* piid,
    unsigned short* pdwMajor,
    unsigned short* pdwMinor);

Parâmetros

punkObj
[dentro] Um apontador para o objeto para o qual a informação deve ser devolvida.

plibid
[fora] Um ponteiro para o LIBID da biblioteca de tipos que contém a definição da interface de origem.

Piid
[fora] Um apontador para o ID da interface de origem padrão do objeto.

pdwMajor
[fora] Um apontador para o número de versão principal da biblioteca de tipos que contém a definição da interface de origem.

pdwMinor
[fora] Um apontador para o número de versão menor da biblioteca de tipos que contém a definição da interface de origem.

Valor de retorno

Um valor HRESULT padrão.

Observações

AtlGetObjectSourceInterface pode fornecer-lhe o ID da interface de origem padrão, juntamente com o LIBID e os números de versão maior e menor da biblioteca de tipos que descrevem essa interface.

Example

O exemplo abaixo mostra como pode definir uma classe de sumidouro de eventos, CEasySink, que reduz o número de argumentos modelo a que pode passar IDispEventImpl para o essencial. EasyAdvise e EasyUnadvise usar 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);
   }
};

Consulte também

Funções
Macros de controle compostas