Long live Qt!

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
+*/