/*!
    \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.

    \quotefromfile activeqt/comapp/main.cpp
    \skipto class Application :
    \printuntil };
    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.

    \quotefromfile activeqt/comapp/main.cpp
    \skipto class DocumentList :
    \printuntil };
    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.

    \quotefromfile activeqt/comapp/main.cpp
    \skipto class Document :
    \printuntil };

    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.

    \skipto Document::Document(
    \printto DocumentList::DocumentList(
    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.

    \printto Application::Application(
    The \c DocumentList implementation is straightforward.

    \printuntil #include
    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.

    \printto int main(
    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.

    \printuntil }
    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}.
*/
