path: root/src/controls/doc/src/qtquickcontrols-examples.qdoc

/****************************************************************************
**
** Copyright (C) 2016 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$
**
****************************************************************************/

/*!
    \group qtquickcontrols_examples
    \ingroup all-examples
    \title Qt Quick Controls 1 Examples
    \brief A Collection of examples for \l{Qt Quick Controls 1}, written in QML.

    These examples show how to create user interfaces using
    \l{Qt Quick Controls 1}.
*/

/*!
    \example gallery
    \title Qt Quick Controls 1 - Gallery
    \ingroup qtquickcontrols_examples
    \brief A collection of components for a classic desktop-style UI.

    \raw HTML
    <div class="table"><table style="background:transparent; border:0px">
    <tr><td style="border:0px">
    \endraw
    \image qtquickcontrols-example-gallery-osx.png
    \caption \macos
    \raw HTML
    </td><td style="border:0px">
    \endraw
    \image qtquickcontrols-example-gallery-android.png
    \caption Android - Nexus 5
    \raw HTML
    </td></tr>
    </table></div>
    \endraw

    This example project demonstrates the various UI components provided by
    \l{Qt Quick Controls 1}.

    \include examples-run.qdocinc
*/

/*!
    \example uiforms
    \title Qt Quick Controls 1 - UI Forms
    \ingroup qtquickcontrols_examples
    \brief Demonstrates how to separate the application logic from the UI.

    \image qtquickcontrols-example-uiforms.png

    \e{UI Forms} demonstrates how to separate the application logic
    from the UI using \e ui.qml files. The example is a simple interface to a customer
    database, purely written in QML and JavaScript.

    UI Forms are rigorously split into \e .qml and \e .js files that contain the business logic, and \e .ui.qml
    files that only contain the purely declarative description of the UI.
    The \e .ui.qml files act as forms and they should be only edited in the Design mode of Qt Creator.

    \section1 Exporting Items from Forms

    In all forms, items that are supposed to interact with the application logic are exported:

    \code
    property alias cancel: cancel
    property alias save: save
    property alias textArea: textArea
    \endcode

    This is the way the items are exported in \e NotesForm.ui.qml, so they can be used in
    \e Notes.ui.qml to implement the logic as follows:

    \code
    function readData() {
        CustomerModel.selection.forEach(function (rowIndex) {
            form.textArea.text = CustomerModel.model.get(rowIndex).notes
        })

        save.enabled = true
        cancel.enabled = true
        form.textArea.enabled = true
    }

    function writeData() {
        CustomerModel.selection.forEach(function (rowIndex) {
            var data = CustomerModel.model.get(rowIndex)
            data.notes = form.textArea.text
            CustomerModel.model.set(rowIndex, data)
        })
    }

    cancel.onClicked: readData()
    save.onClicked: writeData()
    \endcode

    \section1 Implementing the Backend in a Singleton

    Because the ListModel is accessed from several different \e .qml files, we access the
    ListModel through a singleton defined in \e CustomerModel.qml and registered in \e main.ccp.
    This way we do not have to rely on the QML context scoping rules to access the ListModel.

    \include examples-run.qdocinc
*/

/*!
    \example tableview
    \title Qt Quick Controls 1 - Table View Example
    \ingroup qtquickcontrols_examples
    \brief An example for the TableView control.
    \image qtquickcontrols-example-tableview.png

    This example project demonstrates the usage of \l {TableView} from
    \l{Qt Quick Controls 1} - a control to display one or more columns of
    information from a data list model. The example includes a model
    that supports sorting and filtering.

    The C++ class, SortFilterProxyModel, is registered as a QML type
    under the namespace, "\c{org.qtproject.example 1.0}".

    The following snippets show how the type is registered under
    a namespace and later imported by \e main.qml.

    QML type registration:

    \code
    #include <QtQml/qqml.h>
    ...
    qmlRegisterType<SortFilterProxyModel>("org.qtproject.example", 1, 0, "SortFilterProxyModel");
    ...
    \endcode

    QML namespace import:

    \code
    import org.qtproject.example 1.0
    \endcode

    For more information about registering C++ classes as QML types, see
    \l {Defining QML Types from C++}.

    \include examples-run.qdocinc
*/

