QTextBlock Class Reference

The QTextBlock class provides a container for text fragments in a QTextDocument. More...

#include <qtextobject.h>

Classes
class	iterator
	The QTextBlock::iterator class provides an iterator for reading the contents of a QTextBlock. More...

Public Types
typedef iterator	Iterator
	Qt-style synonym for QTextBlock::iterator. More...

Public Functions
iterator	begin () const
	Returns a text block iterator pointing to the beginning of the text block. More...
QTextBlockFormat	blockFormat () const
	Returns the QTextBlockFormat that describes block-specific properties. More...
int	blockFormatIndex () const
	Returns an index into the document's internal list of block formats for the text block's format. More...
int	blockNumber () const
	Returns the number of this block, or -1 if the block is invalid. More...
QTextCharFormat	charFormat () const
	Returns the QTextCharFormat that describes the block's character format. More...
int	charFormatIndex () const
	Returns an index into the document's internal list of character formats for the text block's character format. More...
void	clearLayout ()
	Clears the QTextLayout that is used to lay out and display the block's contents. More...
bool	contains (int position) const
	Returns true if the given position is located within the text block; otherwise returns false. More...
QTextDocumentPrivate *	docHandle () const
const QTextDocument *	document () const
	Returns the text document this text block belongs to, or 0 if the text block does not belong to any document. More...
iterator	end () const
	Returns a text block iterator pointing to the end of the text block. More...
int	firstLineNumber () const
	Returns the first line number of this block, or -1 if the block is invalid. More...
int	fragmentIndex () const
bool	isValid () const
	Returns true if this text block is valid; otherwise returns false. More...
bool	isVisible () const
	Returns true if the block is visible; otherwise returns false. More...
QTextLayout *	layout () const
	Returns the QTextLayout that is used to lay out and display the block's contents. More...
int	length () const
	Returns the length of the block in characters. More...
int	lineCount () const
QTextBlock	next () const
	Returns the text block in the document after this block, or an empty text block if this is the last one. More...
bool	operator!= (const QTextBlock &o) const
	Returns true if this text block is different from the other text block. More...
bool	operator< (const QTextBlock &o) const
	Returns true if this text block occurs before the other text block in the document. More...
QTextBlock &	operator= (const QTextBlock &o)
	Assigns the other text block to this text block. More...
bool	operator== (const QTextBlock &o) const
	Returns true if this text block is the same as the other text block. More...
int	position () const
	Returns the index of the block's first character within the document. More...
QTextBlock	previous () const
	Returns the text block in the document before this block, or an empty text block if this is the first one. More...
	QTextBlock (QTextDocumentPrivate *priv, int b)
	QTextBlock ()
	QTextBlock (const QTextBlock &o)
	Copies the other text block's attributes to this text block. More...
int	revision () const
	Returns the blocks revision. More...
void	setLineCount (int count)
void	setRevision (int rev)
	Sets a blocks revision to rev. More...
void	setUserData (QTextBlockUserData *data)
	Attaches the given data object to the text block. More...
void	setUserState (int state)
	Stores the specified state integer value in the text block. More...
void	setVisible (bool visible)
	Sets the block's visibility to visible. More...
QString	text () const
	Returns the block's contents as plain text. More...
Qt::LayoutDirection	textDirection () const
	Returns the resolved text direction. More...
QTextList *	textList () const
	If the block represents a list item, returns the list that the item belongs to; otherwise returns 0. More...
QTextBlockUserData *	userData () const
	Returns a pointer to a QTextBlockUserData object if previously set with setUserData() or a null pointer. More...
int	userState () const
	Returns the integer value previously set with setUserState() or -1. More...

Properties
int	n
QTextDocumentPrivate *	p

Friends
class	QSyntaxHighlighter
class	QTextDocumentPrivate
class	QTextLayout

Detailed Description

The QTextBlock class provides a container for text fragments in a QTextDocument.

Note

This class or function is reentrant.

A text block encapsulates a block or paragraph of text in a QTextDocument. QTextBlock provides read-only access to the block/paragraph structure of QTextDocuments. It is mainly of use if you want to implement your own layouts for the visual representation of a QTextDocument, or if you want to iterate over a document and write out the contents in your own custom format.

Text blocks are created by their parent documents. If you need to create a new text block, or modify the contents of a document while examining its contents, use the cursor-based interface provided by QTextCursor instead.

