内容

公共类型
特性
公共函数
信号
保护函数
详细描述

QAxBase 类

QAxBase 类是提供初始化和访问 COM (组件对象模型) 对象 API 的抽象类。更多...

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

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

公共类型

typedef

PropertyBag

特性

control : QString

公共函数

	QAxBase (IUnknown * iface = Q_NULLPTR)
virtual	~QAxBase ()
QVariant	asVariant () 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
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 )
bool	setControl ( const QString & )
void	setPropertyBag (const 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 类是提供初始化和访问 COM (组件对象模型) 对象 API 的抽象类。

QAxBase 是无法直接使用的抽象类，且实例化是透过子类 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.

Supported COM datatypes are listed in the first column of following table. The second column is the Qt type that can be used with the QObject property functions. The third column is the Qt type that is used in the prototype of generated signals and slots for in-parameters, and the last column is the Qt type that is used in the prototype of signals and slots for out-parameters.

COM 类型	Qt 特性	in-parameter	out-parameter
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	type-dependent	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	unsupported	unsupported	unsupported
VARIANT* (Since Qt 4.5)	unsupported	QVariant&	QVariant&

Supported are also enumerations, and typedefs to supported types.

To call the methods of a COM interface described by the following 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);
};

使用 QAxBase API 像这样：

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 the object should fill has to be provided as an element in the parameter list of QVariant s.

If you need to access properties or pass parameters of unsupported datatypes you must access the COM object directly through its IDispatch implementation or other interfaces. Those interfaces can be retrieved through queryInterface ().

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

To get the definition of the COM interfaces you will have to use the header files provided with the component you want to use. Some compilers can also import type libraries using the #import compiler directive. See the component documentation to find out which type libraries you have to import, and how to use them.

If you need to react to events that pass parameters of unsupported datatypes you can use the generic signal that delivers the event data as provided by the COM event.

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

成员类型文档编制

typedef QAxBase:: PropertyBag

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

If the component's UUID is used the following patterns can be used to initialize the control on a remote machine, to initialize a licensed control or to connect to a running object:

To initialize the control on a different machine use the following pattern:

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

To initialize a licensed control use the following pattern:

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

To connect to an already running object use the following pattern:
```
{8E27C92B-1264-101C-8A2F-040224009C02}&
							
```

The first two patterns can be combined, e.g. to initialize a licensed control on a remote machine:

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

The control's read function always returns the control's UUID, if provided including the license key, and the name of the server, but not including the username, the domain or the password.

访问函数：

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

成员函数文档编制

QAxBase:: QAxBase ( IUnknown * iface = Q_NULLPTR)

创建 QAxBase 对象包裹 COM (组件对象模型) 对象 iface 。若 iface 为 0 (默认)，使用 setControl () 实例化 COM 对象。

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

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

另请参阅 clear ().

QVariant QAxBase:: asVariant () const

返回 QVariant that wraps the COM object. The variant can then be used as a parameter in e.g. dynamicCall ().

`[virtual]` void QAxBase:: clear ()

断开连接并销毁 COM 对象。

If you reimplement this function you must also reimplement the destructor to call clear(), and call this implementation at the end of your clear() function.

void QAxBase:: disableClassInfo ()

Disables the class info generation for this ActiveX container. If you don't require any class information about the ActiveX control use this function to speed up the meta object generation.

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

void QAxBase:: disableEventSink ()

Disables the event sink implementation for this ActiveX container. If you don't intend to listen to the ActiveX control's events use this function to speed up the meta object generation.

Some ActiveX controls might be unstable when connected to an event sink. To get OLE events you must use standard COM methods to register your own event sink. Use queryInterface () to get access to the raw COM object.

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

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 APIs.

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

Calls the COM object's method function , passing the parameters var1 , var1 , var2 , var3 , var4 , var5 , var6 , var7 and var8 , and returns the value returned by the method, or an invalid QVariant if the method does not return a value or when the function call failed.

若 function is a method of the object the string must be provided as the full prototype, for example as it would be written in a QObject::connect () 调用。

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

Alternatively a function can be called passing the parameters embedded in the string, e.g. above function can also be invoked using

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

