QAxBase Class Reference

QAxBase Class Reference
^{^{[QAxContainer module]}}

QAxBase是一个抽象类，提供了初始化及访问COM对象的API. More...

#include <QAxBase>

被QAxObject和QAxWidget继承.

List of all members, including inherited members

Public Types

typedef PropertyBag

Properties

control : QString

Public Functions

QAxBase ( IUnknown * iface = 0 )
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

Signals

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 )

Protected Functions

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

Detailed Description

QAxBase是一个抽象类，提供了初始化及访问COM对象的API.

QAxBase是抽象类不能直接使用, 由其子类QAxObject和QAxWidget来实例化. 该类提供了通过COM对象IUnknow来直接访问对象的API. 如果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(const QString&)),
this, SLOT(setCaption(const QString&)));

QAxBase在COM数据类型和等价的Qt数据类型之间作了转换. 有的COM types没有等价的Qt数据结构.

所支持的COM数据类型列在下面表格中的第一列. 第二列是能被QObject属性函数使用的Qt类型. 第三列是能在生成的信号和槽原型中做输入参数的Qt类型, 最后一列是能被用作信号和槽原型的输出参数中的Qt类型.

COM type	Qt property	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(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

也支持枚举类型和由支持类型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);
};

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

Note that the QList the object should fill has to be provided as an element in the parameter list of QVariants.

如果要访问的属性或传递的参数是不支持的数据类型, 必须通过IDispatch或其他接口直接访问COM对象. 这些接口能通过queryInterface()得到.

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

需要使用组件提供的头文件来获得COM接口的定义. 有的编译器也能使用#import指令导入类型库. 查阅组件的文档找到你需要导入的类型库及其用法.

如果要响应那些有不支持数据类型参数的事件, 可以使用generic signal传递COM事件的事件数据.

参看QAxObject, QAxWidget, QAxScript 和 ActiveQt Framework.

Member Type Documentation

typedef QAxBase::PropertyBag

A QMap<QString,QVariant> that can store properties as name:value pairs.

Property Documentation

control : QString

该属性保存这个QAxBase对象所封装COM对象的名称.

设置这个属性能初始化COM对象. 以前设置的任何COM对象将被关闭.

最高效的设置方法是使用注册组件的UUID, 例如

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

其次是使用注册控件的类名class name(with or without version number), 例如

    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}&

前两个模式能组合起来用, 例如初始化远程机器上的授权控件:

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

读control属性的函数始终返回控件的UUID, 可能包含了license key, 服务器名, 但不包含username, domain或password.

Access functions:

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

Member Function Documentation

QAxBase::QAxBase ( IUnknown * iface = 0 )

创建封装了COM对象iface的QAxBase对象. 若iface为0(缺省值), 要调用setControl()实例化一个COM对象.

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

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

参看clear().

QVariant QAxBase::asVariant () const

返回封装COM对象的QVariant. 该变量能被作为像dynamicCall()之类的参数使用.

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

断开并销毁COM对象.

若reimplement该函数则必须reimplement调用clear()的析构函数, 并在你的clear()函数结尾处调用该实现.

void QAxBase::disableClassInfo ()

不为ActiveX容器生成class info. 若不需要该ActiveX控件的任何class information, 使用该函数可以加速meta object的生成.

注意, 该函数必须在对象构造之后立即调用

void QAxBase::disableEventSink ()

不为ActiveX容器构建事件池. 若不需要监听ActiveX控件的事件, 可以使用该函数加速meta object生成.

连接到事件池时有些ActiveX控件可能会不稳定. 要获得OLE事件必须用标准COM方法注册你自己的事件池. 用queryInterface()获得原COM对象的访问权.

注意, 该函数要在对象构造之后立即调用.

void QAxBase::disableMetaObject ()

不为ActiveX容器生成meta object. 这样也不能生成事件池和class info. 若不需要使用Qt meta object实现, 调用该函数可以加速控件的实例化. 仍然可以用dynamicCall()调用对象, 但信号, 槽和属性将不可用.

使用OLE automation时有的控件可能会不稳定. 可以通过queryInterface()提供的COM接口调用标准COM方法来使用控件.

注意, 该函数必须在对象构造之后立即调用.

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 和 var8, 返回方法的返回值, 当方法不返回值或函数调用失败时返回无效的QVariant.

如果function是对象的一个方法, 该字符串必须提供完整的原型, 像它被写在QObject::connect()调用中那样.

    activeX->dynamicCall("Navigate(const QString&)", "www.trolltech.com");

此外还可以把被调用函数的参数嵌在字符串中, 上面的函数也可以像这样调用

    activeX->dynamicCall("Navigate(\"www.trolltech.com\")");

所有参数被作为字符串传递; 它依赖于控件能否正确解释它们, 这比用正确类型的参数调用函数原型要慢一些.

如果function是属性, 这个字符串必须是属性名. 当var1是一个有效的QVariant值时, 调用设置属性值的函数, 否则调用获取属性值的函数.

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

