Compartir vía

Funciones globales de control compuesto

  • Artículo

Estas funciones proporcionan compatibilidad para crear cuadros de diálogo y para crear, hospedar y otorgar licencias a controles ActiveX.

Importante

Las funciones enumeradas en la tabla siguiente no se pueden usar en las aplicaciones que se ejecutan en Windows Runtime.

Función Descripción
AtlAxDialogBox Crea un cuadro de diálogo modal a partir de una plantilla de cuadros de diálogo proporcionada por el usuario. El cuadro de diálogo resultante puede contener controles ActiveX.
AtlAxCreateDialog Crea un cuadro de diálogo no modal a partir de una plantilla de cuadros de diálogo proporcionada por el usuario. El cuadro de diálogo resultante puede contener controles ActiveX.
AtlAxCreateControl Crea un control ActiveX, lo inicializa y lo hospeda en la ventana especificada.
AtlAxCreateControlEx Crea un control ActiveX, lo inicializa, lo hospeda en la ventana especificada y recupera un puntero (o punteros) de interfaz del control.
AtlAxCreateControlLic Crea un control ActiveX con licencia, lo inicializa y lo hospeda en la ventana especificada.
AtlAxCreateControlLicEx Crea un control ActiveX con licencia, lo inicializa, lo hospeda en la ventana especificada y recupera un puntero (o punteros) de interfaz del control.
AtlAxAttachControl Asocia un control creado previamente con la ventana especificada.
AtlAxGetHost Se usa para obtener un puntero de interfaz directo al contenedor de una ventana especificada (si existe) en función de su identificador.
AtlAxGetControl Se usa para obtener un puntero de interfaz directo al control que se encuentra dentro de una ventana especificada (si existe) en función de su identificador.
AtlSetChildSite Inicializa el elemento IUnknown del sitio secundario.
AtlAxWinInit Inicializa el código de hospedaje para objetos AxWin.
AtlAxWinTerm Anula la inicialización del código de hospedaje para los objetos AxWin.
AtlGetObjectSourceInterface Devuelve información sobre la interfaz de origen predeterminada de un objeto.

Requisitos

Encabezado: atlhost.h

AtlAxDialogBox

Crea un cuadro de diálogo modal a partir de una plantilla de cuadros de diálogo proporcionada por el usuario.

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

Parámetros

hInstance
[in] Identifica una instancia del módulo cuyo archivo ejecutable contiene la plantilla de cuadro de diálogo.

lpTemplateName
[in] Identifica la plantilla de cuadro de diálogo. Este parámetro es el puntero a una cadena de caracteres terminada en NULL que especifica el nombre de la plantilla de cuadro de diálogo o un valor entero que especifica el identificador de recurso de la plantilla de cuadro de diálogo. Si el parámetro especifica un identificador de recurso, su palabra de orden superior debe ser cero y su palabra de orden inferior debe contener el identificador. Puede usar la macro MAKEINTRESOURCE para crear este valor.

hWndParent
[in] Identifica la ventana que posee el cuadro de diálogo.

lpDialogProc
[in] Apunta al procedimiento del cuadro de diálogo. Para obtener más información sobre el procedimiento del cuadro de diálogo, consulte DialogProc.

dwInitParam
[in] Especifica el valor que se va a pasar al cuadro de diálogo en el parámetro lParam del mensaje WM_INITDIALOG.

Valor devuelto

Uno de los valores HRESULT estándar.

Comentarios

Para usar AtlAxDialogBox con una plantilla de cuadro de diálogo que contiene un control ActiveX, especifique una cadena CLSID, APPID o URL válida como campo de texto de la sección CONTROL del recurso de cuadro de diálogo, junto con "AtlAxWin80" como campo de nombre de clase en la misma sección. A continuación se muestra el aspecto que podría tener una sección CONTROL válida:

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

Para obtener más información sobre cómo editar scripts de recursos, consulte Cómo: Crear recursos. Para obtener más información sobre las instrucciones de definición de recursos de control, consulte Parámetros de control comunes en Windows SDK: SDK Tools.

Para obtener más información sobre los cuadros de diálogo en general, consulte DialogBox y CreateDialogParam en Windows SDK.

