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

/*!
    \title To Do List
    \ingroup qtquickdemos
    \example demos/todolist
    \examplecategory {Application Examples}
    \brief A QML implementation of a to-do list application that demonstrates
    how to create an application thats looks native on any platform.
    \meta {tag} {demo,quick}

    \e{To Do List} demonstrates a sample to-do list application that looks
    native on any platform. The example can be run and edited in both Qt Design
    Studio and Qt Creator. It shows how to create and use a custom style and how
    to use settings to control the appearance and behavior of the application.
    It also shows how to implement simple drag and drop behavior on delegates.
    The application uses local storage to store items on the device and
    XMLHttpRequest to retrieve data from the public API (Random Tasks
    functionality). The views are controlled by a StackView component.

    \include examples-run.qdocinc

    \if defined(onlinedocs)
      \tab {to-do-list}{custom-dark}{CustomStyle Dark}{checked}
      \tab {to-do-list}{custom-light}{CustomStyle Light}{}
      \tab {to-do-list}{material-dark}{Material Dark}{}
      \tab {to-do-list}{material-light}{Material Light}{}
      \tab {to-do-list}{ios-dark}{iOS Dark}{}
      \tab {to-do-list}{ios-light}{iOS Light}{}

    \tabcontent {custom-light}
    \else
      \section1 CustomStyle Light
    \endif
    \inlineimage {CustomStyle_Light.png} {light theme custom style}

    \if defined(onlinedocs)
      \endtabcontent
      \tabcontent {custom-dark}
    \else
      \section1 CustomStyle Dark
    \endif
    \inlineimage {CustomStyle_Dark.png} {Dark theme custom style}
    \inlineimage {Settings_CustomStyle.png} {Dark theme settings UI}

    \if defined(onlinedocs)
      \endtabcontent
      \tabcontent {material-light}
    \else
      \section1 Material Light
    \endif
    \inlineimage {Material_Light.png} {Light Material theme}

    \if defined(onlinedocs)
      \endtabcontent
      \tabcontent {material-dark}
    \else
      \section1 Material Dark
    \endif
    \inlineimage {Material_Dark.png} {Dark Material theme}
    \inlineimage {Settings_Material.png} {Dark Material theme settings UI}

    \if defined(onlinedocs)
      \endtabcontent
      \tabcontent {ios-light}
    \else
      \section1 iOS Light
    \endif
    \inlineimage {iOS_Light.png} {Light iOS theme}

    \if defined(onlinedocs)
      \endtabcontent
      \tabcontent {ios-dark}
    \else
      \section1 iOS Dark
    \endif
    \inlineimage {iOS_Dark.png} {Dark iOS theme}
    \inlineimage {Settings_iOS.png} {Dark theme settings UI}

    \if defined(onlinedocs)
        \endtabcontent
    \endif

    \section1 Selecting Application Style
    The application supports different styles depending on the target platform.
    CustomStyle, Basic, Material and Universal are available on each platform (Windows, Android, iOS, macOS).
    The Windows style is available only on Windows and the iOS style is available only on iOS. The list of available styles is located in one of the subpages of the \c SettingsView called Style.
    The currently used style can be changed from the same place. A restart is required to apply the changes.
    The application will inform the user about this with the ToolTip information.

    \section1 Changing theme
    Dark and Light themes are also supported in each style. The theme can be changed from the Theme subpage of the \c SettingsView.
    Not every style allows the user to change the theme manually, e.g. on iOS this option is not available. In this case the theme will be changed according to the default system settings.
    The first time the app is launched it will use the system theme.

    \section1 Controlling app behavior from app settings
    The Behavior and style of the application can be changed from \c SettingsView. The settings allow the user to change:

    \list
        \li style
        \li theme
        \li font size
        \li maximum number of tasks
        \li if the finished tasks should be removed automatically
    \endlist

    \section1 Tasks List Implementation

    The application has three different lists:

    \list
        \li Today's tasks list → The tasks with today's date as due date.
        \li This week's tasks list → the tasks that are due in the next seven days.
        \li Later tasks → the tasks that do not fit into the above lists.
    \endlist

    The tasks are distributed between the list models at the start of the application. Of course, the tasks can migrate through the list models at runtime (when their due date changes).
    The definition of the single list is done in \c TasksList.qml and \c TasksListForm.ui.qml, the instances are created in \c TasksListsView.qml/TasksListsViewForm.ui.qml.

    \quotefromfile demos/todolist/content/TasksListsViewForm.ui.qml
    \skipto ListModel {
    \printuntil laterTasksListModel.count
    \printuntil }
    \printuntil }


    Filling the list model with data is done in \c TasksListsView.qml in \c Component.onCompleted.

    \quotefromfile demos/todolist/content/TasksListsView.qml
    \skipto createTasksLists
    \printuntil laterTasksModel.append
    \printuntil }
    \printuntil }
    \printuntil }
    \skipto Component.onCompleted
    \printuntil )

    \section1 Swipe, Drag and Drop behavior
    The list view uses the \c TasksListDelegate as a delegate. The delegate is a \l SwipeDelegate, it allows the user to swipe the item to highlight it (the item is moved to the top of the list) or to remove it.
    It also allows the user to mark the task as done (the item is moved to the bottom) or drag and drop the item to move it to a specific position in the list.
    Implementation of these behaviors is done in \c TasksListDelegate.qml.

    \section1 Local Storage usage
    Local storage is used to read and write the task items to SQLite databases. The implementation of this and other helper functions is done in \c Database.qml, which is a singleton object.

    \quotefromfile demos/todolist/imports/ToDoList/Database.qml
    \skipto _db
    \printuntil results.rows.item(0).task_id
    \printuntil }

    \section1 Usage of XMLHttpRequest to retrieve data from public API

    The XMLHttpRequest is used to send request to some public API and retrieve the response data.
    The application uses \l {http://www.boredapi.com/} {boredapi} which can return a random task to do. The task is then added to the list of today's tasks.

    \quotefromfile demos/todolist/content/HomePage.qml
    \skipto sendHttpRequest
    \printuntil http.send
    \printuntil }

    \section1 Source files

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