/****************************************************************************
**
** Copyright (C) 2015 The Qt Company Ltd.
** Contact: http://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 http://www.qt.io/terms-conditions. For further
** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
    \title Enginio QML Examples - Todos
    \example todos
    \brief The Todo example shows the EnginioModel usage in Qt Quick.
    \ingroup enginio-qml-examples
    \inmodule enginio-qml

    In this example a simple list of objects is displayed in a
    ListView.  Each item in the list is a "To Do" object which can be
    \e done or \e{not yet done}.  Todos can be added and removed (when
    hovering with the mouse).

    \image todolist.png

    In this simple schema, the objects will only have two properties
    that are added to the default properties (such as creation date,
    which always exists): a string \c title and a bool \c completed.
    The object type will be created when a call to create, or, in this
    case, a call to \l{EnginioModel::append()}{EnginioModel::append()}
    is made.

    A todo object will look like this in \l {http://json.org} {JSON}:
    \code
{
  "title": "Buy Milk",
  "completed": false
}
    \endcode

    The example uses Qt Quick Controls, Layouts, and Enginio.
    \snippet todos/todo.qml imports

    The first step is to create an \l{Enginio::EnginioModel} {Enginio model} and
    its \l {EnginioClient} {Enginio client} with the backend configuration.
    To get nice debug output in case something goes wrong, the client's
    \l {EnginioClient::error} {onError} signal handler is implented. Since the
    error is a \l {http://www.ecma-international.org/ecma-262/5.1/#sec-15.12}
    {JSON object}, JSON.stringify is used to format it to a string.

    \snippet todos/todo.qml model

    A ListView is used to display the list of Todos. In the delegate, the
    properties of the Enginio objects are used.
    \snippet todos/todo.qml view

    It is easy to add a new Todo object to the model using a \l {TextInput}.
    By implementing the \l {TextInput::accepted} {onAccepted} signal handler,
    the Todo data is appended to the model. After appending the new Todo, the
    \l {TextInput::text} {text property} is cleared so that the next Todo can
    be entered.

    \snippet todos/todo.qml append

    Inside the delegate, the data for the index is available by using
    the property names (\e title and \e completed).  The \e title
    property is directly assigned to the text displayed on each list
    item. The \e completed boolean is used to display the item with a
    strikeout font and a light color.

    \snippet todos/todo.qml delegate-properties

    The \l Enginio::EnginioModel::setProperty() function is called to update the data in the Enginio backend.

    \snippet todos/todo.qml setProperty

    The \c _synced property can be used to ascertain whether an item has been synced or not.
    It is always available in the delegate, and may be used, for example, to disable the user interface
    until syncing has completed.

    \snippet todos/todo.qml sync

    Finally, a remove button is visible when hovering over an item with the mouse.
    Removal is implemented by calling \l{Enginio::EnginioModel::remove()}{EnginioModel::remove()} with the row of the item.

    \snippet todos/todo.qml remove
*/