Each text block is located at a specific position() in a document(). The contents of the block can be obtained by using the text() function. The length() function determines the block's size within the document (including formatting characters). The visual properties of the block are determined by its text layout(), its charFormat(), and its blockFormat().

The next() and previous() functions enable iteration over consecutive valid blocks in a document under the condition that the document is not modified by other means during the iteration process. Note that, although blocks are returned in sequence, adjacent blocks may come from different places in the document structure. The validity of a block can be determined by calling isValid().

QTextBlock provides comparison operators to make it easier to work with blocks: operator==() compares two block for equality, operator!=() compares two blocks for inequality, and operator<() determines whether a block precedes another in the same document.

See also

QTextBlockFormat QTextCharFormat QTextFragment

Definition at line 199 of file qtextobject.h.

Typedefs

Iterator

QTextBlock::Iterator

Qt-style synonym for QTextBlock::iterator.

Definition at line 275 of file qtextobject.h.

Constructors and Destructors

QTextBlock() [1/3]

QTextBlock::QTextBlock ( QTextDocumentPrivate *  priv, int  b  )

inline

Warning

This function is not part of the public interface.

Definition at line 203 of file qtextobject.h.

: p(priv), n(b) {}

QTextBlock() [2/3]

QTextBlock::QTextBlock ( )

inline

Warning

This function is not part of the public interface.

Definition at line 204 of file qtextobject.h.

: p(0), n(0) {}

QTextBlock() [3/3]

QTextBlock::QTextBlock ( const QTextBlock &  o )

inline

Copies the other text block's attributes to this text block.

Definition at line 205 of file qtextobject.h.

: p(o.p), n(o.n) {}

Functions

begin()

QTextBlock::iterator QTextBlock::begin

(

)

const

Returns a text block iterator pointing to the beginning of the text block.

See also

end()

Definition at line 1573 of file qtextobject.cpp.

Referenced by QTextControlPrivate::activateLinkUnderCursor(), QTextHtmlExporter::emitBlock(), QTextHtmlExporter::emitBlockAttributes(), QTextHtmlExporter::emitFrame(), QTextControl::findNextPrevAnchor(), and QTextOdfWriter::writeBlock().

{
    if (!p || !n)
        return iterator();

    int pos = position();
    int len = length() - 1; // exclude the fragment that holds the paragraph separator
    int b = p->fragmentMap().findNode(pos);
    int e = p->fragmentMap().findNode(pos+len);
    return iterator(p, b, e, b);
}

blockFormat()

QTextBlockFormat QTextBlock::blockFormat

(

)

const

Returns the QTextBlockFormat that describes block-specific properties.

See also

charFormat()

Definition at line 1182 of file qtextobject.cpp.

Referenced by QTextList::add(), QTextCopyHelper::appendFragment(), QTextCursorPrivate::blockFormat(), QTextCursor::blockFormat(), QAccessibleTextWidget::characterRect(), QTextCopyHelper::copy(), QTextDocumentLayoutPrivate::drawBlock(), QTextDocumentLayoutPrivate::drawFlow(), QTextDocumentLayoutPrivate::drawListItem(), QTextHtmlExporter::emitBlock(), QTextHtmlExporter::emitBlockAttributes(), isEmptyBlockBeforeTable(), QTextList::itemText(), QTextDocumentLayoutPrivate::layoutFlow(), QPlainTextEdit::paintEvent(), and QTextList::remove().

{
    if (!p || !n)
        return QTextFormat().toBlockFormat();

    return p->formatCollection()->blockFormat(p->blockMap().fragment(n)->format);
}

blockFormatIndex()

int QTextBlock::blockFormatIndex

(

)

const

Returns an index into the document's internal list of block formats for the text block's format.

See also

QTextDocument::allFormats()

Definition at line 1196 of file qtextobject.cpp.

Referenced by QTextOdfWriter::writeBlock().

{
    if (!p || !n)
        return -1;

    return p->blockMap().fragment(n)->format;
}

blockNumber()

int QTextBlock::blockNumber

(

)

const

Returns the number of this block, or -1 if the block is invalid.

Since

4.4

\sa QTextCursor::blockNumber()

Definition at line 1512 of file qtextobject.cpp.

Referenced by QPlainTextEditControl::blockBoundingRect(), QTextCursor::blockNumber(), QPlainTextDocumentLayout::documentChanged(), QScriptEdit::extraAreaPaintEvent(), QPlainTextDocumentLayout::layoutBlock(), QPlainTextEditPrivate::pageUpDown(), QPlainTextEditPrivate::setTopBlock(), and QPlainTextEditPrivate::setTopLine().

