QTextLine Class

The QTextLine class represents a line of text inside a QTextLayout. More...

Header:	#include <QTextLine>
qmake:	QT += gui

• List of all members, including inherited members

Note: All functions in this class are reentrant.

Public Types

enum	CursorPosition { CursorBetweenCharacters, CursorOnCharacter }
enum	Edge { Leading, Trailing }

Public Functions

	QTextLine()
qreal	ascent() const
qreal	cursorToX(int *cursorPos, QTextLine::Edge edge = Leading) const
qreal	cursorToX(int cursorPos, QTextLine::Edge edge = Leading) const
qreal	descent() const
void	draw(QPainter *painter, const QPointF &position, const QTextLayout::FormatRange *selection = nullptr) const
QList<QGlyphRun>	glyphRuns(int from = -1, int length = -1) const
qreal	height() const
qreal	horizontalAdvance() const
bool	isValid() const
qreal	leading() const
bool	leadingIncluded() const
int	lineNumber() const
QRectF	naturalTextRect() const
qreal	naturalTextWidth() const
QPointF	position() const
QRectF	rect() const
void	setLeadingIncluded(bool included)
void	setLineWidth(qreal width)
void	setNumColumns(int numColumns)
void	setNumColumns(int numColumns, qreal alignmentWidth)
void	setPosition(const QPointF &pos)
int	textLength() const
int	textStart() const
qreal	width() const
qreal	x() const
int	xToCursor(qreal x, QTextLine::CursorPosition cpos = CursorBetweenCharacters) const
qreal	y() const

Detailed Description

The QTextLine class represents a line of text inside a QTextLayout.

A text line is usually created by QTextLayout::createLine().

After being created, the line can be filled using the setLineWidth() or setNumColumns() functions. A line has a number of attributes including the rectangle it occupies, rect(), its coordinates, x() and y(), its textLength(), width() and naturalTextWidth(), and its ascent() and descent() relative to the text. The position of the cursor in terms of the line is available from cursorToX() and its inverse from xToCursor(). A line can be moved with setPosition().

Member Type Documentation

enum QTextLine::CursorPosition

Constant	Value
QTextLine::CursorBetweenCharacters	0
QTextLine::CursorOnCharacter	1

enum QTextLine::Edge

Constant	Value
QTextLine::Leading	0
QTextLine::Trailing	1

Member Function Documentation

QTextLine::QTextLine()

Creates an invalid line.

qreal QTextLine::ascent() const

Returns the line's ascent.

See also descent() and height().

qreal QTextLine::cursorToX(int *cursorPos, QTextLine::Edge edge = Leading) const

Converts the cursor position cursorPos to the corresponding x position inside the line, taking account of the edge.

If cursorPos is not a valid cursor position, the nearest valid cursor position will be used instead, and cursorPos will be modified to point to this valid cursor position.

See also xToCursor().

qreal QTextLine::cursorToX(int cursorPos, QTextLine::Edge edge = Leading) const

This is an overloaded function.

qreal QTextLine::descent() const

Returns the line's descent.

See also ascent() and height().

void QTextLine::draw(QPainter *painter, const QPointF &position, const QTextLayout::FormatRange *selection = nullptr) const

Draws a line on the given painter at the specified position. The selection is reserved for internal use.

QList<QGlyphRun> QTextLine::glyphRuns(int from = -1, int length = -1) const

Returns the glyph indexes and positions for all glyphs in this QTextLine for characters in the range defined by from and length. The from index is relative to the beginning of the text in the containing QTextLayout, and the range must be within the range of QTextLine as given by functions textStart() and textLength().

If from is negative, it will default to textStart(), and if length is negative it will default to the return value of textLength().

This function was introduced in Qt 5.0.

See also QTextLayout::glyphRuns().

qreal QTextLine::height() const

Returns the line's height. This is equal to ascent() + descent() if leading is not included. If leading is included, this equals to ascent() + descent() + leading().

See also ascent(), descent(), leading(), and setLeadingIncluded().

qreal QTextLine::horizontalAdvance() const

Returns the horizontal advance of the text. The advance of the text is the distance from its position to the next position at which text would naturally be drawn.

By adding the advance to the position of the text line and using this as the position of a second text line, you will be able to position the two lines side-by-side without gaps in-between.

This function was introduced in Qt 4.7.

bool QTextLine::isValid() const

Returns true if this text line is valid; otherwise returns false.

qreal QTextLine::leading() const

Returns the line's leading.

This function was introduced in Qt 4.6.

See also ascent(), descent(), and height().

bool QTextLine::leadingIncluded() const

Returns true if positive leading is included into the line's height; otherwise returns false.

By default, leading is not included.

This function was introduced in Qt 4.6.

See also setLeadingIncluded().

int QTextLine::lineNumber() const

Returns the position of the line in the text engine.

QRectF QTextLine::naturalTextRect() const

Returns the rectangle covered by the line.

qreal QTextLine::naturalTextWidth() const

Returns the width of the line that is occupied by text. This is always <= to width(), and is the minimum width that could be used by layout() without changing the line break position.

QPointF QTextLine::position() const

Returns the line's position relative to the text layout's position.

See also setPosition().

QRectF QTextLine::rect() const

Returns the line's bounding rectangle.

See also x(), y(), textLength(), and width().

void QTextLine::setLeadingIncluded(bool included)

Includes positive leading into the line's height if included is true; otherwise does not include leading.

By default, leading is not included.

Note that negative leading is ignored, it must be handled in the code using the text lines by letting the lines overlap.

This function was introduced in Qt 4.6.

See also leadingIncluded().

void QTextLine::setLineWidth(qreal width)

Lays out the line with the given width. The line is filled from its starting position with as many characters as will fit into the line. In case the text cannot be split at the end of the line, it will be filled with additional characters to the next whitespace or end of the text.

void QTextLine::setNumColumns(int numColumns)

Lays out the line. The line is filled from its starting position with as many characters as are specified by numColumns. In case the text cannot be split until numColumns characters, the line will be filled with as many characters to the next whitespace or end of the text.

void QTextLine::setNumColumns(int numColumns, qreal alignmentWidth)

Lays out the line. The line is filled from its starting position with as many characters as are specified by numColumns. In case the text cannot be split until numColumns characters, the line will be filled with as many characters to the next whitespace or end of the text. The provided alignmentWidth is used as reference width for alignment.

void QTextLine::setPosition(const QPointF &pos)

Moves the line to position pos.

See also position().

int QTextLine::textLength() const

Returns the length of the text in the line.

See also naturalTextWidth().

int QTextLine::textStart() const

Returns the start of the line from the beginning of the string passed to the QTextLayout.

qreal QTextLine::width() const

Returns the line's width as specified by the layout() function.

See also naturalTextWidth(), x(), y(), textLength(), and rect().

qreal QTextLine::x() const

Returns the line's x position.

See also rect(), y(), textLength(), and width().

int QTextLine::xToCursor(qreal x, QTextLine::CursorPosition cpos = CursorBetweenCharacters) const

Converts the x-coordinate x, to the nearest matching cursor position, depending on the cursor position type, cpos. Note that result cursor position includes possible preedit area text.

See also cursorToX().

qreal QTextLine::y() const

Returns the line's y position.

See also x(), rect(), textLength(), and width().