Add API to get more information for each line in a QML Text element

Previously there was no way to know what area is occupied by each line
in a QML Text element.

This commit adds new API to expose implicitWidth and isLast
on QQuickTextLine for use in the lineLaidOut signal.
It also adds improved documentation to the lineLaidOut signal and
an example usage of the new API to the text layout example.

An example use case of the new API is eg. to allow embedding
timestamps and indicators within a text paragraph, to enable
creating more efficient layouts.

[ChangeLog][QtQuick][Text] Added new API that exposes implicitWidth,
and isLast on the QQuickTextLine for use in the lineLaidOut signal.
This allows the user to layout other items relative to the lines
of text.

Fixes: QTBUG-78277
Change-Id: Ibc754db17c78efb01468106aba32e30d70d2f4df
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

3 files changed, 75 insertions, 12 deletions

diff --git a/src/quick/items/qquicktext.cpp b/src/quick/items/qquicktext.cpp
index ae849aeb4b..31df4fdff3 100644
--- a/src/quick/items/qquicktext.cpp
+++ b/src/quick/items/qquicktext.cpp
@@ -517,6 +517,11 @@ void QQuickTextLine::setLineOffset(int offset)
     m_lineOffset = offset;
 }
 
+void QQuickTextLine::setFullLayoutTextLength(int length)
+{
+    m_fullLayoutTextLength = length;
+}
+
 int QQuickTextLine::number() const
 {
     if (m_line)
@@ -524,6 +529,24 @@ int QQuickTextLine::number() const
     return 0;
 }
 
+qreal QQuickTextLine::implicitWidth() const
+{
+    if (m_line)
+        return m_line->naturalTextWidth();
+    return 0;
+}
+
+bool QQuickTextLine::isLast() const
+{
+    if (m_line && (m_line->textStart() + m_line->textLength()) == m_fullLayoutTextLength) {
+        // Ensure that isLast will change if the user reduced the width of the line
+        // so that the text no longer fits.
+        return m_line->width() >= m_line->naturalTextWidth();
+    }
+
+    return false;
+}
+
 qreal QQuickTextLine::width() const
 {
     if (m_line)
@@ -585,12 +608,13 @@ bool QQuickTextPrivate::isLineLaidOutConnected()
     IS_SIGNAL_CONNECTED(q, QQuickText, lineLaidOut, (QQuickTextLine *));
 }
 
-void QQuickTextPrivate::setupCustomLineGeometry(QTextLine &line, qreal &height, int lineOffset)
+void QQuickTextPrivate::setupCustomLineGeometry(QTextLine &line, qreal &height, int fullLayoutTextLength, int lineOffset)
 {
     Q_Q(QQuickText);
 
     if (!textLine)
         textLine = new QQuickTextLine;
+    textLine->setFullLayoutTextLength(fullLayoutTextLength);
     textLine->setLine(&line);
     textLine->setY(height);
     textLine->setHeight(0);
@@ -790,7 +814,7 @@ QRectF QQuickTextPrivate::setupTextLayout(qreal *const baseline)
             if (noBreakLastLine && visibleCount == maxLineCount)
                 layout.engine()->option.setWrapMode(QTextOption::WrapAnywhere);
             if (customLayout) {
-                setupCustomLineGeometry(line, naturalHeight);
+                setupCustomLineGeometry(line, naturalHeight, layoutText.length());
             } else {
                 setLineGeometry(line, lineWidth, naturalHeight);
             }
@@ -1128,7 +1152,7 @@ QRectF QQuickTextPrivate::setupTextLayout(qreal *const baseline)
         QTextLine elidedLine = elideLayout->createLine();
         elidedLine.setPosition(QPointF(0, height));
         if (customLayout) {
-            setupCustomLineGeometry(elidedLine, height, visibleCount - 1);
+            setupCustomLineGeometry(elidedLine, height, elideText.length(), visibleCount - 1);
         } else {
             setLineGeometry(elidedLine, lineWidth, height);
         }
@@ -1335,20 +1359,43 @@ QQuickText::~QQuickText()
     \qmlsignal QtQuick::Text::lineLaidOut(object line)
 
     This signal is emitted for each line of text that is laid out during the layout
-    process. The specified \a line object provides more details about the line that
+    process in plain text or styled text mode. It is not emitted in rich text mode.
+    The specified \a line object provides more details about the line that
     is currently being laid out.
 
     This gives the opportunity to position and resize a line as it is being laid out.
     It can for example be used to create columns or lay out text around objects.
 
     The properties of the specified \a line object are:
-    \list
-    \li number (read-only)
-    \li x
-    \li y
-    \li width
-    \li height
-    \endlist
+
+    \table
+    \header
+        \li Property name
+        \li Description
+    \row
+        \li number (read-only)
+        \li Line number, starts with zero.
+    \row
+        \li x
+        \li Specifies the line's x position inside the \c Text element.
+    \row
+        \li y
+        \li Specifies the line's y position inside the \c Text element.
+    \row
+        \li width
+        \li Specifies the width of the line.
+    \row
+        \li height
+        \li Specifies the height of the line.
+    \row
+        \li implicitWidth (read-only)
+        \li The width that the line would naturally occupy based on its contents,
+            not taking into account any modifications made to \a width.
+    \row
+        \li isLast (read-only)
+        \li Whether the line is the last. This property can change if you
+            set the \a width property to a different value.
+    \endtable
 
     For example, this will move the first 5 lines of a Text item by 100 pixels to the right:
     \code
@@ -1360,6 +1407,16 @@ QQuickText::~QQuickText()
     }
     \endcode
 
