/****************************************************************************
**
** Copyright (C) 2017 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$
**
****************************************************************************/
/*!
    \example texteditor
    \keyword Qt Quick Controls - Text Editor
    \title Qt Quick Controls - Text Editor
    \keyword Qt Quick Controls 2 - Text Editor
    \ingroup qtquickcontrols2-examples
    \brief A QML app using Qt Quick Controls 2 and a C++ class to
    provide a fully-functional rich-text editor application.

    The \e {Text Editor Example} presents a sample HTML file using the TextArea
    control, preserving the HTML formatting. The application comes with two user
    interfaces; one for traditional desktop platforms with a mouse pointer, and
    another simpler, touch-oriented version.

    \section1 Desktop User Interface

    \image qtquickcontrols2-texteditor-desktop.jpg

    The desktop version is a complete text editor with capabilities for formatting
    text, and opening and saving HTML and plain text files. It demonstrates the
    native-looking dialogs and menus using the \l{Qt Labs Platform} module. These
    types are mostly suitable for desktop platforms with support for multiple
    top-level windows, a mouse pointer, and moderate screen size.

    The desktop UI uses FileDialog for opening and saving files:

    \quotefromfile texteditor/qml/texteditor.qml
    \skipto FileDialog
    \printuntil /\bsaveAs\b/
    \printline }

    It uses FontDialog and ColorDialog for choosing fonts and colors:

    \skipto FontDialog
    \printuntil /.*colorDialog$/
    \printuntil /^\s{4}\}$/

    It also uses \l[QML QtLabsPlatform]{Menu} and
    \l[QML QtLabsPlatform]{MenuItem} that provide a context menu to format text
    within:

    \skipto /\bMenu\b/
    \printuntil /^\s{4}\}$/

    \note There is also a standard menubar with more options than the
    context menu.

    \section1 Touch User Interface

    \image qtquickcontrols2-texteditor-touch.jpg

    The touch user interface is a simplified version of the text editor. It is
    suitable for touch devices with limited screen size. The example uses
    \l{Using File Selectors with Qt Quick Controls 2}{file selectors} to load
    the appropriate user interface automatically.

    Unlike the desktop version, which uses top-level dialogs, the touch version
    uses the QML \l Dialog type, which is not a top-level window. This type of
    dialog is fully supported on mobile and embedded platforms that do not support
    multiple top-level windows.

    \quotefromfile texteditor/qml/+touch/texteditor.qml
    \skipto /\bDialog\b/
    \printuntil /^\s{4}\}$/

    \section1 C++ Backend

    Both user interfaces use the same C++ backend, which supports opening, formatting,
    and editing a document. The C++ class, \c DocumentHandler, extends QObject and is
    registered as a QML type under the namespace \c {io.qt.examples.texteditor 1.0}.

    The following snippets show how the type is registered under a namespace and later
    imported and instantiated by \e main.qml. For more information about registering C++
    classes as QML types, see \l {Defining QML Types from C++}.

    QML type registration:

    \code
    #include <QtQml/qqml.h>
    ...
    qmlRegisterType<DocumentHandler>("io.qt.examples.texteditor", 1, 0, "DocumentHandler");
    ...
    \endcode

    QML namespace import:

    \code
    import io.qt.examples.texteditor 1.0
    \endcode

    QML instance:

    \quotefromfile texteditor/qml/texteditor.qml
    \skipto DocumentHandler
    \printuntil /^\s{4}\}$/

    \include examples-run.qdocinc
*/