source: trunk/doc/html/qaxobject.html

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

reference documentation added
File size: 13.5 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/qaxobject.cpp:33 -->
3<html>
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6<title>QAxObject 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>QAxObject Class Reference<br><small>[<a href="qaxcontainer.html">QAxContainer module</a>]</small></h1>
33
34<p>The QAxObject class provides a QObject that wraps a COM object.
35<a href="#details">More...</a>
36<p>This class is part of the <b>Qt ActiveQt Extension</b>.
37<p><tt>#include &lt;<a href="qaxobject-h.html">qaxobject.h</a>&gt;</tt>
38<p>Inherits <a href="qobject.html">QObject</a> and <a href="qaxbase.html">QAxBase</a>.
39<p>Inherited by <a href="qaxscriptengine.html">QAxScriptEngine</a>.
40<p><a href="qaxobject-members.html">List of all member functions.</a>
41<h2>Public Members</h2>
42<ul>
43<li class=fn><a href="#QAxObject"><b>QAxObject</b></a> ( QObject&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
44<li class=fn><a href="#QAxObject-2"><b>QAxObject</b></a> ( const&nbsp;QString&nbsp;&amp;&nbsp;c, QObject&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
45<li class=fn><a href="#QAxObject-3"><b>QAxObject</b></a> ( IUnknown&nbsp;*&nbsp;iface, QObject&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )</li>
46<li class=fn><a href="#~QAxObject"><b>~QAxObject</b></a> ()</li>
47</ul>
48<h2>Important Inherited Members</h2>
49<ul>
50<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>
51<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>
52<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>
53</ul>
54<hr><a name="details"></a><h2>Detailed Description</h2>
55<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.
56<p>
57
58The QAxObject class provides a <a href="qobject.html">QObject</a> that wraps a COM object.
59
60<p>
61
62<p> A QAxObject can be instantiated as an empty object, with the name
63of the COM object it should wrap, or with a pointer to the
64IUnknown that represents an existing COM object. If the COM object
65implements the IDispatch interface, the properties, methods and
66events of that object become available as Qt properties, slots and
67signals. The base class, <a href="qaxbase.html">QAxBase</a>, provides an API to access the
68COM object directly through the IUnknown pointer.
69<p> QAxObject is a QObject and can be used as such, e.g. it can be
70organized in an object hierarchy, receive events and connect to
71signals and slots.
72<p> <b>Warning:</b>
73You can subclass QAxObject, but you cannot use the <a href="metaobjects.html#Q_OBJECT">Q_OBJECT</a> macro
74in the subclass (the generated <a href="moc.html#moc">moc</a>-file will not compile), so you
75cannot add further signals, slots or properties. This limitation is
76due to the metaobject information generated in runtime.
77To work around this problem, aggregate the QAxObject as a member of
78the <a href="qobject.html">QObject</a> subclass.
79<p>
80<hr><h2>Member Function Documentation</h2>
81<h3 class=fn><a name="QAxObject"></a>QAxObject::QAxObject ( <a href="qobject.html">QObject</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )
82</h3>
83Creates an empty COM object and propagates <em>parent</em> and <em>name</em>
84to the <a href="qobject.html">QObject</a> constructor. To initialize the object, call <a href="qaxbase.html#setControl">setControl</a>.
85
86<h3 class=fn><a name="QAxObject-2"></a>QAxObject::QAxObject ( const&nbsp;<a href="qstring.html">QString</a>&nbsp;&amp;&nbsp;c, <a href="qobject.html">QObject</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )
87</h3>
88Creates a QAxObject that wraps the COM object <em>c</em>. <em>parent</em> and
89<em>name</em> are propagated to the <a href="qwidget.html">QWidget</a> contructor.
90<p> <p>See also <a href="qaxbase.html#control-prop">control</a>.
91
92<h3 class=fn><a name="QAxObject-3"></a>QAxObject::QAxObject ( IUnknown&nbsp;*&nbsp;iface, <a href="qobject.html">QObject</a>&nbsp;*&nbsp;parent = 0, const&nbsp;char&nbsp;*&nbsp;name = 0 )
93</h3>
94Creates a QAxObject that wraps the COM object referenced by <em>iface</em>. <em>parent</em> and <em>name</em> are propagated to the <a href="qobject.html">QObject</a>
95contructor.
96
97<h3 class=fn><a name="~QAxObject"></a>QAxObject::~QAxObject ()
98</h3>
99Releases the COM object and destroys the QAxObject,
100cleaning up all allocated resources.
101
102<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 ( ) )
103</h3>
104Calls the COM object's method <em>function</em>, passing the
105parameters <em>var1</em>, <em>var1</em>, <em>var2</em>, <em>var3</em>, <em>var4</em>, <em>var5</em>,
106<em>var6</em>, <em>var7</em> and <em>var8</em>, and returns the value returned by
107the method, or an invalid <a href="qvariant.html">QVariant</a> if the method does not return
108a value or when the function call failed.
109<p> If <em>function</em> is a method of the object the string must be provided
110as the full prototype, for example as it would be written in a
111<a href="qobject.html#connect">QObject::connect</a>() call.
112<pre>
113 activeX-&gt;dynamicCall( "Navigate(const <a href="qstring.html">QString</a>&amp;)", "www.trolltech.com" );
114 </pre>
115
116<p> Alternatively a function can be called passing the parameters embedded
117in the string, e.g. above function can also be invoked using
118<pre>
119 activeX-&gt;dynamicCall("Navigate(\"www.trolltech.com\");
120 </pre>
121
122All parameters are passed as strings; it depends on the control whether
123they are interpreted correctly, and is slower than using the prototype
124with correctly typed parameters.
125<p> If <em>function</em> is a property the string has to be the name of the
126property. The property setter is called when <em>var1</em> is a valid QVariant,
127otherwise the getter is called.
128<pre>
129 activeX-&gt;dynamicCall( "Value", 5 );
130 <a href="qstring.html">QString</a> text = activeX-&gt;dynamicCall( "Text" ).toString();
131 </pre>
132
133Note that it is faster to get and set properties using
134<a href="qobject.html#property">QObject::property</a>() and <a href="qobject.html#setProperty">QObject::setProperty</a>().
135<p> It is only possible to call functions through <a href="qaxbase.html#dynamicCall">dynamicCall</a>() that
136have parameters or return values of datatypes supported by
137<a href="qvariant.html">QVariant</a>. See the <a href="qaxbase.html">QAxBase</a> class documentation for a list of
138supported and unsupported datatypes. If you want to call functions
139that have unsupported datatypes in the parameter list, use
140<a href="qaxbase.html#queryInterface">queryInterface</a>() to retrieve the appropriate COM interface, and
141use the function directly.
142<p> <pre>
143 IWebBrowser2 *webBrowser = 0;
144 activeX-&gt;queryInterface( IID_IWebBrowser2, (void**)&amp;webBrowser );
145 if ( webBrowser ) {
146 webBrowser-&gt;Navigate2( pvarURL );
147 webBrowser-&gt;Release();
148 }
149 </pre>
150
151<p> This is also more efficient.
152
153<p>Example: <a href="qaxcontainer-example-qutlook.html#x2720">qutlook/centralwidget.cpp</a>.
154<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 )
155</h3>
156This is an overloaded member function, provided for convenience. It behaves essentially like the above function.
157<p> Calls the COM object's method <em>function</em>, passing the
158parameters in <em>vars</em>, and returns the value returned by
159the method. If the method does not return a value or when
160the function call failed this function returns an invalid
161<a href="qvariant.html">QVariant</a> object.
162<p> The QVariant objects in <em>vars</em> are updated when the method has
163out-parameters.
164
165<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 ( ) )
166</h3>
167Returns a pointer to a QAxObject wrapping the COM object provided
168by the method or property <em>name</em>, passing passing the parameters
169<em>var1</em>, <em>var1</em>, <em>var2</em>, <em>var3</em>, <em>var4</em>, <em>var5</em>, <em>var6</em>,
170<em>var7</em> and <em>var8</em>.
171<p> If <em>name</em> is provided by a method the string must include the
172full function prototype.
173<p> If <em>name</em> is a property the string must be the name of the property,
174and <em>var1</em>, ... <em>var8</em> are ignored.
175<p> The returned QAxObject is a child of this object (which is either of
176type QAxObject or <a href="qaxwidget.html">QAxWidget</a>), and is deleted when this object is
177deleted. It is however safe to delete the returned object yourself,
178and you should do so when you iterate over lists of subobjects.
179<p> COM enabled applications usually have an object model publishing
180certain elements of the application as dispatch interfaces. Use
181this method to navigate the hierarchy of the object model, e.g.
182<p> <pre>
183 <a href="qaxwidget.html">QAxWidget</a> outlook( "Outlook.Application" );
184 QAxObject *session = outlook.<a href="qaxbase.html#querySubObject">querySubObject</a>( "Session" );
185 if ( session ) {
186 QAxObject *defFolder = session-&gt;<a href="qaxbase.html#querySubObject">querySubObject</a>(
187 "GetDefaultFolder(OlDefaultFolders)",
188 "olFolderContacts" );
189 //...
190 }
191 </pre>
192
193
194<p>Example: <a href="qaxcontainer-example-qutlook.html#x2721">qutlook/centralwidget.cpp</a>.
195<!-- eof -->
196<hr><p>
197This file is part of the <a href="index.html">Qt toolkit</a>.
198Copyright &copy; 1995-2007
199<a href="http://www.trolltech.com/">Trolltech</a>. All Rights Reserved.<p><address><hr><div align=center>
200<table width=100% cellspacing=0 border=0><tr>
201<td>Copyright &copy; 2007
202<a href="troll.html">Trolltech</a><td align=center><a href="trademarks.html">Trademarks</a>
203<td align=right><div align=right>Qt 3.3.8</div>
204</table></div></address></body>
205</html>
Note: See TracBrowser for help on using the repository browser.