1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** 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 The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example messagenavigator
\title MessageNavigator Example
The MessageNavigator example shows how to create a client application
which displays messages stored by the Messaging Framework. The
example application allows the user to browse for messages using a tree
view to expose the hierarchical structure of email accounts that use folders.
It displays the messages in each folder in a list, and when a message is
selected, it uses Qt Extended services to delegate the display of the
message to another application.
\image messagenavigator-example.png Screenshot of the MessageNavigator example
The application is structured as a stack of widgets, contained by a
QStackedWidget. We need two widgets in our stack: one to select a folder
from a tree, and another to select a message from a list.
The example application uses the Messaging Framework Client library's
QMailMessageSetModel class to build a model of the messages in the Qt
Extended mail store. It divides all the messages into groups, first by the
account to which they belong, and within an account, by the folder where
they are located. This task is performed by subclassing the
QMailMessageSetModel class to create our FolderModel class:
\quotefromfile messagenavigator/foldermodel.h
\skipto class FolderModel
\printuntil };
The base class is specialized in two ways. The content of the model is
determined by adding the necessary items in the constructor, and the
data elements that are displayed for each item are augmented with an
icon by overriding the \l{QMailMessageSetModel::data()}{data} function.
The content of the model is configured by appending the items we want to
display to the model, in the constructor. To the empty model, we successively
append a new QMailAccountMessageSet item for each account in the mail store:
\quotefromfile messagenavigator/foldermodel.cpp
\skipto FolderModel::FolderModel
\printuntil }
The QMailAccountMessageSet class represents a message set defined by
selecting all messages associated with the account the item is configured
with. The constructor for QMailAccountMessageSet takes a parent
container to which it should be appended, and the identifier of the account
that it should represent. It also takes a third parameter, which is used
to specify the optional \c hierarchical property. If \c hierarchical is true,
then the QMailAccountMessageSet class will automatically maintain
a tree of QMailFolderMessageSet items as child items, corresponding to
the folders belonging to the relevant account in the mail store. This
determines the entire content of our model.
In order to customize the display of the items in our tree view, the
FolderModel class overrides the \l{QMailMessageSetModel::data()}{data} function
of QMailMessageSetModel and provides data for the Qt::DecorationRole value
used by QtopiaItemDelegate:
\quotefromfile messagenavigator/foldermodel.cpp
\skipto FolderModel::data
\printto end-data
For our application, we create a FolderSelector widget which uses a QTreeView
to present our folder model:
\quotefromfile messagenavigator/messagenavigator.cpp
\skipto class FolderSelector
\printto Adjust FolderSelector
\skipuntil end-Adjust
\printuntil };
When we select an item from the tree view, we extract the QMailMessageSet
object represented by the selected item, and emit that data to our MessageSelector
object:
\quotefromfile messagenavigator/messagenavigator.cpp
\skipto FolderSelector::activated
\printuntil }
Once we have selected a message set, we will display a listing of the messages
defined by that message set. For this, we need a stackable widget to list messages.
The MessageSelector uses a QListView to present a listing of messages
associated with a specific contact. To do this, we need to create a
model of message data that the QListView will present. Our class
therefore contains a QMailMessageListModel object, and a QMailMessageDelegate
object, whose responsibility is to render each element in the list
view using the data of each message.
\quotefromfile messagenavigator/messagenavigator.cpp
\skipto class MessageSelector
\printto Adjust MessageSelector
\skipuntil end-Adjust
\printuntil };
Now that we have widgets to display our folder model and a message list,
we simply need to connect them together:
\quotefromfile messagenavigator/messagenavigator.cpp
\skipto MessageNavigator::MessageNavigator
\printto Adjust MessageNavigator
\skipuntil end-Adjust
\printuntil }
\skipto MessageNavigator::showFolderTree
\printuntil }
When we have a folder selected from our folder tree, we create a
list of messages corresponding to that folder. The QMailMessageListModel
provides the setKey() function, which allows the caller to specify the
messages to be listed by providing a QMailMessageKey object that selects
them from the mail store. We can use the messageKey() function of the
QMailMessageSet object selected in the FolderSelector to acquire a
message key for our model:
\quotefromfile messagenavigator/messagenavigator.cpp
\skipto void MessageSelector::listMessages(
\printto end-listMessages
When the message list has been prepared, we move our message list to
the top of the widget stack, in MessageNavigator::showMessageList():
\skipto void MessageNavigator::showMessageList(
\printuntil }
Finally, we handle the event where the user selects a message from our
list. Rather than displaying the message ourself, we will use the
QtopiaServiceRequest mechanism to request that another application
handle this task for us. The \c Messages service exports a \c viewMessage
function, which takes a QMailMessageId object as a parameter; we respond to the
user's selection by invoking this service with the identifier of the
message that they selected:
\skipto void MessageNavigator::viewMessage(
\printuntil }
\sa {MessageViewer Example}
*/
|