AtlAxCreateDialog

Crea un cuadro de diálogo no modal a partir de una plantilla de cuadros de diálogo proporcionada por el usuario.

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

Parámetros

hInstance
[in] Identifica una instancia del módulo cuyo archivo ejecutable contiene la plantilla de cuadro de diálogo.

lpTemplateName
[in] Identifica la plantilla de cuadro de diálogo. Este parámetro es el puntero a una cadena de caracteres terminada en NULL que especifica el nombre de la plantilla de cuadro de diálogo o un valor entero que especifica el identificador de recurso de la plantilla de cuadro de diálogo. Si el parámetro especifica un identificador de recurso, su palabra de orden superior debe ser cero y su palabra de orden inferior debe contener el identificador. Puede usar la macro MAKEINTRESOURCE para crear este valor.

hWndParent
[in] Identifica la ventana que posee el cuadro de diálogo.

lpDialogProc
[in] Apunta al procedimiento del cuadro de diálogo. Para obtener más información sobre el procedimiento del cuadro de diálogo, consulte DialogProc.

dwInitParam
[in] Especifica el valor que se va a pasar al cuadro de diálogo en el parámetro lParam del mensaje WM_INITDIALOG.

Valor devuelto

Uno de los valores HRESULT estándar.

Comentarios

El cuadro de diálogo resultante puede contener controles ActiveX.

Consulte CreateDialog y CreateDialogParam en Windows SDK.

AtlAxCreateControl

Crea un control ActiveX, lo inicializa y lo hospeda en la ventana especificada.

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

Parámetros

lpszName
Puntero a una cadena que se va a pasar al control. Debe tener el formato de una de las siguientes maneras:

  • Un ProgID como "MSCAL.Calendar.7"

  • Un CLSID como "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • Una dirección URL como "<https://www.microsoft.com>"

  • Referencia a un documento activo como "file://\\\Documents\MyDoc.doc"

  • Un fragmento de HTML como "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

    Nota:

    "MSHTML:" debe preceder al fragmento de HTML para que se designe como una secuencia MSHTML.

hWnd
[in] Identificador de la ventana a la que se asociará el control.

pStream
[in] Puntero a una secuencia que se usa para inicializar las propiedades del control. Puede ser NULL.

ppUnkContainer
[out] Dirección de un puntero que recibirá el elemento IUnknown del contenedor. Puede ser NULL.

Valor devuelto

Uno de los valores HRESULT estándar.

Comentarios

Esta función global proporciona el mismo resultado que si se llama a AtlAxCreateControlEx(lpszName, hWnd, pStream, NULL, NULL, NULL, NULL);.

Para crear un control ActiveX con licencia, consulte AtlAxCreateControlLic.

AtlAxCreateControlEx

Crea un control ActiveX, lo inicializa y lo hospeda en la ventana especificada. También se puede crear un puntero de interfaz y un receptor de eventos para el nuevo control.

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

Parámetros

lpszName
Puntero a una cadena que se va a pasar al control. Debe tener el formato de una de las siguientes maneras:

  • Un ProgID como "MSCAL.Calendar.7"

  • Un CLSID como "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • Una dirección URL como "<https://www.microsoft.com>"

  • Referencia a un documento activo como "file://\\\Documents\MyDoc.doc"

  • Un fragmento de HTML como "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

    Nota:

    "MSHTML:" debe preceder al fragmento de HTML para que se designe como una secuencia MSHTML.

hWnd
[in] Identificador de la ventana a la que se asociará el control.

pStream
[in] Puntero a una secuencia que se usa para inicializar las propiedades del control. Puede ser NULL.

ppUnkContainer
[out] Dirección de un puntero que recibirá el elemento IUnknown del contenedor. Puede ser NULL.

ppUnkControl
[out] Dirección de un puntero que recibirá el elemento IUnknown del control creado. Puede ser NULL.

iidSink
Identificador de interfaz de una interfaz de salida en el objeto contenido.

punkSink
Puntero a la interfaz IUnknown del objeto receptor que se va a conectar al punto de conexión especificado por iidSink en el objeto contenido después de que este se haya creado correctamente.

Valor devuelto

Uno de los valores HRESULT estándar.

