source: trunk/doc/html/qaxbase.html

Last change on this file was 190, checked in by rudi, 14 years ago

reference documentation added
File size: 35.2 KB
RevLine 
[190]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<!-- /home/espenr/tmp/qt-3.3.8-espenr-2499/qt-x11-free-3.3.8/extensions/activeqt/container/qaxbase.cpp:556 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QAxBase Class</title>
7<style type="text/css"><!--
8fn { margin-left: 1cm; text-indent: -1cm; }
9a:link { color: #004faf; text-decoration: none }
10a:visited { color: #672967; text-decoration: none }
11body { background: #ffffff; color: black; }
12--></style>
13</head>
14<body>
15
16<table border="0" cellpadding="0" cellspacing="0" width="100%">
17<tr bgcolor="#E5E5E5">
18<td valign=center>
19 <a href="index.html">
20<font color="#004faf">Home</font></a>
21 | <a href="classes.html">
22<font color="#004faf">All&nbsp;Classes</font></a>
23 | <a href="mainclasses.html">
24<font color="#004faf">Main&nbsp;Classes</font></a>
25 | <a href="annotated.html">
26<font color="#004faf">Annotated</font></a>
27 | <a href="groups.html">
28<font color="#004faf">Grouped&nbsp;Classes</font></a>
29 | <a href="functions.html">
30<font color="#004faf">Functions</font></a>
31</td>
32<td align="right" valign="center"><img src="logo32.png" align="right" width="64" height="32" border="0"></td></tr></table><h1 align=center>QAxBase Class Reference<br><small>[<a href="qaxcontainer.html">QAxContainer module</a>]</small></h1>
33
34<p>The QAxBase class is an abstract class that provides an API
35to initalize and access a COM object.
36<a href="#details">More...</a>
37<p>This class is part of the <b>Qt ActiveQt Extension</b>.
38<p><tt>#include &lt;<a href="qaxbase-h.html">qaxbase.h</a>&gt;</tt>
39<p>Inherited by <a href="qaxobject.html">QAxObject</a> and <a href="qaxwidget.html">QAxWidget</a>.
40<p><a href="qaxbase-members.html">List of all member functions.</a>
41<h2>Public Members</h2>
42<ul>
43<li class=fn><a href="#QAxBase"><b>QAxBase</b></a> ( IUnknown&nbsp;*&nbsp;iface = 0 )</li>
44<li class=fn>virtual <a href="#~QAxBase"><b>~QAxBase</b></a> ()</li>
45<li class=fn>QString <a href="#control"><b>control</b></a> () const</li>
46<li class=fn>long <a href="#queryInterface"><b>queryInterface</b></a> ( const&nbsp;QUuid&nbsp;&amp;&nbsp;uuid, void&nbsp;**&nbsp;iface ) const</li>
47<li class=fn>QVariant <a href="#dynamicCall"><b>dynamicCall</b></a> ( const&nbsp;QCString&nbsp;&amp;&nbsp;function, const&nbsp;QVariant&nbsp;&amp;&nbsp;var1 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var2 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var3 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var4 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var5 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var6 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var7 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var8 = QVariant ( ) )</li>
48<li class=fn>QVariant <a href="#dynamicCall-2"><b>dynamicCall</b></a> ( const&nbsp;QCString&nbsp;&amp;&nbsp;function, QValueList&lt;QVariant&gt;&nbsp;&amp;&nbsp;vars )</li>
49<li class=fn>QAxObject * <a href="#querySubObject"><b>querySubObject</b></a> ( const&nbsp;QCString&nbsp;&amp;&nbsp;name, const&nbsp;QVariant&nbsp;&amp;&nbsp;var1 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var2 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var3 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var4 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var5 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var6 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var7 = QVariant ( ), const&nbsp;QVariant&nbsp;&amp;&nbsp;var8 = QVariant ( ) )</li>
50<li class=fn>PropertyBag <a href="#propertyBag"><b>propertyBag</b></a> () const</li>
51<li class=fn>void <a href="#setPropertyBag"><b>setPropertyBag</b></a> ( const&nbsp;PropertyBag&nbsp;&amp;&nbsp;bag )</li>
52<li class=fn>QString <a href="#generateDocumentation"><b>generateDocumentation</b></a> ()</li>
53<li class=fn>virtual bool <a href="#propertyWritable"><b>propertyWritable</b></a> ( const&nbsp;char&nbsp;*&nbsp;prop ) const</li>
54<li class=fn>virtual void <a href="#setPropertyWritable"><b>setPropertyWritable</b></a> ( const&nbsp;char&nbsp;*&nbsp;prop, bool&nbsp;ok )</li>
55<li class=fn>bool <a href="#isNull"><b>isNull</b></a> () const</li>
56<li class=fn>QVariant <a href="#asVariant"><b>asVariant</b></a> () const</li>
57<li class=fn>enum <a href="#PropertyBag-enum"><b>PropertyBag</b></a> { }</li>
58<li class=fn>virtual void <a href="#clear"><b>clear</b></a> ()</li>
59<li class=fn>bool <a href="#setControl"><b>setControl</b></a> ( const QString &amp; )</li>
60<li class=fn>void <a href="#disableMetaObject"><b>disableMetaObject</b></a> ()</li>
61<li class=fn>void <a href="#disableClassInfo"><b>disableClassInfo</b></a> ()</li>
62<li class=fn>void <a href="#disableEventSink"><b>disableEventSink</b></a> ()</li>
63</ul>
64<h2>Signals</h2>
65<ul>
66<li class=fn>void <a href="#signal"><b>signal</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name, int&nbsp;argc, void&nbsp;*&nbsp;argv )</li>
67<li class=fn>void <a href="#propertyChanged"><b>propertyChanged</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;name )</li>
68<li class=fn>void <a href="#exception"><b>exception</b></a> ( int&nbsp;code, const&nbsp;QString&nbsp;&amp;&nbsp;source, const&nbsp;QString&nbsp;&amp;&nbsp;desc, const&nbsp;QString&nbsp;&amp;&nbsp;help )</li>
69</ul>
70<h2>Properties</h2>
71<ul>
72<li class=fn>QString <a href="#control-prop"><b>control</b></a>&nbsp;- the name of the COM object wrapped by this QAxBase object</li>
73</ul>
74<h2>Protected Members</h2>
75<ul>
76<li class=fn>virtual bool <a href="#initialize"><b>initialize</b></a> ( IUnknown&nbsp;**&nbsp;ptr )</li>
77<li class=fn>bool <a href="#initializeRemote"><b>initializeRemote</b></a> ( IUnknown&nbsp;**&nbsp;ptr )</li>
78<li class=fn>bool <a href="#initializeLicensed"><b>initializeLicensed</b></a> ( IUnknown&nbsp;**&nbsp;ptr )</li>
79<li class=fn>bool <a href="#initializeActive"><b>initializeActive</b></a> ( IUnknown&nbsp;**&nbsp;ptr )</li>
80</ul>
81<hr><a name="details"></a><h2>Detailed Description</h2>
82<p> This class is defined in the <b>Qt <a href="activeqt.html#ActiveQt">ActiveQt</a> Extension</b>, which can be found in the <tt>qt/extensions</tt> directory. It is not included in the main Qt API.
83<p>
84
85<p> The QAxBase class is an abstract class that provides an API
86to initalize and access a COM object.
87
88<p>
89
90<p> QAxBase is an abstract class that cannot be used directly, and is
91instantiated through the subclasses <a href="qaxobject.html">QAxObject</a> and <a href="qaxwidget.html">QAxWidget</a>. This
92class provides the API to access the COM object directly
93through its IUnknown implementation. If the COM object implements
94the IDispatch interface, the properties and methods of that object
95become available as Qt properties and slots.
96<p> <pre>
97 connect( buttonBack, SIGNAL(clicked()), webBrowser, SLOT(GoBack()) );
98 </pre>
99
100<p> Properties exposed by the object's IDispatch implementation can be
101read and written through the property system provided by the Qt
102Object Model (both subclasses are QObjects, 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">QObject</a>). Properties
103with multiple parameters are not supported.
104<p> <pre>
105 activeX-&gt;setProperty( "text", "some text" );
106 int value = activeX-&gt;property( "value" );
107 </pre>
108
109<p> Write-functions for properties and other methods exposed by the
110object's IDispatch implementation can be called directly using
111<a href="#dynamicCall">dynamicCall</a>(), or indirectly as slots connected to a signal.
112<p> <pre>
113 webBrowser-&gt;dynamicCall( "GoHome()" );
114 </pre>
115
116<p> Outgoing events supported by the COM object are emitted as
117standard Qt signals.
118<p> <pre>
119 connect( webBrowser, SIGNAL(TitleChanged(const <a href="qstring.html">QString</a>&amp;)),
120 this, SLOT(setCaption(const <a href="qstring.html">QString</a>&amp;)) );
121 </pre>
122
123<p> QAxBase transparently converts between COM data types and the
124equivalent Qt data types. Some COM types have no equivalent Qt data structure.
125<p> Supported COM datatypes are listed in the first column of following table.
126The second column is the Qt type that can be used with the <a href="qobject.html">QObject</a> property
127functions. The third column is the Qt type that is used in the prototype of
128generated signals and slots for in-parameters, and the last column is the Qt
129type that is used in the prototype of signals and slots for out-parameters.
130<center><table cellpadding="4" cellspacing="2" border="0">
131<tr bgcolor="#a2c511">
132<th valign="top">COM type
133<th valign="top">Qt property
134<th valign="top">in-parameter
135<th valign="top">out-parameter
136<tr bgcolor="#f0f0f0">
137<td valign="top">VARIANT_BOOL
138<td valign="top">bool
139<td valign="top">bool
140<td valign="top">bool&
141<tr bgcolor="#d0d0d0">
142<td valign="top">BSTR
143<td valign="top">QString
144<td valign="top">const <a href="qstring.html">QString</a>&
145<td valign="top">QString&
146<tr bgcolor="#f0f0f0">
147<td valign="top">char, short, int, long
148<td valign="top">int
149<td valign="top">int
150<td valign="top">int&
151<tr bgcolor="#d0d0d0">
152<td valign="top">uchar, ushort, uint, ulong
153<td valign="top">uint
154<td valign="top">uint
155<td valign="top">uint&
156<tr bgcolor="#f0f0f0">
157<td valign="top">float, double
158<td valign="top">double
159<td valign="top">double
160<td valign="top">double&
161<tr bgcolor="#d0d0d0">
162<td valign="top">DATE
163<td valign="top">QDateTime
164<td valign="top">const <a href="qdatetime.html">QDateTime</a>&
165<td valign="top">QDateTime&
166<tr bgcolor="#f0f0f0">
167<td valign="top">CY
168<td valign="top">Q_LLONG
169<td valign="top">Q_LLONG
170<td valign="top">Q_LLONG&
171<tr bgcolor="#d0d0d0">
172<td valign="top">OLE_COLOR
173<td valign="top">QColor
174<td valign="top">const <a href="qcolor.html">QColor</a>&
175<td valign="top">QColor&
176<tr bgcolor="#f0f0f0">
177<td valign="top">SAFEARRAY(VARIANT)
178<td valign="top">QValueList&lt;QVariant&gt;
179<td valign="top">const <a href="qvaluelist.html">QValueList</a>&lt;QVariant&gt;&
180<td valign="top">QValueList&lt;QVariant&gt;&
181<tr bgcolor="#d0d0d0">
182<td valign="top">SAFEARRAY(BYTE)
183<td valign="top">QByteArray
184<td valign="top">const <a href="qbytearray.html">QByteArray</a>&
185<td valign="top">QByteArray&
186<tr bgcolor="#f0f0f0">
187<td valign="top">SAFEARRAY(BSTR)
188<td valign="top">QStringList
189<td valign="top">const <a href="qstringlist.html">QStringList</a>&
190<td valign="top">QStringList&
191<tr bgcolor="#d0d0d0">
192<td valign="top">VARIANT
193<td valign="top">type-dependent
194<td valign="top">const <a href="qvariant.html">QVariant</a>&
195<td valign="top">QVariant&
196<tr bgcolor="#f0f0f0">
197<td valign="top">IFontDisp*
198<td valign="top">QFont
199<td valign="top">const <a href="qfont.html">QFont</a>&
200<td valign="top">QFont&
201<tr bgcolor="#d0d0d0">
202<td valign="top">IPictureDisp*
203<td valign="top">QPixmap
204<td valign="top">const <a href="qpixmap.html">QPixmap</a>&
205<td valign="top">QPixmap&
206<tr bgcolor="#f0f0f0">
207<td valign="top">IDispatch*
208<td valign="top">QAxObject* (read-only)
209<td valign="top"><a href="#asVariant">QAxBase::asVariant</a>()
210<td valign="top">QAxObject* (return value)
211<tr bgcolor="#d0d0d0">
212<td valign="top">IUnknown*
213<td valign="top">QAxObject* (read-only)
214<td valign="top"><a href="#asVariant">QAxBase::asVariant</a>()
215<td valign="top">QAxObject* (return value)
216<tr bgcolor="#f0f0f0">
217<td valign="top">SCODE, DECIMAL
218<td valign="top"><em>unsupported</em>
219<td valign="top"><em>unsupported</em>
220<td valign="top"><em>unsupported</em>
221</table></center>
222<p> Supported are also enumerations, and typedefs to supported types.
223<p> To call the methods of a COM interface described by the following IDL
224<pre>
225 dispinterface IControl
226 {
227 properties:
228 [id(1)] BSTR text;
229 [id(2)] IFontDisp *font;
230
231 methods:
232 [id(6)] void showColumn( [in] int i );
233 [id(3)] bool addColumn( [in] BSTR t );
234 [id(4)] int fillList( [in, out] SAFEARRAY(VARIANT) *list );
235 [id(5)] IDispatch *item( [in] int i );
236 };
237 </pre>
238
239use the QAxBase API like this:
240<pre>
241 <a href="qaxobject.html">QAxObject</a> object( "&lt;CLSID&gt;" );
242
243 <a href="qstring.html">QString</a> text = object.<a href="qobject.html#property">property</a>( "text" ).toString();
244 object.<a href="qobject.html#setProperty">setProperty</a>( "font", QFont( "Times New Roman", 12 ) );
245
246 connect( this, SIGNAL(clicked(int)), &amp;object, SLOT(showColumn(int)) );
247 bool ok = object.<a href="#dynamicCall">dynamicCall</a>( "addColumn(const <a href="qstring.html">QString</a>&amp;)", "Column 1" ).toBool();
248
249 <a href="qvaluelist.html">QValueList</a>&lt;QVariant&gt; varlist;
250 <a href="qvaluelist.html">QValueList</a>&lt;QVariant&gt; parameters;
251 parameters &lt;&lt; QVariant( varlist );
252 int n = object.<a href="#dynamicCall">dynamicCall</a>( "fillList(QValueList&lt;QVariant&gt;&amp;)", parameters ).toInt();
253
254 <a href="qaxobject.html">QAxObject</a> *item = object.querySubItem( "item(int)", 5 );
255 </pre>
256
257<p> Note that the <a href="qvaluelist.html">QValueList</a> the object should fill has to be provided as an
258element in the parameter list of QVariants.
259<p> If you need to access properties or pass parameters of unsupported
260datatypes you must access the COM object directly through its
261IDispatch implementation or other interfaces. Those interfaces can be
262retrieved through <a href="#queryInterface">queryInterface</a>().
263<p> <pre>
264 IUnknown *iface = 0;
265 activeX-&gt;queryInterface( IID_IUnknown, (void**)&amp;iface );
266 if ( iface ) {
267 // use the interface
268 iface-&gt;Release();
269 }
270 </pre>
271
272<p> To get the definition of the COM interfaces you will have to use the header
273files provided with the component you want to use. Some compilers can also
274import type libraries using the #import compiler directive. See the component
275documentation to find out which type libraries you have to import, and how to use
276them.
277<p> If you need to react to events that pass parameters of unsupported
278datatypes you can use the generic signal that delivers the event
279data as provided by the COM event.
280
281<hr><h2>Member Type Documentation</h2>
282<h3 class=fn><a name="PropertyBag-enum"></a>QAxBase::PropertyBag</h3>
283
284<p> A <a href="qmap.html">QMap</a><QString,QVariant> that can store properties as name:value pairs.
285
286<hr><h2>Member Function Documentation</h2>
287<h3 class=fn><a name="QAxBase"></a>QAxBase::QAxBase ( IUnknown&nbsp;*&nbsp;iface = 0 )
288</h3>
289Creates a QAxBase 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
290object.
291
292<h3 class=fn><a name="~QAxBase"></a>QAxBase::~QAxBase ()<tt> [virtual]</tt>
293</h3>
294Shuts down the COM object and destroys the QAxBase object.
295<p> <p>See also <a href="#clear">clear</a>().
296
297<h3 class=fn><a href="qvariant.html">QVariant</a> <a name="asVariant"></a>QAxBase::asVariant () const
298</h3>
299Returns a <a href="qvariant.html">QVariant</a> that wraps the COM object. The variant can
300then be used as a parameter in e.g. <a href="#dynamicCall">dynamicCall</a>().
301
302<h3 class=fn>void <a name="clear"></a>QAxBase::clear ()<tt> [virtual]</tt>
303</h3>
304Disconnects and destroys the COM object.
305<p> If you reimplement this function you must also reimplement the
306destructor to call <a href="#clear">clear</a>(), and call this implementation at the
307end of your clear() function.
308
309<h3 class=fn><a href="qstring.html">QString</a> <a name="control"></a>QAxBase::control () const
310</h3><p>Returns the name of the COM object wrapped by this QAxBase object.
311See the <a href="qaxbase.html#control-prop">"control"</a> property for details.
312<h3 class=fn>void <a name="disableClassInfo"></a>QAxBase::disableClassInfo ()
313</h3>
314Disables the class info generation for this ActiveX container. If
315you don't require any class information about the ActiveX control
316use this function to speed up the <a href="metaobjects.html#meta-object">meta object</a> generation.
317<p> Note that this function must be called immediately after
318construction of the object (without passing an object identifier),
319and before calling <a href="qaxwidget.html">QAxWidget</a>->setControl().
320
321<h3 class=fn>void <a name="disableEventSink"></a>QAxBase::disableEventSink ()
322</h3>
323Disables the event sink implementation for this ActiveX container.
324If you don't intend to listen to the ActiveX control's events use
325this function to speed up the <a href="metaobjects.html#meta-object">meta object</a> generation.
326<p> Some ActiveX controls might be unstable when connected to an event
327sink. To get OLE events you must use standard COM methods to
328register your own event sink. Use <a href="#queryInterface">queryInterface</a>() to get access
329to the raw COM object.
330<p> Note that this function should be called immediately after
331construction of the object (without passing an object identifier),
332and before calling <a href="qaxwidget.html">QAxWidget</a>->setControl().
333
334<h3 class=fn>void <a name="disableMetaObject"></a>QAxBase::disableMetaObject ()
335</h3>
336Disables the <a href="metaobjects.html#meta-object">meta object</a> generation for this ActiveX container.
337This also disables the event sink and class info generation. If
338you don't intend to use the Qt meta object implementation call
339this function to speed up the meta object generation.
340<p> Some ActiveX controls might be unstable when used with OLE
341automation. Use standard COM methods to use those controls through
342the COM interfaces provided by <a href="#queryInterface">queryInterface</a>().
343<p> Note that this function must be called immediately after
344construction of the object (without passing an object identifier),
345and before calling <a href="qaxwidget.html">QAxWidget</a>->setControl().
346
347<h3 class=fn><a href="qvariant.html">QVariant</a> <a name="dynamicCall"></a>QAxBase::dynamicCall ( const&nbsp;<a href="qcstring.html">QCString</a>&nbsp;&amp;&nbsp;function, const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var1 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var2 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var3 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var4 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var5 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var6 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var7 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var8 = QVariant ( ) )
348</h3>
349Calls the COM object's method <em>function</em>, passing the
350parameters <em>var1</em>, <em>var1</em>, <em>var2</em>, <em>var3</em>, <em>var4</em>, <em>var5</em>,
351<em>var6</em>, <em>var7</em> and <em>var8</em>, and returns the value returned by
352the method, or an invalid <a href="qvariant.html">QVariant</a> if the method does not return
353a value or when the function call failed.
354<p> If <em>function</em> is a method of the object the string must be provided
355as the full prototype, for example as it would be written in a
356<a href="qobject.html#connect">QObject::connect</a>() call.
357<pre>
358 activeX-&gt;dynamicCall( "Navigate(const <a href="qstring.html">QString</a>&amp;)", "www.trolltech.com" );
359 </pre>
360
361<p> Alternatively a function can be called passing the parameters embedded
362in the string, e.g. above function can also be invoked using
363<pre>
364 activeX-&gt;dynamicCall("Navigate(\"www.trolltech.com\");
365 </pre>
366
367All parameters are passed as strings; it depends on the control whether
368they are interpreted correctly, and is slower than using the prototype
369with correctly typed parameters.
370<p> If <em>function</em> is a property the string has to be the name of the
371property. The property setter is called when <em>var1</em> is a valid QVariant,
372otherwise the getter is called.
373<pre>
374 activeX-&gt;dynamicCall( "Value", 5 );
375 <a href="qstring.html">QString</a> text = activeX-&gt;dynamicCall( "Text" ).toString();
376 </pre>
377
378Note that it is faster to get and set properties using
379<a href="qobject.html#property">QObject::property</a>() and <a href="qobject.html#setProperty">QObject::setProperty</a>().
380<p> It is only possible to call functions through <a href="#dynamicCall">dynamicCall</a>() that
381have parameters or return values of datatypes supported by
382<a href="qvariant.html">QVariant</a>. See the QAxBase class documentation for a list of
383supported and unsupported datatypes. If you want to call functions
384that have unsupported datatypes in the parameter list, use
385<a href="#queryInterface">queryInterface</a>() to retrieve the appropriate COM interface, and
386use the function directly.
387<p> <pre>
388 IWebBrowser2 *webBrowser = 0;
389 activeX-&gt;queryInterface( IID_IWebBrowser2, (void**)&amp;webBrowser );
390 if ( webBrowser ) {
391 webBrowser-&gt;Navigate2( pvarURL );
392 webBrowser-&gt;Release();
393 }
394 </pre>
395
396<p> This is also more efficient.
397
398<p>Example: <a href="qaxcontainer-example-qutlook.html#x2720">qutlook/centralwidget.cpp</a>.
399<h3 class=fn><a href="qvariant.html">QVariant</a> <a name="dynamicCall-2"></a>QAxBase::dynamicCall ( const&nbsp;<a href="qcstring.html">QCString</a>&nbsp;&amp;&nbsp;function, <a href="qvaluelist.html">QValueList</a>&lt;QVariant&gt;&nbsp;&amp;&nbsp;vars )
400</h3>
401This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
402<p> Calls the COM object's method <em>function</em>, passing the
403parameters in <em>vars</em>, and returns the value returned by
404the method. If the method does not return a value or when
405the function call failed this function returns an invalid
406<a href="qvariant.html">QVariant</a> object.
407<p> The QVariant objects in <em>vars</em> are updated when the method has
408out-parameters.
409
410<h3 class=fn>void <a name="exception"></a>QAxBase::exception ( int&nbsp;code, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;source, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;desc, const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;help )<tt> [signal]</tt>
411</h3>
412
413<p> This signal is emitted when the COM object throws an exception while called using the OLE automation
414interface IDispatch. <em>code</em>, <em>source</em>, <em>desc</em> and <em>help</em> provide information about the exception as
415provided by the COM server and can be used to provide useful feedback to the end user. <em>help</em> includes
416the help file, and the help context ID in brackets, e.g. "filename [id]".
417
418<h3 class=fn><a href="qstring.html">QString</a> <a name="generateDocumentation"></a>QAxBase::generateDocumentation ()
419</h3>
420
421<p> Returns a rich text string with documentation for the
422wrapped COM object. Dump the string to an HTML-file,
423or use it in e.g. a <a href="qtextbrowser.html">QTextBrowser</a> widget.
424
425<h3 class=fn>bool <a name="initialize"></a>QAxBase::initialize ( IUnknown&nbsp;**&nbsp;ptr )<tt> [virtual protected]</tt>
426</h3>
427This virtual function is called by <a href="#setControl">setControl</a>() and creates the
428requested COM object. <em>ptr</em> is set to the object's IUnknown
429implementation. The function returns TRUE if the object
430initialization succeeded; otherwise the function returns FALSE.
431<p> The default implementation interprets the string returned by
432<a href="#control">control</a>(), and calls <a href="#initializeRemote">initializeRemote</a>(), <a href="#initializeLicensed">initializeLicensed</a>()
433or <a href="#initializeActive">initializeActive</a>() if the string matches the respective
434patterns. If no pattern is matched, or if remote or licensed
435initialization fails, CoCreateInstance is used directly to create
436the object.
437<p> See the <a href="#control-prop">control</a> property documentation for details about
438supported patterns.
439<p> The interface returned in <em>ptr</em> must be referenced exactly once
440when this function returns. The interface provided by e.g.
441CoCreateInstance is already referenced, and there is no need to
442reference it again.
443
444<h3 class=fn>bool <a name="initializeActive"></a>QAxBase::initializeActive ( IUnknown&nbsp;**&nbsp;ptr )<tt> [protected]</tt>
445</h3>
446Returns an active instance running on the current machine, and returns the
447IUnknown interface to the running object in <em>ptr</em>. This function returns TRUE
448if successful, otherwise returns FALSE.
449<p> This function is called by <a href="#initialize">initialize</a>() if the control string contains the
450substring "}&".
451<p> <p>See also <a href="#initialize">initialize</a>().
452
453<h3 class=fn>bool <a name="initializeLicensed"></a>QAxBase::initializeLicensed ( IUnknown&nbsp;**&nbsp;ptr )<tt> [protected]</tt>
454</h3>
455Creates an instance of a licensed control, and returns the IUnknown interface
456to the object in <em>ptr</em>. This functions returns TRUE if successful, otherwise
457returns FALSE.
458<p> This function is called by <a href="#initialize">initialize</a>() if the control string contains the
459substring "}:". The license key needs to follow this substring.
460<p> <p>See also <a href="#initialize">initialize</a>().
461
462<h3 class=fn>bool <a name="initializeRemote"></a>QAxBase::initializeRemote ( IUnknown&nbsp;**&nbsp;ptr )<tt> [protected]</tt>
463</h3>
464Creates the instance on a remote server, and returns the IUnknown interface
465to the object in <em>ptr</em>. This function returns TRUE if successful, otherwise
466returns FALSE.
467<p> This function is called by <a href="#initialize">initialize</a>() if the control string contains the
468substring "/{". The information about the remote machine needs to be provided
469in front of the substring.
470<p> <p>See also <a href="#initialize">initialize</a>().
471
472<h3 class=fn>bool <a name="isNull"></a>QAxBase::isNull () const
473</h3>
474Returns TRUE if there is no COM object loaded by this wrapper;
475otherwise return FALSE.
476<p> <p>See also <a href="#control-prop">control</a>.
477
478<h3 class=fn><a href="qaxbase.html#PropertyBag-enum">PropertyBag</a> <a name="propertyBag"></a>QAxBase::propertyBag () const
479</h3>
480Returns a name:value map of all the properties exposed by the COM
481object.
482<p> This is more efficient than getting multiple properties
483individually if the COM object supports property bags.
484<p> <b>Warning:</b> It is not guaranteed that the property bag implementation
485of the COM object returns all properties, or that the properties
486returned are the same as those available through the IDispatch
487interface.
488
489<h3 class=fn>void <a name="propertyChanged"></a>QAxBase::propertyChanged ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name )<tt> [signal]</tt>
490</h3>
491
492<p> If the COM object supports property notification, this signal gets
493emitted when the property called <em>name</em> is changed.
494
495<h3 class=fn>bool <a name="propertyWritable"></a>QAxBase::propertyWritable ( const&nbsp;char&nbsp;*&nbsp;prop ) const<tt> [virtual]</tt>
496</h3>
497Returns TRUE if the property <em>prop</em> is writable; otherwise
498returns FALSE. By default, all properties are writable.
499<p> <b>Warning:</b>
500Depending on the control implementation this setting might be
501ignored for some properties.
502<p> <p>See also <a href="#setPropertyWritable">setPropertyWritable</a>() and <a href="#propertyChanged">propertyChanged</a>().
503
504<h3 class=fn>long <a name="queryInterface"></a>QAxBase::queryInterface ( const&nbsp;<a href="quuid.html">QUuid</a>&nbsp;&amp;&nbsp;uuid, void&nbsp;**&nbsp;iface ) const
505</h3>
506Requests the interface <em>uuid</em> from the COM object and sets the
507value of <em>iface</em> to the provided interface, or to 0 if the
508requested interface could not be provided.
509<p> Returns the result of the QueryInterface implementation of the COM object.
510<p> <p>See also <a href="#control-prop">control</a>.
511
512<h3 class=fn><a href="qaxobject.html">QAxObject</a>&nbsp;* <a name="querySubObject"></a>QAxBase::querySubObject ( const&nbsp;<a href="qcstring.html">QCString</a>&nbsp;&amp;&nbsp;name, const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var1 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var2 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var3 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var4 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var5 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var6 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var7 = QVariant ( ), const&nbsp;<a href="qvariant.html">QVariant</a>&nbsp;&amp;&nbsp;var8 = QVariant ( ) )
513</h3>
514Returns a pointer to a <a href="qaxobject.html">QAxObject</a> wrapping the COM object provided
515by the method or property <em>name</em>, passing passing the parameters
516<em>var1</em>, <em>var1</em>, <em>var2</em>, <em>var3</em>, <em>var4</em>, <em>var5</em>, <em>var6</em>,
517<em>var7</em> and <em>var8</em>.
518<p> If <em>name</em> is provided by a method the string must include the
519full function prototype.
520<p> If <em>name</em> is a property the string must be the name of the property,
521and <em>var1</em>, ... <em>var8</em> are ignored.
522<p> The returned QAxObject is a child of this object (which is either of
523type QAxObject or <a href="qaxwidget.html">QAxWidget</a>), and is deleted when this object is
524deleted. It is however safe to delete the returned object yourself,
525and you should do so when you iterate over lists of subobjects.
526<p> COM enabled applications usually have an object model publishing
527certain elements of the application as dispatch interfaces. Use
528this method to navigate the hierarchy of the object model, e.g.
529<p> <pre>
530 <a href="qaxwidget.html">QAxWidget</a> outlook( "Outlook.Application" );
531 <a href="qaxobject.html">QAxObject</a> *session = outlook.<a href="#querySubObject">querySubObject</a>( "Session" );
532 if ( session ) {
533 <a href="qaxobject.html">QAxObject</a> *defFolder = session-&gt;<a href="#querySubObject">querySubObject</a>(
534 "GetDefaultFolder(OlDefaultFolders)",
535 "olFolderContacts" );
536 //...
537 }
538 </pre>
539
540
541<p>Example: <a href="qaxcontainer-example-qutlook.html#x2721">qutlook/centralwidget.cpp</a>.
542<h3 class=fn>bool <a name="setControl"></a>QAxBase::setControl ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp; )
543</h3><p>Sets the name of the COM object wrapped by this QAxBase object.
544See the <a href="qaxbase.html#control-prop">"control"</a> property for details.
545<h3 class=fn>void <a name="setPropertyBag"></a>QAxBase::setPropertyBag ( const&nbsp;<a href="qaxbase.html#PropertyBag-enum">PropertyBag</a>&nbsp;&amp;&nbsp;bag )
546</h3>
547Sets the properties of the COM object to the corresponding values
548in <em>bag</em>.
549<p> <b>Warning:</b>
550You should only set property bags that have been returned by the
551propertyBag function, as it cannot be guaranteed that the property
552bag implementation of the COM object supports the same properties
553that are available through the IDispatch interface.
554<p> <p>See also <a href="#propertyBag">propertyBag</a>().
555
556<h3 class=fn>void <a name="setPropertyWritable"></a>QAxBase::setPropertyWritable ( const&nbsp;char&nbsp;*&nbsp;prop, bool&nbsp;ok )<tt> [virtual]</tt>
557</h3>
558Sets the property <em>prop</em> to writable if <em>ok</em> is TRUE, otherwise
559sets <em>prop</em> to be read-only. By default, all properties are
560writable.
561<p> <b>Warning:</b>
562Depending on the control implementation this setting might be
563ignored for some properties.
564<p> <p>See also <a href="#propertyWritable">propertyWritable</a>() and <a href="#propertyChanged">propertyChanged</a>().
565
566<h3 class=fn>void <a name="signal"></a>QAxBase::signal ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;name, int&nbsp;argc, void&nbsp;*&nbsp;argv )<tt> [signal]</tt>
567</h3>
568
569<p> This generic signal gets emitted when the COM object issues the
570event <em>name</em>. <em>argc</em> is the number of parameters provided by the
571event (DISPPARAMS.cArgs), and <em>argv</em> is the pointer to the
572parameter values (DISPPARAMS.rgvarg). Note that the order of parameter
573values is turned around, ie. the last element of the array is the first
574parameter in the function.
575<p> <pre>
576 void Receiver::slot( const <a href="qstring.html">QString</a> &amp;name, int argc, void *argv )
577 {
578 VARIANTARG *params = (VARIANTARG*)argv;
579 if ( name.<a href="qstring.html#startsWith">startsWith</a>( "BeforeNavigate2(" ) ) {
580 IDispatch *pDisp = params[argc-1].pdispVal;
581 VARIANTARG URL = *params[argc-2].pvarVal;
582 VARIANTARG Flags = *params[argc-3].pvarVal;
583 VARIANTARG TargetFrameName = *params[argc-4].pvarVal;
584 VARIANTARG PostData = *params[argc-5].pvarVal;
585 VARIANTARG Headers = *params[argc-6].pvarVal;
586 bool *Cancel = params[argc-7].pboolVal;
587 }
588 }
589 </pre>
590
591<p> Use this signal if the event has parameters of unsupported data
592types. Otherwise, connect directly to the signal <em>name</em>.
593
594<hr><h2>Property Documentation</h2>
595<h3 class=fn><a href="qstring.html">QString</a> <a name="control-prop"></a>control</h3>
596<p>This property holds the name of the COM object wrapped by this QAxBase object.
597<p>Setting this property initilializes the COM object. Any COM object
598previously set is shut down.
599<p> The most efficient way to set this property is by using the
600registered component's UUID, e.g.
601<pre>
602 ctrl-&gt;setControl( "{8E27C92B-1264-101C-8A2F-040224009C02}" );
603 </pre>
604
605The second fastest way is to use the registered control's class
606name (with or without version number), e.g.
607<pre>
608 ctrl-&gt;setControl( "MSCal.Calendar" );
609 </pre>
610
611The slowest, but easiest way to use is to use the control's full
612name, e.g.
613<pre>
614 ctrl-&gt;setControl( "Calendar Control 9.0" );
615 </pre>
616
617<p> If the component's UUID is used the following patterns can be used
618to initialize the control on a remote machine, to initialize a
619licensed control or to connect to a running object:
620<ul>
621<li> To initialize the control on a different machine use the following
622pattern:
623<pre>
624 &lt;domain/username&gt;:&lt;password&gt;@server/{8E27C92B-1264-101C-8A2F-040224009C02}
625 </pre>
626
627<li> To initialize a licensed control use the following pattern:
628<pre>
629 {8E27C92B-1264-101C-8A2F-040224009C02}:&lt;LicenseKey&gt;
630 </pre>
631
632<li> To connect to an already running object use the following pattern:
633<pre>
634 {8E27C92B-1264-101C-8A2F-040224009C02}&amp;
635 </pre>
636
637</ul>
638The first two patterns can be combined, e.g. to initialize a licensed
639control on a remote machine:
640<pre>
641 ctrl-&gt;setControl("DOMAIN/user:password@server/{8E27C92B-1264-101C-8A2F-040224009C02}:LicenseKey");
642 </pre>
643
644<p> The control's read function always returns the control's UUID, if provided including the license
645key, and the name of the server, but not including the username, the domain or the password.
646
647<p>Set this property's value with <a href="#setControl">setControl</a>() and get this property's value with <a href="#control">control</a>().
648<!-- eof -->
649<hr><p>
650This file is part of the <a href="index.html">Qt toolkit</a>.
651Copyright &copy; 1995-2007
652<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
653<table width=100% cellspacing=0 border=0><tr>
654<td>Copyright &copy; 2007
655<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
656<td align=right><div align=right>Qt 3.3.8</div>
657</table></div></address></body>
658</html>
Note: See TracBrowser for help on using the repository browser.