QAxBase 类

The QAxBase class is an abstract class that provides an API to initialize and access a COM object. 更多...

头：	#include <QAxBase>
CMake:	find_package(Qt6 REQUIRED COMPONENTS AxContainer) target_link_libraries(mytarget PRIVATE Qt6::AxContainer)
qmake:	QT += axcontainer
继承者：	QAxObject and QAxWidget

所有成员列表，包括继承成员

公共类型

PropertyBag

公共函数

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

保护函数

	QAxBase ()
virtual bool	initialize (IUnknown ** ptr )
bool	initializeActive (IUnknown ** ptr )
bool	initializeFromFile (IUnknown ** ptr )
bool	initializeLicensed (IUnknown ** ptr )
bool	initializeRemote (IUnknown ** ptr )

详细描述

QAxBase is an abstract class that cannot be used directly, and is instantiated through the subclasses QAxObject and QAxWidget 。此类提供能直接访问 COM 对象的 API，透过其 IUnknown 实现。若 COM 对象有实现 IDispatch 接口，该对象的特性和方法将变为可用 Qt 特性和槽。

connect(buttonBack, SIGNAL(clicked()), webBrowser, SLOT(GoBack()));

由对象 IDispatch 实现暴露的特性，可以透过 Qt 对象模型提供的特性系统进行读写 (两者的子类是 QObject ，所以可以使用 QObject::setProperty () 和 QObject::property ())。不支持具有多个参数的特性。

activeX->setProperty("text", "some text");
int value = activeX->property("value");

可以直接调用由对象的 IDispatch 实现暴露的属性及其它方法的写入函数，使用 dynamicCall ()，或间接作为连接到信号的槽。

webBrowser->dynamicCall("GoHome()");

由 COM 对象支持的传出事件，将作为标准 Qt 信号被发射。

connect(webBrowser, SIGNAL(TitleChanged(QString)),
        this, SLOT(setCaption(QString)));

QAxBase transparently converts between COM data types and the equivalent Qt data types. Some COM types have no equivalent Qt data structure.

下表第 1 列列出支持的 COM 数据类型。第 2 列是 Qt 类型可以用于 QObject 特性函数。第 3 列是 Qt 类型用于生成信号原型和内参数槽，最后列是 Qt 类型用于信号原型和外参数槽。

COM 类型	Qt 特性	内参数	外参数
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	从属类型	const QVariant &	QVariant &
IFontDisp*	QFont	const QFont &	QFont &
IPictureDisp*	QPixmap	const QPixmap &	QPixmap &
IDispatch*	QAxObject *	`QAxBase::asVariant()`	QAxObject * (return value)
IUnknown*	QAxObject *	`QAxBase::asVariant()`	QAxObject * (return value)
SCODE, DECIMAL	不支持	不支持	不支持
VARIANT* (从 Qt 4.5 起)	不支持	QVariant&	QVariant&

还支持枚举和支持类型的 typedef。

调用以下 IDL 描述的 COM 接口方法

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);
};

use the QAxBase API like this:

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);

注意， QList 对象的填充必须提供成元素在参数列表 QVariant 。

若需要访问不支持数据类型的特性 (或传递参数)，必须直接访问 COM 对象透过其 IDispatch 实现或其它接口。可以检索这些接口透过 queryInterface ().

IUnknown *iface = 0;
activeX->queryInterface(IID_IUnknown, (void**)&iface);
if (iface) {
    // use the interface
    iface->Release();
}

要获取 COM 接口的定义，必须使用随要使用组件提供的头文件。某些编译器还可以使用 #import 编译器指令导入类型库。见组件文档编制，找出必须导入哪些类型库及如何使用它们。

若需要对传递不支持数据类型的参数的事件做出反应，可以使用如由 COM 事件提供的交付事件数据的一般信号。

另请参阅 QAxObject , QAxWidget , QAxScript ，和 ActiveQt 框架 .

成员类型文档编制

`[alias]` QAxBase:: PropertyBag

A QMap < QString , QVariant > 可以按 name:value 对形式存储特性。

成员函数文档编制

`[protected]` QAxBase:: QAxBase ()

Creates a QAxBase object.

`[virtual noexcept]` QAxBase:: ~QAxBase ()

