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
{
特性：
    [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 )