{
    if (!p || !n)
        return -1;
    return p->blockMap().position(n, 1);
}

charFormat()

QTextCharFormat QTextBlock::charFormat

(

)

const

Returns the QTextCharFormat that describes the block's character format.

The block's character format is used when inserting text into an empty block.

See also

blockFormat()

Definition at line 1211 of file qtextobject.cpp.

Referenced by QTextCopyHelper::appendFragment(), QTextCursor::blockCharFormat(), QTextHtmlExporter::emitBlock(), QTextHtmlExporter::emitBlockAttributes(), QPlainTextDocumentLayout::layoutBlock(), QTextDocumentLayoutPrivate::layoutBlock(), and QScriptLine::setDefaultHeight().

{
    if (!p || !n)
        return QTextFormat().toCharFormat();

    return p->formatCollection()->charFormat(charFormatIndex());
}

charFormatIndex()

int QTextBlock::charFormatIndex

(

)

const

Returns an index into the document's internal list of character formats for the text block's character format.

See also

QTextDocument::allFormats()

Definition at line 1225 of file qtextobject.cpp.

{
    if (!p || !n)
        return -1;

    return p->blockCharFormatIndex(n);
}

clearLayout()

void QTextBlock::clearLayout

(

)

Clears the QTextLayout that is used to lay out and display the block's contents.

Since

4.4

See also

layout()

Definition at line 1167 of file qtextobject.cpp.

Referenced by QTextDocumentLayout::documentChanged(), and QPlainTextDocumentLayout::documentChanged().

{
    if (!p || !n)
        return;

    const QTextBlockData *b = p->blockMap().fragment(n);
    if (b->layout)
        b->layout->clearLayout();
}

contains()

bool QTextBlock::contains

(

int

position

)

const

Returns true if the given position is located within the text block; otherwise returns false.

Definition at line 1126 of file qtextobject.cpp.

Referenced by QTextDocumentLayoutPrivate::drawBlock(), QTextDocumentLayoutPrivate::drawFlow(), and QPlainTextEdit::paintEvent().

{
    if (!p || !n)
        return false;

    int pos = p->blockMap().position(n);
    int len = p->blockMap().size(n);
    return position >= pos && position < pos + len;
}

docHandle()

QTextDocumentPrivate * QTextBlock::docHandle ( ) const

inline

Warning

This function is not part of the public interface.

Definition at line 283 of file qtextobject.h.

Referenced by QTextList::add(), QTextEngine::calculateTabWidth(), QTextLine::draw(), findInBlock(), QTextEngine::font(), QTextEngine::fontEngine(), QTextInlineObject::format(), QTextEngine::format(), QTextEngine::formatIndex(), QTextEngine::hasFormats(), QTextEngine::indexAdditionalFormats(), QTextEngine::itemize(), QTextLine::layout_helper(), QTextList::remove(), QTextEngine::resolveAdditionalFormats(), QScriptLine::setDefaultHeight(), QTextEngine::shape(), QTextEngine::validate(), and QTextEngine::visualCursorMovement().

{ return p; }

document()

const QTextDocument * QTextBlock::document

(

)

const

Returns the text document this text block belongs to, or 0 if the text block does not belong to any document.

Definition at line 1313 of file qtextobject.cpp.

Referenced by QPlainTextEditPrivate::ensureVisible(), QSyntaxHighlighter::rehighlightBlock(), and QPlainTextDocumentLayoutPrivate::relayout().

{
    return p ? p->document() : 0;
}

end()

QTextBlock::iterator QTextBlock::end

(

)

const

Returns a text block iterator pointing to the end of the text block.

See also

begin() next() previous()

Definition at line 1591 of file qtextobject.cpp.

Referenced by QTextControl::findNextPrevAnchor().

{
    if (!p || !n)
        return iterator();

    int pos = position();
    int len = length() - 1; // exclude the fragment that holds the paragraph separator
    int b = p->fragmentMap().findNode(pos);
    int e = p->fragmentMap().findNode(pos+len);
    return iterator(p, b, e, e);
}

firstLineNumber()

int QTextBlock::firstLineNumber

(

)

const

Returns the first line number of this block, or -1 if the block is invalid.

Since

4.5

Unless the layout supports it, the line number is identical to the block number.

\sa QTextBlock::blockNumber()

