diff options
Diffstat (limited to 'doc/src/examples/activeqt/comapp.qdoc')
| -rw-r--r-- | doc/src/examples/activeqt/comapp.qdoc | 124 |
1 files changed, 124 insertions, 0 deletions
diff --git a/doc/src/examples/activeqt/comapp.qdoc b/doc/src/examples/activeqt/comapp.qdoc new file mode 100644 index 0000000..05f3fb5 --- /dev/null +++ b/doc/src/examples/activeqt/comapp.qdoc @@ -0,0 +1,124 @@ +/**************************************************************************** +** +** 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$ +** +****************************************************************************/ + +/*! + \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: + + \snippet doc/src/snippets/code/doc_src_examples_activeqt_comapp.qdoc 0 + + To build the example you must first build the QAxServer library. + Then run \c qmake and your make tool in + \c{examples\activeqt\comapp}. +*/ |