+    The following example will allow you to position an item at the end of the last line:
+    \code
+    onLineLaidOut: {
+        if (line.isLast) {
+            lastLineMarker.x = line.x + line.implicitWidth
+            lastLineMarker.y = line.y + (line.height - lastLineMarker.height) / 2
+        }
+    }
+    \endcode
+
     The corresponding handler is \c onLineLaidOut.
 */
 
diff --git a/src/quick/items/qquicktext_p.h b/src/quick/items/qquicktext_p.h
index 394ea25b83..d310db508e 100644
--- a/src/quick/items/qquicktext_p.h
+++ b/src/quick/items/qquicktext_p.h
@@ -330,6 +330,8 @@ class QQuickTextLine : public QObject
     Q_PROPERTY(qreal height READ height WRITE setHeight)
     Q_PROPERTY(qreal x READ x WRITE setX)
     Q_PROPERTY(qreal y READ y WRITE setY)
+    Q_PROPERTY(qreal implicitWidth READ implicitWidth)
+    Q_PROPERTY(bool isLast READ isLast)
     QML_ANONYMOUS
 
 public:
@@ -337,7 +339,10 @@ public:
 
     void setLine(QTextLine* line);
     void setLineOffset(int offset);
+    void setFullLayoutTextLength(int length);
     int number() const;
+    qreal implicitWidth() const;
+    bool isLast() const;
 
     qreal width() const;
     void setWidth(qreal width);
@@ -355,6 +360,7 @@ private:
     QTextLine *m_line;
     qreal m_height;
     int m_lineOffset;
+    int m_fullLayoutTextLength;
 };
 
 QT_END_NAMESPACE
diff --git a/src/quick/items/qquicktext_p_p.h b/src/quick/items/qquicktext_p_p.h
index c01998b100..1fbf942130 100644
--- a/src/quick/items/qquicktext_p_p.h
+++ b/src/quick/items/qquicktext_p_p.h
@@ -195,7 +195,7 @@ public:
     void ensureDoc();
 
     QRectF setupTextLayout(qreal * const baseline);
-    void setupCustomLineGeometry(QTextLine &line, qreal &height, int lineOffset = 0);
+    void setupCustomLineGeometry(QTextLine &line, qreal &height, int fullLayoutTextLength, int lineOffset = 0);
     bool isLinkActivatedConnected();
     bool isLinkHoveredConnected();
     static QString anchorAt(const QTextLayout *layout, const QPointF &mousePos);