Definition at line 1531 of file qtextobject.cpp.

Referenced by QPlainTextEditPrivate::_q_adjustScrollbars(), QPlainTextEditControl::blockBoundingRect(), QPlainTextEditPrivate::setTopBlock(), and QPlainTextEditPrivate::setTopLine().

{
    if (!p || !n)
        return -1;
    return p->blockMap().position(n, 2);
}

fragmentIndex()

int QTextBlock::fragmentIndex ( ) const

inline

Warning

This function is not part of the public interface.

Definition at line 284 of file qtextobject.h.

{ return n; }

isValid()

bool QTextBlock::isValid ( ) const

inline

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

Definition at line 208 of file qtextobject.h.

Referenced by QPlainTextEditPrivate::_q_adjustScrollbars(), QPlainTextEditControl::blockBoundingRect(), QTextDocumentLayout::blockBoundingRect(), QPlainTextDocumentLayout::blockBoundingRect(), QAccessibleTextWidget::characterRect(), QAccessibleTextEdit::childAt(), QTextCursor::columnNumber(), currentTextLine(), QTextControlPrivate::cursorMoveKeyEvent(), QTextDocumentLayout::documentChanged(), QPlainTextDocumentLayout::documentChanged(), QTextDocumentLayoutPrivate::drawFrame(), QPlainTextDocumentLayout::ensureBlockLayout(), QScriptEdit::extraAreaPaintEvent(), QTextDocument::find(), QTextControl::findNextPrevAnchor(), QScriptEdit::gotoLine(), QPlainTextEditControl::hitTest(), isEmptyBlockAfterTable(), isEmptyBlockBeforeTable(), isLineSeparatorBlockAfterTable(), QPlainTextDocumentLayout::layoutBlock(), QTextDocumentLayoutPrivate::layoutFlow(), QTextCursorPrivate::movePosition(), QTextEngine::nextLogicalPosition(), QPlainTextEditPrivate::pageUpDown(), QPlainTextEdit::paintEvent(), QSyntaxHighlighter::previousBlockState(), qTextBlockAt(), qTextBlockPosition(), QAccessibleTextEdit::rect(), QTextControlPrivate::rectForPosition(), QSyntaxHighlighterPrivate::reformatBlock(), QSyntaxHighlighterPrivate::reformatBlocks(), QSyntaxHighlighter::rehighlightBlock(), QPlainTextDocumentLayoutPrivate::relayout(), QTextControl::selectionRect(), setBlockCharFormatHelper(), QTextDocumentPrivate::setBlockFormat(), QTextDocumentPrivate::setCharFormat(), QAccessibleTextEdit::setText(), QPlainTextEditPrivate::setTopBlock(), QTextLine::textLength(), QTextDocumentPrivate::undoRedo(), and QTextEngine::validate().

{ return p != 0 && n != 0; }

isVisible()

bool QTextBlock::isVisible

(

)

const

Returns true if the block is visible; otherwise returns false.

Since

4.4

See also

setVisible()

Definition at line 1472 of file qtextobject.cpp.

Referenced by QPlainTextEditPrivate::_q_adjustScrollbars(), QPlainTextEditControl::blockBoundingRect(), QPlainTextDocumentLayout::blockBoundingRect(), QScriptEdit::extraAreaPaintEvent(), QPlainTextDocumentLayout::layoutBlock(), QTextCursor::movePosition(), QPlainTextEdit::paintEvent(), and QPlainTextDocumentLayoutPrivate::relayout().

{
    if (!p || !n)
        return true;

    const QTextBlockData *b = p->blockMap().fragment(n);
    return !b->hidden;
}

layout()

QTextLayout * QTextBlock::layout

(

)

const

Returns the QTextLayout that is used to lay out and display the block's contents.

Note that the returned QTextLayout object can only be modified from the documentChanged implementation of a QAbstractTextDocumentLayout subclass. Any changes applied from the outside cause undefined behavior.

See also

clearLayout()

Definition at line 1146 of file qtextobject.cpp.