Comentarios

AtlAxCreateControlEx es similar a AtlAxCreateControl, pero también permite recibir un puntero de interfaz al control recién creado y configurar un receptor de eventos para recibirlos desencadenados por el control.

Para crear un control ActiveX con licencia, consulte AtlAxCreateControlLicEx.

AtlAxCreateControlLic

Crea un control ActiveX con licencia, lo inicializa y lo hospeda en la ventana especificada.

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

Parámetros

lpszName
Puntero a una cadena que se va a pasar al control. Debe tener el formato de una de las siguientes maneras:

  • Un ProgID como "MSCAL.Calendar.7"

  • Un CLSID como "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • Una dirección URL como "<https://www.microsoft.com>"

  • Referencia a un documento activo como "file://\\\Documents\MyDoc.doc"

  • Un fragmento de HTML como "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

    Nota:

    "MSHTML:" debe preceder al fragmento de HTML para que se designe como una secuencia MSHTML.

hWnd
Identificador de la ventana a la que se asociará el control.

pStream
Puntero a una secuencia que se usa para inicializar las propiedades del control. Puede ser NULL.

ppUnkContainer
Dirección de un puntero que recibirá el elemento IUnknown del contenedor. Puede ser NULL.

bstrLic
BSTR que contiene la licencia del control.

Valor devuelto

Uno de los valores HRESULT estándar.

Ejemplo

Consulte Hospedaje de controles ActiveX mediante ATL AXHost para obtener un ejemplo de cómo usar AtlAxCreateControlLic.

AtlAxCreateControlLicEx

Crea un control ActiveX con licencia, lo inicializa y lo hospeda en la ventana especificada. También se puede crear un puntero de interfaz y un receptor de eventos para el nuevo control.

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
Puntero a una cadena que se va a pasar al control. Debe tener el formato de una de las siguientes maneras:

  • Un ProgID como "MSCAL.Calendar.7"

  • Un CLSID como "{8E27C92B-1264-101C-8A2F-040224009C02}"

  • Una dirección URL como "<https://www.microsoft.com>"

  • Referencia a un documento activo como "file://\\\Documents\MyDoc.doc"

  • Un fragmento de HTML como "MSHTML:\<HTML>\<BODY>This is a line of text\</BODY>\</HTML>"

    Nota:

    "MSHTML:" debe preceder al fragmento de HTML para que se designe como una secuencia MSHTML.

hWnd
Identificador de la ventana a la que se asociará el control.

pStream
Puntero a una secuencia que se usa para inicializar las propiedades del control. Puede ser NULL.

ppUnkContainer
Dirección de un puntero que recibirá el elemento IUnknown del contenedor. Puede ser NULL.

ppUnkControl
[out] Dirección de un puntero que recibirá el elemento IUnknown del control creado. Puede ser NULL.

iidSink
Identificador de interfaz de una interfaz de salida en el objeto contenido.

punkSink
Puntero a la interfaz IUnknown del objeto receptor que se va a conectar al punto de conexión especificado por iidSink en el objeto contenido después de que este se haya creado correctamente.

bstrLic
BSTR que contiene la licencia del control.

Valor devuelto

Uno de los valores HRESULT estándar.

Comentarios

AtlAxCreateControlLicEx es similar a AtlAxCreateControl, pero también permite recibir un puntero de interfaz al control recién creado y configurar un receptor de eventos para recibirlos desencadenados por el control.

Ejemplo

Consulte Hospedaje de controles ActiveX mediante ATL AXHost para obtener un ejemplo de cómo usar AtlAxCreateControlLicEx.

AtlAxAttachControl

Asocia un control creado previamente con la ventana especificada.

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

Parámetros

pControl
[in] Puntero al elemento IUnknown del control.

hWnd
[in] Identificador de la ventana que hospedará el control.

ppUnkContainer
[out] Puntero a un puntero al elemento IUnknown del objeto contenedor.

Valor devuelto

Uno de los valores HRESULT estándar.

Comentarios

Use AtlAxCreateControlEx y AtlAxCreateControl para crear y asociar un control simultáneamente.

Nota:

El objeto de control que se asocia debe inicializarse correctamente antes de llamar a AtlAxAttachControl.

