From bd0f3345a938b35ce6a12f6150373b0955b8dd12 Mon Sep 17 00:00:00 2001 From: Timothy Pearson Date: Sun, 10 Jul 2011 15:24:15 -0500 Subject: Add Qt3 development HEAD version --- doc/html/qaxbase.html | 658 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 658 insertions(+) create mode 100644 doc/html/qaxbase.html (limited to 'doc/html/qaxbase.html') diff --git a/doc/html/qaxbase.html b/doc/html/qaxbase.html new file mode 100644 index 0000000..95ef8ba --- /dev/null +++ b/doc/html/qaxbase.html @@ -0,0 +1,658 @@ + + + + + +QAxBase Class + + + + + + + +
+ +Home + | +All Classes + | +Main Classes + | +Annotated + | +Grouped Classes + | +Functions +

QAxBase Class Reference
[QAxContainer module]

+ +

The QAxBase class is an abstract class that provides an API +to initalize and access a COM object. +More... +

This class is part of the Qt ActiveQt Extension. +

#include <qaxbase.h> +

Inherited by QAxObject and QAxWidget. +

List of all member functions. +

Public Members

+ +

Signals

+ +

Properties

+ +

Protected Members

+ +

Detailed Description

+

This class is defined in the Qt ActiveQt Extension, which can be found in the qt/extensions directory. It is not included in the main Qt API. +

+ +

The QAxBase class is an abstract class that provides an API +to initalize and access a COM object. + +

+ +

QAxBase is an abstract class that cannot be used directly, and is +instantiated through the subclasses QAxObject and QAxWidget. This +class provides the API to access the COM object directly +through its IUnknown implementation. If the COM object implements +the IDispatch interface, the properties and methods of that object +become available as Qt properties and slots. +

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

Properties exposed by the object's IDispatch implementation can be +read and written through the property system provided by the Qt +Object Model (both subclasses are QObjects, so you can use setProperty() and property() as with QObject). Properties +with multiple parameters are not supported. +

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

Write-functions for properties and other methods exposed by the +object's IDispatch implementation can be called directly using +dynamicCall(), or indirectly as slots connected to a signal. +

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

Outgoing events supported by the COM object are emitted as +standard Qt signals. +

