← Back to branch summary

~oif-team/ubuntu/natty/qt4-x11/xi2.1

« back to all changes in this revision

Viewing changes to doc/src/qaxcontainer.qdoc

  • Committer: Bazaar Package Importer
  • Author(s): Alessandro Ghersi
  • Date: 2009-11-02 18:30:08 UTC
  • mfrom: (1.2.2 upstream)
  • mto: (15.2.5 experimental)
  • mto: This revision was merged to the branch mainline in revision 88.
  • Revision ID: james.westby@ubuntu.com-20091102183008-b6a4gcs128mvfb3m
Tags: upstream-4.6.0~beta1
Import upstream version 4.6.0~beta1

Show diffs side-by-side

added added

removed removed

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