AtlAxGetHost

Obtiene un puntero de interfaz directo al contenedor de una ventana especificada (si existe) en función de su identificador.

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

Parámetros

h
[in] Identificador de la ventana que hospeda el control.

pp
[out] IUnknown del contenedor del control.

Valor devuelto

Uno de los valores HRESULT estándar.

AtlAxGetControl

Obtiene un puntero de interfaz directo al control que se encuentra dentro de una ventana especificada en función de su identificador.

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

Parámetros

h
[in] Identificador de la ventana que hospeda el control.

pp
[out] IUnknown del control que se hospeda.

Valor devuelto

Uno de los valores HRESULT estándar.

AtlSetChildSite

Llame a esta función para establecer el sitio del objeto secundario en la interfaz IUnknown del objeto primario.

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

Parámetros

punkChild
[in] Puntero en la interfaz IUnknown del elemento secundario.

punkParent
[in] Puntero a la interfaz IUnknown del elemento primario.

Valor devuelto

Valor HRESULT estándar.

AtlAxWinInit

Esta función inicializa el código que hospeda los controles de ATL registrando las clases de ventana "AtlAxWin80" y "AtlAxWinLic80" junto con un par de mensajes personalizados de la ventana.

ATLAPI_(BOOL) AtlAxWinInit();

Valor devuelto

Distinto de cero si se ha realizado correctamente la inicialización del código que hospeda los controles; de lo contrario, FALSE.

Comentarios

Se debe llamar a esta función antes de usar la API de hospedaje de controles ATL. Después de una llamada a esta función, la clase de ventana "AtlAxWin" se puede usar en llamadas a CreateWindow o CreateWindowEx, como se describe en Windows SDK.

AtlAxWinTerm

Esta función anula la inicialización del código que hospeda los controles de ATL anulando el registro de las clases de ventana "AtlAxWin80" y "AtlAxWinLic80".

inline BOOL AtlAxWinTerm();

Valor devuelto

Siempre devuelve TRUE.

Comentarios

Esta función simplemente llama a UnregisterClass como se describe en Windows SDK.

Llame a esta función para limpiar después de que se hayan destruido todas las ventanas host existentes si llamó a AtlAxWinInit y ya no necesita crear ventanas host. Si no llama a esta función, se anulará automáticamente el registro de la clase de ventana cuando finalice el proceso.

AtlGetObjectSourceInterface

Llame a esta función para recuperar información sobre la interfaz de origen predeterminada de un objeto.

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

Parámetros

punkObj
[in] Puntero al objeto para el que se va a devolver información.

plibid
[out] Puntero al LIBID de la biblioteca de tipos que contiene la definición de la interfaz de origen.

piid
[out] Puntero al identificador de interfaz de la interfaz de origen predeterminada del objeto.

pdwMajor
[out] Puntero al número de versión principal de la biblioteca de tipos que contiene la definición de la interfaz de origen.

pdwMinor
[out] Puntero al número de versión secundaria de la biblioteca de tipos que contiene la definición de la interfaz de origen.

Valor devuelto

Valor HRESULT estándar.

Comentarios

AtlGetObjectSourceInterface puede proporcionar el identificador de interfaz de la interfaz de origen predeterminada, junto con el LIBID y los números de versión principal y secundaria de la biblioteca de tipos que describe esa interfaz.

Nota:

Para que esta función recupere correctamente la información solicitada, el objeto representado por punkObj debe implementar IDispatch (e información sobre el tipo de valor devuelto a través de IDispatch::GetTypeInfo), además de que también debe implementar IProvideClassInfo2 o IPersist. La información de tipo para la interfaz de origen debe estar en la misma biblioteca de tipos que la información de tipo para IDispatch.

Ejemplo

En el ejemplo siguiente se muestra cómo puede definir una clase de receptor de eventos, CEasySink, que reduce el número de argumentos de plantilla que puede pasar a IDispEventImpl a lo esencial. EasyAdvise y EasyUnadvise usan AtlGetObjectSourceInterface para inicializar los miembros IDispEventImpl antes de llamar a DispEventAdvise o 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 también

Funciones
Macros de control compuesto