/****************************************************************************
**
** Copyright (C) 2004-2007 Trolltech ASA. All rights reserved.
**
** This file is part of the documentation of the Qt Toolkit.
**
** This file may be used under the terms of the GNU General Public
** License version 2.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 GNU
** General Public Licensing requirements will be met:
** http://trolltech.com/products/qt/licenses/licensing/opensource/
**
** If you are unsure which license is appropriate for your use, please
** review the following information:
** http://trolltech.com/products/qt/licenses/licensing/licensingoverview
** or contact the sales department at sales@trolltech.com.
**
** In addition, as a special exception, Trolltech gives you certain
** additional rights. These rights are described in the Trolltech GPL
** Exception version 1.0, which can be found at
** http://www.trolltech.com/products/qt/gplexception/ and in the file
** GPL_EXCEPTION.txt in this package.
**
** In addition, as a special exception, Trolltech, as the sole copyright
** holder for Qt Designer, grants users of the Qt/Eclipse Integration
** plug-in the right for the Qt/Eclipse Integration to link to
** functionality provided by Qt Designer and its related libraries.
**
** Trolltech reserves all rights not expressly granted herein.
**
** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
**
****************************************************************************/

/*!
    \example activeqt/comapp
    \title COM App Example (ActiveQt)

    The COM App example shows how to use ActiveQt to develop a Qt
    application that can be automated via COM. Different QObject
    based classes are exposed as COM objects that communicate with the
    GUI of the running Qt application. The APIs of those COM objects
    has been designed to resemble the APIs of standard COM
    applications; i.e. those from Microsoft Office.

    \snippet examples/activeqt/comapp/main.cpp 2
    The first class \c Application represents the application object. It
    exposes read-only properties \c documents and \c id to get access to the
    list of documents, and an identifier. A read/write property \c visible
    controls whether the QTabWidget-based user interface of the application 
    should be visible, and a slot \c quit() terminates the application.

    The \e RegisterObject attribute is set to make sure that instances of this
    class are registered in COM's running object table (ROT) - this allows COM
    clients to connect to an already instantiated COM object.

    \snippet examples/activeqt/comapp/main.cpp 1
    The \c DocumentList class stores a list of documents. It provides an API
    to read the number of documents, to access each document by index and to 
    create a new document. The \c application property returns the root object.

    \snippet examples/activeqt/comapp/main.cpp 0

    The \c Document class finally represents a document in the application.
    Each document is represented by a page in the application's tab widget, and
    has a title that is readable and writable through the document's API.
    The \c application property again returns the root object.

    \snippet examples/activeqt/comapp/main.cpp 3
    The implementation of the \c Document class creates a new page for the tab
    widget, and uses the title of that page for the title property. The page 
    is deleted when the document is deleted.

    \snippet examples/activeqt/comapp/main.cpp 4
    The \c DocumentList implementation is straightforward.

    \snippet examples/activeqt/comapp/main.cpp 5
    The \c Application class initializes the user interface in the constructor,
    and shows and hides it in the implementation of \c setVisible(). The object
    name (accessible through the \c id property) is set to \c "From QAxFactory" 
    to indicate that this COM object has been created by COM. Note that there is 
    no destructor that would delete the QTabWidget - this is instead done in the 
    \c quit() slot, before calling QApplication::quit() through a single-shot-timer, 
    which is necessary ensure that the COM call to the slot is complete.

    \snippet examples/activeqt/comapp/main.cpp 6
    The classes are exported from the server using the QAxFactory macros. Only
    \c Application objects can be instantiated from outside - the other APIs can
    only be used after accessing the respective objects throught the \c Application
    API.

    \snippet examples/activeqt/comapp/main.cpp 7
    The main() entry point function creates a QApplication, and just enters the
    event loop if the application has been started by COM. If the application
    has been started by the user, then the \c Application object is created and 
    the object name is set to "From Application". Then the COM server is started,
    and the application object is registered with COM. It is now accessible to
    COM clients through the client-specific APIs.

    Application exiting is controlled explicitly - if COM started the application, 
    then the client code has to call quit(); if the user started the application,
    then the application terminates when the last window has been closed.

    Finally, the user interface is made visible, and the event loop is started.

    A simple Visual Basic application could now access this Qt application. In VB,
    start a new "Standard Exe" project and add a project reference to the comappLib
    type library. Create a form with a listbox "DocumentList", a static label 
    "DocumentsCount" and a command button "NewDocument". Finally, implement the code 
    for the form like this:

    \code
        Private Application As comappLib.Application
        Private MyApp As Boolean

        Private Sub UpdateList()
            DocumentList.Clear
            DocumentsCount.Caption = Application.documents.Count
            For Index = 0 To Application.documents.Count - 1
               DocumentList.AddItem (Application.documents.Item(Index).Title)
            Next
        End Sub

        Private Sub Form_Load()
            On Error GoTo CreateNew
            Set Application = GetObject(, "comapp.Application")
            MyApp = False
            GoTo Initialized
        CreateNew:
            On Error GoTo InitializeFailed
            Set Application = New Application
            Application.Visible = True
            MyApp = True
        Initialized:
            Caption = Application.id
            UpdateList
        InitializeFailed:
        End Sub

        Private Sub Form_Unload(Cancel As Integer)
            If MyApp Then
                Application.quit
            End If
        End Sub

        Private Sub NewDocument_Click()
            Application.documents.addDocument
            UpdateList
        End Sub
    \endcode

    To build the example you must first build the QAxServer library.
    Then run \c qmake and your make tool in
    \c{examples\activeqt\comapp}.
*/
