Add \brief comments to ActiveQt examples.
[qt:qtactiveqt.git] / src / activeqt / doc / src / examples / qutlook.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2012 Digia Plc and/or its subsidiary(-ies).
4 ** Contact: http://www.qt-project.org/legal
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and Digia.  For licensing terms and
14 ** conditions see http://qt.digia.com/licensing.  For further information
15 ** use the contact form at http://qt.digia.com/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*! 
29     \example activeqt/qutlook
30     \title Qutlook Example (ActiveQt)
31
32     \brief The Qutlook example demonstrates the use of ActiveQt to automate
33     Outlook. The example makes use of the \l dumpcpp tool to generate
34     a C++ namespace for the type library describing the Outlook
35     Object Model.
36
37     The project file for the example looks like this:
38
39     \snippet examples/activeqt/qutlook/qutlook.pro 1
40     \snippet examples/activeqt/qutlook/qutlook.pro 2
41
42     The project file uses the \c dumpcpp tool to add an MS Outlook type library to the project.
43     If this fails, then the generated makefile will just print an error message, otherwise
44     the build step will now run the \e dumpcpp tool on the type library, and 
45     generate a header and a cpp file (in this case, \c msoutl.h and \c msoutl.cpp) that 
46     declares and implement an easy to use API to the Outlook objects.
47
48     \snippet examples/activeqt/qutlook/addressview.h 0
49
50     The AddressView class is a QWidget subclass for the user interface. The QTreeView widget
51     will display the contents of Outlook's Contact folder as provided by the \c{model}.
52
53     \snippet examples/activeqt/qutlook/addressview.cpp 0
54     The AddressBookModel class is a QAbstractListModel subclass that communicates directly with 
55     Outlook, using a QHash for caching.
56
57     \snippet examples/activeqt/qutlook/addressview.cpp 1
58     The constructor initializes Outlook. The various signals Outlook provides to notify about 
59     contents changes are connected to the \c updateOutlook() slot.
60
61     \snippet examples/activeqt/qutlook/addressview.cpp 2
62     The destructor logs off from the session.
63
64     \snippet examples/activeqt/qutlook/addressview.cpp 3
65     The \c rowCount() implementation returns the number of entries as reported by Outlook. \c columnCount
66     and \c headerData are implemented to show four columns in the tree view.
67
68     \snippet examples/activeqt/qutlook/addressview.cpp 4
69     The \c headerData() implementation returns hardcoded strings.
70
71     \snippet examples/activeqt/qutlook/addressview.cpp 5
72     The \c data() implementation is the core of the model. If the requested data is in the cache the
73     cached value is used, otherwise the data is acquired from Outlook.
74
75     \snippet examples/activeqt/qutlook/addressview.cpp 6
76     The \c changeItem() slot is called when the user changes the current entry using the user interface.
77     The Outlook item is accessed using the Outlook API, and is modified using the property setters.
78     Finally, the item is saved to Outlook, and removed from the cache. Note that the model does not
79     signal the view of the data change, as Outlook will emit a signal on its own.
80
81     \snippet examples/activeqt/qutlook/addressview.cpp 7
82     The \c addItem() slot calls the CreateItem method of Outlook to create a new contact item,
83     sets the properties of the new item to the values entered by the user and saves the item.
84
85     \snippet examples/activeqt/qutlook/addressview.cpp 8
86     The \c update() slot clears the cache, and emits the reset() signal to notify the view about the
87     data change requiring a redraw of the contents.
88
89     \snippet examples/activeqt/qutlook/addressview.cpp 9
90     \snippet examples/activeqt/qutlook/addressview.cpp 10
91     The rest of the file implements the user interface using only Qt APIs, i.e. without communicating
92     with Outlook directly.
93
94     \snippet examples/activeqt/qutlook/main.cpp 0
95
96     The \c main() entry point function finally instantiates the user interface and enters the
97     event loop.
98
99     To build the example you must first build the QAxContainer
100     library. Then run your make tool in \c examples/activeqt/qutlook
101     and run the resulting \c qutlook.exe.
102 */