/*!
    \example texteditor
    \title Qt Quick Controls 1 - Text Editor Example
    \ingroup qtquickcontrols_examples
    \brief A QML app using Qt Quick Controls and a C++ class to
    provide a fully-functional rich-text editor application.

    \image qtquickcontrols-example-text.png

    The \e{Text Editor Example} presents a sample HTML file using the TextArea
    control, preserving the HTML formatting. It uses a C++ class to handle the
    document by providing options to open, format, and edit. The app also lets
    you open and edit a plain text files.

    The C++ class, DocumentHandler, extends QObject and is registered
    as a QML type under the namespace, "\c{org.qtproject.example 1.0}".

    The following snippets show how the type is registered under
    a namespace and later imported by \e main.qml.

    QML type registration:

    \code
    #include <QtQml/qqml.h>
    ...
    qmlRegisterType<DocumentHandler>("org.qtproject.example", 1, 0, "DocumentHandler");
    ...
    \endcode

    QML namespace import:

    \code
    import org.qtproject.example 1.0
    \endcode

    For more information about registering C++ classes as QML types, see
    \l {Defining QML Types from C++}.

    \include examples-run.qdocinc
*/

/*!
    \example touch
    \title Qt Quick Controls 1 - Touch Gallery
    \ingroup qtquickcontrols_examples
    \brief Demonstrates UI controls for a touch interface.
    \image qtquickcontrols-example-touch.png

    \e {Touch Gallery} demonstrates how to implement a UI suitable for touch
    input using the following \l{Qt Quick Controls 1}:

    \list
        \li \l ApplicationWindow
        \li \l Button
        \li \l ProgressBar
        \li \l ScrollView
        \li \l Slider
        \li \l StackView
        \li \l Switch
        \li \l Tab
        \li \l TabView
        \li \l TextField
    \endlist

    The appearance of the controls is customized by using
    \l {Qt Quick Controls 1 Styles}.

    \include examples-run.qdocinc

    \section1 Creating the Main Page

    In the main.qml file, we use a \l Rectangle type within the
    \l ApplicationWindow type to create the main page of the application:

    \quotefromfile touch/main.qml
    \skipto ApplicationWindow
    \printuntil }

    To use the Qt Quick Controls, we must import them:

    \code
    import QtQuick.Controls 1.2
    \endcode

    The \c toolBar property of the application window holds a BorderImage type
    that we use to create a separator between the application name and a list of
    additional pages:

    \quotefromfile touch/main.qml
    \skipto toolBar
    \printuntil height

    We use an \l Image type in a \l Rectangle type to create a back button. We
    use the \c onClicked signal handler to call the StackView \c pop() function
    that pops off the page when users tap the button:

    \printuntil pop()
    \printuntil }
    \printuntil }

    We use the \c opacity property to hide the back button on the main page.

    We use a \l Text type to display the application name:

    \printuntil text:
    \printuntil }

    The \c x position of the \l Text type is bound to the position and width of
    the back button, and animated using a \l Behavior.

    We use a ListModel type that contains ListElement definitions to define
    titles and source files for the other pages in the application:

    \skipto ListModel
    \printuntil ListPage
    \printuntil }
    \printuntil }

    \section1 Navigating in the Application

    We implement a stack-based navigation model to link the application pages
    together. Items are pushed onto the stack as users navigate deeper into the
    application, and popped off again when they return to the main page.

    In main.qml, we add a \l StackView type as a child of the application
    window:

    \skipto StackView
    \printuntil }

    The stack is used by invoking its navigation methods. To load the first item
    in the stack view, we assign it to \c initialItem:

    \printuntil /^\}/

    We use a ListView type to display a list of the items provided by
    \c pageModel. The \c AndroidDelegate custom type defines each item
    instantiated by the view.

    \section1 Creating Push Buttons and Switches

    In ButtonPage.qml we use the \l Button type to create two buttons that
    change color when users tap them and one that pops off the page and returns
    the user to the main page:

    \quotefromfile touch/content/ButtonPage.qml
    \skipto Button
    \printuntil stackView
    \printuntil }

    We use a \l Switch type to create two switches that users can turn on and
    off. They are placed within a \l Row type to lay them out horizontally:

    \printuntil switchStyle
    \printuntil switchStyle
    \printuntil }
    \printuntil }

    A \l ButtonStyle type creates a custom appearance for the buttons:

    \skipto Component
    \printuntil }

    To use Qt Quick Controls Styles, we must import them:

    \code
    import QtQuick.Controls.Styles 1.1
    \endcode

    A \l SwitchStyle type creates a custom appearance for the switches:

    \quotefromfile touch/content/ButtonPage.qml
    \skipuntil Component
    \skipto Component
    \printuntil /^\}/

    The \c groove property holds the background groove of the switch and the
    \c handle property defines the switch handle.

    \section1 Creating Sliders

    In SliderPage.qml, we use a \l Slider type to create three horizontal
    sliders that are placed within a \l Column type to lay them out in a column:

    \quotefromfile touch/content/SliderPage.qml
    \skipto Column
    \printuntil 1.0
    \printuntil }
    \printuntil }

    The \c value property holds the initial handle position on the slider.

    A SliderStyle type creates a custom appearance for the sliders:

    \printuntil /^\}/

    The \c handle property defines the slider handle and the \c groove property
    holds the background groove of the slider.

    \section1 Indicating Progress

    In ProgressBar.qml, we use a ProgressBar type to create three progress bars:

    \quotefromfile touch/content/ProgressBarPage.qml
    \skipto Column
    \printuntil 1
    \printuntil 400
    \printuntil }

    We use a NumberAnimation type with a SequentialAnimation type to run two
    number animations in a sequence. We apply the animations on the \c progress
    custom property to animate the current value on the progress bars:

    \quotefromfile touch/content/ProgressBarPage.qml
    \skipto progress
    \printuntil }
    \printuntil }

    A ProgressBarStyle type creates a custom appearance for the progress bars:

    \quotefromfile touch/content/ProgressBarPage.qml
    \skipto Component
    \printuntil /^\}/

    \section1 Creating Tabs

    In TabBarPage.qml, we use a TabView type with a \l Tab type to provide a
    tab-based navigation model for our application. We use tabs to display the
    ButtonPage, SliderPage, and ProgressBarPage on separate tab pages:

    \quotefromfile touch/content/TabBarPage.qml
    \skipto TabView
    \printuntil ProgressBarPage
    \printuntil }

    A TabViewStyle type creates a custom appearance for the tabs:

    \skipto Component
    \printuntil /^\}/

    \section1 Creating Text Input Fields

    In the TextInputPage.qml, we use a TextField type to create an input field
    and a read-only text field:

    \quotefromfile touch/content/TextInputPage.qml
    \skipto Column
    \printuntil true
    \printuntil }
    \printuntil }

    A TextFieldStyle creates a custom appearance for the text fields:

    \printuntil /^\}/

    We use a BorderImage type with an image to create borders for the fields.

    \section1 Creating Scrolling Lists

    In ListPage.qml, we use a ScrollView type to provide a scrolling page with a
    vertical scoll bar:

    \quotefromfile touch/content/ListPage.qml
    \skipto ScrollView
    \printuntil true

    We use a ListView type to display a list of 100 items by specifying an
    \l{Models and Views in Qt Quick#Integers as Models}{integer} as the value of
    the \c model property. We reuse the \c AndroidDelegate custom type here to
    define each item instantiated by the view. The \c text property adds the
    string \c {Item #} to each list item:

    \printuntil }
    \printuntil }

    A ScrollViewStyle type creates a custom appearance for the scroll view:

    \printuntil /^\}/

    The \c transientScrollBars property is set to \c true to make the scroll
    bars appear when the content is scrolled and disappear when they are no
    longer needed.

    The \c handle property controls the appearance of the scroll bar handle and
    the \c scrollBarBackground property that of the background.
*/

