Document Gallery

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 (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; QGalleryQueryRequest takes a type, a parent item, and some filtering criteria (QGalleryFilter) and returns meta-data for all matching items. QGalleryItemRequest takes an item ID and returns meta-data for just that item. And QGalleryTypeRequest takes an item type and returns meta-data describing that type.

The requests operate on implementations of the QAbstractGallery. The default implementation is 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 QGalleryResultSet class which provides accessors for reading and writing the meta-data of a set of items.

A 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.