Update Controls Text Editor example and docs

a27b75c89da31a9ed1cf6dc6f6d3f3514ad28f8e doesn't work in its
entirety on 6.7 branch; but this patch applies the parts that are
possible. These docs have been adapted from the version in
6217408799c43869b8a7c1fcbff882d42ae71171.

We update the html and markdown example files.

We also move ScrollBar to make explanation easier.

Pick-to: 6.7.0
Change-Id: If65de335f840382b5e236d8a04db382b0b7aee6a
Reviewed-by: Oliver Eftevaag <oliver.eftevaag@qt.io>
(cherry picked from commit 6217408799c43869b8a7c1fcbff882d42ae71171)

1 files changed, 131 insertions, 34 deletions

diff --git a/examples/quickcontrols/texteditor/doc/src/qtquickcontrols-texteditor.qdoc b/examples/quickcontrols/texteditor/doc/src/qtquickcontrols-texteditor.qdoc
index 4f7a9beb04..1e3144f942 100644
--- a/examples/quickcontrols/texteditor/doc/src/qtquickcontrols-texteditor.qdoc
+++ b/examples/quickcontrols/texteditor/doc/src/qtquickcontrols-texteditor.qdoc
@@ -7,46 +7,152 @@
     \keyword Qt Quick Controls 2 - Text Editor
     \ingroup qtquickcontrols-examples
     \examplecategory {Graphics}
-    \brief A QML app using Qt Quick Controls and a C++ class to
-    provide a fully-functional rich-text editor application.
+    \brief A rich-text editor app using Qt Quick Controls.
 
-    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.
+    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 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.
+    text, and opening and saving HTML, Markdown and plain text files.
 
-    The desktop UI uses FileDialog for opening and saving 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 FileDialog
-    \printuntil /\bsaveAs\b/
-    \printline }
+    \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
 
-    It uses FontDialog and ColorDialog for choosing fonts and colors:
+    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 FontDialog
-    \printuntil /.*colorDialog$/
-    \printuntil /^\s{4}\}$/
+    \skipto ToolBar
+    \printuntil copyButton
+    \printuntil }
+    \dots 12
 
-    It also uses \l[QML QtLabsPlatform]{Menu} and
-    \l[QML QtLabsPlatform]{MenuItem} that provide a context menu to format text
-    within:
+    The main part of the text editor is a \l TextArea inside a \l Flickable:
 
-    \skipto /\bMenu\b/
-    \printuntil /^\s{4}\}$/
+    \skipto Flickable
+    \printuntil persistentSelection
+    \dots 12
 
-    \note There is also a standard menubar with more options than the
-    context menu.
+    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
 
@@ -57,14 +163,5 @@
     \l{Using File Selectors with Qt Quick Controls}{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}\}$/
-
     \include examples-run.qdocinc
 */