QTextFrame Class

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

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


Note: All functions in this class are reentrant.

Public Types

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


Qt-style synonym for QTextFrame::iterator.

Member Function Documentation

QTextFrame::QTextFrame(QTextDocument *document)

Creates a new empty frame for the text document.

[virtual] 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().

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.