1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
|
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file. Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://www.qtsoftware.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\module QAxContainer
\title QAxContainer Module
\contentspage Qt's Modules
\previouspage QtTest
\nextpage QAxServer
\ingroup modules
\brief The QAxContainer module is a Windows-only extension for
accessing ActiveX controls and COM objects.
The QAxContainer module is part of the \l ActiveQt framework. It
provides a library implementing a QWidget subclass, QAxWidget,
that acts as a container for ActiveX controls, and a QObject
subclass, QAxObject, that can be used to easily access non-visual
COM objects. Scripting COM objects embedded using these classes
is possible through the QAxScript, QAxScriptManager and
QAxScriptEngine classes, and a set of \l{Tools for ActiveQt}{tools}
makes it easy to access COM objects programmatically.
The module consists of six classes
\list 1
\o QAxBase is an abstract class that provides an API to initialize
and access a COM object or ActiveX control.
\o QAxObject provides a QObject that wraps a COM object.
\o QAxWidget is a QWidget that wraps an ActiveX control.
\o QAxScriptManager, QAxScript and QAxScriptEngine provide an
interface to the Windows Script Host.
\endlist
Some \l{Qt Examples#ActiveQt}{example applications} that use
standard ActiveX controls to provide high-level user interface
functionality are provided.
\sa {ActiveQt Framework}
Topics:
\tableofcontents
\section1 Using the Library
To build Qt applications that can host COM objects and ActiveX controls
link the application against the QAxContainer module by adding
\snippet doc/src/snippets/code/doc_src_qaxcontainer.qdoc 0
to your application's \c .pro file.
\section2 Distributing QAxContainer Applications
The QAxContainer library is static, so there is no need to redistribute
any additional files when using this module. Note however that the
ActiveX server binaries you are using might not be installed on the
target system, so you have to ship them with your package and register
them during the installation process of your application.
\section1 Instantiating COM Objects
To instantiate a COM object use the QAxBase::setControl() API, or pass
the name of the object directly into the constructor of the QAxBase
subclass you are using.
The control can be specified in a variety of formats, but the fastest
and most powerful format is to use the class ID (CLSID) of the object
directly. The class ID can be prepended with information about a remote
machine that the object should run on, and can include a license key
for licensed controls.
\section2 Typical Error Messages
ActiveQt prints error messages to the debug output when it
encounters error situations at runtime. Usually you must run
your program in the debugger to see these messages (e.g. in Visual
Studio's Debug output).
\section3 Requested control could not be instantiated
The control requested in QAxBase::setControl() is not installed
on this system, or is not accessible for the current user.
The control might require administrator rights, or a license key.
If the control is licensed, pass the license key to QAxBase::setControl
as documented.
\section1 Accessing the Object API
ActiveQt provides a Qt API to the COM object, and replaces COM
datatypes with Qt equivalents.
There are four ways to call APIs on the COM object:
\list
\o Generating a C++ namespace
\o Call-by-name
\o Through a script engine
\o Using the native COM interfaces
\endlist
\section2 Generating a C++ Namespace
To generate a C++ namespace for the type library you want to access,
use the \l dumpcpp tool. Run this tool manually on the type library you
want to use, or integrate it into the build system by adding the type
libraries to the \c TYPELIBS variable in your application's \c .pro file:
\snippet doc/src/snippets/code/doc_src_qaxcontainer.qdoc 1
Note that \l dumpcpp might not be able to expose all APIs in the type
library.
Include the resulting header file in your code to access the
object APIs through the generated C++ classes. See the
\l{activeqt/qutlook}{Qutlook} example for more information.
\section2 Call-by-Name
Use QAxBase::dynamicCall() and QAxBase::querySubObject() as well as
the QObject::setProperty() and QObject::property() APIs to call the
methods and properties of the COM object through their name. Use the
\l dumpdoc tool to get the documentation of the Qt API for any COM
object and its subobjects; note that not all of the COM object's APIs
might be available.
See the \l{activeqt/webbrowser}{Webbrowser} example for more information.
\section2 Calling Function Through a Script Engine
A Qt application can host any ActiveScript engine installed on the system.
The script engine can then run script code that accesses the COM objects.
To instantiate a script engine, use QAxScriptManager::addObject() to
register the COM objects you want to access from script, and
QAxScriptManager::load() to load the script code into the engine. Then
call the script functions using QAxScriptManager::call() or
QAxScript::call().
Which APIs of the COM object are available through scripting depends on
the script language used.
The \l{testcon - An ActiveX Test Container (ActiveQt)}{ActiveX Test Container}
demonstrates loading of script files.
\section2 Calling a Function Using the Native COM Interfaces
To call functions of the COM object that can not be accessed via any
of the above methods it is possible to request the COM interface directly
using QAxBase::queryInterface(). To get a C++ definition of the respective
interface classes use the \c #import directive with the type library
provided with the control; see your compiler manual for details.
\section2 Typical Error Messages
ActiveQt prints error messages to the debug output when it
encounters error situations at runtime. Usually you must run
your program in the debugger to see these messages (e.g. in Visual
Studio's Debug output).
\section3 QAxBase::internalInvoke: No such method
A QAxBase::dynamicCall() failed - the function prototype did not
match any function available in the object's API.
\section3 Error calling IDispatch member: Non-optional parameter missing
A QAxBase::dynamicCall() failed - the function prototype was correct,
but too few parameters were provided.
\section3 Error calling IDispatch member: Type mismatch in parameter n
A QAxBase::dynamicCall() failed - the function prototype was correct,
but the paramter at index \c n was of the wrong type and could
not be coerced to the correct type.
\section3 QAxScriptManager::call(): No script provides this function
You try to call a function that is provided through an engine
that doesn't provide introspection (ie. ActivePython or
ActivePerl). You need to call the function directly on the
respective QAxScript object.
\section1 License Information
The QAxContainer module is not covered by the \l{GNU General Public License (GPL)},
the \l{GNU Lesser General Public License (LGPL)}, or the
\l{Qt Commercial Editions}{Qt Commercial License}. Instead, it is distributed under
the following license.
\legalese
Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).\br
All rights reserved.
Contact: Nokia Corporation (qt-info@nokia.com)\br
You may use this file under the terms of the BSD license as follows:\br
"Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
* Redistributions of source code must retain the above copyright notice, this list
of conditions and the following disclaimer.\br
* Redistributions in binary form must reproduce the above copyright notice, this
list of conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.\br
* Neither the name of Nokia Corporation and its Subsidiary(-ies) nor the names of
its contributors may be used to endorse or promote products derived from this
software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
\endlegalese
*/
|
