From 953e04346773beb5d10c3758a12aae5c82646ae1 Mon Sep 17 00:00:00 2001 From: Shawn Rutledge Date: Mon, 13 Jan 2020 08:34:03 +0100 Subject: Text and TextEdit: document MarkdownText format Task-number: QTBUG-81306 Change-Id: I8ee50727f4e75eee8c0997f17193d8c99e855551 Reviewed-by: Paul Wicking Reviewed-by: Venugopal Shivashankar --- src/quick/items/qquicktext.cpp | 61 +++++++++++++++++++----------------------- 1 file changed, 27 insertions(+), 34 deletions(-) (limited to 'src/quick/items/qquicktext.cpp') diff --git a/src/quick/items/qquicktext.cpp b/src/quick/items/qquicktext.cpp index ae849aeb4b..b95a2559ff 100644 --- a/src/quick/items/qquicktext.cpp +++ b/src/quick/items/qquicktext.cpp @@ -1640,6 +1640,9 @@ void QQuickText::itemChange(ItemChange change, const ItemChangeData &value) The item will try to automatically determine whether the text should be treated as styled text. This determination is made using Qt::mightBeRichText(). + However, detection of Markdown is not automatic. + + \sa textFormat */ QString QQuickText::text() const { @@ -2067,26 +2070,25 @@ void QQuickText::resetMaximumLineCount() /*! \qmlproperty enumeration QtQuick::Text::textFormat - The way the text property should be displayed. + The way the \l text property should be displayed. Supported text formats are: - \list - \li Text.AutoText (default) - \li Text.PlainText - \li Text.StyledText - \li Text.RichText - \endlist + \value Text.AutoText (default) detected via the Qt::mightBeRichText() heuristic + \value Text.PlainText all styling tags are treated as plain text + \value Text.StyledText optimized basic rich text as in HTML 3.2 + \value Text.RichText \l {Supported HTML Subset} {a subset of HTML 4} + \value Text.MarkdownText \l {https://commonmark.org/help/}{CommonMark} plus the + \l {https://guides.github.com/features/mastering-markdown/}{GitHub} + extensions for tables and task lists (since 5.14) If the text format is \c Text.AutoText the Text item will automatically determine whether the text should be treated as - styled text. This determination is made using Qt::mightBeRichText() - which uses a fast and therefore simple heuristic. It mainly checks - whether there is something that looks like a tag before the first - line break. Although the result may be correct for common cases, - there is no guarantee. + styled text. This determination is made using Qt::mightBeRichText(), + which can detect the presence of an HTML tag on the first line of text, + but cannot distinguish Markdown from plain text. - Text.StyledText is an optimized format supporting some basic text + \c Text.StyledText is an optimized format supporting some basic text styling markup, in the style of HTML 3.2: \code @@ -2112,30 +2114,21 @@ void QQuickText::resetMaximumLineCount() \table \row \li - \qml -Column { - Text { - font.pointSize: 24 - text: "Hello World!" - } - Text { - font.pointSize: 24 - textFormat: Text.RichText - text: "Hello World!" - } - Text { - font.pointSize: 24 - textFormat: Text.PlainText - text: "Hello World!" - } -} - \endqml + \snippet qml/text/textFormats.qml 0 \li \image declarative-textformat.png \endtable - Text.RichText supports a larger subset of HTML 4, as described on the - \l {Supported HTML Subset} page. You should prefer using Text.PlainText - or Text.StyledText instead, as they offer better performance. + \c Text.RichText supports a larger subset of HTML 4, as described on the + \l {Supported HTML Subset} page. You should prefer using \c Text.PlainText, + \c Text.StyledText or \c Text.MarkdownText instead, as they offer better performance. + + \note With \c Text.MarkdownText, and with the supported subset of HTML, + some decorative elements are not rendered as they would be in a web browser: + \list + \li code blocks use the \l {QFontDatabase::FixedFont}{default monospace font} but without a surrounding highlight box + \li block quotes are indented, but there is no vertical line alongside the quote + \li horizontal rules are not rendered + \endlist */ QQuickText::TextFormat QQuickText::textFormat() const { -- cgit v1.2.3