// Copyright (C) 2017 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
    \example texteditor
    \keyword Qt Quick Controls - Text Editor
    \title Qt Quick Controls - Text Editor
    \keyword Qt Quick Controls 2 - Text Editor
    \ingroup qtquickcontrols-examples
    \examplecategory {Graphics}
    \brief A rich-text editor app using Qt Quick Controls.

    The \e {Text Editor Example} allows WYSIWYG editing of an HTML, Markdown or
    plain text file. The application comes with two user interfaces: one for
    larger screens, and a simplified UI for small touch-based devices. Both are
    "pure" QML. \c texteditor.cpp contains the \c main() function, which calls
    QFontDatabase::addApplicationFont() to add an icon font. (\l FontLoader
    would be an alternative way to achieve the same result.)

    \section1 Desktop User Interface

    \image qtquickcontrols-texteditor-desktop.jpg

    The desktop version is a complete text editor with capabilities for formatting
    text, and opening and saving HTML, Markdown and plain text files.

    In the \l {https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller}{model-view-control (MVC)}
    design pattern, the \e control layer includes the set of operations that
    can be performed. In Qt Quick Controls, the \l Action type is used to
    encapsulate a single operation or command. Accordingly, we begin with a
    set of Action objects:

    \quotefromfile texteditor/qml/texteditor.qml
    \skipto Action
    \printuntil openAction
    \printto Action

    The \l Action for opening a file must first prompt the user if the existing
    document has been changed, to avoid losing the user's changes. Otherwise
    it simply opens the FileDialog which is declared further below.

    The \l Action for saving the file is enabled only if there are changes to save:

    \printuntil saveAction
    \printto Action

    \skipto quitAction
    \skipuntil }

    The \l Action for copying selected text is enabled only if some text is selected:

    \printuntil copyAction
    \printuntil }

    \skipto pasteAction
    \skipuntil }

    Each Action to change text formatting (such as bold, italic and alignment)
    is \l {Action::}{checkable}, and its boolean \c checked state
    is in sync with the relevant property in the
    \l {TextEdit::selectedText}{selected text}.
    Since declarative bidirectional synchronization is difficult, we use
    an \c onTriggered script to change the property when the Action is
    activated. The \l {TextEdit::}{cursorSelection} property
    is new in Qt 6.7 and makes this much easier than it was.

    \printuntil boldAction
    \printto Action

    \skipto alignLeftAction
    \skipuntil }

    \printuntil alignCenterAction
    \printto Action

    We have a \l {Qt.labs.platform::}{MenuBar} containing the hierarchy of
    \l {Qt.labs.platform::Menu}{Menus} and MenuItems. \c Platform.MenuItem does
    not have an \c action property, so at minimum we need to set \c text and
    implement \c onTriggered.

    \note In Qt Quick Controls, each \l {QtQuick.Controls::}{MenuItem} could
    simply bind the relevant \l {AbstractButton::}{action}. In a near-future
    version of Qt, \c Qt.labs.platform will be obsolete, and
    \l {QtQuick.Controls::}{MenuBar} will be suitable on every platform.
    Unless you need a native menu bar (only on platforms that provide one)
    in Qt 6.7 and older versions, you should avoid importing \c Qt.labs.platform.
    \c QtQuick.Controls is more portable.

    \skipto MenuBar
    \printuntil copyAction
    \printuntil }
    \dots 8

    The existing \l Action objects are reused in the \l ToolBar; but here we
    override each Action's \l {AbstractButton::}{text} property to
    choose a textual icon from our icon font:

    \skipto ToolBar
    \printuntil copyButton
    \printuntil }
    \dots 12

    The main part of the text editor is a \l TextArea inside a \l Flickable:

    \skipto Flickable
    \printuntil persistentSelection
    \dots 12

    A \l ScrollBar is attached to the vertical axis. Since word-wrapping is
    enabled via \l {TextEdit::}{wrapMode}, we don't need a horizontal
    ScrollBar.

    The \l {TextArea::flickable}{TextArea.flickable} attached property is used
    so that when the text cursor is moved out of the viewport (for example via
    arrow keys, or by typing a lot of text), \l TextArea scrolls the
    \l Flickable to keep the cursor visible.

    There is a context menu; we use a TapHandler to detect a right-click and
    open it:

    \skipto TapHandler
    \printuntil }

    The context \l {Qt.labs.platform::}{Menu} contains
    \l {Qt.labs.platform::MenuItem}{MenuItems}.

    \skipto Menu
    \printuntil MenuItem
    \printuntil }
    \dots 8

    We consistently use the \l qsTr function to enable translation of UI text,
    so that the application will make sense regardless of the end user's native
    language.

    We use several kinds of \l {Qt Quick Dialogs QML Types}{dialogs}:

    \quotefromfile texteditor/qml/texteditor.qml
    \skipto FileDialog
    \printuntil discardDialog
    \printuntil }
    \printuntil }

    It's generally easier to declare separate instances for each purpose.
    We have two instances of \l {QtQuick.Dialogs::}{FileDialog}, for opening
    and saving files respectively. This became easier in Qt 6.7, with new
    features in \l TextDocument.

    A \l {QtQuick.Dialogs::}{FontDialog} and a \l {QtQuick.Dialogs::ColorDialog}{ColorDialog}
    allow changing text formatting. (In Markdown format, there's no syntax to
    represent specific font and color choices; but font characteristics such as
    bold, italic and monospace are saved. In HTML format, all formatting is
    saved.)

    We have a \l {QtQuick.Dialogs::}{MessageDialog} to show error messages, and
    two more for prompting the user what to do when a file has been modified.

    \section1 Touch User Interface

    \image qtquickcontrols-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}{file selectors} to load
    the appropriate user interface automatically.

    \include examples-run.qdocinc
*/
