diff options
| author | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2011-11-08 12:31:36 -0600 |
|---|---|---|
| committer | Timothy Pearson <kb9vqf@pearsoncomputing.net> | 2011-11-08 12:31:36 -0600 |
| commit | d796c9dd933ab96ec83b9a634feedd5d32e1ba3f (patch) | |
| tree | 6e3dcca4f77e20ec8966c666aac7c35bd4704053 /doc/html/qaxbase.html | |
| download | tqt3-d796c9dd933ab96ec83b9a634feedd5d32e1ba3f.tar.gz tqt3-d796c9dd933ab96ec83b9a634feedd5d32e1ba3f.zip | |
Test conversion to TQt3 from Qt3 8c6fc1f8e35fd264dd01c582ca5e7549b32ab731
Diffstat (limited to 'doc/html/qaxbase.html')
| -rw-r--r-- | doc/html/qaxbase.html | 658 |
1 files changed, 658 insertions, 0 deletions
diff --git a/doc/html/qaxbase.html b/doc/html/qaxbase.html new file mode 100644 index 000000000..473d5cad2 --- /dev/null +++ b/doc/html/qaxbase.html @@ -0,0 +1,658 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/extensions/activeqt/container/qaxbase.cpp:556 --> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title>TQAxBase Class</title> +<style type="text/css"><!-- +fn { margin-left: 1cm; text-indent: -1cm; } +a:link { color: #004faf; text-decoration: none } +a:visited { color: #672967; text-decoration: none } +body { background: #ffffff; color: black; } +--></style> +</head> +<body> + +<table border="0" cellpadding="0" cellspacing="0" width="100%"> +<tr bgcolor="#E5E5E5"> +<td valign=center> + <a href="index.html"> +<font color="#004faf">Home</font></a> + | <a href="classes.html"> +<font color="#004faf">All Classes</font></a> + | <a href="mainclasses.html"> +<font color="#004faf">Main Classes</font></a> + | <a href="annotated.html"> +<font color="#004faf">Annotated</font></a> + | <a href="groups.html"> +<font color="#004faf">Grouped Classes</font></a> + | <a href="functions.html"> +<font color="#004faf">Functions</font></a> +</td> +<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>TQAxBase Class Reference<br><small>[<a href="qaxcontainer.html">TQAxContainer module</a>]</small></h1> + +<p>The TQAxBase class is an abstract class that provides an API +to initalize and access a COM object. +<a href="#details">More...</a> +<p>This class is part of the <b>TQt ActiveTQt Extension</b>. +<p><tt>#include <<a href="qaxbase-h.html">qaxbase.h</a>></tt> +<p>Inherited by <a href="qaxobject.html">TQAxObject</a> and <a href="qaxwidget.html">TQAxWidget</a>. +<p><a href="qaxbase-members.html">List of all member functions.</a> +<h2>Public Members</h2> +<ul> +<li class=fn><a href="#TQAxBase"><b>TQAxBase</b></a> ( IUnknown * iface = 0 )</li> +<li class=fn>virtual <a href="#~TQAxBase"><b>~TQAxBase</b></a> ()</li> +<li class=fn>TQString <a href="#control"><b>control</b></a> () const</li> +<li class=fn>long <a href="#queryInterface"><b>queryInterface</b></a> ( const TQUuid & uuid, void ** iface ) const</li> +<li class=fn>TQVariant <a href="#dynamicCall"><b>dynamicCall</b></a> ( const TQCString & function, const TQVariant & var1 = TQVariant ( ), const TQVariant & var2 = TQVariant ( ), const TQVariant & var3 = TQVariant ( ), const TQVariant & var4 = TQVariant ( ), const TQVariant & var5 = TQVariant ( ), const TQVariant & var6 = TQVariant ( ), const TQVariant & var7 = TQVariant ( ), const TQVariant & var8 = TQVariant ( ) )</li> +<li class=fn>TQVariant <a href="#dynamicCall-2"><b>dynamicCall</b></a> ( const TQCString & function, TQValueList<TQVariant> & vars )</li> +<li class=fn>TQAxObject * <a href="#querySubObject"><b>querySubObject</b></a> ( const TQCString & name, const TQVariant & var1 = TQVariant ( ), const TQVariant & var2 = TQVariant ( ), const TQVariant & var3 = TQVariant ( ), const TQVariant & var4 = TQVariant ( ), const TQVariant & var5 = TQVariant ( ), const TQVariant & var6 = TQVariant ( ), const TQVariant & var7 = TQVariant ( ), const TQVariant & var8 = TQVariant ( ) )</li> +<li class=fn>PropertyBag <a href="#propertyBag"><b>propertyBag</b></a> () const</li> +<li class=fn>void <a href="#setPropertyBag"><b>setPropertyBag</b></a> ( const PropertyBag & bag )</li> +<li class=fn>TQString <a href="#generateDocumentation"><b>generateDocumentation</b></a> ()</li> +<li class=fn>virtual bool <a href="#propertyWritable"><b>propertyWritable</b></a> ( const char * prop ) const</li> +<li class=fn>virtual void <a href="#setPropertyWritable"><b>setPropertyWritable</b></a> ( const char * prop, bool ok )</li> +<li class=fn>bool <a href="#isNull"><b>isNull</b></a> () const</li> +<li class=fn>TQVariant <a href="#asVariant"><b>asVariant</b></a> () const</li> +<li class=fn>enum <a href="#PropertyBag-enum"><b>PropertyBag</b></a> { }</li> +<li class=fn>virtual void <a href="#clear"><b>clear</b></a> ()</li> +<li class=fn>bool <a href="#setControl"><b>setControl</b></a> ( const TQString & )</li> +<li class=fn>void <a href="#disableMetaObject"><b>disableMetaObject</b></a> ()</li> +<li class=fn>void <a href="#disableClassInfo"><b>disableClassInfo</b></a> ()</li> +<li class=fn>void <a href="#disableEventSink"><b>disableEventSink</b></a> ()</li> +</ul> +<h2>Signals</h2> +<ul> +<li class=fn>void <a href="#signal"><b>signal</b></a> ( const TQString & name, int argc, void * argv )</li> +<li class=fn>void <a href="#propertyChanged"><b>propertyChanged</b></a> ( const TQString & name )</li> +<li class=fn>void <a href="#exception"><b>exception</b></a> ( int code, const TQString & source, const TQString & desc, const TQString & help )</li> +</ul> +<h2>Properties</h2> +<ul> +<li class=fn>TQString <a href="#control-prop"><b>control</b></a> - the name of the COM object wrapped by this TQAxBase object</li> +</ul> +<h2>Protected Members</h2> +<ul> +<li class=fn>virtual bool <a href="#initialize"><b>initialize</b></a> ( IUnknown ** ptr )</li> +<li class=fn>bool <a href="#initializeRemote"><b>initializeRemote</b></a> ( IUnknown ** ptr )</li> +<li class=fn>bool <a href="#initializeLicensed"><b>initializeLicensed</b></a> ( IUnknown ** ptr )</li> +<li class=fn>bool <a href="#initializeActive"><b>initializeActive</b></a> ( IUnknown ** ptr )</li> +</ul> +<hr><a name="details"></a><h2>Detailed Description</h2> +<p> This class is defined in the <b>TQt <a href="activeqt.html#ActiveTQt">ActiveTQt</a> Extension</b>, which can be found in the <tt>qt/extensions</tt> directory. It is not included in the main TQt API. +<p> + +<p> The TQAxBase class is an abstract class that provides an API +to initalize and access a COM object. + +<p> + +<p> TQAxBase is an abstract class that cannot be used directly, and is +instantiated through the subclasses <a href="qaxobject.html">TQAxObject</a> and <a href="qaxwidget.html">TQAxWidget</a>. 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 TQt properties and slots. +<p> <pre> + connect( buttonBack, SIGNAL(clicked()), webBrowser, SLOT(GoBack()) ); + </pre> + +<p> Properties exposed by the object's IDispatch implementation can be +read and written through the property system provided by the TQt +Object Model (both subclasses are TQObjects, so you can use <a href="qobject.html#setProperty">setProperty()</a> and <a href="qobject.html#property">property()</a> as with <a href="qobject.html">TQObject</a>). Properties +with multiple parameters are not supported. +<p> <pre> + activeX->setProperty( "text", "some text" ); + int value = activeX->property( "value" ); + </pre> + +<p> Write-functions for properties and other methods exposed by the +object's IDispatch implementation can be called directly using +<a href="#dynamicCall">dynamicCall</a>(), or indirectly as slots connected to a signal. +<p> <pre> + webBrowser->dynamicCall( "GoHome()" ); + </pre> + +<p> Outgoing events supported by the COM object are emitted as +standard TQt signals. +<p> <pre> + connect( webBrowser, SIGNAL(TitleChanged(const <a href="qstring.html">TQString</a>&)), + this, SLOT(setCaption(const <a href="qstring.html">TQString</a>&)) ); + </pre> + +<p> TQAxBase transparently converts between COM data types and the +equivalent TQt data types. Some COM types have no equivalent TQt data structure. +<p> Supported COM datatypes are listed in the first column of following table. +The second column is the TQt type that can be used with the <a href="qobject.html">TQObject</a> property +functions. The third column is the TQt type that is used in the prototype of +generated signals and slots for in-parameters, and the last column is the TQt +type that is used in the prototype of signals and slots for out-parameters. +<center><table cellpadding="4" cellspacing="2" border="0"> +<tr bgcolor="#a2c511"> +<th valign="top">COM type +<th valign="top">TQt property +<th valign="top">in-parameter +<th valign="top">out-parameter +<tr bgcolor="#f0f0f0"> +<td valign="top">VARIANT_BOOL +<td valign="top">bool +<td valign="top">bool +<td valign="top">bool& +<tr bgcolor="#d0d0d0"> +<td valign="top">BSTR +<td valign="top">TQString +<td valign="top">const <a href="qstring.html">TQString</a>& +<td valign="top">TQString& +<tr bgcolor="#f0f0f0"> +<td valign="top">char, short, int, long +<td valign="top">int +<td valign="top">int +<td valign="top">int& +<tr bgcolor="#d0d0d0"> +<td valign="top">uchar, ushort, uint, ulong +<td valign="top">uint +<td valign="top">uint +<td valign="top">uint& +<tr bgcolor="#f0f0f0"> +<td valign="top">float, double +<td valign="top">double +<td valign="top">double +<td valign="top">double& +<tr bgcolor="#d0d0d0"> +<td valign="top">DATE +<td valign="top">TQDateTime +<td valign="top">const <a href="qdatetime.html">TQDateTime</a>& +<td valign="top">TQDateTime& +<tr bgcolor="#f0f0f0"> +<td valign="top">CY +<td valign="top">Q_LLONG +<td valign="top">Q_LLONG +<td valign="top">Q_LLONG& +<tr bgcolor="#d0d0d0"> +<td valign="top">OLE_COLOR +<td valign="top">TQColor +<td valign="top">const <a href="qcolor.html">TQColor</a>& +<td valign="top">TQColor& +<tr bgcolor="#f0f0f0"> +<td valign="top">SAFEARRAY(VARIANT) +<td valign="top">TQValueList<TQVariant> +<td valign="top">const <a href="qvaluelist.html">TQValueList</a><TQVariant>& +<td valign="top">TQValueList<TQVariant>& +<tr bgcolor="#d0d0d0"> +<td valign="top">SAFEARRAY(BYTE) +<td valign="top">TQByteArray +<td valign="top">const <a href="qbytearray.html">TQByteArray</a>& +<td valign="top">TQByteArray& +<tr bgcolor="#f0f0f0"> +<td valign="top">SAFEARRAY(BSTR) +<td valign="top">TQStringList +<td valign="top">const <a href="qstringlist.html">TQStringList</a>& +<td valign="top">TQStringList& +<tr bgcolor="#d0d0d0"> +<td valign="top">VARIANT +<td valign="top">type-dependent +<td valign="top">const <a href="qvariant.html">TQVariant</a>& +<td valign="top">TQVariant& +<tr bgcolor="#f0f0f0"> +<td valign="top">IFontDisp* +<td valign="top">TQFont +<td valign="top">const <a href="qfont.html">TQFont</a>& +<td valign="top">TQFont& +<tr bgcolor="#d0d0d0"> +<td valign="top">IPictureDisp* +<td valign="top">TQPixmap +<td valign="top">const <a href="qpixmap.html">TQPixmap</a>& +<td valign="top">TQPixmap& +<tr bgcolor="#f0f0f0"> +<td valign="top">IDispatch* +<td valign="top">TQAxObject* (read-only) +<td valign="top"><a href="#asVariant">TQAxBase::asVariant</a>() +<td valign="top">TQAxObject* (return value) +<tr bgcolor="#d0d0d0"> +<td valign="top">IUnknown* +<td valign="top">TQAxObject* (read-only) +<td valign="top"><a href="#asVariant">TQAxBase::asVariant</a>() +<td valign="top">TQAxObject* (return value) +<tr bgcolor="#f0f0f0"> +<td valign="top">SCODE, DECIMAL +<td valign="top"><em>unsupported</em> +<td valign="top"><em>unsupported</em> +<td valign="top"><em>unsupported</em> +</table></center> +<p> Supported are also enumerations, and typedefs to supported types. +<p> To call the methods of a COM interface described by the following IDL +<pre> + 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 ); + }; + </pre> + +use the TQAxBase API like this: +<pre> + <a href="qaxobject.html">TQAxObject</a> object( "<CLSID>" ); + + <a href="qstring.html">TQString</a> text = object.<a href="qobject.html#property">property</a>( "text" ).toString(); + object.<a href="qobject.html#setProperty">setProperty</a>( "font", TQFont( "Times New Roman", 12 ) ); + + connect( this, SIGNAL(clicked(int)), &object, SLOT(showColumn(int)) ); + bool ok = object.<a href="#dynamicCall">dynamicCall</a>( "addColumn(const <a href="qstring.html">TQString</a>&)", "Column 1" ).toBool(); + + <a href="qvaluelist.html">TQValueList</a><TQVariant> varlist; + <a href="qvaluelist.html">TQValueList</a><TQVariant> parameters; + parameters << TQVariant( varlist ); + int n = object.<a href="#dynamicCall">dynamicCall</a>( "fillList(TQValueList<TQVariant>&)", parameters ).toInt(); + + <a href="qaxobject.html">TQAxObject</a> *item = object.querySubItem( "item(int)", 5 ); + </pre> + +<p> Note that the <a href="qvaluelist.html">TQValueList</a> the object should fill has to be provided as an +element in the parameter list of TQVariants. +<p> 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 <a href="#queryInterface">queryInterface</a>(). +<p> <pre> + IUnknown *iface = 0; + activeX->queryInterface( IID_IUnknown, (void**)&iface ); + if ( iface ) { + // use the interface + iface->Release(); + } + </pre> + +<p> 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. +<p> 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. + +<hr><h2>Member Type Documentation</h2> +<h3 class=fn><a name="PropertyBag-enum"></a>TQAxBase::PropertyBag</h3> + +<p> A <a href="qmap.html">TQMap</a><TQString,TQVariant> that can store properties as name:value pairs. + +<hr><h2>Member Function Documentation</h2> +<h3 class=fn><a name="TQAxBase"></a>TQAxBase::TQAxBase ( IUnknown * iface = 0 ) +</h3> +Creates a TQAxBase object that wraps the COM object <em>iface</em>. If <em>iface</em> is 0 (the default), use <a href="#setControl">setControl</a>() to instantiate a COM +object. + +<h3 class=fn><a name="~TQAxBase"></a>TQAxBase::~TQAxBase ()<tt> [virtual]</tt> +</h3> +Shuts down the COM object and destroys the TQAxBase object. +<p> <p>See also <a href="#clear">clear</a>(). + +<h3 class=fn><a href="qvariant.html">TQVariant</a> <a name="asVariant"></a>TQAxBase::asVariant () const +</h3> +Returns a <a href="qvariant.html">TQVariant</a> that wraps the COM object. The variant can +then be used as a parameter in e.g. <a href="#dynamicCall">dynamicCall</a>(). + +<h3 class=fn>void <a name="clear"></a>TQAxBase::clear ()<tt> [virtual]</tt> +</h3> +Disconnects and destroys the COM object. +<p> If you reimplement this function you must also reimplement the +destructor to call <a href="#clear">clear</a>(), and call this implementation at the +end of your clear() function. + +<h3 class=fn><a href="qstring.html">TQString</a> <a name="control"></a>TQAxBase::control () const +</h3><p>Returns the name of the COM object wrapped by this TQAxBase object. +See the <a href="qaxbase.html#control-prop">"control"</a> property for details. +<h3 class=fn>void <a name="disableClassInfo"></a>TQAxBase::disableClassInfo () +</h3> +Disables the class info generation for this ActiveX container. If +you don't retquire any class information about the ActiveX control +use this function to speed up the <a href="metaobjects.html#meta-object">meta object</a> generation. +<p> Note that this function must be called immediately after +construction of the object (without passing an object identifier), +and before calling <a href="qaxwidget.html">TQAxWidget</a>->setControl(). + +<h3 class=fn>void <a name="disableEventSink"></a>TQAxBase::disableEventSink () +</h3> +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 <a href="metaobjects.html#meta-object">meta object</a> generation. +<p> 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 <a href="#queryInterface">queryInterface</a>() to get access +to the raw COM object. +<p> Note that this function should be called immediately after +construction of the object (without passing an object identifier), +and before calling <a href="qaxwidget.html">TQAxWidget</a>->setControl(). + +<h3 class=fn>void <a name="disableMetaObject"></a>TQAxBase::disableMetaObject () +</h3> +Disables the <a href="metaobjects.html#meta-object">meta object</a> generation for this ActiveX container. +This also disables the event sink and class info generation. If +you don't intend to use the TQt meta object implementation call +this function to speed up the meta object generation. +<p> 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 <a href="#queryInterface">queryInterface</a>(). +<p> Note that this function must be called immediately after +construction of the object (without passing an object identifier), +and before calling <a href="qaxwidget.html">TQAxWidget</a>->setControl(). + +<h3 class=fn><a href="qvariant.html">TQVariant</a> <a name="dynamicCall"></a>TQAxBase::dynamicCall ( const <a href="qcstring.html">TQCString</a> & function, const <a href="qvariant.html">TQVariant</a> & var1 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var2 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var3 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var4 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var5 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var6 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var7 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var8 = TQVariant ( ) ) +</h3> +Calls the COM object's method <em>function</em>, passing the +parameters <em>var1</em>, <em>var1</em>, <em>var2</em>, <em>var3</em>, <em>var4</em>, <em>var5</em>, +<em>var6</em>, <em>var7</em> and <em>var8</em>, and returns the value returned by +the method, or an invalid <a href="qvariant.html">TQVariant</a> if the method does not return +a value or when the function call failed. +<p> If <em>function</em> is a method of the object the string must be provided +as the full prototype, for example as it would be written in a +<a href="qobject.html#connect">TQObject::connect</a>() call. +<pre> + activeX->dynamicCall( "Navigate(const <a href="qstring.html">TQString</a>&)", "www.trolltech.com" ); + </pre> + +<p> Alternatively a function can be called passing the parameters embedded +in the string, e.g. above function can also be invoked using +<pre> + activeX->dynamicCall("Navigate(\"www.trolltech.com\"); + </pre> + +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. +<p> If <em>function</em> is a property the string has to be the name of the +property. The property setter is called when <em>var1</em> is a valid TQVariant, +otherwise the getter is called. +<pre> + activeX->dynamicCall( "Value", 5 ); + <a href="qstring.html">TQString</a> text = activeX->dynamicCall( "Text" ).toString(); + </pre> + +Note that it is faster to get and set properties using +<a href="qobject.html#property">TQObject::property</a>() and <a href="qobject.html#setProperty">TQObject::setProperty</a>(). +<p> It is only possible to call functions through <a href="#dynamicCall">dynamicCall</a>() that +have parameters or return values of datatypes supported by +<a href="qvariant.html">TQVariant</a>. See the TQAxBase 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 +<a href="#queryInterface">queryInterface</a>() to retrieve the appropriate COM interface, and +use the function directly. +<p> <pre> + IWebBrowser2 *webBrowser = 0; + activeX->queryInterface( IID_IWebBrowser2, (void**)&webBrowser ); + if ( webBrowser ) { + webBrowser->Navigate2( pvarURL ); + webBrowser->Release(); + } + </pre> + +<p> This is also more efficient. + +<p>Example: <a href="qaxcontainer-example-qutlook.html#x2720">qutlook/centralwidget.cpp</a>. +<h3 class=fn><a href="qvariant.html">TQVariant</a> <a name="dynamicCall-2"></a>TQAxBase::dynamicCall ( const <a href="qcstring.html">TQCString</a> & function, <a href="qvaluelist.html">TQValueList</a><TQVariant> & vars ) +</h3> +This is an overloaded member function, provided for convenience. It behaves essentially like the above function. +<p> Calls the COM object's method <em>function</em>, passing the +parameters in <em>vars</em>, 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 +<a href="qvariant.html">TQVariant</a> object. +<p> The TQVariant objects in <em>vars</em> are updated when the method has +out-parameters. + +<h3 class=fn>void <a name="exception"></a>TQAxBase::exception ( int code, const <a href="qstring.html">TQString</a> & source, const <a href="qstring.html">TQString</a> & desc, const <a href="qstring.html">TQString</a> & help )<tt> [signal]</tt> +</h3> + +<p> This signal is emitted when the COM object throws an exception while called using the OLE automation +interface IDispatch. <em>code</em>, <em>source</em>, <em>desc</em> and <em>help</em> provide information about the exception as +provided by the COM server and can be used to provide useful feedback to the end user. <em>help</em> includes +the help file, and the help context ID in brackets, e.g. "filename [id]". + +<h3 class=fn><a href="qstring.html">TQString</a> <a name="generateDocumentation"></a>TQAxBase::generateDocumentation () +</h3> + +<p> 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 <a href="qtextbrowser.html">TQTextBrowser</a> widget. + +<h3 class=fn>bool <a name="initialize"></a>TQAxBase::initialize ( IUnknown ** ptr )<tt> [virtual protected]</tt> +</h3> +This virtual function is called by <a href="#setControl">setControl</a>() and creates the +requested COM object. <em>ptr</em> is set to the object's IUnknown +implementation. The function returns TRUE if the object +initialization succeeded; otherwise the function returns FALSE. +<p> The default implementation interprets the string returned by +<a href="#control">control</a>(), and calls <a href="#initializeRemote">initializeRemote</a>(), <a href="#initializeLicensed">initializeLicensed</a>() +or <a href="#initializeActive">initializeActive</a>() 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. +<p> See the <a href="#control-prop">control</a> property documentation for details about +supported patterns. +<p> The interface returned in <em>ptr</em> 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. + +<h3 class=fn>bool <a name="initializeActive"></a>TQAxBase::initializeActive ( IUnknown ** ptr )<tt> [protected]</tt> +</h3> +Returns an active instance running on the current machine, and returns the +IUnknown interface to the running object in <em>ptr</em>. This function returns TRUE +if successful, otherwise returns FALSE. +<p> This function is called by <a href="#initialize">initialize</a>() if the control string contains the +substring "}&". +<p> <p>See also <a href="#initialize">initialize</a>(). + +<h3 class=fn>bool <a name="initializeLicensed"></a>TQAxBase::initializeLicensed ( IUnknown ** ptr )<tt> [protected]</tt> +</h3> +Creates an instance of a licensed control, and returns the IUnknown interface +to the object in <em>ptr</em>. This functions returns TRUE if successful, otherwise +returns FALSE. +<p> This function is called by <a href="#initialize">initialize</a>() if the control string contains the +substring "}:". The license key needs to follow this substring. +<p> <p>See also <a href="#initialize">initialize</a>(). + +<h3 class=fn>bool <a name="initializeRemote"></a>TQAxBase::initializeRemote ( IUnknown ** ptr )<tt> [protected]</tt> +</h3> +Creates the instance on a remote server, and returns the IUnknown interface +to the object in <em>ptr</em>. This function returns TRUE if successful, otherwise +returns FALSE. +<p> This function is called by <a href="#initialize">initialize</a>() if the control string contains the +substring "/{". The information about the remote machine needs to be provided +in front of the substring. +<p> <p>See also <a href="#initialize">initialize</a>(). + +<h3 class=fn>bool <a name="isNull"></a>TQAxBase::isNull () const +</h3> +Returns TRUE if there is no COM object loaded by this wrapper; +otherwise return FALSE. +<p> <p>See also <a href="#control-prop">control</a>. + +<h3 class=fn><a href="qaxbase.html#PropertyBag-enum">PropertyBag</a> <a name="propertyBag"></a>TQAxBase::propertyBag () const +</h3> +Returns a name:value map of all the properties exposed by the COM +object. +<p> This is more efficient than getting multiple properties +individually if the COM object supports property bags. +<p> <b>Warning:</b> 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. + +<h3 class=fn>void <a name="propertyChanged"></a>TQAxBase::propertyChanged ( const <a href="qstring.html">TQString</a> & name )<tt> [signal]</tt> +</h3> + +<p> If the COM object supports property notification, this signal gets +emitted when the property called <em>name</em> is changed. + +<h3 class=fn>bool <a name="propertyWritable"></a>TQAxBase::propertyWritable ( const char * prop ) const<tt> [virtual]</tt> +</h3> +Returns TRUE if the property <em>prop</em> is writable; otherwise +returns FALSE. By default, all properties are writable. +<p> <b>Warning:</b> +Depending on the control implementation this setting might be +ignored for some properties. +<p> <p>See also <a href="#setPropertyWritable">setPropertyWritable</a>() and <a href="#propertyChanged">propertyChanged</a>(). + +<h3 class=fn>long <a name="queryInterface"></a>TQAxBase::queryInterface ( const <a href="quuid.html">TQUuid</a> & uuid, void ** iface ) const +</h3> +Requests the interface <em>uuid</em> from the COM object and sets the +value of <em>iface</em> to the provided interface, or to 0 if the +requested interface could not be provided. +<p> Returns the result of the QueryInterface implementation of the COM object. +<p> <p>See also <a href="#control-prop">control</a>. + +<h3 class=fn><a href="qaxobject.html">TQAxObject</a> * <a name="querySubObject"></a>TQAxBase::querySubObject ( const <a href="qcstring.html">TQCString</a> & name, const <a href="qvariant.html">TQVariant</a> & var1 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var2 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var3 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var4 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var5 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var6 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var7 = TQVariant ( ), const <a href="qvariant.html">TQVariant</a> & var8 = TQVariant ( ) ) +</h3> +Returns a pointer to a <a href="qaxobject.html">TQAxObject</a> wrapping the COM object provided +by the method or property <em>name</em>, passing passing the parameters +<em>var1</em>, <em>var1</em>, <em>var2</em>, <em>var3</em>, <em>var4</em>, <em>var5</em>, <em>var6</em>, +<em>var7</em> and <em>var8</em>. +<p> If <em>name</em> is provided by a method the string must include the +full function prototype. +<p> If <em>name</em> is a property the string must be the name of the property, +and <em>var1</em>, ... <em>var8</em> are ignored. +<p> The returned TQAxObject is a child of this object (which is either of +type TQAxObject or <a href="qaxwidget.html">TQAxWidget</a>), 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. +<p> 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. +<p> <pre> + <a href="qaxwidget.html">TQAxWidget</a> outlook( "Outlook.Application" ); + <a href="qaxobject.html">TQAxObject</a> *session = outlook.<a href="#querySubObject">querySubObject</a>( "Session" ); + if ( session ) { + <a href="qaxobject.html">TQAxObject</a> *defFolder = session-><a href="#querySubObject">querySubObject</a>( + "GetDefaultFolder(OlDefaultFolders)", + "olFolderContacts" ); + //... + } + </pre> + + +<p>Example: <a href="qaxcontainer-example-qutlook.html#x2721">qutlook/centralwidget.cpp</a>. +<h3 class=fn>bool <a name="setControl"></a>TQAxBase::setControl ( const <a href="qstring.html">TQString</a> & ) +</h3><p>Sets the name of the COM object wrapped by this TQAxBase object. +See the <a href="qaxbase.html#control-prop">"control"</a> property for details. +<h3 class=fn>void <a name="setPropertyBag"></a>TQAxBase::setPropertyBag ( const <a href="qaxbase.html#PropertyBag-enum">PropertyBag</a> & bag ) +</h3> +Sets the properties of the COM object to the corresponding values +in <em>bag</em>. +<p> <b>Warning:</b> +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. +<p> <p>See also <a href="#propertyBag">propertyBag</a>(). + +<h3 class=fn>void <a name="setPropertyWritable"></a>TQAxBase::setPropertyWritable ( const char * prop, bool ok )<tt> [virtual]</tt> +</h3> +Sets the property <em>prop</em> to writable if <em>ok</em> is TRUE, otherwise +sets <em>prop</em> to be read-only. By default, all properties are +writable. +<p> <b>Warning:</b> +Depending on the control implementation this setting might be +ignored for some properties. +<p> <p>See also <a href="#propertyWritable">propertyWritable</a>() and <a href="#propertyChanged">propertyChanged</a>(). + +<h3 class=fn>void <a name="signal"></a>TQAxBase::signal ( const <a href="qstring.html">TQString</a> & name, int argc, void * argv )<tt> [signal]</tt> +</h3> + +<p> This generic signal gets emitted when the COM object issues the +event <em>name</em>. <em>argc</em> is the number of parameters provided by the +event (DISPPARAMS.cArgs), and <em>argv</em> 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. +<p> <pre> + void Receiver::slot( const <a href="qstring.html">TQString</a> &name, int argc, void *argv ) + { + VARIANTARG *params = (VARIANTARG*)argv; + if ( name.<a href="qstring.html#startsWith">startsWith</a>( "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; + } + } + </pre> + +<p> Use this signal if the event has parameters of unsupported data +types. Otherwise, connect directly to the signal <em>name</em>. + +<hr><h2>Property Documentation</h2> +<h3 class=fn><a href="qstring.html">TQString</a> <a name="control-prop"></a>control</h3> +<p>This property holds the name of the COM object wrapped by this TQAxBase object. +<p>Setting this property initilializes the COM object. Any COM object +previously set is shut down. +<p> The most efficient way to set this property is by using the +registered component's UUID, e.g. +<pre> + ctrl->setControl( "{8E27C92B-1264-101C-8A2F-040224009C02}" ); + </pre> + +The second fastest way is to use the registered control's class +name (with or without version number), e.g. +<pre> + ctrl->setControl( "MSCal.Calendar" ); + </pre> + +The slowest, but easiest way to use is to use the control's full +name, e.g. +<pre> + ctrl->setControl( "Calendar Control 9.0" ); + </pre> + +<p> 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: +<ul> +<li> To initialize the control on a different machine use the following +pattern: +<pre> + <domain/username>:<password>@server/{8E27C92B-1264-101C-8A2F-040224009C02} + </pre> + +<li> To initialize a licensed control use the following pattern: +<pre> + {8E27C92B-1264-101C-8A2F-040224009C02}:<LicenseKey> + </pre> + +<li> To connect to an already running object use the following pattern: +<pre> + {8E27C92B-1264-101C-8A2F-040224009C02}& + </pre> + +</ul> +The first two patterns can be combined, e.g. to initialize a licensed +control on a remote machine: +<pre> + ctrl->setControl("DOMAIN/user:password@server/{8E27C92B-1264-101C-8A2F-040224009C02}:LicenseKey"); + </pre> + +<p> 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. + +<p>Set this property's value with <a href="#setControl">setControl</a>() and get this property's value with <a href="#control">control</a>(). +<!-- eof --> +<hr><p> +This file is part of the <a href="index.html">TQt toolkit</a>. +Copyright © 1995-2007 +<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center> +<table width=100% cellspacing=0 border=0><tr> +<td>Copyright © 2007 +<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a> +<td align=right><div align=right>TQt 3.3.8</div> +</table></div></address></body> +</html> |