diff options
Diffstat (limited to 'doc/src/qaxcontainer.qdoc')
| -rw-r--r-- | doc/src/qaxcontainer.qdoc | 260 |
1 files changed, 260 insertions, 0 deletions
diff --git a/doc/src/qaxcontainer.qdoc b/doc/src/qaxcontainer.qdoc new file mode 100644 index 0000000..48c76fc --- /dev/null +++ b/doc/src/qaxcontainer.qdoc @@ -0,0 +1,260 @@ +/**************************************************************************** +** +** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies). +** Contact: Qt Software Information (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 qt-sales@nokia.com. +** $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: Qt Software Information (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 +*/ |