关闭 COM 对象并销毁 QAxBase 对象。

另请参阅 clear ().

QVariant QAxBase:: asVariant () const

返回 QVariant 包裹 COM (组件对象模型) 对象。然后，变体可以用作参数，如在 dynamicCall ().

ulong QAxBase:: classContext () const

Returns the context the ActiveX control will run in (default CLSCTX_SERVER).

另请参阅 setClassContext ().

void QAxBase:: clear ()

断开连接并销毁 COM 对象。

若重实现此函数，还必须重实现析构函数以调用 clear()，并在 clear() 函数末尾调用此实现。

QString QAxBase:: control () const

Returns the ActiveX control.

void QAxBase:: disableClassInfo ()

禁用此 ActiveX 容器的类信息生成。若不要求有关 ActiveX 控件的任何类信息，使用此函数以加速元对象的生成。

注意，必须在构造对象后立即调用此函数

void QAxBase:: disableEventSink ()

禁用此 ActiveX 容器的事件汇点实现。若不打算监听 ActiveX 控件事件，使用此函数能加速元对象的生成。

某些 ActiveX 控件可能不稳定，当连接到事件汇点时。要获取 OLE (对象链接和嵌入) 事件，必须使用标准 COM 方法注册自己的事件汇点。使用 queryInterface () 能访问原生 COM 对象。

注意，应立即调用此函数在对象构造后。

void QAxBase:: disableMetaObject ()

Disables the meta object generation for this ActiveX container. This also disables the event sink and class info generation. If you don't intend to use the Qt meta object implementation call this function to speed up instantiation of the control. You will still be able to call the object through dynamicCall (), but signals, slots and properties will not be available with QObject API。

Some ActiveX controls might be unstable when used with OLE automation. Use standard COM methods to use those controls through the COM interfaces provided by queryInterface ().

Note that this function must be called immediately after construction of the object.

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())

调用 COM 对象的方法 function ，传递参数 var1 , var1 , var2 , var3 , var4 , var5 , var6 , var7 and var8 ，并返回由方法返回的值，或无效 QVariant 若方法不返回值，或当函数调用失败时。

若 function 是必须以完整原型提供的字符串对象方法，例如，如将编写它在 QObject::connect () 调用。

activeX->dynamicCall("Navigate(const QString&)", "www.qt-project.org");

另外，可以调用嵌入字符串中的参数传递函数，如，也可以援引上述函数使用

activeX->dynamicCall("Navigate(\"www.qt-project.org\")");

所有参数以字符串形式传递；从属控件是否正确解释它们，但比使用带有正确类型参数的原型要慢。

若 function 是字符串必须是特性名的特性。调用 setter 特性当 var1 有效 QVariant ，否则调用 Getter。

activeX->dynamicCall("Value", 5);
QString text = activeX->dynamicCall("Text").toString();

请注意，它更快比获取和设置特性使用 QObject::property () 和 QObject::setProperty ().

dynamicCall() 还可以用于调用对象采用禁用元对象 wrapper, which can improve performance significantely, esp. when calling many different objects of different types during an automation process. ActiveQt will then however not validate parameters.

只能透过 dynamicCall() 调用拥有参数或数据类型返回值的函数，数据类型的支持是通过 QVariant 。见 QAxBase 类文档编制了解支持和不支持的数据类型列表。若想要调用参数列表中拥有不支持数据类型的函数，使用 queryInterface () 检索适当 COM 接口，并直接使用函数。

IWebBrowser2 *webBrowser = 0;
activeX->queryInterface(IID_IWebBrowser2, (void **)&webBrowser);
if (webBrowser) {
    webBrowser->Navigate2(pvarURL);
    webBrowser->Release();
}

此外，这更高效。

QVariant QAxBase:: dynamicCall (const char * function , QList < QVariant > & vars )

这是重载函数。

调用 COM 对象的方法 function ，传递参数在 vars ，并返回由方法返回的值。若方法不返回值 (或当函数调用失败时)，此函数返回无效 QVariant 对象。

The QVariant 对象在 vars 会更新当方法拥有输出参数时。

QString QAxBase:: generateDocumentation ()

