← Back to branch summary

~chris.gagnon/+junk/qtpim-coverage

« back to all changes in this revision

Viewing changes to src/versit/doc/src/versit.qdoc

  • Committer: chris.gagnon
  • Date: 2013-12-10 23:09:37 UTC
  • Revision ID: chris.gagnon@canonical.com-20131210230937-2akf1ft1edcttk87
first post

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/versit/doc/src/versit.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 PIM Module.
 
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
 
 
30
\page versit.html
 
31
\title Qt Versit Overview
 
32
\brief An API to import and export to the vCard and iCalendar formats.
 
33
 
 
34
\ingroup qtpim-c++
 
35
 
 
36
\tableofcontents
 
37
 
 
38
\section1 Overview
 
39
The Versit API is part of a collection of
 
40
Personal Information Management API's providing a
 
41
library to convert \l{QContact}{QContacts} to and from
 
42
\l{http://en.wikipedia.org/wiki/Vcard}{vCard} files, and to convert
 
43
\l{QOrganizerItem}{QOrganizerItems} to and from
 
44
\l{http://en.wikipedia.org/wiki/ICalendar}{iCalendar} files.
 
45
 
 
46
Because vCard and iCalendar share the same structure, they are represented in
 
47
abstract form with a common class, namely QVersitDocument.  vCard and iCalendar
 
48
files can be parsed into QVersitDocument form using QVersitReader.
 
49
QVersitDocument objects can be written to an I/O device using QVersitWriter.
 
50
 
 
51
A QVersitDocument object can represent either a vCard or an iCalendar.
 
52
\l{QVersitDocument}{QVersitDocuments} representing vCards can be converted to
 
53
\l{QContact}{QContacts} using QVersitContactImporter.
 
54
\l{QVersitDocument}{QVersitDocuments} representing iCalendars can be converted
 
55
to \l{QOrganizerItem}{QOrganizerItems} using QVersitOrganizerImporter.
 
56
\l{QContact}{QContacts} and \l{QOrganizerItem}{QOrganizerItems} can be converted
 
57
to \l{QVersitDocument}{QVersitDocuments} using QVersitContactExporter and
 
58
QVersitOrganizerExporter, respectively.
 
59
 
 
60
Currently \l{QVersitReader} and \l{QVersitWriter} support
 
61
reading and writing vCard 2.1, vCard 3.0 and iCalendar 2.0 format documents.
 
62
Please note that the Organizer API is still under development, so
 
63
the Qt Versit API classes related to importing and exporting organizer items
 
64
is subject to change.
 
65
 
 
66
Versit \reg is a trademark of the Internet Mail Consortium.
 
67
 
 
68
For full list of classes, see \l{Qt Versit C++ API}.
 
69
 
 
70
\section1 Importing and Exporting Data
 
71
The following example goes through the process of reading a vCard and importing
 
72
it to QContact format, then exporting and writing it back out.
 
73
 
 
74
First, let's create some data to read.  In this case, we create a QBuffer as a demonstration, but
 
75
any QIODevice will work.
 
76
\snippet qtversitdocsample/qtversitdocsample.cpp Complete example - create
 
77
 
 
78
QVersitReader can be used to parse a vCard or iCalendar from an I/O device to
 
79
produce a list of QVersitDocuments.
 
80
\snippet qtversitdocsample/qtversitdocsample.cpp Complete example - read
 
81
 
 
82
QVersitDocuments aren't very useful to the QtContacts API.  They need to be imported using the
 
83
QVersitContactImporter.  If the QVersitDocuments were iCalendar objects, they could be imported
 
84
using QVersitOrganizerImporter.
 
85
\snippet qtversitdocsample/qtversitdocsample.cpp Complete example - import
 
86
 
 
87
Conversely, QVersitContactExporter can be used to convert from QContacts to QVersitDocuments.
 
88
(QVersitOrganizerExporter can be used for QOrganizerItem):
 
89
\snippet qtversitdocsample/qtversitdocsample.cpp Complete example - export
 
90
 
 
91
To complete the exporting process, QVersitWriter can be used to write to an I/O device.
 
92
\snippet qtversitdocsample/qtversitdocsample.cpp Complete example - write
 
93
 
 
94
\section1 Classes
 
95
The main classes for a client interested in importing or exporting vCard and
 
96
iCalendar documents are:
 
97
\list
 
98
    \li \l{QVersitProperty}
 
99
    \li \l{QVersitDocument}
 
100
    \li \l{QVersitReader}
 
101
    \li \l{QVersitWriter}
 
102
    \li \l{QVersitContactImporter}
 
103
    \li \l{QVersitContactExporter}
 
104
    \li \l{QVersitOrganizerImporter}
 
105
    \li \l{QVersitOrganizerExporter}
 
106
\endlist
 
107
 
 
108
It is also possible to extend the behaviour of the importer and exporter classes
 
109
by writing handlers and plugins.  For more details, see \l{Qt Versit Plugins}.
 
110
\annotatedlist versit-extension
 
111
 
 
112
\section1 Supported Features
 
113
Please see the following documents for supported Versit Module features:
 
114
 \list
 
115
    \li \l{vcardsupport}{Supported vCard Features} document for a list of vCard features
 
116
     that the Versit module supports.
 
117
    \li \l{icalsupport}{Supported iCalendar Features} document for a list of iCal features
 
118
     that the Organizer Versit module supports.
 
119
\endlist
 
120
*/