/*!
    \example calendar
    \title Qt Quick Controls 1 - Calendar Example
    \ingroup qtquickcontrols_examples
    \brief Demonstrates the use of Calendar control.
    \image qtquickcontrols-example-calendar.png

    The Calendar example displays a Calendar control and an events list for
    the selected date. It uses a C++ class to fetch the event details from an
    SQLite database. The example app uses a custom CalendarStyle to highlight
    the selected date and mark the dates that have events.

    The following snippet from \e main.qml shows how the Calendar control is
    used in the app:

    \code
    Calendar {
        id: calendar
        width: (parent.width > parent.height ? parent.width * 0.6 - parent.spacing : parent.width)
        height: (parent.height > parent.width ? parent.height * 0.6 - parent.spacing : parent.height)
        frameVisible: true
        weekNumbersVisible: true
        selectedDate: new Date(2014, 0, 1)
        focus: true

        style: CalendarStyle {
            dayDelegate: Item {
                     ...
                }
           }
    }
    \endcode

    The C++ class, SqlEventModel, inherits SqlQueryModel to create a database
    with dummy events for certain dates.

    \quotefromfile calendar/src/sqleventmodel.cpp
    \skipto SqlEventModel::SqlEventModel()
    \printto QList
    \skipto void SqlEventModel
    \printuntil /^\}/

    In \e main.qml, the SqlEventModel custom type is used to get the list of
    events to mark the dates on the calendar.

    \code
    SqlEventModel {
        id: eventModel
    }

    Calendar {
        ...
        style: CalendarStyle {
            dayDelegate: Item {
                ...
                Image {
                    visible: eventModel.eventsForDate(styleData.date).length > 0
                    ...
                    source: "qrc:/images/eventindicator.png"
                }
            }
        }
    }
    \endcode

    The app uses a Flow type to position the items, and manipulates the
    items' width and height based on the orientation change on mobile devices.

    \code
    Calendar {
        id: calendar
        width: (parent.width > parent.height ? parent.width * 0.6 - parent.spacing : parent.width)
        height: (parent.height > parent.width ? parent.height * 0.6 - parent.spacing : parent.height)
    }

    Rectangle {
        width: (parent.width > parent.height ? parent.width * 0.4 - parent.spacing : parent.width)
        height: (parent.height > parent.width ? parent.height * 0.4 - parent.spacing : parent.height)
        border.color: Qt.darker(color, 1.2)

        ListView {
            ...
        }
    }
    \endcode
    \include examples-run.qdocinc
*/

/*!
    \example styles
    \title Qt Quick Controls 1 - Styles Example
    \ingroup qtquickcontrols_examples
    \brief Demonstrates custom styles.
    \image qtquickcontrols-example-styles.png

    This example shows how to create custom styles for \l{Qt Quick Controls 1}.

    \include examples-run.qdocinc
*/

/*!
    \example filesystembrowser
    \title Qt Quick Controls 1 - File System Browser Example
    \ingroup qtquickcontrols_examples
    \brief An example for the TreeView control.
    \image qtquickcontrols-example-filesystembrowser.png

    This example project demonstrates the usage of \l {TreeView} from
    \l{Qt Quick Controls 1} - a control to display a tree representation of items
    from a model derived from the QAbstractItemModel class.

    The example displays the home path data given by the QFileSystemModel model.
*/