/****************************************************************************
**
** 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 qml-gallery
    \title QML Document Gallery
    QML Support for the QtMobility Project Document Gallery API.

*/

/*!
    \group qml-gallery-filters
    \title Gallery Filters for QML
    \brief Filter classes for the Doc Gallery QML Plugin.
*/

/*!
    \page qml-gallery.html

    \title Gallery QML Plugin

    \brief A QML plugin for the QtMobility Document Gallery API.


    \section1 Overview

    The QML Gallery plugin contains features that can be used to search
    for and retrieve documents from the Document Gallery.

    \section2 Search Filters

    Searching is performed by creating a filter based on a derived gallery filter
    class. This results in a set of Gallery QML elements for filtering.
    The Search parameters can be set by specifying property values which
    refer to the meta-data of the documents. For example, a meta-data
    key might be "author". Then, for example, by setting the filter property to
    "author" and the value to "torvalds" the filter is ready to enable a search
    for all documents authored by "torvalds".

    Available filters include

    \annotatedlist qml-gallery-filters

    There is nothing to prevent the developer creating a number of filters.
    Then she could use either a \l {GalleryFilterUnion} or a \l
    {GalleryFilterIntersection} to find the result of OR-ing or AND-ing the
    criteria respectively to create a more complex search requirement.

    \section2 Gallery Item

    \l {DocumentGalleryItem}s are elements that are a means to request information
    about a single item from a gallery. The information may include
    monitoring the state of the request, reading the meta-data for the
    document or writing meta-data.

    When a request is made the \l {DocumentGalleryItem::status}{status} property
    contains the current status of the request including whether it is active
    or canceled.

    Progress of the request is available through the \l qreal (floating point
    number) item property \l {DocumentGalleryItem::progress}{progress}.



    \section2 Query Requests

    The \l DocumentGalleryModel element is used to perform the requests on a
    document gallery. The following snippet of QML from the
    \l DocumentGalleryModel documentation is worth a closer look because it puts
    together several of the elements discussed in this overview.

    \code
    import QtMobility.gallery 1.1

        ...

        model: DocumentGalleryModel {
            rootType: DocumentGallery.Image
            properties: ["url"]
            filter: GalleryWildcardFilter {
                property: "fileName";
                value: "*.jpg";
            }
        }

        ...
    \endcode

    Here we have a model using a DocumentGalleryQueryModel. Within Qt the
    term 'model' usually refers to the Model part of a variation on the
    Model-View-Controller design pattern. In essence it is a data-oriented
    part of the Gallery query object, what data types are part of this query.
    For a clearer understanding \l{http://doc.qt.nokia.com/4.7/model-view-programming.html}{see the Qt documentation}.


    \section1 Classes

    \annotatedlist  qml-gallery

*/


