/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.  For licensing terms and
** conditions see http://qt.digia.com/licensing.  For further information
** use the contact form at http://qt.digia.com/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file.  Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
    \module QAxContainer
    \title QAxContainer C++ Classes
    \ingroup modules
    \qtvariable axcontainer

    \brief The QAxContainer module is a Windows-only extension for
    accessing ActiveX controls and COM objects.

    QAxContainer is part of the \l{Active Qt} module.
    The \l{Using ActiveX controls and COM in Qt} page contains information about
    containers for ActiveX controls.

    \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 License}. Instead, it is distributed under
    the following license.

    \legalese
    Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).\br
    Contact: http://www.qt-project.org/legal\br

    You may use this file under the terms of the BSD license as follows:

    "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.
      * 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.
      * Neither the name of Digia Plc 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
*/

/*!
    \page activeqt-container.html
    \title Using ActiveX controls and COM in Qt
    \ingroup qt-activex

    \brief 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
    \li QAxBase is an abstract class that provides an API to initialize
       and access a COM object or ActiveX control.
    \li QAxObject provides a QObject that wraps a COM object.
    \li QAxWidget is a QWidget that wraps an ActiveX control.
    \li QAxScriptManager, QAxScript and QAxScriptEngine provide an
       interface to the Windows Script Host.
    \endlist

    Some \l{ActiveQt Examples}{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_qaxcontainer.pro 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
    \li Generating a C++ namespace
    \li Call-by-name
    \li Through a script engine
    \li 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_qaxcontainer.pro 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 parameter 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.
*/
