- Qt 6.8
- Qt GUI
- C++ Classes
- QTextFrame
- Qt 6.8.3 Reference Documentation

# QTextFrame Class

The QTextFrame class represents a frame in a QTextDocument. More...

Header: | `#include <QTextFrame>`
CMake: | `find_package(Qt6 REQUIRED COMPONENTS Gui)` `target_link_libraries(mytarget PRIVATE Qt6::Gui)`
qmake: | `QT += gui`
Inherits: | QTextObject
Inherited By: | QTextTable

- List of all members, including inherited members
- QTextFrame is part of Rich Text Processing APIs.

Note: All functions in this class are reentrant.

## Public Types

class | iterator
| Iterator

## Public Functions

| QTextFrame(QTextDocument *document)
virtual | ~QTextFrame()
QTextFrame::iterator | begin() const
QList<QTextFrame *> | childFrames() const
QTextFrame::iterator | end() const
QTextCursor | firstCursorPosition() const
int | firstPosition() const
QTextFrameFormat | frameFormat() const
QTextCursor | lastCursorPosition() const
int | lastPosition() const
QTextFrame * | parentFrame() const
void | setFrameFormat(const QTextFrameFormat &format)

## Detailed Description

Text frames provide structure for the text in a document. They are used as generic containers for other document elements. Frames are usually created by using QTextCursor::insertFrame().

Frames can be used to create hierarchical structures in rich text documents. Each document has a root frame (QTextDocument::rootFrame()), and each frame beneath the root frame has a parent frame and a (possibly empty) list of child frames. The parent frame can be found with parentFrame(), and the childFrames() function provides a list of child frames.

Each frame contains at least one text block to enable text cursors to insert new document elements within. As a result, the QTextFrame::iterator class is used to traverse both the blocks and child frames within a given frame. The first and last child elements in the frame can be found with begin() and end().

A frame also has a format (specified using QTextFrameFormat) which can be set with setFormat() and read with format().

Text cursors can be obtained that point to the first and last valid cursor positions within a frame; use the firstCursorPosition() and lastCursorPosition() functions for this. The frame's extent in the document can be found with firstPosition() and lastPosition().

You can iterate over a frame's contents using the QTextFrame::iterator class: this provides read-only access to its internal list of text blocks and child frames.

See also QTextCursor and QTextDocument.

## Member Type Documentation

### QTextFrame::Iterator

Qt-style synonym for QTextFrame::iterator.

## Member Function Documentation

### `[explicit]` QTextFrame::QTextFrame(QTextDocument *document)

Creates a new empty frame for the text document.

### `[virtual noexcept]` QTextFrame::~QTextFrame()

Destroys the text frame.

Warning: Text frames are owned by the document, so you should never destroy them yourself. In order to remove a frame from its document, remove its contents using a `QTextCursor`.

### QTextFrame::iterator QTextFrame::begin() const

Returns an iterator pointing to the first document element inside the frame. Please see the document STL-style-Iterators for more information.

See also end().

### QList<QTextFrame *> QTextFrame::childFrames() const

Returns a (possibly empty) list of the frame's child frames.

See also parentFrame().

### QTextFrame::iterator QTextFrame::end() const

Returns an iterator pointing to the position past the last document element inside the frame. Please see the document STL-Style Iterators for more information.

See also begin().

### QTextCursor QTextFrame::firstCursorPosition() const

Returns the first cursor position inside the frame.

See also lastCursorPosition(), firstPosition(), and lastPosition().

### int QTextFrame::firstPosition() const

Returns the first document position inside the frame.

See also lastPosition(), firstCursorPosition(), and lastCursorPosition().

### QTextFrameFormat QTextFrame::frameFormat() const

Returns the frame's format.

See also setFrameFormat().

### QTextCursor QTextFrame::lastCursorPosition() const

Returns the last cursor position inside the frame.

See also firstCursorPosition(), firstPosition(), and lastPosition().

### int QTextFrame::lastPosition() const

Returns the last document position inside the frame.

See also firstPosition(), firstCursorPosition(), and lastCursorPosition().

### QTextFrame *QTextFrame::parentFrame() const

Returns the frame's parent frame. If the frame is the root frame of a document, this will return 0.

See also childFrames() and QTextDocument::rootFrame().

### void QTextFrame::setFrameFormat(const QTextFrameFormat &format)

Sets the frame's format.

See also frameFormat().