Referenced by QPlainTextEditPrivate::_q_adjustScrollbars(), QSyntaxHighlighterPrivate::applyFormatChanges(), QTextDocumentLayout::blockBoundingRect(), QPlainTextDocumentLayout::blockBoundingRect(), QTextCursorPrivate::blockLayout(), QPlainTextDocumentLayout::blockWidth(), QAccessibleTextWidget::characterRect(), currentTextLine(), QTextControlPrivate::cursorMoveKeyEvent(), QPlainTextDocumentLayout::documentChanged(), QTextDocumentLayoutPrivate::drawBlock(), QTextDocumentLayoutPrivate::drawFrame(), QTextDocumentLayoutPrivate::drawListItem(), QPlainTextDocumentLayout::ensureBlockLayout(), flowPosition(), QPlainTextEditControl::hitTest(), QTextDocumentLayoutPrivate::hitTest(), QTextControlPrivate::inputMethodEvent(), QPlainTextDocumentLayout::layoutBlock(), QTextDocumentLayoutPrivate::layoutBlock(), QTextDocumentLayoutPrivate::layoutFlow(), QTextDocumentPrivate::leftCursorPosition(), QTextDocumentPrivate::nextCursorPosition(), QPlainTextEditPrivate::pageUpDown(), QPlainTextEdit::paintEvent(), QDeclarativeTextEdit::positionAt(), QTextDocumentLayout::positionInlineObject(), QTextDocumentPrivate::previousCursorPosition(), QTextControlPrivate::rectForPosition(), QPlainTextDocumentLayoutPrivate::relayout(), QTextDocumentPrivate::rightCursorPosition(), QTextControl::selectionRect(), and QPlainTextEditPrivate::verticalOffset().

{
    if (!p || !n)
        return 0;

    const QTextBlockData *b = p->blockMap().fragment(n);
    if (!b->layout)
        b->layout = new QTextLayout(*this);
    return b->layout;
}

length()

int QTextBlock::length

(

)

const

Returns the length of the block in characters.

Note

The length returned includes all formatting characters, for example, newline.

See also

text() charFormat() blockFormat()

Definition at line 1114 of file qtextobject.cpp.

Referenced by QSyntaxHighlighterPrivate::applyFormatChanges(), QTextCursor::atBlockEnd(), QTextDocumentLayout::blockBoundingRect(), QTextCursor::charFormat(), QTextDocumentLayoutPrivate::drawBlock(), QTextHtmlExporter::emitBlock(), QTextDocument::find(), QTextControl::findNextPrevAnchor(), QTextDocumentLayoutPrivate::hitTest(), QTextControl::inputMethodQuery(), isEmptyBlockAfterTable(), isEmptyBlockBeforeTable(), isLineSeparatorBlockAfterTable(), QTextEngine::itemize(), QTextControlPrivate::keyPressEvent(), QTextDocumentLayoutPrivate::layoutBlock(), QTextBlockGroupPrivate::markBlocksDirty(), QTextTable::mergeCells(), QTextCursorPrivate::movePosition(), QTextCursor::movePosition(), QTextDocumentPrivate::nextCursorPosition(), QTextEngine::nextLogicalPosition(), QPlainTextEdit::paintEvent(), QTextDocumentLayout::positionInlineObject(), QSyntaxHighlighterPrivate::reformatBlock(), QSyntaxHighlighterPrivate::reformatBlocks(), QTextCursor::select(), QTextDocumentPrivate::setBlockFormat(), QTextEdit::setText(), QTextDocumentPrivate::undoRedo(), and QTextOdfWriter::writeBlock().

{
    if (!p || !n)
        return 0;

    return p->blockMap().size(n);
}

lineCount()

int QTextBlock::lineCount

(

)

const

Since

4.5

Returns the line count. Not all document layouts support this feature.

See also

setLineCount()

Definition at line 1559 of file qtextobject.cpp.

{
    if (!p || !n)
        return -1;
    return p->blockMap().size(n, 2);
}

next()

QTextBlock QTextBlock::next

(

)

const

Returns the text block in the document after this block, or an empty text block if this is the last one.

Note that the next block may be in a different frame or table to this block.

See also

previous() begin() end()

Definition at line 1612 of file qtextobject.cpp.

Referenced by QPlainTextEditControl::blockBoundingRect(), QPlainTextDocumentLayout::blockBoundingRect(), QTextControlPrivate::cursorMoveKeyEvent(), QTextDocumentLayout::documentChanged(), QPlainTextDocumentLayout::documentChanged(), QScriptEdit::extraAreaPaintEvent(), QTextDocument::find(), QTextControl::findNextPrevAnchor(), QPlainTextEditControl::hitTest(), QPlainTextDocumentLayout::layoutBlock(), QTextCursorPrivate::movePosition(), QTextCursor::movePosition(), QPlainTextEditPrivate::pageUpDown(), QPlainTextEdit::paintEvent(), qTextBlockAt(), QSyntaxHighlighterPrivate::reformatBlocks(), QPlainTextDocumentLayoutPrivate::relayout(), setBlockCharFormatHelper(), QTextDocumentPrivate::setBlockFormat(), QTextDocumentPrivate::setCharFormat(), and QTextEngine::validate().