注意, 使用QObject::property()和QObject::setProperty()读取和设置属性速度更快一些.

dynamicCall()能调用没有元对象的封装器的对象, 这样能有效改善性能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对象.

若方法有传出参数时, vars中的QVariant对象会被更新.

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

使用OLE自动接口IDispatch调用对象过程中, COM对象抛出异常时发射该信号. code, source, desc 和 help 是COM服务器提供的异常相关信息及对最终用户有用的反馈. help包括帮助文件和the help context ID in brackets, 如"filename [id]".

QString QAxBase::generateDocumentation ()

返回一个包含所封装COM对象生成的文档的富文本串. 串可以转储为HTML文件, 或直接在例如QTextBrowser等部件中使用.

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

这个虚函数被setControl()调用, 创建请求的COM对象. ptr指向对象的IUnknown实现. 对象初始化成功返回true; 否则返回false.

缺省实现是解释control()返回的字串, 如果与某个模式匹配则调用initializeRemote(), initializeLicensed()或initializeActive(). 如果control()是一个存在的文件名,调用initializeFromFile(). 如果没有匹配的模式, 或者远程或授权初始化失败, 则直接调用CoCreateInstance创建对象.

参看属性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.

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

连接到当前机器上正在运行的一个实例, 把正在运行的实例的IUnknown接口返回到ptr中. 成功则函数返回true, 否则返回false.

若control string中包含"}&"子串则该函数在initialize()中被调用.

参看initialize().

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

创建control属性中文件名指定的COM对象, 并把对象的IUnknown接口返回给指针ptr. 成功则返回true, 否则返回false.

如果control string中有文件名, initialize()会调用该函数.

参看initialize().

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

创建一个授权控件的实例, 把对象的IUnknown接口返回给ptr. 成功则返回true否则false.

若control string中含有子串"}:"该函数会在initialize()中被调用. 子串后面应该跟上授权码.

参看initialize().

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

创建远程服务器上的实例, 把对象的IUnknown接口返回给ptr. 成功则返回true否则返回false.

若control string中包含子串"/{"则该函数被initialize()调用. 子串前面需要提供远程机器的信息.

参看initialize().

bool QAxBase::isNull () const

若封装器没有装载任何对象则返回true; 否则返回false.

参看control.

PropertyBag QAxBase::propertyBag () const

返回COM对象暴露出来的所有属性的name:value映射.

若COM对象支持属性包, 用该方法比逐个获取属性要高效的多.

注意: 不能保证COM对象实现的属性包返回了所有属性, 或返回的属性与通过IDispatch接口获得的一样.

参看setPropertyBag().

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

若COM对象支持property notification, 则属性name改变时, 该信号被发射.

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

若属性prop是可写的返回true; 否则返回false. 缺省时, 所有属性都是可写的.

注意: 这个设置依赖于控件的实现, 有些属性可能会忽略该设置.

参看setPropertyWritable()和propertyChanged().

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

从COM对象请求uuid并且把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() )

返回一个包装了COM对象的QAxObject对象的指针, 该对象有方法或属性name, 传递参数var1, var1, var2, var3, var4, var5, var6, var7和var8.

如果name是方法名, 字符串必须包含完整函数原型.

如果name是属性, 字符串必须是属性名, 并且var1, ... var8应被忽略.

返回的QAxObject是这个对象的child(它的类型是QAxObject或QAxWidget), 当这个对象被删除时它也被删除. 但自己手动删除返回的对象也是安全的, and you should do so when you iterate over lists of subobjects.

COM应用程序通常有一个发布它的某些元素作为dispatch interfaces的对象模型. 用这个方法可以操纵对象模型的层次, 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 )

这是为方便使用而重载的函数. 其本质行为和上面函数一样.

当方法有输出参数时vars中的QVariant对象会被更新.

void QAxBase::setPropertyBag ( const PropertyBag & bag )

把COM对象的属性设置为相应的值bag.

注意: 应该只设置propertyBag函数返回的属性包, 因为不能确保COM对象实现的属性包支持从IDispatch接口获得的属性

参看propertyBag().

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

若ok为true则把属性prop设置为可写的, 否则设置prop为只读. 默认所有属性可写.

注意: 这个设置依赖于控件的实现, 有的属性可能会忽略它.

参看propertyWritable()和propertyChanged().

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

当COM对象发出事件name时这个generic signal被发射. argc事件提供的参数个数(DISPPARAMS.cArgs), argv是指向参数值的指针(DISPPARAMS.rgvarg). 注意, 参数值的顺序被逆转, 也就是说, 数组的最后一个元素是函数的第一个参数.

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

当事件有不支持数据类型的参数时使用此信号. 否则, 直接连接到信号name.

QStringList QAxBase::verbs () const

返回COM对象能执行的动作列表. 如果对象没有实现IOleObject, 或不支持任何动作, 返回一个空stringlist.

注意, OLE缺省动作(OLEIVERB_SHOW etc)不被包括在清单中.

该函数是Qt 4.1中引入的.

原文链接：http://yanboo.ycool.com/post.987049.html