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) 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$
**
****************************************************************************/
/*!
\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 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
*/
|
