Table of Content
Document Gallery API
A Document Gallery is a virtual gallery of documents and media. The Document Gallery API [doc.qt.nokia.com] provides methods to discover the contents and their meta-data, of a Gallery.
Meta-data is information which describes a document, it can identify the creator of a document or a contributor, it can identify logical collections a document belongs to and significant dates in a documents history, and many other things. The document gallery stores all this information and provides interfaces to query it.
Documents can be found in the gallery using their type, filters, and collections. The type of a document is a generic classification of its content and usually encapsulates multiple MIME types, a document may be a File, a Folder, a Document, Audio, an Image, Video, or a Playlist.
Filters provide a means to express criteria which the meta-data of a document must pass for the document to be included in a query result. A filter either compares a meta-data property to a value or collects a group of sub-filters in a logical union or intersection.
Collections are sets of documents in the gallery that can all be identified by a common property or parent. Each collection is itself a document with its own set of properties that may be queried. Some collections mirror an actual file (Folder), while others are compiled from the meta-data documents they contain (Artist, Album Artist, Album, AudioGenre, PhotoAlbum).
- Browse collections of documents with common identifying meta-data.
- Query meta-data values from individual documents and collections of documents.
- Edit the meta-data of documents.
- Filter query results using meta-data expressions.
- Sort query results using meta-data.
- Stay up to date as documents are added, removed, and changed with live queries.
The Media Browser example [doc.qt.nokia.com] demonstrates how to use collections to navigate the document gallery.
The application menu in the media browser provides a list of gallery item types; both collections (Artists, Album Artists and Albums) and documents (Songs and Photos). Selecting a type from the menu will display a list of all items of that type, and selecting a virtual item from that list will display items belonging to that collection.
The Media Browser also allows you to edit meta-data of items in the Songs list. Changing an editable field (Track number, Title, Artist, or Album Artist) will write those changes back to the gallery.
The Document Share example is a simple web browser with a download manager which demonstrates how to query the meta-data of a document using it’s URL.
The download manager queries the document gallery for the ID and type of downloaded files, then when the user selects a file it is able to use that information to query the document gallery for type appropriate meta-data to present in a download summary.