diff options
Diffstat (limited to 'examples/quickcontrols/texteditor/doc/src/qtquickcontrols-texteditor.qdoc')
| -rw-r--r-- | examples/quickcontrols/texteditor/doc/src/qtquickcontrols-texteditor.qdoc | 165 |
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 */ |