Context Navigation

qaxbase.html

Last change on this file was 190, checked in by rudi, 14 years ago
reference documentation added
File size: 35.2 KB

Line
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"><!--
8	fn { margin-left: 1cm; text-indent: -1cm; }
9	a:link { color: #004faf; text-decoration: none }
10	a:visited { color: #672967; text-decoration: none }
11	body { 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 Classes</font></a>
23	\| <a href="mainclasses.html">
24	<font color="#004faf">Main 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 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
35	to 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 <<a href="qaxbase-h.html">qaxbase.h</a>></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 * 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 QUuid & uuid, void ** iface ) const</li>
47	<li class=fn>QVariant <a href="#dynamicCall"><b>dynamicCall</b></a> ( 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 ( ) )</li>
48	<li class=fn>QVariant <a href="#dynamicCall-2"><b>dynamicCall</b></a> ( const QCString & function, QValueList<QVariant> & vars )</li>
49	<li class=fn>QAxObject * <a href="#querySubObject"><b>querySubObject</b></a> ( 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 ( ) )</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 PropertyBag & 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 char * prop ) const</li>
54	<li class=fn>virtual void <a href="#setPropertyWritable"><b>setPropertyWritable</b></a> ( const char * prop, bool 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 & )</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 QString & name, int argc, void * argv )</li>
67	<li class=fn>void <a href="#propertyChanged"><b>propertyChanged</b></a> ( const QString & name )</li>
68	<li class=fn>void <a href="#exception"><b>exception</b></a> ( int code, const QString & source, const QString & desc, const QString & help )</li>
69	</ul>
70	<h2>Properties</h2>
71	<ul>
72	<li class=fn>QString <a href="#control-prop"><b>control</b></a> - 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 ** ptr )</li>
77	<li class=fn>bool <a href="#initializeRemote"><b>initializeRemote</b></a> ( IUnknown ** ptr )</li>
78	<li class=fn>bool <a href="#initializeLicensed"><b>initializeLicensed</b></a> ( IUnknown ** ptr )</li>
79	<li class=fn>bool <a href="#initializeActive"><b>initializeActive</b></a> ( IUnknown ** 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
86	to initalize and access a COM object.
87
88	<p>
89
90	<p> QAxBase is an abstract class that cannot be used directly, and is
91	instantiated through the subclasses <a href="qaxobject.html">QAxObject</a> and <a href="qaxwidget.html">QAxWidget</a>. This
92	class provides the API to access the COM object directly
93	through its IUnknown implementation. If the COM object implements
94	the IDispatch interface, the properties and methods of that object
95	become 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
101	read and written through the property system provided by the Qt
102	Object 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
103	with multiple parameters are not supported.
104	<p> <pre>
105	activeX->setProperty( "text", "some text" );
106	int value = activeX->property( "value" );
107	</pre>
108
109	<p> Write-functions for properties and other methods exposed by the
110	object'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->dynamicCall( "GoHome()" );
114	</pre>
115
116	<p> Outgoing events supported by the COM object are emitted as
117	standard Qt signals.
118	<p> <pre>
119	connect( webBrowser, SIGNAL(TitleChanged(const <a href="qstring.html">QString</a>&)),
120	this, SLOT(setCaption(const <a href="qstring.html">QString</a>&)) );
121	</pre>
122
123	<p> QAxBase transparently converts between COM data types and the
124	equivalent 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.
126	The second column is the Qt type that can be used with the <a href="qobject.html">QObject</a> property
127	functions. The third column is the Qt type that is used in the prototype of
128	generated signals and slots for in-parameters, and the last column is the Qt
129	type 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<QVariant>
179	<td valign="top">const <a href="qvaluelist.html">QValueList</a><QVariant>&
180	<td valign="top">QValueList<QVariant>&
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
239	use the QAxBase API like this:
240	<pre>
241	<a href="qaxobject.html">QAxObject</a> object( "<CLSID>" );
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)), &object, SLOT(showColumn(int)) );
247	bool ok = object.<a href="#dynamicCall">dynamicCall</a>( "addColumn(const <a href="qstring.html">QString</a>&)", "Column 1" ).toBool();
248
249	<a href="qvaluelist.html">QValueList</a><QVariant> varlist;
250	<a href="qvaluelist.html">QValueList</a><QVariant> parameters;
251	parameters << QVariant( varlist );
252	int n = object.<a href="#dynamicCall">dynamicCall</a>( "fillList(QValueList<QVariant>&)", 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
258	element in the parameter list of QVariants.
259	<p> If you need to access properties or pass parameters of unsupported
260	datatypes you must access the COM object directly through its
261	IDispatch implementation or other interfaces. Those interfaces can be
262	retrieved through <a href="#queryInterface">queryInterface</a>().
263	<p> <pre>
264	IUnknown *iface = 0;
265	activeX->queryInterface( IID_IUnknown, (void**)&iface );
266	if ( iface ) {
267	// use the interface
268	iface->Release();
269	}
270	</pre>
271
272	<p> To get the definition of the COM interfaces you will have to use the header
273	files provided with the component you want to use. Some compilers can also
274	import type libraries using the #import compiler directive. See the component
275	documentation to find out which type libraries you have to import, and how to use
276	them.
277	<p> If you need to react to events that pass parameters of unsupported
278	datatypes you can use the generic signal that delivers the event
279	data 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 * iface = 0 )
288	</h3>
289	Creates 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
290	object.
291
292	<h3 class=fn><a name="~QAxBase"></a>QAxBase::~QAxBase ()<tt> [virtual]</tt>
293	</h3>
294	Shuts 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>
299	Returns a <a href="qvariant.html">QVariant</a> that wraps the COM object. The variant can
300	then 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>
304	Disconnects and destroys the COM object.
305	<p> If you reimplement this function you must also reimplement the
306	destructor to call <a href="#clear">clear</a>(), and call this implementation at the
307	end 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.
311	See 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>
314	Disables the class info generation for this ActiveX container. If
315	you don't require any class information about the ActiveX control
316	use 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
318	construction of the object (without passing an object identifier),
319	and before calling <a href="qaxwidget.html">QAxWidget</a>->setControl().
320
321	<h3 class=fn>void <a name="disableEventSink"></a>QAxBase::disableEventSink ()
322	</h3>
323	Disables the event sink implementation for this ActiveX container.
324	If you don't intend to listen to the ActiveX control's events use
325	this 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
327	sink. To get OLE events you must use standard COM methods to
328	register your own event sink. Use <a href="#queryInterface">queryInterface</a>() to get access
329	to the raw COM object.
330	<p> Note that this function should be called immediately after
331	construction of the object (without passing an object identifier),
332	and before calling <a href="qaxwidget.html">QAxWidget</a>->setControl().
333
334	<h3 class=fn>void <a name="disableMetaObject"></a>QAxBase::disableMetaObject ()
335	</h3>
336	Disables the <a href="metaobjects.html#meta-object">meta object</a> generation for this ActiveX container.
337	This also disables the event sink and class info generation. If
338	you don't intend to use the Qt meta object implementation call
339	this function to speed up the meta object generation.
340	<p> Some ActiveX controls might be unstable when used with OLE
341	automation. Use standard COM methods to use those controls through
342	the COM interfaces provided by <a href="#queryInterface">queryInterface</a>().
343	<p> Note that this function must be called immediately after
344	construction of the object (without passing an object identifier),
345	and 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 <a href="qcstring.html">QCString</a> & function, const <a href="qvariant.html">QVariant</a> & var1 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var2 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var3 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var4 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var5 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var6 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var7 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var8 = QVariant ( ) )
348	</h3>
349	Calls the COM object's method <em>function</em>, passing the
350	parameters <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
352	the method, or an invalid <a href="qvariant.html">QVariant</a> if the method does not return
353	a value or when the function call failed.
354	<p> If <em>function</em> is a method of the object the string must be provided
355	as 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->dynamicCall( "Navigate(const <a href="qstring.html">QString</a>&)", "www.trolltech.com" );
359	</pre>
360
361	<p> Alternatively a function can be called passing the parameters embedded
362	in the string, e.g. above function can also be invoked using
363	<pre>
364	activeX->dynamicCall("Navigate(\"www.trolltech.com\");
365	</pre>
366
367	All parameters are passed as strings; it depends on the control whether
368	they are interpreted correctly, and is slower than using the prototype
369	with correctly typed parameters.
370	<p> If <em>function</em> is a property the string has to be the name of the
371	property. The property setter is called when <em>var1</em> is a valid QVariant,
372	otherwise the getter is called.
373	<pre>
374	activeX->dynamicCall( "Value", 5 );
375	<a href="qstring.html">QString</a> text = activeX->dynamicCall( "Text" ).toString();
376	</pre>
377
378	Note 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
381	have parameters or return values of datatypes supported by
382	<a href="qvariant.html">QVariant</a>. See the QAxBase class documentation for a list of
383	supported and unsupported datatypes. If you want to call functions
384	that have unsupported datatypes in the parameter list, use
385	<a href="#queryInterface">queryInterface</a>() to retrieve the appropriate COM interface, and
386	use the function directly.
387	<p> <pre>
388	IWebBrowser2 *webBrowser = 0;
389	activeX->queryInterface( IID_IWebBrowser2, (void**)&webBrowser );
390	if ( webBrowser ) {
391	webBrowser->Navigate2( pvarURL );
392	webBrowser->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 <a href="qcstring.html">QCString</a> & function, <a href="qvaluelist.html">QValueList</a><QVariant> & vars )
400	</h3>
401	This 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
403	parameters in <em>vars</em>, and returns the value returned by
404	the method. If the method does not return a value or when
405	the 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
408	out-parameters.
409
410	<h3 class=fn>void <a name="exception"></a>QAxBase::exception ( int code, const <a href="qstring.html">QString</a> & source, const <a href="qstring.html">QString</a> & desc, const <a href="qstring.html">QString</a> & 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
414	interface IDispatch. <em>code</em>, <em>source</em>, <em>desc</em> and <em>help</em> provide information about the exception as
415	provided by the COM server and can be used to provide useful feedback to the end user. <em>help</em> includes
416	the 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
422	wrapped COM object. Dump the string to an HTML-file,
423	or 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 ** ptr )<tt> [virtual protected]</tt>
426	</h3>
427	This virtual function is called by <a href="#setControl">setControl</a>() and creates the
428	requested COM object. <em>ptr</em> is set to the object's IUnknown
429	implementation. The function returns TRUE if the object
430	initialization 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>()
433	or <a href="#initializeActive">initializeActive</a>() if the string matches the respective
434	patterns. If no pattern is matched, or if remote or licensed
435	initialization fails, CoCreateInstance is used directly to create
436	the object.
437	<p> See the <a href="#control-prop">control</a> property documentation for details about
438	supported patterns.
439	<p> The interface returned in <em>ptr</em> must be referenced exactly once
440	when this function returns. The interface provided by e.g.
441	CoCreateInstance is already referenced, and there is no need to
442	reference it again.
443
444	<h3 class=fn>bool <a name="initializeActive"></a>QAxBase::initializeActive ( IUnknown ** ptr )<tt> [protected]</tt>
445	</h3>
446	Returns an active instance running on the current machine, and returns the
447	IUnknown interface to the running object in <em>ptr</em>. This function returns TRUE
448	if successful, otherwise returns FALSE.
449	<p> This function is called by <a href="#initialize">initialize</a>() if the control string contains the
450	substring "}&".
451	<p> <p>See also <a href="#initialize">initialize</a>().
452
453	<h3 class=fn>bool <a name="initializeLicensed"></a>QAxBase::initializeLicensed ( IUnknown ** ptr )<tt> [protected]</tt>
454	</h3>
455	Creates an instance of a licensed control, and returns the IUnknown interface
456	to the object in <em>ptr</em>. This functions returns TRUE if successful, otherwise
457	returns FALSE.
458	<p> This function is called by <a href="#initialize">initialize</a>() if the control string contains the
459	substring "}:". 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 ** ptr )<tt> [protected]</tt>
463	</h3>
464	Creates the instance on a remote server, and returns the IUnknown interface
465	to the object in <em>ptr</em>. This function returns TRUE if successful, otherwise
466	returns FALSE.
467	<p> This function is called by <a href="#initialize">initialize</a>() if the control string contains the
468	substring "/{". The information about the remote machine needs to be provided
469	in 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>
474	Returns TRUE if there is no COM object loaded by this wrapper;
475	otherwise 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>
480	Returns a name:value map of all the properties exposed by the COM
481	object.
482	<p> This is more efficient than getting multiple properties
483	individually if the COM object supports property bags.
484	<p> <b>Warning:</b> It is not guaranteed that the property bag implementation
485	of the COM object returns all properties, or that the properties
486	returned are the same as those available through the IDispatch
487	interface.
488
489	<h3 class=fn>void <a name="propertyChanged"></a>QAxBase::propertyChanged ( const <a href="qstring.html">QString</a> & name )<tt> [signal]</tt>
490	</h3>
491
492	<p> If the COM object supports property notification, this signal gets
493	emitted when the property called <em>name</em> is changed.
494
495	<h3 class=fn>bool <a name="propertyWritable"></a>QAxBase::propertyWritable ( const char * prop ) const<tt> [virtual]</tt>
496	</h3>
497	Returns TRUE if the property <em>prop</em> is writable; otherwise
498	returns FALSE. By default, all properties are writable.
499	<p> <b>Warning:</b>
500	Depending on the control implementation this setting might be
501	ignored 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 <a href="quuid.html">QUuid</a> & uuid, void ** iface ) const
505	</h3>
506	Requests the interface <em>uuid</em> from the COM object and sets the
507	value of <em>iface</em> to the provided interface, or to 0 if the
508	requested 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> * <a name="querySubObject"></a>QAxBase::querySubObject ( const <a href="qcstring.html">QCString</a> & name, const <a href="qvariant.html">QVariant</a> & var1 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var2 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var3 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var4 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var5 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var6 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var7 = QVariant ( ), const <a href="qvariant.html">QVariant</a> & var8 = QVariant ( ) )
513	</h3>
514	Returns a pointer to a <a href="qaxobject.html">QAxObject</a> wrapping the COM object provided
515	by 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
519	full function prototype.
520	<p> If <em>name</em> is a property the string must be the name of the property,
521	and <em>var1</em>, ... <em>var8</em> are ignored.
522	<p> The returned QAxObject is a child of this object (which is either of
523	type QAxObject or <a href="qaxwidget.html">QAxWidget</a>), and is deleted when this object is
524	deleted. It is however safe to delete the returned object yourself,
525	and you should do so when you iterate over lists of subobjects.
526	<p> COM enabled applications usually have an object model publishing
527	certain elements of the application as dispatch interfaces. Use
528	this 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-><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 <a href="qstring.html">QString</a> & )
543	</h3><p>Sets the name of the COM object wrapped by this QAxBase object.
544	See the <a href="qaxbase.html#control-prop">"control"</a> property for details.
545	<h3 class=fn>void <a name="setPropertyBag"></a>QAxBase::setPropertyBag ( const <a href="qaxbase.html#PropertyBag-enum">PropertyBag</a> & bag )
546	</h3>
547	Sets the properties of the COM object to the corresponding values
548	in <em>bag</em>.
549	<p> <b>Warning:</b>
550	You should only set property bags that have been returned by the
551	propertyBag function, as it cannot be guaranteed that the property
552	bag implementation of the COM object supports the same properties
553	that 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 char * prop, bool ok )<tt> [virtual]</tt>
557	</h3>
558	Sets the property <em>prop</em> to writable if <em>ok</em> is TRUE, otherwise
559	sets <em>prop</em> to be read-only. By default, all properties are
560	writable.
561	<p> <b>Warning:</b>
562	Depending on the control implementation this setting might be
563	ignored 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 <a href="qstring.html">QString</a> & name, int argc, void * argv )<tt> [signal]</tt>
567	</h3>
568
569	<p> This generic signal gets emitted when the COM object issues the
570	event <em>name</em>. <em>argc</em> is the number of parameters provided by the
571	event (DISPPARAMS.cArgs), and <em>argv</em> is the pointer to the
572	parameter values (DISPPARAMS.rgvarg). Note that the order of parameter
573	values is turned around, ie. the last element of the array is the first
574	parameter in the function.
575	<p> <pre>
576	void Receiver::slot( const <a href="qstring.html">QString</a> &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
592	types. 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
598	previously set is shut down.
599	<p> The most efficient way to set this property is by using the
600	registered component's UUID, e.g.
601	<pre>
602	ctrl->setControl( "{8E27C92B-1264-101C-8A2F-040224009C02}" );
603	</pre>
604
605	The second fastest way is to use the registered control's class
606	name (with or without version number), e.g.
607	<pre>
608	ctrl->setControl( "MSCal.Calendar" );
609	</pre>
610
611	The slowest, but easiest way to use is to use the control's full
612	name, e.g.
613	<pre>
614	ctrl->setControl( "Calendar Control 9.0" );
615	</pre>
616
617	<p> If the component's UUID is used the following patterns can be used
618	to initialize the control on a remote machine, to initialize a
619	licensed control or to connect to a running object:
620	<ul>
621	<li> To initialize the control on a different machine use the following
622	pattern:
623	<pre>
624	<domain/username>:<password>@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}:<LicenseKey>
630	</pre>
631
632	<li> To connect to an already running object use the following pattern:
633	<pre>
634	{8E27C92B-1264-101C-8A2F-040224009C02}&
635	</pre>
636
637	</ul>
638	The first two patterns can be combined, e.g. to initialize a licensed
639	control on a remote machine:
640	<pre>
641	ctrl->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
645	key, 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>
650	This file is part of the <a href="index.html">Qt toolkit</a>.
651	Copyright © 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 © 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.

Context Navigation

source: trunk/doc/html/qaxbase.html

Download in other formats: