QAxBase Class
La clase QAxBase es una clase abstracta que proporciona una API para inicializar y acceder a un objeto COM. Más información...
| Encabezado: | #include <qaxbase.h> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS AxContainer) target_link_libraries(mytarget PRIVATE Qt6::AxContainer) |
| qmake: | QT += axcontainer |
| Heredado por: |
Tipos públicos
Funciones públicas
| virtual | ~QAxBase() |
| QVariant | asVariant() const |
| ulong | classContext() const |
| void | clear() |
| QString | control() const |
| void | disableClassInfo() |
| void | disableEventSink() |
| void | disableMetaObject() |
| QVariant | dynamicCall(const char *function, const QVariant &var1 = QVariant(), const QVariant &var2 = QVariant(), const QVariant &var3 = QVariant(), const QVariant &var4 = QVariant(), const QVariant &var5 = QVariant(), const QVariant &var6 = QVariant(), const QVariant &var7 = QVariant(), const QVariant &var8 = QVariant()) |
| QVariant | dynamicCall(const char *function, QList<QVariant> &vars) |
| QString | generateDocumentation() |
| bool | isNull() const |
| QAxBase::PropertyBag | propertyBag() const |
| virtual bool | propertyWritable(const char *prop) const |
| long | queryInterface(const QUuid &uuid, void **iface) const |
| QAxObject * | querySubObject(const char *name, const QVariant &var1 = QVariant(), const QVariant &var2 = QVariant(), const QVariant &var3 = QVariant(), const QVariant &var4 = QVariant(), const QVariant &var5 = QVariant(), const QVariant &var6 = QVariant(), const QVariant &var7 = QVariant(), const QVariant &var8 = QVariant()) |
| QAxObject * | querySubObject(const char *name, QList<QVariant> &vars) |
| void | setClassContext(ulong classContext) |
| void | setPropertyBag(const QAxBase::PropertyBag &bag) |
| virtual void | setPropertyWritable(const char *prop, bool ok) |
| QStringList | verbs() const |
Funciones protegidas
| QAxBase() | |
| virtual bool | initialize(IUnknown **ptr) |
| bool | initializeActive(IUnknown **ptr) |
| bool | initializeFromFile(IUnknown **ptr) |
| bool | initializeLicensed(IUnknown **ptr) |
| bool | initializeRemote(IUnknown **ptr) |
Descripción detallada
QAxBase es una clase abstracta que no se puede utilizar directamente, y se instancia a través de las subclases QAxObject y QAxWidget. Esta clase proporciona la API para acceder al objeto COM directamente a través de su implementación de IUnknown. Si el objeto COM implementa la interfaz IDispatch, las propiedades y métodos de dicho objeto pasan a estar disponibles como propiedades y ranuras de Qt.
connect(buttonBack, SIGNAL(clicked()), webBrowser, SLOT(GoBack()));Las propiedades expuestas por la implementación de IDispatch del objeto se pueden leer y escribir a través del sistema de propiedades que proporciona el modelo de objetos de Qt (ambas subclases son de tipo ` QObject`, por lo que se puede utilizar ` QObject::setProperty()` y ` QObject::property()`). No se admiten propiedades con varios parámetros.
activeX->setProperty("text", "some text");
int value = activeX->property("value");Las funciones de escritura para las propiedades y otros métodos expuestos por la implementación de IDispatch del objeto pueden invocarse directamente mediante dynamicCall(), o indirectamente como ranuras conectadas a una señal.
webBrowser->dynamicCall("GoHome()");Los eventos salientes admitidos por el objeto COM se emiten como señales estándar de Qt.
QAxBase realiza la conversión de forma transparente entre los tipos de datos COM y los tipos de datos Qt equivalentes. Algunos tipos COM no tienen una estructura de datos Qt equivalente.
Los tipos de datos COM compatibles se enumeran en la primera columna de la siguiente tabla. La segunda columna muestra el tipo de Qt que se puede utilizar con las funciones de propiedad de QObject. La tercera columna muestra el tipo de Qt que se utiliza en el prototipo de las señales y ranuras generadas para los parámetros de entrada, y la última columna muestra el tipo de Qt que se utiliza en el prototipo de las señales y ranuras para los parámetros de salida.
| Tipo COM | Propiedad de Qt | Parámetro de entrada | Parámetro de salida |
|---|---|---|---|
| VARIANT_BOOL | bool | bool | bool& |
| BSTR | QString | const QString& | QString& |
| char, short, int, long | int | int | int& |
| uchar, ushort, uint, ulong | uint | uint | uint& |
| float, double | double | double | double& |
| DATE | QDateTime | const QDateTime& | QDateTime& |
| CY | qlonglong | qlonglong | qlonglong& |
| OLE_COLOR | QColor | const QColor& | QColor& |
| SAFEARRAY(VARIANT) | QList<QVariant> | const QList<QVariant>& | QList<QVariant>& |
| SAFEARRAY(int), SAFEARRAY(double), SAFEARRAY(Date) | QList<QVariant> | const QList<QVariant>& | QList<QVariant>& |
| SAFEARRAY(BYTE) | QByteArray | const QByteArray& | QByteArray& |
| SAFEARRAY(BSTR) | QStringList | const QStringList& | QStringList& |
| VARIANT | depende del tipo | const QVariant& | QVariant& |
| IFontDisp* | QFont | const QFont& | QFont& |
| IPictureDisp* | QPixmap | const QPixmap& | QPixmap& |
| IDispatch* | QAxObject* | QAxBase::asVariant() | QAxObject* (valor de retorno) |
| IUnknown* | QAxObject* | QAxBase::asVariant() | QAxObject* (valor de retorno) |
| SCODE, DECIMAL | no compatible | no compatible | no compatible |
| VARIANT* (Desde Qt 4.5) | no compatible | QVariant& | QVariant& |
También se admiten enumeraciones y definiciones de tipo (typedef) para tipos compatibles.
Para llamar a los métodos de una interfaz COM descrita por el siguiente IDL
dispinterface IControl
{
properties:
[id(1)] BSTR text;
[id(2)] IFontDisp *font;
methods:
[id(6)] void showColumn([in] int i);
[id(3)] bool addColumn([in] BSTR t);
[id(4)] int fillList([in, out] SAFEARRAY(VARIANT) *list);
[id(5)] IDispatch *item([in] int i);
};utilice la API QAxBase de la siguiente manera:
QAxObject object("<CLSID>");
QString text = object.property("text").toString();
object.setProperty("font", QFont("Times New Roman", 12));
connect(this, SIGNAL(clicked(int)), &object, SLOT(showColumn(int)));
bool ok = object.dynamicCall("addColumn(const QString&)", "Column 1").toBool();
QList<QVariant> varlist;
QList<QVariant> parameters;
parameters << QVariant(varlist);
int n = object.dynamicCall("fillList(QList<QVariant>&)", parameters).toInt();
QAxObject *item = object.querySubItem("item(int)", 5);Ten en cuenta que el ` QList ` que debe rellenar el objeto debe proporcionarse como un elemento en la lista de parámetros de ` QVariants`.
Si necesitas acceder a propiedades o pasar parámetros de tipos de datos no compatibles, debes acceder al objeto COM directamente a través de su implementación de « IDispatch » u otras interfaces. Dichas interfaces se pueden obtener mediante ` queryInterface()`.
IUnknown *iface = 0;
activeX->queryInterface(IID_IUnknown, (void**)&iface);
if (iface) {
// use the interface
iface->Release();
}Para obtener la definición de las interfaces COM, tendrás que utilizar los archivos de cabecera proporcionados con el componente que desees utilizar. Algunos compiladores también pueden importar bibliotecas de tipos mediante la directiva del compilador #import. Consulta la documentación del componente para averiguar qué bibliotecas de tipos debes importar y cómo utilizarlas.
Si necesitas reaccionar ante eventos que pasan parámetros de tipos de datos no compatibles, puedes utilizar la señal genérica que proporciona los datos del evento tal y como los ofrece el evento COM.
Véase también QAxObject, QAxWidget, QAxScript y ActiveQt Framework.
Documentación sobre tipos de miembros
[alias] QAxBase::PropertyBag
Un objeto ` QMap` <QString,QVariant> capaz de almacenar propiedades como pares nombre:valor.
Documentación de las funciones de miembro
[protected] QAxBase::QAxBase()
Crea un objeto QAxBase.
[virtual noexcept] QAxBase::~QAxBase()
Cierra el objeto COM y destruye el objeto QAxBase.
Véase también clear().
QVariant QAxBase::asVariant() const
Devuelve una variable de tipo « QVariant » que envuelve el objeto COM. A continuación, la variante se puede utilizar como parámetro, por ejemplo, en la función ` dynamicCall()`.
ulong QAxBase::classContext() const
Devuelve el contexto en el que se ejecutará el control ActiveX (por defecto, CLSCTX_SERVER).
Véase también setClassContext().
void QAxBase::clear()
Desconecta y destruye el objeto COM.
Si reimplementas esta función, también debes reimplementar el destructor para llamar a clear(), y llamar a esta implementación al final de tu función clear().
QString QAxBase::control() const
Devuelve el control ActiveX.
void QAxBase::disableClassInfo()
Desactiva la generación de información de clase para este contenedor ActiveX. Si no necesitas ninguna información de clase sobre el control ActiveX, utiliza esta función para acelerar la generación de metaojetos.
Ten en cuenta que esta función debe llamarse inmediatamente después de la construcción del objeto.
void QAxBase::disableEventSink()
Desactiva la implementación del receptor de eventos para este contenedor ActiveX. Si no tienes intención de escuchar los eventos del control ActiveX, utiliza esta función para acelerar la generación del metaoobjeto.
Algunos controles ActiveX pueden resultar inestables cuando se conectan a un receptor de eventos. Para obtener eventos OLE, debes utilizar métodos COM estándar para registrar tu propio receptor de eventos. Utiliza queryInterface() para acceder al objeto COM sin procesar.
Ten en cuenta que esta función debe llamarse inmediatamente después de la construcción del objeto.
void QAxBase::disableMetaObject()
Desactiva la generación de metaobjetos para este contenedor ActiveX. Esto también desactiva la generación del receptor de eventos y de la información de clase. Si no tienes intención de utilizar la implementación de metaobjetos de Qt, llama a esta función para acelerar la instanciación del control. Seguirás pudiendo llamar al objeto mediante dynamicCall(), pero las señales, las ranuras y las propiedades no estarán disponibles con las API de QObject.
Algunos controles ActiveX pueden resultar inestables cuando se utilizan con la automatización OLE. Utilice métodos COM estándar para utilizar dichos controles a través de las interfaces COM proporcionadas por queryInterface().
Tenga en cuenta que esta función debe invocarse inmediatamente después de la creación del objeto.
QVariant QAxBase::dynamicCall(const char *function, const QVariant &var1 = QVariant(), const QVariant &var2 = QVariant(), const QVariant &var3 = QVariant(), const QVariant &var4 = QVariant(), const QVariant &var5 = QVariant(), const QVariant &var6 = QVariant(), const QVariant &var7 = QVariant(), const QVariant &var8 = QVariant())
Llama al método « function » del objeto COM, pasando los parámetros « var1 », « var1 », « var2 », « var3 », « var4 », « var5 », « var6 », « var7 » y « var8 », y devuelve el valor devuelto por el método, o un « QVariant » no válido si el método no devuelve ningún valor o si la llamada a la función ha fallado.
Si function es un método del objeto, la cadena debe proporcionarse como el prototipo completo, por ejemplo, tal y como se escribiría en una llamada QObject::connect().
activeX->dynamicCall("Navigate(const QString&)", "www.qt-project.org");Como alternativa, se puede llamar a una función pasando los parámetros incrustados en la cadena; por ejemplo, la función anterior también se puede invocar utilizando
activeX->dynamicCall("Navigate(\"www.qt-project.org\")");Todos los parámetros se pasan como cadenas; depende del control que se interpreten correctamente, y es más lento que utilizar el prototipo con parámetros correctamente tipados.
Si function es una propiedad, la cadena debe ser el nombre de la propiedad. El setter de la propiedad se invoca cuando var1 es un QVariant válido; de lo contrario, se invoca el getter.
activeX->dynamicCall("Value", 5);
QString text = activeX->dynamicCall("Text").toString();Ten en cuenta que es más rápido obtener y establecer propiedades utilizando QObject::property() y QObject::setProperty().
dynamicCall() también se puede utilizar para llamar a objetos con un envoltorio disabled metaobject, lo que puede mejorar significativamente el rendimiento, especialmente al llamar a muchos objetos diferentes de distintos tipos durante un proceso de automatización. Sin embargo, en ese caso, ActiveQt no validará los parámetros.
Solo es posible llamar a funciones mediante dynamicCall() que tengan parámetros o devuelvan valores de tipos de datos compatibles con QVariant. Consulte la documentación de la clase QAxBase para obtener una lista de los tipos de datos compatibles y no compatibles. Si desea llamar a funciones que tengan tipos de datos no compatibles en la lista de parámetros, utilice queryInterface() para obtener la interfaz COM adecuada y utilice la función directamente.
IWebBrowser2 *webBrowser = 0;
activeX->queryInterface(IID_IWebBrowser2, (void **)&webBrowser);
if (webBrowser) {
webBrowser->Navigate2(pvarURL);
webBrowser->Release();
}Además, esto resulta más eficiente.
QVariant QAxBase::dynamicCall(const char *function, QList<QVariant> &vars)
Llama al método « function » del objeto COM, pasando los parámetros de « vars », y devuelve el valor devuelto por el método. Si el método no devuelve ningún valor o si la llamada a la función ha fallado, esta función devuelve un objeto « QVariant » no válido.
Los objetos ` QVariant ` de ` vars ` se actualizan cuando el método tiene parámetros de salida.
Esta es una función sobrecargada.
QString QAxBase::generateDocumentation()
Devuelve una cadena de texto enriquecido con la documentación del objeto COM envuelto. Guarda la cadena en un archivo HTML o utilízala, por ejemplo, en un widget de QTextBrowser.
[virtual protected] bool QAxBase::initialize(IUnknown **ptr)
Esta función virtual es llamada por setControl() y crea el objeto COM solicitado. Se asigna ptr a la implementación de IUnknown del objeto. La función devuelve «true» si la inicialización del objeto se ha realizado correctamente; en caso contrario, devuelve «false».
La implementación predeterminada interpreta la cadena devuelta por ` control()` y llama a ` initializeRemote()`, ` initializeLicensed()` o ` initializeActive()` si la cadena coincide con los patrones respectivos. Si ` control()` es el nombre de un archivo existente, se llama a ` initializeFromFile()`. Si no se encuentra ninguna coincidencia con los patrones, o si falla la inicialización remota o con licencia, se utiliza directamente `CoCreateInstance` para crear el objeto.
Consulte la documentación de la propiedad QAxBaseWidget::control para obtener más detalles sobre los patrones admitidos.
La interfaz devuelta en ptr debe referenciarse exactamente una vez cuando esta función devuelva un valor. La interfaz proporcionada, por ejemplo, por CoCreateInstance ya está referenciada, por lo que no es necesario volver a referenciarla.
[protected] bool QAxBase::initializeActive(IUnknown **ptr)
Se conecta a una instancia activa que se está ejecutando en el equipo actual y devuelve la interfaz IUnknown del objeto en ejecución en ptr. Esta función devuelve «true» si se ejecuta correctamente; en caso contrario, devuelve «false».
Esta función es llamada por initialize() si la cadena de control contiene la subcadena «}&».
Véase también initialize().
[protected] bool QAxBase::initializeFromFile(IUnknown **ptr)
Crea el objeto COM que gestiona el nombre de archivo de la propiedad «control» y devuelve la interfaz IUnknown del objeto en ptr. Esta función devuelve «true» si se ejecuta correctamente; en caso contrario, devuelve «false».
Esta función es llamada por initialize() si la cadena del control es el nombre de un archivo existente.
Véase también initialize().
[protected] bool QAxBase::initializeLicensed(IUnknown **ptr)
Crea una instancia de un control con licencia y devuelve la interfaz IUnknown del objeto en ` ptr`. Esta función devuelve `true` si se ejecuta correctamente; en caso contrario, devuelve `false`.
Esta función es llamada por initialize() si la cadena del control contiene la subcadena «}:». La clave de licencia debe aparecer inmediatamente después de esta subcadena.
Véase también initialize().
[protected] bool QAxBase::initializeRemote(IUnknown **ptr)
Crea la instancia en un servidor remoto y devuelve la interfaz IUnknown del objeto en ptr. Esta función devuelve «true» si se ejecuta correctamente; en caso contrario, devuelve «false».
Esta función es llamada por initialize() si la cadena de control contiene la subcadena «/{». La información sobre el equipo remoto debe proporcionarse antes de dicha subcadena.
Véase también initialize().
bool QAxBase::isNull() const
Devuelve «true» si este envoltorio no tiene cargado ningún objeto COM; en caso contrario, devuelve «false».
Véase también control().
QAxBase::PropertyBag QAxBase::propertyBag() const
Devuelve un mapa nombre:valor con todas las propiedades expuestas por el objeto COM.
Esto resulta más eficiente que obtener varias propiedades de forma individual si el objeto COM admite bolsas de propiedades.
Advertencia: Nose garantiza que la implementación de la bolsa de propiedades del objeto COM devuelva todas las propiedades, ni que las propiedades devueltas sean las mismas que las disponibles a través de la interfaz IDispatch.
Véase también setPropertyBag().
[virtual] bool QAxBase::propertyWritable(const char *prop) const
Devuelve «true» si la propiedad prop es modificable; en caso contrario, devuelve «false». Por defecto, todas las propiedades son modificables.
Advertencia: Dependiendo de la implementación del control, es posible que esta configuración se ignore para algunas propiedades.
Véase también setPropertyWritable(), QAxBaseWidget::propertyChanged() y QAxBaseObject::propertyChanged().
long QAxBase::queryInterface(const QUuid &uuid, void **iface) const
Solicita la interfaz « uuid » al objeto COM y establece el valor de « iface » en la interfaz proporcionada, o en 0 si no se ha podido proporcionar la interfaz solicitada.
Devuelve el resultado de la implementación de QueryInterface del objeto COM.
Véase también control().
QAxObject *QAxBase::querySubObject(const char *name, const QVariant &var1 = QVariant(), const QVariant &var2 = QVariant(), const QVariant &var3 = QVariant(), const QVariant &var4 = QVariant(), const QVariant &var5 = QVariant(), const QVariant &var6 = QVariant(), const QVariant &var7 = QVariant(), const QVariant &var8 = QVariant())
Devuelve un puntero a un objeto ` QAxObject ` que envuelve el objeto COM proporcionado por el método o la propiedad ` name`, pasando los parámetros ` var1`, ` var1`, ` var2`, ` var3`, ` var4`, ` var5`, ` var6`, ` var7 ` y ` var8`.
Si name se proporciona mediante un método, la cadena debe incluir el prototipo completo de la función.
Si ` name ` es una propiedad, la cadena debe ser el nombre de la propiedad, y se ignoran ` var1`, `...` var8.
El objeto ` QAxObject ` devuelto es un hijo de este objeto (que es de tipo ` QAxObject ` o ` QAxWidget`), y se elimina cuando se elimina este objeto. No obstante, es seguro eliminar el objeto devuelto por tu cuenta, y debes hacerlo cuando iteres sobre listas de subobjetos.
Las aplicaciones compatibles con COM suelen tener un modelo de objetos que publica determinados elementos de la aplicación como interfaces de despacho. Utiliza este método para navegar por la jerarquía del modelo de objetos, por ejemplo:
QAxWidget outlook("Outlook.Application");
QAxObject *session = outlook.querySubObject("Session");
if (session) {
QAxObject *defFolder = session->querySubObject(
"GetDefaultFolder(OlDefaultFolders)",
"olFolderContacts");
//...
}QAxObject *QAxBase::querySubObject(const char *name, QList<QVariant> &vars)
Los objetos ` QVariant ` de ` vars ` se actualizan cuando el método tiene parámetros de salida.
Se trata de una función sobrecargada.
void QAxBase::setClassContext(ulong classContext)
Establece el contexto en el que se ejecutará el control ActiveX classContext
Afecta al argumento «dwClsContext» al llamar a CoCreateInstance. Esto puede utilizarse para controlar el inicio «in-proc» frente al «out-of-proc» en los controles que admiten ambas alternativas. Además, se puede utilizar para modificar o reducir los permisos del control cuando se emplea junto con CLSCTX_ENABLE_CLOAKING y un token de suplantación de identidad.
Ten en cuenta que esta función debe invocarse antes de setControl() para que surta efecto.
Véase también classContext().
void QAxBase::setPropertyBag(const QAxBase::PropertyBag &bag)
Establece las propiedades del objeto COM con los valores correspondientes de bag.
Advertencia: Solodebe establecer los conjuntos de propiedades que haya devuelto la función propertyBag, ya que no se puede garantizar que la implementación del conjunto de propiedades del objeto COM admita las mismas propiedades que están disponibles a través de la interfaz IDispatch.
Véase también propertyBag().
[virtual] void QAxBase::setPropertyWritable(const char *prop, bool ok)
Establece la propiedad « prop » como modificable si « ok » es verdadero; en caso contrario, establece « prop » como de solo lectura. Por defecto, todas las propiedades son modificables.
Advertencia: Dependiendo de la implementación del control, es posible que esta configuración se ignore para algunas propiedades.
Véanse también propertyWritable(), QAxBaseWidget::propertyChanged() y QAxBaseObject::propertyChanged().
QStringList QAxBase::verbs() const
Devuelve la lista de verbos que el objeto COM puede ejecutar. Si el objeto no implementa IOleObject o no admite ningún verbo, esta función devuelve una lista de cadenas vacía.
Ten en cuenta que los verbos predeterminados de OLE (OLEIVERB_SHOW, etc.) no se incluyen en la lista.
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.