Funciones globales de control compuesto
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);
}
};