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
|
/****************************************************************************
**
** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the Technology Preview License Agreement accompanying
** this package.
**
** GNU Free Documentation License
** 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.
**
** If you have questions regarding the use of this file, please contact
** Nokia at qt-info@nokia.com.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\group gallery-requests
\title Document Gallery Requests
API for requesting information, and actions from a document gallery.
*/
/*!
\group gallery-filters
\title Document Gallery Filters
API for identifying documents within a gallery.
*/
/*!
\group gallery-galleries
\title Document Galleries.
API for document galleries.
*/
/*!
\group gallery-examples
\title Document Gallery Examples
*/
/*!
\page gallery.html
\group gallery
\title Document Gallery
\ingroup mobility
\brief An API to navigate and query documents using their meta-data.
\section1 Namespace
The QtMobility APIs are placed into the \i{QtMobility} namespace. This
is done to facilitate the future migration of QtMobility APIs into Qt. See
the \l {Quickstart Example}{Quickstart guide} for an example on how the
namespace impacts on application development.
\section1 Overview
The Document Gallery provides an API for navigating and querying documents
using their meta-data. The common use case would be populating the media
selection views of a music player, or image viewer. It also provides API's
for querying and editing the meta-data of individual documents.
Typically all files in user directories should be available in the
document gallery. The principal types are Audio, Video, Image, and
(Office) Document, but files can also be categorized as a File, Folder,
Text, or Playlist. There are also some meta-types composed from the
meta-data of files, these are Artist, Album, AudioGenre, and PhotoAlbum.
The document gallery API is composed of a set of asynchronous request
(\l QGalleryAbstractRequest) classes which talk to the system file indexing
service, this would be tracker on Maemo platforms, the meta-data system
(MDS) on Symbian and potentially Windows Search, or Spotlight on macs.
There are three requests; \l QGalleryQueryRequest takes a type, a parent
item, and some filtering criteria (\l QGalleryFilter) and returns
meta-data for all matching items.
\l QGalleryItemRequest takes an item ID and returns meta-data for just that
item. And \l QGalleryTypeRequest takes an item type and returns meta-data
describing that type.
The requests operate on implementations of the \l QAbstractGallery.
The default implementation is \l QDocumentGallery, but it's possible to
create alternative implementations which talk to a media server or web
services.
The primary interface to the results of a request is the
\l QGalleryResultSet class which provides accessors for reading and writing
the meta-data of a set of items.
A \l QGalleryResultSet cannot be created directly and may not need to be
accessed directly, instead an instance must be requested from a gallery
using one of the gallery request classes which typically also provide
convenience functions for accessing the items in a result set.
\section2 Requests
The gallery request classes inherit from \l QGalleryAbstractRequest and
are used to fetch items from a gallery, or to initiate service provided
by a gallery.
\annotatedlist gallery-requests
\section2 Filters
The filter classes provide a way to describe meta-data criteria items must
satisfy to be included in the results of some requests.
\annotatedlist gallery-filters
\section2 Galleries
The gallery classes provide instances of different gallery types. Currently
the only gallery type is the Document Gallery.
\annotatedlist gallery-galleries
\section2 QGalleryQueryModel
The \l QGalleryQueryModel class implements a QAbstractItemModel using
QGalleryQueryRequest. This is a convenience class which simplifies the
process of presenting gallery items in a list view.
\section2 \l QML Elements
QML elements providing access to the document gallery are implemented in
the \l {Gallery QML Plugin}.
\annotatedlist qml-gallery
\section1 Examples
\annotatedlist gallery-examples
*/
|
