/usr/share/doc/qmf/html/messageviewer.html is in qmf-doc-html 1.0.7~2011w23.2-2.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<!-- messageviewer.qdoc -->
<head>
<title>MessageViewer Example</title>
<link href="classic.css" rel="stylesheet" type="text/css" />
</head>
<body>
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td align="left" valign="top" width="32"><img src="images/qtlogo.png" align="left" border="0" /></td>
<td width="1"> </td><td class="postheader" valign="center"><a href="index.html"><font color="#004faf">Home</font></a></td>
<td align="right" valign="top" width="230"><img src="images/codeless.png" border="0" /></td></tr></table><h1 class="title">MessageViewer Example<br /><span class="subtitle"></span>
</h1>
<p>The MessageViewer example shows how to create a client application which accesses messages stored by the Messaging Framework. The example application searches for, and displays the properties of messages stored by the Messaging Framework, but uses Qt Extended services to delegate the display of the messages to another application.</p>
<p align="center"><img src="images/messageviewer-example.png" alt="Screenshot of the MessageViewer example" /></p><p>The example application uses the Qt Extended PIM library's Contacts listing to list the messages stored on the device, by contact. The application starts by allowing the user to select a contact from those stored on the device. Once a contact has been selected, a list of all the messages exchanged with that contact is displayed. When a message is selected from this list, the application creates a QtopiaServiceRequest to request that another application display the content of the selected message.</p>
<p>The application is structured as a stack of widgets, contained by a <a href="http://doc.trolltech.com/4.5/qstackedwidget.html">QStackedWidget</a>. We need two widgets in our stack: one to select a contact from a list, and another to select a message from a list.</p>
<p>The contact selector widget uses a QContactListView to present a list of available contacts:</p>
<pre></pre>
<p>Once we have selected a contact, we will display a listing of the messages that have been exchanged with the contact. For this, we need a stackable widget to list messages:</p>
<pre></pre>
<p>The MessageSelector uses a <a href="http://doc.trolltech.com/4.5/qlistview.html">QListView</a> 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 <a href="http://doc.trolltech.com/4.5/qlistview.html">QListView</a> will present. Our class therefore contains a model object, of type MessageModel, and an object of type MessageDelegate, whose responsibility is to render each element in the list view using the data of each message.</p>
<p>The MessageModel class is derived from <a href="http://doc.trolltech.com/4.5/qstandarditemmodel.html">QStandardItemModel</a>, which is extended with a simple interface. With setContact(), we supply the model with a QContact, and it creates a listing of messages associated with that contact. It also provides the utility function messageId() which we use to extract the identifier of a message from the listing, given an index into the model.</p>
<pre></pre>
<p>The Messaging Framework Client library uses <a href="qmailmessageid.html">QMailMessageId</a> objects to identify messages stored in the system. <a href="qmailmessageid.html">QMailMessageId</a> objects can be default-constructed to an uninitialised state that does not identify any message, or they can contain the identifier for any message stored in the device. When we wish to view a message, the identifier for that message is all that we will need in order to request that another application display the message.</p>
<p>The MessageModel class uses a helper class to contain the data elements relevant to each individual message that we will list. The helper class, MessageItem, is derived from <a href="http://doc.trolltech.com/4.5/qstandarditem.html">QStandardItem</a>:</p>
<pre></pre>
<p>The MessageModel::setContact() member function does the work of finding messages associated with a contact, and adding them to our data model. To find messages, we use the <a href="qmailstore.html#queryMessages">QMailStore::queryMessages</a>() function. One of the overloads of this function takes a <a href="qmailmessagekey.html">QMailMessageKey</a> parameter, which contains the filtering information needed to locate a subset of the device's messages. A <a href="qmailmessagekey.html">QMailMessageKey</a> contains three data elements: a message property, a value, and a relation to compare the value to the specified property of each message. More complicated filters can be created by logically composing <a href="qmailmessagekey.html">QMailMessageKey</a> objects, with AND and OR operators.</p>
<p>For our application, we want to find messages that are related to the contact that the user has chosen. So, we will find messages that fit into either of two categories: those that were sent to the contact, and those that were received from the contact.</p>
<pre></pre>
<p>The contact may have numerous phone numbers, so we pass over the list of phone numbers stored for this contact, and for each phone number, we add another filter criterion to our query. For messages we received from the contact, we add a <a href="qmailmessagekey.html">QMailMessageKey</a> matching where the message's <tt>Sender</tt> property is equal to the current phone number (note that the <tt>Equal</tt> relation is the default, so we don't need to specify it explicitly.) For messages that we sent to the contact, we add a <a href="qmailmessagekey.html">QMailMessageKey</a> matching where the message's <tt>Recipients</tt> property contains the current number. Unlike <tt>Sender</tt>, a messages's <tt>Recipients</tt> property can contain multiple contact's addresses, so we need to use the <tt>Includes</tt> relation instead of the default <tt>Equal</tt>.</p>
<pre></pre>
<p>We also want to locate messages exchanged with this contact using email, so we add further criteria to our filters for each email address that is stored for this contact:</p>
<pre></pre>
<p>Now we have created the message filters we want, we use the <a href="qmailstore.html#queryMessages">QMailStore::queryMessages</a>() function to locate the matching messages. This function applies the criteria of the supplied <a href="qmailmessagekey.html">QMailMessageKey</a> to each message stored by the Messaging Framework, and returns a list containing the <a href="qmailmessageid.html">QMailMessageId</a> of each matching message. An overload of the function takes a second parameter: a <a href="qmailmessagesortkey.html">QMailMessageSortKey</a> which determines the order in which the matching messages are returned. We will use this option to sort the messages into reverse chronological order.</p>
<pre></pre>
<p>We then take each <a href="qmailmessageid.html">QMailMessageId</a> from the list, and create a new MessageItem object from each one, to add to our model:</p>
<pre></pre>
<p>The MessageItem class stores the data we need to present each message in our <a href="http://doc.trolltech.com/4.5/qlistview.html">QListView</a>. In order to present a useful listing of the message, we need to extract some data from the message. We do this using the <a href="qmailmessagemetadata.html">QMailMessageMetaData</a> class, which has a constructor taking a <a href="qmailmessageid.html">QMailMessageId</a>. Since we only need summary information to present the message in the list view, we only want to load the meta data for the message identified by the <a href="qmailmessageid.html">QMailMessageId</a>. If we needed to access the content of the message, we would instead need to create an instance of the <a href="qmailmessage.html">QMailMessage</a> class.</p>
<p>Once we have loaded the message information, we extract some useful elements (such as the message subject, the message timestamp, and the type of the message), and store those items for the <a href="http://doc.trolltech.com/4.5/qlistview.html">QListView</a> delegate to use when rendering the message item:</p>
<pre></pre>
<p>The MessageDelegate class simply takes the data items stored by each MessageItem instance, and uses them to render a representation of the message.</p>
<p>Now that we have widgets to list contacts and messages, we simply need to connect them together:</p>
<pre></pre>
<p>When we have a contact selected from our contact list, we create a list of messages for that contact. This is handled by the MessageSelector::listMessages() function:</p>
<pre></pre>
<p>When the message list has been prepared, we move our message list to the top of the widget stack, in MessageViewer::showMessageList():</p>
<pre></pre>
<p>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 <tt>Messages</tt> service exports a <tt>viewMessage</tt> function, which takes a <a href="qmailmessageid.html">QMailMessageId</a> object as a parameter; we respond to the user's selection by invoking this service with the identifier of the message that they selected:</p>
<pre></pre>
<p>See also <a href="messagenavigator.html">MessageNavigator Example</a>.</p>
<p /><address><hr /><div align="center">
<table width="100%" cellspacing="0" border="0"><tr class="address">
<td align="left">Copyright © 2010 QtSoftware</td>
<td align="right"><div align="right">Messaging Framework</div></td>
</tr></table></div></address></body>
</html>
|