// Copyright (C) 2022 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \example tutorials/alarms
    \title Getting Started Programming with Qt Quick
    \brief A tutorial for Qt Quick based on an alarms application.
    \meta {tag} {tutorial,quick}

    This tutorial shows how to develop a simple alarm application as
    an introduction to Qt Quick and Qt Quick Controls.

    This application is similar to the alarm application usually
    found on an Android phone. Its features let you enter, edit,
    or delete alarms. An alarm can trigger on a given date, and you
    can set it to repeat on a series of subsequent days.

    The main screen shows the list of saved alarms:

    \image mainscreen.png "Alarms application"

    The detail screen lets you edit or delete existing alarms:

    \image detailscreen.png "Detail screen"

    The dialog screen is used for adding new alarms. It pops up
    when you click on the "+" RoundButton on the bottom of the main
    screen:

    \image addalarms.png "Add alarms"

    The source files are located in the qtdoc repository.
    You can either fetch the Qt sources from the Qt Project,
    or install them as part of Qt. The application is also available
    in the example list of Qt Creator's Welcome mode.

    \section1 Creating the Alarms Project

    This section shows how to create the project in Qt Creator. It discusses
    the files generated automatically by Qt Creator, and the two files
    the programmer has to create in Qt Creator or some other editor.
    The latter two files are included with the source code for this
    tutorial.

    \note The UI text in Qt Creator and the contents of the generated files
    depend on the Qt Creator version that you use.

    \section1 Qt Creator

    Setting up a new project in Qt Creator is aided by a wizard that
    guides you step-by-step through the project creation process. The
    wizard prompts you to enter the settings needed for that particular
    type of project and creates the project for you.

    To create the Alarms project, select \uicontrol{File} >
    \uicontrol{New Project} > \uicontrol{Application (Qt)} >
    \uicontrol{Qt Quick Application} > \uicontrol{Choose}.
    Type \e alarms in the \uicontrol{Name} field, and follow the instructions
    of the wizard.

    \image alarms2.png "Qt Creator New Project dialog"

    \image alarms3.png "Project Location"

    The Qt Quick application wizard creates a project that contains
    the following source files:

    \table
        \header
            \li Source file
            \li Purpose
        \row
            \li CMakeLists.txt
            \li The project file
        \row
            \li main.cpp
            \li The main C++ code file for the application.
       \row
           \li main.qml
           \li The main QML code file for the application. We will instantiate
               our custom QML types (\c AlarmDialog, \c AlarmModel,
               \c AlarmDelegate, and \c TumblerDelegate) in this file.
    \endtable

    The wizard generates the code in the main.cpp file below.
    This code block enables High DPI scaling and declares \c app
    and \c engine. The engine then loads our main QML file.

    \quotefromfile tutorials/alarms/main.cpp
    \skipto main
    \printuntil }

    \section1 Additional source files

    \table
       \header
           \li Source file
           \li Purpose
       \row
           \li \c qtquickcontrols2.conf
           \li Selects the \c Material style with the \c Dark theme.
       \row
           \li \c AlarmDialog.qml
           \li Defines the dialog for adding new alarms.
       \row
           \li \c AlarmDelegate.qml
           \li Defines the layout of the main screen of the app.
       \row
           \li \c AlarmModel.qml
           \li Defines the ListModel used for storing the alarms' data.
       \row
           \li \c TumblerDelegate.qml
           \li Defines the graphical layout of the Tumblers.
        \row
            \li \c qml.qrc
            \li The resource file, which contains the names of the
                source files, except main.cpp and the project file.
    \endtable


    \section2 \c qtquickcontrols2.conf

    The following snippet shows how to set the \c Dark theme in the
    \c Material style:

    \quotefile tutorials/alarms/qtquickcontrols2.conf

    \section2 \c main.qml

    \c mainWindow, an ApplicationWindow QML type, is the root item in
    this app.

    \quotefromfile tutorials/alarms/main.qml
    \skipto ApplicationWindow
    \printuntil visible

    The ListView \c alarmListView combines the data from \c alarmModel
    with the layout defined in \c alarmDelegate.

    \quotefromfile tutorials/alarms/main.qml
    \skipuntil visible
    \printto RoundButton

    New alarms can be added by clicking RoundButton \c addAlarmButton.
    Clicking it opens a \l [QtQuickControls2] {Dialog} screen \c alarmDialog.

    \printuntil alarmDialog.open
    \printuntil alarmListView.model
    \printline }

    \section2 \c AlarmDialog.qml

    This dialog screen has a RowLayout with a \l {Tumbler} each for hours
    and minutes, and another RowLayout with a Tumbler each for day, month,
    and year.

    \quotefromfile tutorials/alarms/AlarmDialog.qml
    \skipto contentItem
    \printuntil /model\: years/
    \printuntil /^\}/

    If you click on \b OK in the dialog, the entered data will be
    added to \c alarmModel:

    \quotefromfile tutorials/alarms/AlarmDialog.qml
    \skipto onAccepted
    \printuntil onRejected

    \section2 \c AlarmDelegate.qml

    Each alarm in the main screen is an ItemDelegate. The ItemDelegate
    \c root contains all fields on the main screen and the detail
    screen. The detail screen's fields are only visible after an alarm
    has been clicked on, i.e. when \c root.checked is \c true.

    \quotefromfile tutorials/alarms/AlarmDelegate.qml
    \skipto ItemDelegate
    \printuntil /^\}/

    \section2 \c AlarmModel.qml

    This QML file contains the definition of \c alarmModel, the ListModel
    that manages the alarm data.

    It creates five \l {ListElement}{ListElements} with example alarms.

    \quotefromfile tutorials/alarms/AlarmModel.qml
    \skipto import
    \printuntil /^\}/

    \section2 TumblerDelegate.qml

    TumblerDelegate defines the graphical properties of the Tumblers.

    \quotefromfile tutorials/alarms/TumblerDelegate.qml
    \skipto import
    \printuntil /^\}/

    \section1 Entering new alarms

    At the bottom of the startup screen, you can see a Button for adding
    alarms.  Click it to open the \b {Add new alarm} dialog.

    \quotefromfile tutorials/alarms/main.qml
    \skipto RoundButton
    \printto AlarmDialog

    The dialog for new alarms:

    \image addalarms.png "Add alarms"

    All fields are entered using \l {Tumbler} QML types. If you press \c OK,
    the values selected in the Tumblers are written to \c alarmModel.

    \quotefromfile tutorials/alarms/AlarmDialog.qml
    \skipto contentItem
    \printuntil /^\}/

    \section1 Editing alarms

    If you click on a particular alarm, you can edit it in the detail
    screen.

    \image detailscreen.png

    Clicking on an alarm sets \c root.checked to \c true, which makes
    visible the fields of the detail screen.

    \code
        visible: root.checked
    \endcode

    If you want the alarm to trigger also on other days, check \c alarmRepeat.
    The Repeater will display a checkable RoundButton for each day of the week.

    \quotefromfile tutorials/alarms/AlarmDelegate.qml
    \skipto Flow
    \printto TextField

    If you modify the description of the alarm, it will be reflected in
    the main screen afterwards.

    \printto Button

    \section1 Deleting alarms

    The detail screen (see above) has a Button for deleting alarms.
    When \c onClicked is emitted, the current ListElement is deleted
    from \c alarmModel.

    \printuntil root.ListView.view.model.remove
    \printuntil }

    \section2 Summary

    The app has no code for adding sound or vibration to the alarm, nor does
    it store the alarms in any format or database. Maybe it could be an
    interesting coding project to add those features. Storing the data
    could be done quickly and easily in \l{JSON Support in Qt}{JSON format}.

    \sa {JSON Support in Qt}
*/
