/****************************************************************************
**
** Copyright (C) 2017 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** 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 The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/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: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/

/*!
    \title Qt Quick Demo - Photo Surface
    \ingroup qtquickdemos
    \example demos/photosurface
    \brief A QML app for touch devices that uses a Repeater with a
    FolderListModel to access content in a folder, and a PinchArea that contains
    a MouseArea to handle pinch gestures on the fetched content.
    \image qtquick-demo-photosurface-small.png

    \e{Photo Surface} demonstrates how to use a \l{Repeater} with a
    FolderListModel and a FileDialog to access images from a folder selected
    by a user and how to handle dragging, rotation and pinch zooming within the
    same item using a \l PinchArea that contains a \l MouseArea.

    All the app code is contained in one QML file, photosurface.qml. Inline
    JavaScript code is used to place, rotate, and scale images on the photo
    surface.

    \include examples-run.qdocinc

    \section1 Creating the Main Window

    To create the main window for the Photo Surface app, we use the \l{Window}
    QML type as the root item. It automatically sets up the window for use with
    \l{Qt Quick} graphical types:

    \quotefromfile demos/photosurface/photosurface.qml
    \skipto Window {
    \printuntil currentFrame

    To use the \l{Window} type, we must import it:

    \code
    import QtQuick.Window 2.1
    \endcode

    \section1 Accessing Folder Contents

    We use a \l{Repeater} QML type together with the FolderListModel to display
    GIF, JPG, and PNG images located in a folder:

    \quotefromfile demos/photosurface/photosurface.qml
    \skipto Repeater
    \printuntil }

    To use the FolderListModel type, we must import it:

    \code
    import Qt.labs.folderlistmodel 1.0
    \endcode

    We use a FileDialog to enable users to select the folder that contains
    the images:

    \quotefromfile demos/photosurface/photosurface.qml
    \skipto FileDialog
    \printuntil }

    To use the FileDialog type, we must import \l{Qt Quick Dialogs}:

    \code
    import QtQuick.Dialogs 1.0
    \endcode

    We use the \c {fileDialog.open()} function to open the file dialog when the
    app starts:

    \code
    Component.onCompleted: fileDialog.open()
    \endcode

    Users can also click the file dialog icon to open the file dialog. We use
    an \l{Image} QML type to display the icon. Inside the \l{Image} type, we
    use a MouseArea with the \c onClicked signal handler to call the
    \c {fileDialog.open()} function:

    \quotefromfile demos/photosurface/photosurface.qml
    \skipuntil Image {
    \skipto Image {
    \printuntil }
    \printuntil }

    \section1 Displaying Images on the Photo Surface

    We use a \l{Rectangle} as a delegate for a \l{Repeater} to provide a frame
    for each image that the FolderListModel finds in the selected folder. We use
    JavaScript \c Math() methods to place the frames randomly on the photo
    surface and to rotate them at random angles, as well as to scale the images:

    \quotefromfile demos/photosurface/photosurface.qml
    \skipto Rectangle
    \printuntil Component.onCompleted
    \printuntil }

    \section1 Handling Pinch Gestures

    We use a PinchArea that contains a MouseArea in the photo frames to handle
    dragging, rotation and pinch zooming of the frame:

    \skipto PinchArea
    \printuntil onPinchStarted

    We use the \c pinch group property to control how the photo frames react to
    pinch gestures. The \c pinch.target sets \c photoFrame as the item to
    manipulate. The rotation properties specify that the frames can be rotated
    at all angles and the scale properties specify that they can be scaled
    between \c 0.1 and \c 10.

    In the MouseArea's \c onPressed signal handler, we raise the selected photo
    frame to the top by increasing the value of its \c z property. The root item
    stores the z value of the top-most frame. The border color of the photo
    frame is controlled in the \c onEntered signal handler to highlight the
    selected image:

    \skipto MouseArea
    \printuntil onEntered

    To enable you to test the example on the desktop, we use the MouseArea's
    \c onWheel signal handler to simulate pinch gestures by using a mouse:

    \printuntil photoFrame.scale
    \printuntil }
    \printuntil }

    The \c onWheel signal handler is called in response to mouse wheel gestures.
    Use the vertical wheel to zoom and Ctrl and the vertical wheel to rotate
    frames. If the mouse has a horizontal wheel, use it to rotate frames.

    \sa {QML Applications}
*/