qt-everywhere-src-5.15.1/qtdoc/examples/demos/clocks/doc/src/clocks.qdoc

/****************************************************************************
**
** 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 - Clocks
    \ingroup qtquickdemos
    \example demos/clocks
    \brief A QML clock application that demonstrates using a ListView type to
    display data generated by a ListModel and a SpringAnimation type to animate
    images.
    \image qtquick-demo-clocks-small.png

    \e Clocks demonstrates using a ListView type to display data generated by a
    ListModel. The delegate used by the model is specified as a custom QML type
    that is specified in the Clock.qml file.

    JavaScript methods are used to fetch the current time in several cities in
    different time zones and QML types are used to display the time on a clock
    face with animated clock hands.

    \include examples-run.qdocinc

    \section1 Displaying Data Generated by List Models

    In the clocks.qml file, we use a \l Rectangle type to create the application
    main window:

    \quotefromfile demos/clocks/clocks.qml
    \skipto Rectangle
    \printuntil color

    We use a ListView type to display a list of the items provided by a
    ListModel type:

    \printuntil Los Angeles
    \printuntil }
    \printuntil }

    List elements are defined like other QML types except that they contain a
    collection of \e role definitions instead of properties. Roles both define
    how the data is accessed and include the data itself.

    For each list element, we use the \c cityName role to specify the name of a
    city and the \c timeShift role to specify a time zone as a positive or
    negative offset from UTC (coordinated universal time).

    The Clock custom type is used as the ListView's \c delegate, defining the
    visual appearance of list items. To use the Clock type, we add an import
    statement that imports the folder called \c content where the type is
    located:

    \quotefromfile demos/clocks/clocks.qml
    \skipto content
    \printuntil "

    We use an \l Image type to display arrows that indicate whether users can
    flick the view to see more clocks on the left or right:

    \quotefromfile demos/clocks/clocks.qml
    \skipto Image
    \printuntil /^\}/

    We use the \c opacity property to hide the arrows when the list view is
    located at the beginning or end of the x axis.

    In Clock.qml, we define a \c timeChanged() function in which we use
    methods from the JavaScript \c Date object to fetch the current time in
    UTC and to adjust it to the correct time zone:

   \quotefromfile demos/clocks/content/Clock.qml
    \skipto timeChanged
    \printuntil }

    We use a \l Timer type to update the time at intervals of 100 milliseconds:

    \printuntil }

    We use \l Image types within an \l Item type to display the time on an
    analog clock face. Different images are used for daytime and nighttime
    hours:

    \printuntil clock-night.png

    A \l Rotation transform applied to \l Image types provides a way to rotate
    the clock hands. The \c origin property holds the point that stays fixed
    relative to the parent as the rest of the item rotates. The \c angle
    property determines the angle to rotate the hands in degrees clockwise.

    \printuntil center.png
    \printuntil }

    We use a \l Behavior type on the \c angle property to apply a
    SpringAnimation when the time changes. The \c spring and \c damping
    properties enable the spring-like motion of the clock hands, and a
    \c modulus of \c 360 makes the animation target values wrap around at a
    full circle.

    We use a \l Text type to display the city name below the clock:

    \printuntil }

    \sa {QML Applications}
*/