/****************************************************************************
**
** 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 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

*/