diff options
Diffstat (limited to 'examples/quickcontrols/texteditor/doc/src/qtquickcontrols-texteditor.qdoc')
| -rw-r--r-- | examples/quickcontrols/texteditor/doc/src/qtquickcontrols-texteditor.qdoc | 181 |
1 files changed, 122 insertions, 59 deletions
diff --git a/examples/quickcontrols/texteditor/doc/src/qtquickcontrols-texteditor.qdoc b/examples/quickcontrols/texteditor/doc/src/qtquickcontrols-texteditor.qdoc index b1d7e842cf..40ab1915e6 100644 --- a/examples/quickcontrols/texteditor/doc/src/qtquickcontrols-texteditor.qdoc +++ b/examples/quickcontrols/texteditor/doc/src/qtquickcontrols-texteditor.qdoc @@ -6,95 +6,158 @@ \title Qt Quick Controls - Text Editor \keyword Qt Quick Controls 2 - Text Editor \ingroup qtquickcontrols-examples - \brief A QML app using Qt Quick Controls and a C++ class to - provide a fully-functional rich-text editor application. + \examplecategory {Graphics} + \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 - It uses FontDialog and ColorDialog for choosing fonts and colors: + 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. - \skipto FontDialog - \printuntil /.*colorDialog$/ - \printuntil /^\s{4}\}$/ + The \l Action for saving the file is enabled only if there are changes to save: - It also uses \l[QML QtLabsPlatform]{Menu} and - \l[QML QtLabsPlatform]{MenuItem} that provide a context menu to format text - within: + \printuntil saveAction + \printto Action - \skipto /\bMenu\b/ - \printuntil /^\s{4}\}$/ + \skipto quitAction + \skipuntil } - \note There is also a standard menubar with more options than the - context menu. + The \l Action for copying selected text is enabled only if some text is selected: - \section1 Touch User Interface + \printuntil copyAction + \printuntil } - \image qtquickcontrols-texteditor-touch.jpg + \skipto pasteAction + \skipuntil } - 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. + 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 MenuBar containing the hierarchy of \l {Menu}{Menus} and + MenuItems. Each \l MenuItem merely needs to bind the relevant + \l {AbstractButton::}{action}, which encapsulates the + UI representation and the implementation. + + \skipto MenuBar + \printuntil copyAction + \printuntil } + \dots 8 + + The same \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 - 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. + The main part of the text editor is a \l TextArea inside a \l Flickable: - \quotefromfile texteditor/qml/+touch/texteditor.qml - \skipto /\bDialog\b/ - \printuntil /^\s{4}\}$/ + \skipto Flickable + \printuntil persistentSelection + \dots 12 - \section1 C++ Backend + 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. - 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 \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. - 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++}. + There is a context menu; we use a TapHandler to detect a right-click and + open it: - QML type registration: + \skipto TapHandler + \printuntil } - \code - #include <QtQml/qqml.h> - ... - qmlRegisterType<DocumentHandler>("io.qt.examples.texteditor", 1, 0, "DocumentHandler"); - ... - \endcode + The context \l Menu contains \l {MenuItem}{MenuItems} that reuse the same + \l Action objects as the main \l MenuBar and \l ToolBar are using. + As before, it's enough to bind \l {AbstractButton::}{action} to the + reusable Action that represents the operation to be performed. However, + we override each menu item's \l {MenuItem::}{text} to omit the + underlined mnemonics on the context menu. - QML namespace import: + \skipto Menu + \printuntil MenuItem + \printuntil } + \dots 8 - \code - import io.qt.examples.texteditor 1.0 - \endcode + 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. - QML instance: + We use several kinds of \l {Qt Quick Dialogs QML Types}{dialogs}: \quotefromfile texteditor/qml/texteditor.qml - \skipto DocumentHandler - \printuntil /^\s{4}\}$/ + \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 */ |