{
    if (!isValid() || !p->blockMap().isValid(n))
        return QTextBlock();

    return QTextBlock(p, p->blockMap().next(n));
}

operator!=()

bool QTextBlock::operator!= ( const QTextBlock &  o ) const

inline

Returns true if this text block is different from the other text block.

Definition at line 211 of file qtextobject.h.

{ return p != o.p || n != o.n; }

operator<()

bool QTextBlock::operator< ( const QTextBlock &  o ) const

inline

Returns true if this text block occurs before the other text block in the document.

Definition at line 212 of file qtextobject.h.

{ return position() < o.position(); }

operator=()

QTextBlock & QTextBlock::operator= ( const QTextBlock &  o )

inline

Assigns the other text block to this text block.

Definition at line 206 of file qtextobject.h.

{ p = o.p; n = o.n; return *this; }

operator==()

bool QTextBlock::operator== ( const QTextBlock &  o ) const

inline

Returns true if this text block is the same as the other text block.

Definition at line 210 of file qtextobject.h.

{ return p == o.p && n == o.n; }

position()

int QTextBlock::position

(

)

const

Returns the index of the block's first character within the document.

Definition at line 1098 of file qtextobject.cpp.

Referenced by QTextControlPrivate::activateLinkUnderCursor(), QTextCopyHelper::appendFragment(), QSyntaxHighlighterPrivate::applyFormatChanges(), QTextCursor::atBlockEnd(), QTextCursor::atBlockStart(), QTextDocumentLayout::blockBoundingRect(), QAccessibleTextWidget::characterRect(), QTextCursor::charFormat(), QTextCursor::columnNumber(), QTextCopyHelper::copy(), currentTextLine(), QTextLine::draw(), QTextDocumentLayoutPrivate::drawBlock(), QTextDocumentLayoutPrivate::drawFlow(), QTextDocumentLayoutPrivate::drawFrame(), QTextHtmlExporter::emitBlock(), QScriptDebuggerCodeView::event(), QTextControlPrivate::extendWordwiseSelection(), QScriptEdit::extraAreaMouseEvent(), QTextDocument::find(), findInBlock(), QTextControl::findNextPrevAnchor(), QTextEngine::formatIndex(), QPlainTextEditControl::hitTest(), QTextDocumentLayoutPrivate::hitTest(), QTextControlPrivate::inputMethodEvent(), QTextControl::inputMethodQuery(), isEmptyBlockAfterTable(), isEmptyBlockBeforeTable(), isLineSeparatorBlockAfterTable(), QTextEngine::itemize(), QTextControlPrivate::keyPressEvent(), QTextLine::layout_helper(), QTextDocumentLayoutPrivate::layoutFlow(), QTextDocumentPrivate::leftCursorPosition(), QTextBlockGroupPrivate::markBlocksDirty(), QTextCursorPrivate::movePosition(), QTextCursor::movePosition(), QTextDocumentPrivate::nextCursorPosition(), operator<(), QPlainTextEdit::paintEvent(), QTextCursor::positionInBlock(), QTextDocumentLayout::positionInlineObject(), QTextDocumentPrivate::previousCursorPosition(), QTextCursor::QTextCursor(), QTextControlPrivate::rectForPosition(), QSyntaxHighlighterPrivate::reformatBlocks(), QTextDocumentPrivate::rightCursorPosition(), QTextControl::selectionRect(), setBlockCharFormatHelper(), QTextDocumentPrivate::setBlockFormat(), QTextEdit::setText(), QTextCursorPrivate::setX(), QTextEngine::shape(), QTextDocumentPrivate::undoRedo(), and QTextOdfWriter::writeFrame().

{
    if (!p || !n)
        return 0;

    return p->blockMap().position(n);
}

previous()

QTextBlock QTextBlock::previous

(

)

const

Returns the text block in the document before this block, or an empty text block if this is the first one.

Note that the next block may be in a different frame or table to this block.

See also

next() begin() end()

Definition at line 1628 of file qtextobject.cpp.