返回带有包裹 COM 对象文档编制的富文本字符串。将字符串转储到 HTML 文件，或使它如在 QTextBrowser 小部件。

`[virtual protected]` bool QAxBase:: initialize ( IUnknown ** ptr )

This virtual function is called by setControl() and creates the requested COM object. ptr is set to the object's IUnknown implementation. The function returns true if the object initialization succeeded; otherwise the function returns false.

The default implementation interprets the string returned by control (), and calls initializeRemote (), initializeLicensed () 或 initializeActive () if the string matches the respective patterns. If control () is the name of an existing file, initializeFromFile () is called. If no pattern is matched, or if remote or licensed initialization fails, CoCreateInstance is used directly to create the object.

见 QAxBaseWidget::control 特性文档编制，了解支持模式的有关细节。

The interface returned in ptr must be referenced exactly once when this function returns. The interface provided by e.g. CoCreateInstance is already referenced, and there is no need to reference it again.

`[protected]` bool QAxBase:: initializeActive ( IUnknown ** ptr )

Connects to an active instance running on the current machine, and returns the IUnknown interface to the running object in ptr . This function returns true if successful, otherwise returns false.

此函数被调用通过 initialize () if the control string contains the substring "}&".

另请参阅 initialize ().

`[protected]` bool QAxBase:: initializeFromFile ( IUnknown ** ptr )

Creates the COM object handling the filename in the control property, and returns the IUnknown interface to the object in ptr . This function returns true if successful, otherwise returns false.

此函数被调用通过 initialize () 若控制字符串是现有文件名。

另请参阅 initialize ().

`[protected]` bool QAxBase:: initializeLicensed ( IUnknown ** ptr )

Creates an instance of a licensed control, and returns the IUnknown interface to the object in ptr . This functions returns true if successful, otherwise returns false.

此函数被调用通过 initialize () if the control string contains the substring "}:". The license key needs to follow this substring.

另请参阅 initialize ().

`[protected]` bool QAxBase:: initializeRemote ( IUnknown ** ptr )

Creates the instance on a remote server, and returns the IUnknown interface to the object in ptr . This function returns true if successful, otherwise returns false.

此函数被调用通过 initialize () if the control string contains the substring "/{". The information about the remote machine needs to be provided in front of the substring.

另请参阅 initialize ().

bool QAxBase:: isNull () const

返回 true 若此包裹器没有加载 COM 对象；否则返回 false。

另请参阅 control ().

QAxBase::PropertyBag QAxBase:: propertyBag () const

返回由 COM 对象暴露的所有特性的 name:value 映射。

This is more efficient than getting multiple properties individually if the COM object supports property bags.

警告： It is not guaranteed that the property bag implementation of the COM object returns all properties, or that the properties returned are the same as those available through the IDispatch interface.

另请参阅 setPropertyBag ().

`[虚拟]` bool QAxBase:: propertyWritable (const char * prop ) const

返回 true 若特性 prop 可写；否则返回 false。默认情况下，所有特性可写。

警告： 从属控件实现，某些特性可能忽略此设置。

另请参阅 setPropertyWritable (), QAxBaseWidget::propertyChanged ()，和 QAxBaseObject::propertyChanged ().

long QAxBase:: queryInterface (const QUuid & uuid , void ** iface ) const

请求接口 uuid 从 COM 对象并设置值 iface 为提供接口，或为 0 若无法提供请求接口。

返回 COM 对象 QueryInterface 实现的结果。

另请参阅 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())

返回指针指向 QAxObject 包裹 COM 对象提供通过方法或特性 name ，传递参数 var1 , var1 , var2 , var3 , var4 , var5 , var6 , var7 and var8 .

若 name 由方法提供，字符串必须包含完整函数原型。

若 name 是特性，字符串必须是特性名，且 var1 , ... var8 被忽略。

返回的 QAxObject 是此对象的子级 (类型 QAxObject or QAxWidget )，并被删除当删除此对象时。不管怎样，自己删除返回对象是安全的，且应该这样做当遍历子对象列表时。

启用 COM (组件对象模型) 的应用程序通常拥有对象模型，将应用程序的某些元素发布成分派接口。使用此方法能导航对象模型的层次结构，如

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 )

这是重载函数。