+    connect( webBrowser, SIGNAL(TitleChanged(const QString&)),
+             this, SLOT(setCaption(const 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 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 +Q_LLONG +Q_LLONG +Q_LLONG& +
OLE_COLOR +QColor +const QColor& +QColor& +
SAFEARRAY(VARIANT) +QValueList<QVariant> +const QValueList<QVariant>& +QValueList<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* (read-only) +QAxBase::asVariant() +QAxObject* (return value) +
IUnknown* +QAxObject* (read-only) +QAxBase::asVariant() +QAxObject* (return value) +
SCODE, DECIMAL +unsupported +unsupported +unsupported +
+

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 );
+    };
+
+ +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();
+
+    QValueList<QVariant> varlist;
+    QValueList<QVariant> parameters;
+    parameters << QVariant( varlist );
+    int n = object.dynamicCall( "fillList(QValueList<QVariant>&)", parameters ).toInt();
+
+    QAxObject *item = object.querySubItem( "item(int)", 5 );
+
+ +

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

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

Member Type Documentation

+

QAxBase::PropertyBag

+ +

A QMap that can store properties as name:value pairs. + +

Member Function Documentation

+

QAxBase::QAxBase ( IUnknown * iface = 0 ) +

+Creates a QAxBase object that wraps the COM object iface. If iface is 0 (the default), use setControl() to instantiate a COM +object. + +

QAxBase::~QAxBase () [virtual] +

+Shuts down the COM object and destroys the QAxBase object. +

See also clear(). + +

QVariant QAxBase::asVariant () const +

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

void QAxBase::clear () [virtual] +

+Disconnects and destroys the COM object. +

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

QString QAxBase::control () const +

Returns the name of the COM object wrapped by this QAxBase object. +See the "control" property for details. +

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 (without passing an object identifier), +and before calling QAxWidget->setControl(). + +

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 (without passing an object identifier), +and before calling QAxWidget->setControl(). + +

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 the meta object generation. +

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 (without passing an object identifier), +and before calling QAxWidget->setControl(). + +

QVariant QAxBase::dynamicCall ( const QCString & 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. +

If 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() call. +

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

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.trolltech.com\");
+
+ +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. +

If function is a property the string has to be the name of the +property. The property setter is called when var1 is a valid 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() and QObject::setProperty(). +

It is only possible to call functions through dynamicCall() that +have parameters or return values of datatypes supported by +QVariant. See the 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. + +

Example: qutlook/centralwidget.cpp. +

QVariant QAxBase::dynamicCall ( const QCString & function, QValueList<QVariant> & vars ) +

+This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +

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 object. +

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

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

+ +

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 widget. + +

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

+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() +or initializeActive() if the string matches the respective +patterns. If no pattern is matched, or if remote or licensed +initialization fails, CoCreateInstance is used directly to create +the object. +

See the 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. + +

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

+Returns 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. +

This function is called by initialize() if the control string contains the +substring "}&". +

See also initialize(). + +

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

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

This function is called by initialize() if the control string contains the +substring "}:". The license key needs to follow this substring. +

See also initialize(). + +

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

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

This function is called by initialize() if the control string contains the +substring "/{". The information about the remote machine needs to be provided +in front of the substring. +

See also initialize(). + +

bool QAxBase::isNull () const +

+Returns TRUE if there is no COM object loaded by this wrapper; +otherwise return FALSE. +

See also 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. +

Warning: 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. + +

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

+ +

If the COM object supports property notification, this signal gets +emitted when the property called name is changed. + +

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

+Returns TRUE if the property prop is writable; otherwise +returns FALSE. By default, all properties are writable. +

Warning: +Depending on the control implementation this setting might be +ignored for some properties. +

See also setPropertyWritable() and 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. +

See also control. + +

QAxObject * QAxBase::querySubObject ( const QCString & 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 ( ) ) +

+Returns a pointer to a 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. +

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

If name is a property the string must be the name of the property, +and var1, ... var8 are ignored. +

The returned 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" );
+        //...
+    }
+
+ + +

Example: qutlook/centralwidget.cpp. +

bool QAxBase::setControl ( const QString & ) +

Sets the name of the COM object wrapped by this QAxBase object. +See the "control" property for details. +

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

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

Warning: +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. +

See also propertyBag(). + +

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

+Sets the property prop to writable if ok is TRUE, otherwise +sets prop to be read-only. By default, all properties are +writable. +

Warning: +Depending on the control implementation this setting might be +ignored for some properties. +

See also propertyWritable() and propertyChanged(). + +

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

+ +

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

Property Documentation

+

QString control

+

This property holds the name of the COM object wrapped by this QAxBase object. +

Setting this property initilializes the COM object. Any COM object +previously set is shut down. +

The most efficient way to set this property is by using the +registered component's UUID, e.g. +

+    ctrl->setControl( "{8E27C92B-1264-101C-8A2F-040224009C02}" );
+
+ +The second fastest way is to use the registered control's class +name (with or without version number), e.g. +
+    ctrl->setControl( "MSCal.Calendar" );
+
+ +The slowest, but easiest way to use is to use the control's full +name, e.g. +
+    ctrl->setControl( "Calendar Control 9.0" );
+
+ +

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: +

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

Set this property's value with setControl() and get this property's value with control(). + +

+This file is part of the Qt toolkit. +Copyright © 1995-2007 +Trolltech. All Rights Reserved.

+ +
Copyright © 2007 +TrolltechTrademarks +
Qt 3.3.8
+
+ -- cgit v1.2.1