Referenced by QPlainTextEditPrivate::_q_adjustScrollbars(), QPlainTextEditControl::blockBoundingRect(), QPlainTextEditPrivate::ensureVisible(), QTextDocument::find(), QTextControl::findNextPrevAnchor(), QPlainTextEditControl::hitTest(), QTextCursorPrivate::movePosition(), QTextCursor::movePosition(), QPlainTextEditPrivate::pageUpDown(), and qTextBlockPosition().

{
    if (!p)
        return QTextBlock();

    return QTextBlock(p, p->blockMap().previous(n));
}

revision()

int QTextBlock::revision

(

)

const

Returns the blocks revision.

Since

4.4

See also

setRevision(), QTextDocument::revision()

Definition at line 1434 of file qtextobject.cpp.

{
    if (!p || !n)
        return -1;

    const QTextBlockData *b = p->blockMap().fragment(n);
    return b->revision;
}

setLineCount()

void QTextBlock::setLineCount

(

int

count

)

Since

4.5

Sets the line count to count.

See also

lineCount()

Definition at line 1546 of file qtextobject.cpp.

Referenced by QPlainTextDocumentLayoutPrivate::relayout().

{
    if (!p || !n)
        return;
    p->blockMap().setSize(n, count, 2);
}

setRevision()

void QTextBlock::setRevision

(

int

rev

)

Sets a blocks revision to rev.

Since

4.4

See also

revision(), QTextDocument::revision()

Definition at line 1453 of file qtextobject.cpp.

{
    if (!p || !n)
        return;

    const QTextBlockData *b = p->blockMap().fragment(n);
    b->revision = rev;
}

setUserData()

void QTextBlock::setUserData

(

QTextBlockUserData *

data

)

Attaches the given data object to the text block.

Since

4.1

QTextBlockUserData can be used to store custom settings. The ownership is passed to the underlying text document, i.e. the provided QTextBlockUserData object will be deleted if the corresponding text block gets deleted. The user data object is not stored in the undo history, so it will not be available after undoing the deletion of a text block.

For example, if you write a programming editor in an IDE, you may want to let your user set breakpoints visually in your code for an integrated debugger. In a programming editor a line of text usually corresponds to one QTextBlock. The QTextBlockUserData interface allows the developer to store data for each QTextBlock, like for example in which lines of the source code the user has a breakpoint set. Of course this could also be stored externally, but by storing it inside the QTextDocument, it will for example be automatically deleted when the user deletes the associated line. It's really just a way to store custom information in the QTextDocument without using custom properties in QTextFormat which would affect the undo/redo stack.

Definition at line 1378 of file qtextobject.cpp.

{
    if (!p || !n)
        return;

    const QTextBlockData *b = p->blockMap().fragment(n);
    if (data != b->userData)
        delete b->userData;
    b->userData = data;
}

setUserState()

void QTextBlock::setUserState

(

int

state

)

Stores the specified state integer value in the text block.

Since

4.1

This may be useful for example in a syntax highlighter to store a text parsing state.

Definition at line 1415 of file qtextobject.cpp.

Referenced by QTextCopyHelper::appendFragment(), and QTextHtmlImporter::processBlockNode().

{
    if (!p || !n)
        return;

    const QTextBlockData *b = p->blockMap().fragment(n);
    b->userState = state;
}

setVisible()

void QTextBlock::setVisible

(

bool

visible

)

Sets the block's visibility to visible.

Since

4.4

See also

isVisible()

Definition at line 1491 of file qtextobject.cpp.

{
    if (!p || !n)
        return;

    const QTextBlockData *b = p->blockMap().fragment(n);
    b->hidden = !visible;
}

text()

QString QTextBlock::text

(

)

const

Returns the block's contents as plain text.

See also

length() charFormat() blockFormat()

Definition at line 1288 of file qtextobject.cpp.

Referenced by QScriptDebuggerCodeView::event(), findInBlock(), QTextControl::inputMethodQuery(), isLineSeparatorBlockAfterTable(), QTextCursorPrivate::movePosition(), QSyntaxHighlighterPrivate::reformatBlock(), QAccessibleTextEdit::text(), and QTextEngine::validate().

{
    if (!p || !n)
        return QString();

    const QString buffer = p->buffer();
    QString text;
    text.reserve(length());

    const int pos = position();
    QTextDocumentPrivate::FragmentIterator it = p->find(pos);
    QTextDocumentPrivate::FragmentIterator end = p->find(pos + length() - 1); // -1 to omit the block separator char
    for (; it != end; ++it) {
        const QTextFragmentData * const frag = it.value();
        text += QString::fromRawData(buffer.constData() + frag->stringPosition, frag->size_array[0]);
    }

    return text;
}