The QVariant 对象在 vars 会更新当方法拥有输出参数时。

void QAxBase:: setClassContext ( ulong classContext )

Sets the context the ActiveX control will run in to classContext

Affects the "dwClsContext" argument when calling CoCreateInstance. This can be used to control in-proc vs. out-of-proc startup for controls supporting both alternatives. Also, it can be used to modify/reduce control permissions when used with CLSCTX_ENABLE_CLOAKING and an impersonation token.

Note that this function must be called before setControl() to have any effect.

另请参阅 classContext ().

void QAxBase:: setPropertyBag (const QAxBase::PropertyBag & bag )

将 COM (组件对象模型) 对象的特性设为相应值按 bag .

警告： 才应设置特性包若有返回通过 propertyBag 函数，因为无法保证 COM 对象特性包实现，支持可用于 IDispatch 接口的相同特性。

另请参阅 propertyBag ().

`[虚拟]` void QAxBase:: setPropertyWritable (const char * prop , bool ok )

设置特性 prop 可写若 ok 为 true，否则设置 prop 为只读。默认情况下，所有属性可写。

警告： 从属控件实现，某些特性可能忽略此设置。

另请参阅 propertyWritable (), QAxBaseWidget::propertyChanged ()，和 QAxBaseObject::propertyChanged ().

QStringList QAxBase:: verbs () const

返回 COM 对象的可执行 verbs 列表。若对象未实现 IOleObject，或不支持任何 verbs，那么此函数返回空字符串列表。

注意，OLE 默认 verbs (OLIVERB_SHOW 等) 未包括在列表中。

QAxBase 类

公共类型

公共函数

保护函数

详细描述

成员类型文档编制

[alias] QAxBase:: PropertyBag

成员函数文档编制

[protected] QAxBase:: QAxBase ()

[virtual noexcept] QAxBase:: ~QAxBase ()

QVariant QAxBase:: asVariant () const

ulong QAxBase:: classContext () const

void QAxBase:: clear ()

QString QAxBase:: control () const

void QAxBase:: disableClassInfo ()

void QAxBase:: disableEventSink ()

void QAxBase:: disableMetaObject ()

QVariant QAxBase:: dynamicCall (const char * function , QList < QVariant > & vars )

QString QAxBase:: generateDocumentation ()

[virtual protected] bool QAxBase:: initialize ( IUnknown ** ptr )

[protected] bool QAxBase:: initializeActive ( IUnknown ** ptr )

[protected] bool QAxBase:: initializeFromFile ( IUnknown ** ptr )

[protected] bool QAxBase:: initializeLicensed ( IUnknown ** ptr )

[protected] bool QAxBase:: initializeRemote ( IUnknown ** ptr )

bool QAxBase:: isNull () const

QAxBase::PropertyBag QAxBase:: propertyBag () const

[虚拟] bool QAxBase:: propertyWritable (const char * prop ) const

long QAxBase:: queryInterface (const QUuid & uuid , void ** iface ) const

QAxObject *QAxBase:: querySubObject (const char * name , QList < QVariant > & vars )

void QAxBase:: setClassContext ( ulong classContext )

void QAxBase:: setPropertyBag (const QAxBase::PropertyBag & bag )

[虚拟] void QAxBase:: setPropertyWritable (const char * prop , bool ok )

QStringList QAxBase:: verbs () const

内容

`[alias]` QAxBase:: PropertyBag

`[protected]` QAxBase:: QAxBase ()

`[virtual noexcept]` QAxBase:: ~QAxBase ()

`[virtual protected]` bool QAxBase:: initialize ( IUnknown ** ptr )

`[protected]` bool QAxBase:: initializeActive ( IUnknown ** ptr )

`[protected]` bool QAxBase:: initializeFromFile ( IUnknown ** ptr )

`[protected]` bool QAxBase:: initializeLicensed ( IUnknown ** ptr )

`[protected]` bool QAxBase:: initializeRemote ( IUnknown ** ptr )

`[虚拟]` bool QAxBase:: propertyWritable (const char * prop ) const

QAxObject QAxBase:: querySubObject (const char name , QList < QVariant > & vars )

`[虚拟]` void QAxBase:: setPropertyWritable (const char * prop , bool ok )