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
|
/****************************************************************************
**
** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
** 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 Digia. For licensing terms and
** conditions see http://qt.digia.com/licensing. For further information
** use the contact form at http://qt.digia.com/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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\example samplephonebook
\title Sample Phonebook Example
\tableofcontents
\section1 Phone Book
This example shows how to write a simple phonebook with the \l{Contacts}{Contacts API}.
\section2 Motivation
This application was written to provide an example to developers of how to use the QtContacts and
QtVersit APIs.
It provides an example of how to use the QtMobility libraries to:
\list
\o select a backend for persistent storage
\o list the stored contacts
\o add contacts
\o edit contacts
\o use filters to find contacts matching certain criteria
\o import and export contact lists as vCards\reg *
\endlist
[*] \i{vCard is a registered trademark of the Internet Mail Consortium}
\section2 Use Case
Most people have a need to store information (such as addresses, telephone numbers and email addresses)
of people that they know. This sample application provides a simple phone book that allows users
to store certain pieces of information about their contacts, and save them to the contacts database of
their device.
\section2 Interface
The application is designed to work on desktop and mobile platforms with
minimal differences in code between the platforms. The interface is
organized into a paged view, showing the \i {Contact List} by default.
Contacts can be added, edited or deleted using the buttons at the bottom
of the contact list.
To search for a contact in the list, a filter can be applied using the
\i {Apply Filter} item in the \i Contacts menu.
Here we see the \i {Contact List} with some names added.
\image sample-phonebook-1.png
When adding a new contact a new page is shown, with a \i{Set Picture}
button to import an image. It is a good idea to use smaller images if
you intend to export the contacts to a file later.
\image sample-phonebook-2.png
From the main menu, \i{Contacts}, you can select \i{Apply Filter}. This
will display a new page which enables the user to specify filter criteria.
In the screenshot below, we are selecting based on the first two characters
of the Name,
\image sample-phonebook-3.png
which gives us a subset of the list of contacts.
\image sample-phonebook-4.png
To reset this, just select \i{Clear Filter} from the \i {Contacts} menu.
The contact list can also be imported and exported to the vCard format
through the \i {Import Contacts} and \i {Export Contacts} items in the
\i Contacts menu. This functionality can be used to populate the
list from another device or application.
\section2 Known Issues
The example is not intended to be feature complete. Only a very limited subset of detail types are
supported by the application. It exercises only a very small portion of the Qt Contacts API.
In particular:
\list
\o The example only exercises the synchronous API of QtContacts. For most real applications, the
asynchronous API is the preferred interface to use as it does not block the GUI while a query
is made to the contacts backend.
\o Detail subtypes and contexts are not supported by the interface.
\o Duplicate contacts are not filtered out - importing the same contact twice results in two
identical contacts appearing in the list. In a real application, more complex synchronization
code may be required.
\o Contact groups are not supported. The QtContacts API supports two methods of grouping contacts.
One way is to use contacts of type \l{QContactType::TypeGroup}{TypeGroup}, along with the
\l{QContactRelationship::HasMember}{HasMember} QContactRelationship. The other way is to use
the QContactTag detail by giving related contacts the same tag. A real application may support
grouping via one or both of these methods.
\endlist
This application has the following known issues on Harmattan:
\list
\o You cannot edit contacts because tapping QLineEdit widget does not open the virtual keyboard.
See \l{https://bugreports.qt.nokia.com/browse/QTBUG-23144}{QTBUG-23144}
\o You cannot set a thumbnail image for contacts. See \l{https://bugreports.qt.nokia.com/browse/QTMOBILITY-1992}{QTMOBILITY-1992}
*/
|