textDirection()

Qt::LayoutDirection QTextBlock::textDirection

(

)

const

Returns the resolved text direction.

Since

4.7

If the block has no explicit direction set, it will resolve the direction from the blocks content. Returns either Qt::LeftToRight or Qt::RightToLeft.

See also

QTextFormat::layoutDirection(), QString::isRightToLeft(), Qt::LayoutDirection

Definition at line 1247 of file qtextobject.cpp.

Referenced by QTextDocumentLayoutPrivate::drawListItem(), QTextHtmlExporter::emitBlockAttributes(), QTextList::itemText(), QTextDocumentLayoutPrivate::layoutBlock(), and QTextCursorPrivate::movePosition().

{
    Qt::LayoutDirection dir = blockFormat().layoutDirection();
    if (dir != Qt::LayoutDirectionAuto)
        return dir;

    dir = p->defaultTextOption.textDirection();
    if (dir != Qt::LayoutDirectionAuto)
        return dir;

    const QString buffer = p->buffer();

    const int pos = position();
    QTextDocumentPrivate::FragmentIterator it = p->find(pos);
    QTextDocumentPrivate::FragmentIterator end = p->find(pos + length() - 1); // -1 to omit the block separator char
    for (; it != end; ++it) {
        const QTextFragmentData * const frag = it.value();
        const QChar *p = buffer.constData() + frag->stringPosition;
        const QChar * const end = p + frag->size_array[0];
        while (p < end) {
            switch(QChar::direction(p->unicode()))
            {
            case QChar::DirL:
                return Qt::LeftToRight;
            case QChar::DirR:
            case QChar::DirAL:
                return Qt::RightToLeft;
            default:
                break;
            }
            ++p;
        }
    }
    return Qt::LeftToRight;
}

textList()

QTextList * QTextBlock::textList

(

)

const

If the block represents a list item, returns the list that the item belongs to; otherwise returns 0.

Definition at line 1322 of file qtextobject.cpp.

Referenced by QTextCopyHelper::appendFragment(), QTextHtmlExporter::emitBlock(), and QTextOdfWriter::writeBlock().

{
    if (!isValid())
        return 0;

    const QTextBlockFormat fmt = blockFormat();
    QTextObject *obj = p->document()->objectForFormat(fmt);
    return qobject_cast<QTextList *>(obj);
}

userData()

QTextBlockUserData * QTextBlock::userData

(

)

const

Returns a pointer to a QTextBlockUserData object if previously set with setUserData() or a null pointer.

Since

4.1

Definition at line 1341 of file qtextobject.cpp.

{
    if (!p || !n)
        return 0;

    const QTextBlockData *b = p->blockMap().fragment(n);
    return b->userData;
}

userState()

int QTextBlock::userState

(

)

const

Returns the integer value previously set with setUserState() or -1.

Since

4.1

Definition at line 1397 of file qtextobject.cpp.

Referenced by QTextCopyHelper::appendFragment(), QTextHtmlExporter::emitBlockAttributes(), QSyntaxHighlighter::previousBlockState(), and QSyntaxHighlighterPrivate::reformatBlocks().

{
    if (!p || !n)
        return -1;

    const QTextBlockData *b = p->blockMap().fragment(n);
    return b->userState;
}

Friends and Related Functions

QSyntaxHighlighter

friend class QSyntaxHighlighter

friend

Definition at line 201 of file qtextobject.h.

QTextDocumentPrivate

friend class QTextDocumentPrivate

friend

Definition at line 289 of file qtextobject.h.

QTextLayout

friend class QTextLayout

friend

Definition at line 290 of file qtextobject.h.

Properties

n

int QTextBlock::n

private

Definition at line 288 of file qtextobject.h.

Referenced by QTextDocumentPrivate::block(), fragmentIndex(), operator!=(), operator=(), and operator==().

p

QTextDocumentPrivate* QTextBlock::p

private

Definition at line 287 of file qtextobject.h.

Referenced by QTextDocumentPrivate::block(), docHandle(), operator!=(), operator=(), and operator==().

---

The documentation for this class was generated from the following files:

• /src/gui/text/qtextobject.h
• /src/gui/text/qtextobject.cpp