QAxBase 类

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

头：	#include <QAxBase>
qmake:	QT += axcontainer
继承者：	QAxObject and QAxWidget

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

公共类型

(alias)

PropertyBag

特性

control : QString

公共函数

	QAxBase (IUnknown * iface = nullptr)
virtual	~QAxBase ()
QVariant	asVariant () const
unsigned long	classContext () const
virtual 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 (unsigned long classContext )
bool	setControl ( const QString & )
void	setPropertyBag (const QAxBase::PropertyBag & bag )
virtual void	setPropertyWritable (const char * prop , bool ok )
QStringList	verbs () const

信号

void	exception (int code , const QString & source , const QString & desc , const QString & help )
void	propertyChanged (const QString & name )
void	signal (const QString & name , int argc , void * argv )

保护函数

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

This is a type alias for QMap<QString, QVariant>.

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

特性文档编制

control : QString

此特性保持包裹的 COM 对象名称通过此 QAxBase 对象。

设置此特性将初始化 COM (组件对象模型) 对象。关闭先前设置的任何 COM 对象。

设置此特性的最有效方式是使用注册组件 UUID，如

ctrl->setControl("{8E27C92B-1264-101C-8A2F-040224009C02}");

第 2 种最快方式是使用已注册控件类名 (带或不带版本号)，如

ctrl->setControl("MSCal.Calendar");

最慢但最轻松的方式是使用控件的完整名称，如

ctrl->setControl("Calendar Control 9.0");

从文件初始化对象也是可能的，如

ctrl->setControl("c:/files/file.doc");

若使用组件 UUID 则可以使用下列模式初始化远程机器控件，以初始化许可控件或连接到正运行对象：

要初始化不同机器中的控件，使用以下模式：

<domain/username>:<password>@server/{8E27C92B-1264-101C-8A2F-040224009C02}

要初始化许可控件，使用以下模式：

{8E27C92B-1264-101C-8A2F-040224009C02}:<LicenseKey>

要连接到已运行对象，使用以下模式：

{8E27C92B-1264-101C-8A2F-040224009C02}&

前 2 种模式可以组合，如初始化远程机器中的许可控件：

ctrl->setControl("DOMAIN/user:password@server/{8E27C92B-1264-101C-8A2F-040224009C02}:LicenseKey");

控件的读取函数始终返回控件的 UUID，若提供包括许可密钥和服务器名称，但不包括用户名、域或口令。

访问函数：

QString	control () const
bool	setControl ( const QString & )

另请参阅 setClassContext ().

成员函数文档编制

QAxBase:: QAxBase ( IUnknown * iface = nullptr)

Creates a QAxBase object that wraps the COM object iface 。若 iface 为 0 (默认)，使用 setControl () 实例化 COM 对象。

`[signal]` void QAxBase:: exception ( int code , const QString & source , const QString & desc , const QString & help )

This signal is emitted when the COM object throws an exception while called using the OLE automation interface IDispatch. code , source , desc and help provide information about the exception as provided by the COM server and can be used to provide useful feedback to the end user. help includes the help file, and the help context ID in brackets, e.g. "filename [id]".

`[signal]` void QAxBase:: propertyChanged (const QString & name )

若 COM (组件对象模型) 对象支持特性通知，此信号获得发射当特性称为 name 改变。

`[signal]` void QAxBase:: signal (const QString & name , int argc , void * argv )

This generic signal gets emitted when the COM object issues the event name . argc is the number of parameters provided by the event (DISPPARAMS.cArgs), and argv is the pointer to the parameter values (DISPPARAMS.rgvarg). Note that the order of parameter values is turned around, ie. the last element of the array is the first parameter in the function.

void Receiver::slot(const QString &name, int argc, void *argv)
{
    VARIANTARG *params = (VARIANTARG*)argv;
    if (name.startsWith("BeforeNavigate2(")) {
        IDispatch *pDisp = params[argc-1].pdispVal;
        VARIANTARG URL = *params[argc-2].pvarVal;
        VARIANTARG Flags = *params[argc-3].pvarVal;
        VARIANTARG TargetFrameName = *params[argc-4].pvarVal;
        VARIANTARG PostData = *params[argc-5].pvarVal;
        VARIANTARG Headers = *params[argc-6].pvarVal;
        bool *Cancel = params[argc-7].pboolVal;
    }
}

Use this signal if the event has parameters of unsupported data types. Otherwise, connect directly to the signal name .

`[虚拟]` QAxBase:: ~QAxBase ()

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

另请参阅 clear ().

QVariant QAxBase:: asVariant () const

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

unsigned long QAxBase:: classContext () const

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

该函数在 Qt 5.13 引入。

另请参阅 setClassContext ().

`[虚拟]` void QAxBase:: clear ()

断开连接并销毁 COM 对象。

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

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() 还可以用于调用对象采用禁用元对象包裹器，可以显著提高性能，尤其，在自动化过程中调用不同类型的许多不同对象时。 ActiveQt 不管怎样，不会验证参数。

只能透过 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 )

此虚函数被调用由 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.

见 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 () 和 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 ( unsigned long 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.

该函数在 Qt 5.13 引入。

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

QStringList QAxBase:: verbs () const

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

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

该函数在 Qt 4.1 引入。

QAxBase 类

公共类型

特性

公共函数

信号

保护函数

详细描述

成员类型文档编制

[alias] QAxBase:: PropertyBag

特性文档编制

control : QString

成员函数文档编制

QAxBase:: QAxBase ( IUnknown * iface = nullptr)

[signal] void QAxBase:: exception ( int code , const QString & source , const QString & desc , const QString & help )

[signal] void QAxBase:: propertyChanged (const QString & name )

[signal] void QAxBase:: signal (const QString & name , int argc , void * argv )

[虚拟] QAxBase:: ~QAxBase ()

QVariant QAxBase:: asVariant () const

unsigned long QAxBase:: classContext () const

[虚拟] void QAxBase:: clear ()

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 ( unsigned long classContext )

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

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

QStringList QAxBase:: verbs () const

内容

`[alias]` QAxBase:: PropertyBag

`[signal]` void QAxBase:: exception ( int code , const QString & source , const QString & desc , const QString & help )

`[signal]` void QAxBase:: propertyChanged (const QString & name )

`[signal]` void QAxBase:: signal (const QString & name , int argc , void * argv )

`[虚拟]` QAxBase:: ~QAxBase ()

`[虚拟]` void QAxBase:: clear ()

`[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 )