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

/*!
    \title Getting Started programming with Qt Quick: An Alarm Application
    \brief A tutorial for Qt Quick based on an alarms application.
    \examplecategory {Application Examples}
    \example tutorials/alarms
    \meta {tag} {quick,alarm,getting started}

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

    In this tutorial you can 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.
    This application is similar to the alarm application usually
    found on an Android phone.

    \include examples-run.qdocinc

    \section1 Creating the Alarms Project

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

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

    \section1 \QC

    Setting up a new project in \QC 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.
    Use Qt Quick Application (compact) if you want to use other build systems
    than CMake or Qt versions lower than 6.

    \image alarms2.png
           {Setting up the new project}

    \image alarms3.png
           {Setting the 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 \c 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
           {Setting up the 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
          {Different alarms settings for different days}

    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 }

    \section1 Next Steps

    The app has no code for adding sound or vibration to the alarm, nor does
    it store the alarms in any format or database. Challenge yourself by adding
    these features to the project. Storing the data could be done in
    \l{JSON Support in Qt}{JSON format}.

    \section1 Source files

    \sa {JSON Support in Qt}, {All Qt Examples}, {Qt Quick Examples and Tutorials}
*/