Contents

• Public Types
• Public Functions
• Detailed Description

Detailed Description

TheQTextBlock class provides a container for text fragments in aQTextDocument.

A text block encapsulates a block or paragraph of text in aQTextDocument.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 aQTextDocument, 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 byQTextCursor instead.

Each text block is located at a specificposition() in adocument(). The contents of the block can be obtained by using thetext() function. Thelength() function determines the block's size within the document (including formatting characters). The visual properties of the block are determined by its textlayout(), itscharFormat(), and itsblockFormat().

Thenext() andprevious() 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 callingisValid().

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

Member Type Documentation

typedef QTextBlock::Iterator

Qt-style synonym forQTextBlock::iterator.

Member Function Documentation

QTextBlock::QTextBlock(constQTextBlock & other)

Copies theother text block's attributes to this text block.

iterator QTextBlock::begin() const

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

See alsoend().

QTextBlockFormat QTextBlock::blockFormat() const

Returns theQTextBlockFormat that describes block-specific properties.

See alsocharFormat().

int QTextBlock::blockFormatIndex() const

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

See alsoQTextDocument::allFormats().

int QTextBlock::blockNumber() const

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

This function was introduced in Qt 4.4.

See alsoQTextCursor::blockNumber().

QTextCharFormat QTextBlock::charFormat() const

Returns theQTextCharFormat that describes the block's character format. The block's character format is used when inserting text into an empty block.

See alsoblockFormat().

int QTextBlock::charFormatIndex() const

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

See alsoQTextDocument::allFormats().

void QTextBlock::clearLayout()

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

This function was introduced in Qt 4.4.

See alsolayout().

bool QTextBlock::contains(int position) const

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

constQTextDocument * QTextBlock::document() const

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

iterator QTextBlock::end() const

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

See alsobegin(),next(), andprevious().

int QTextBlock::firstLineNumber() const

Returns the first line number of this block, or -1 if the block is invalid. Unless the layout supports it, the line number is identical to the block number.

This function was introduced in Qt 4.5.

See alsoQTextBlock::blockNumber().

bool QTextBlock::isValid() const

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

bool QTextBlock::isVisible() const

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

This function was introduced in Qt 4.4.

See alsosetVisible().

QTextLayout * QTextBlock::layout() const

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

Note that the returnedQTextLayout object can only be modified from the documentChanged implementation of aQAbstractTextDocumentLayout subclass. Any changes applied from the outside cause undefined behavior.

See alsoclearLayout().

int QTextBlock::length() const

Returns the length of the block in characters.

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

See alsotext(),charFormat(), andblockFormat().

int QTextBlock::lineCount() const

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

This function was introduced in Qt 4.5.

See alsosetLineCount().

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 alsoprevious(),begin(), andend().

int QTextBlock::position() const

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

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 alsonext(),begin(), andend().

int QTextBlock::revision() const

Returns the blocks revision.

This function was introduced in Qt 4.4.

See alsosetRevision() andQTextDocument::revision().

void QTextBlock::setLineCount(int count)

Sets the line count tocount.

This function was introduced in Qt 4.5.

See alsolineCount().

void QTextBlock::setRevision(int rev)

Sets a blocks revision torev.

This function was introduced in Qt 4.4.

See alsorevision() andQTextDocument::revision().

void QTextBlock::setUserData(QTextBlockUserData * data)

Attaches the givendata object to the text block.

QTextBlockUserData can be used to store custom settings. The ownership is passed to the underlying text document, i.e. the providedQTextBlockUserData 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 oneQTextBlock. TheQTextBlockUserData interface allows the developer to store data for eachQTextBlock, 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 theQTextDocument, 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 theQTextDocument without using custom properties inQTextFormat which would affect the undo/redo stack.

This function was introduced in Qt 4.1.

See alsouserData().

void QTextBlock::setUserState(int state)

Stores the specifiedstate integer value in the text block. This may be useful for example in a syntax highlighter to store a text parsing state.

This function was introduced in Qt 4.1.

See alsouserState().

void QTextBlock::setVisible(bool visible)

Sets the block's visibility tovisible.

This function was introduced in Qt 4.4.

See alsoisVisible().

QString QTextBlock::text() const

Returns the block's contents as plain text.

See alsolength(),charFormat(), andblockFormat().

Qt::LayoutDirection QTextBlock::textDirection() const

Returns the resolved text direction.

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

This function was introduced in Qt 4.7.

See alsoQTextFormat::layoutDirection(),QString::isRightToLeft(), andQt::LayoutDirection.

QTextList * QTextBlock::textList() const

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

QTextBlockUserData * QTextBlock::userData() const

Returns a pointer to aQTextBlockUserData object if previously set withsetUserData() or a null pointer.

This function was introduced in Qt 4.1.

See alsosetUserData().

int QTextBlock::userState() const

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

This function was introduced in Qt 4.1.

See alsosetUserState().

bool QTextBlock::operator!=(constQTextBlock & other) const

Returns true if this text block is different from theother text block.

bool QTextBlock::operator<(constQTextBlock & other) const

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

QTextBlock & QTextBlock::operator=(constQTextBlock & other)

Assigns theother text block to this text block.

bool QTextBlock::operator==(constQTextBlock & other) const

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