All parameters are passed as strings; it depends on the control whether they are interpreted correctly, and is slower than using the prototype with correctly typed parameters.

若 function is a property the string has to be the name of the property. The property setter is called when var1 有效 QVariant , otherwise the getter is called.

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

Note that it is faster to get and set properties using QObject::property () 和 QObject::setProperty ().

dynamicCall() can also be used to call objects with a disabled metaobject 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.

It is only possible to call functions through dynamicCall() that have parameters or return values of datatypes supported by QVariant 。见 QAxBase class documentation for a list of supported and unsupported datatypes. If you want to call functions that have unsupported datatypes in the parameter list, use queryInterface () to retrieve the appropriate COM interface, and use the function directly.

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

This is also more efficient.

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

这是重载函数。

Calls the COM object's method function , passing the parameters in vars , and returns the value returned by the method. If the method does not return a value or when the function call failed this function returns an invalid QVariant 对象。

QVariant objects in vars are updated when the method has out-parameters.

`[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]".

QString QAxBase:: generateDocumentation ()

Returns a rich text string with documentation for the wrapped COM object. Dump the string to an HTML-file, or use it in e.g. a 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 property documentation for details about supported patterns.

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 () if the control string is the name of an existing file.

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

PropertyBag QAxBase:: propertyBag () const

Returns a name:value map of all the properties exposed by the COM object.

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

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

If the COM object supports property notification, this signal gets emitted when the property called name 改变。

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

Returns true if the property prop is writable; otherwise returns false. By default, all properties are writable.

警告： Depending on the control implementation this setting might be ignored for some properties.

另请参阅 setPropertyWritable () 和 propertyChanged ().

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

Requests the interface uuid from the COM object and sets the value of iface to the provided interface, or to 0 if the requested interface could not be provided.

Returns the result of the QueryInterface implementation of the COM object.

另请参阅 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 wrapping the COM object provided by the method or property name , passing passing the parameters var1 , var1 , var2 , var3 , var4 , var5 , var6 , var7 and var8 .

若 name is provided by a method the string must include the full function prototype.

若 name is a property the string must be the name of the property, and var1 , ... var8 被忽略。

返回的 QAxObject is a child of this object (which is either of type QAxObject or QAxWidget ), and is deleted when this object is deleted. It is however safe to delete the returned object yourself, and you should do so when you iterate over lists of subobjects.

COM enabled applications usually have an object model publishing certain elements of the application as dispatch interfaces. Use this method to navigate the hierarchy of the object model, e.g.

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 )

这是重载函数。

QVariant objects in vars are updated when the method has out-parameters.

void QAxBase:: setPropertyBag (const PropertyBag & bag )

Sets the properties of the COM object to the corresponding values in bag .

警告： You should only set property bags that have been returned by the propertyBag function, as it cannot be guaranteed that the property bag implementation of the COM object supports the same properties that are available through the IDispatch interface.

另请参阅 propertyBag ().

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

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

警告： Depending on the control implementation this setting might be ignored for some properties.

另请参阅 propertyWritable () 和 propertyChanged ().

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

QStringList QAxBase:: verbs () const

Returns the list of verbs that the COM object can execute. If the object does not implement IOleObject, or does not support any verbs, then this function returns an empty stringlist.

Note that the OLE default verbs (OLEIVERB_SHOW etc) are not included in the list.

该函数在 Qt 4.1 引入。

内容

QAxBase 类

公共类型

特性

公共函数

信号

保护函数

详细描述

成员类型文档编制

typedef QAxBase:: PropertyBag

特性文档编制

control : QString

成员函数文档编制

QAxBase:: QAxBase ( IUnknown * iface = Q_NULLPTR)

[virtual] QAxBase:: ~QAxBase ()

QVariant QAxBase:: asVariant () const

[virtual] void QAxBase:: clear ()

void QAxBase:: disableClassInfo ()

void QAxBase:: disableEventSink ()

void QAxBase:: disableMetaObject ()

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

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

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

PropertyBag QAxBase:: propertyBag () const

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

[virtual] 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:: setPropertyBag (const PropertyBag & bag )

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

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

QStringList QAxBase:: verbs () const

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

`[virtual]` void QAxBase:: clear ()

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

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

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

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

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

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

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