QTextDocument¶
The
QTextDocument
class holds formatted text. More…
Synopsis¶
Functions¶
def
addResource
(type, name, resource)def
adjustSize
()def
allFormats
()def
availableRedoSteps
()def
availableUndoSteps
()def
baseUrl
()def
begin
()def
blockCount
()def
characterAt
(pos)def
characterCount
()def
clearUndoRedoStacks
([historyToClear=UndoAndRedoStacks])def
clone
([parent=None])def
defaultCursorMoveStyle
()def
defaultFont
()def
defaultStyleSheet
()def
defaultTextOption
()def
documentLayout
()def
documentMargin
()def
drawContents
(painter[, rect=QRectF()])def
end
()def
find
(expr, cursor[, options=QTextDocument.FindFlags()])def
find
(expr, cursor[, options=QTextDocument.FindFlags()])def
find
(expr[, from=0[, options=QTextDocument.FindFlags()]])def
find
(expr[, from=0[, options=QTextDocument.FindFlags()]])def
find
(subString, cursor[, options=QTextDocument.FindFlags()])def
find
(subString[, from=0[, options=QTextDocument.FindFlags()]])def
findBlock
(pos)def
findBlockByLineNumber
(blockNumber)def
findBlockByNumber
(blockNumber)def
firstBlock
()def
frameAt
(pos)def
idealWidth
()def
indentWidth
()def
isEmpty
()def
isModified
()def
isRedoAvailable
()def
isUndoAvailable
()def
isUndoRedoEnabled
()def
lastBlock
()def
lineCount
()def
markContentsDirty
(from, length)def
maximumBlockCount
()def
metaInformation
(info)def
object
(objectIndex)def
objectForFormat
(arg__1)def
pageCount
()def
pageSize
()def
print_
(printer)def
redo
(cursor)def
resource
(type, name)def
revision
()def
rootFrame
()def
setBaseUrl
(url)def
setDefaultCursorMoveStyle
(style)def
setDefaultFont
(font)def
setDefaultStyleSheet
(sheet)def
setDefaultTextOption
(option)def
setDocumentLayout
(layout)def
setDocumentMargin
(margin)def
setHtml
(html)def
setIndentWidth
(width)def
setMaximumBlockCount
(maximum)def
setMetaInformation
(info, arg__2)def
setPageSize
(size)def
setPlainText
(text)def
setTextWidth
(width)def
setUndoRedoEnabled
(enable)def
setUseDesignMetrics
(b)def
size
()def
textWidth
()def
toHtml
([encoding=QByteArray()])def
toPlainText
()def
toRawText
()def
undo
(cursor)def
useDesignMetrics
()
Virtual functions¶
def
clear
()def
createObject
(f)def
loadResource
(type, name)
Slots¶
def
redo
()def
setModified
([m=true])def
undo
()
Signals¶
def
baseUrlChanged
(url)def
blockCountChanged
(newBlockCount)def
contentsChange
(from, charsRemoved, charsAdded)def
contentsChanged
()def
cursorPositionChanged
(cursor)def
documentLayoutChanged
()def
modificationChanged
(m)def
redoAvailable
(arg__1)def
undoAvailable
(arg__1)def
undoCommandAdded
()
Detailed Description¶
QTextDocument
is a container for structured rich text documents, providing support for styled text and various types of document elements, such as lists, tables, frames, and images. They can be created for use in aQTextEdit
, or used independently.Each document element is described by an associated format object. Each format object is treated as a unique object by QTextDocuments, and can be passed to
objectForFormat()
to obtain the document element that it is applied to.A
QTextDocument
can be edited programmatically using aQTextCursor
, and its contents can be examined by traversing the document structure. The entire document structure is stored as a hierarchy of document elements beneath the root frame, found with therootFrame()
function. Alternatively, if you just want to iterate over the textual contents of the document you can usebegin()
,end()
, andfindBlock()
to retrieve text blocks that you can examine and iterate over.The layout of a document is determined by the
documentLayout()
; you can create your ownQAbstractTextDocumentLayout
subclass and set it usingsetDocumentLayout()
if you want to use your own layout logic. The document’s title and other meta-information can be obtained by calling themetaInformation()
function. For documents that are exposed to users through theQTextEdit
class, the document title is also available via thedocumentTitle()
function.The
toPlainText()
andtoHtml()
convenience functions allow you to retrieve the contents of the document as plain text and HTML. The document’s text can be searched using thefind()
functions.Undo/redo of operations performed on the document can be controlled using the
setUndoRedoEnabled()
function. The undo/redo system can be controlled by an editor widget through theundo()
andredo()
slots; the document also providescontentsChanged()
,undoAvailable()
, andredoAvailable()
signals that inform connected editor widgets about the state of the undo/redo system. The following are the undo/redo operations of aQTextDocument
:
Insertion or removal of characters. A sequence of insertions or removals within the same text block are regarded as a single undo/redo operation.
Insertion or removal of text blocks. Sequences of insertion or removals in a single operation (e.g., by selecting and then deleting text) are regarded as a single undo/redo operation.
Text character format changes.
Text block format changes.
Text block group format changes.
-
class
QTextDocument
([parent=None])¶ QTextDocument(text[, parent=None])
- param parent
QObject
- param text
unicode
Constructs an empty
QTextDocument
with the givenparent
.
-
PySide2.QtGui.QTextDocument.
MetaInformation
¶ This enum describes the different types of meta information that can be added to a document.
Constant
Description
QTextDocument.DocumentTitle
The title of the document.
QTextDocument.DocumentUrl
The url of the document. The
loadResource()
function uses this url as the base when loading relative resources.See also
-
PySide2.QtGui.QTextDocument.
FindFlag
¶ This enum describes the options available to
QTextDocument
‘s find function. The options can be OR-ed together from the following list:Constant
Description
QTextDocument.FindBackward
Search backwards instead of forwards.
QTextDocument.FindCaseSensitively
By default find works case insensitive. Specifying this option changes the behaviour to a case sensitive find operation.
QTextDocument.FindWholeWords
Makes find match only complete words.
-
PySide2.QtGui.QTextDocument.
ResourceType
¶ This enum describes the types of resources that can be loaded by
QTextDocument
‘sloadResource()
function.Constant
Description
QTextDocument.HtmlResource
The resource contains HTML.
QTextDocument.ImageResource
The resource contains image data. Currently supported data types are
Pixmap
andImage
. If the corresponding variant is of typeByteArray
then Qt attempts to load the image usingloadFromData
.Icon
is currently not supported. The icon needs to be converted to one of the supported types first, for example usingpixmap
.QTextDocument.StyleSheetResource
The resource contains CSS.
QTextDocument.UserResource
The first available value for user defined resource types.
See also
-
PySide2.QtGui.QTextDocument.
Stacks
¶ Constant
Description
QTextDocument.UndoStack
The undo stack.
QTextDocument.RedoStack
The redo stack.
QTextDocument.UndoAndRedoStacks
Both the undo and redo stacks.
New in version 4.7.
-
PySide2.QtGui.QTextDocument.
addResource
(type, name, resource)¶ - Parameters
type –
int
name –
QUrl
resource – object
Adds the resource
resource
to the resource cache, usingtype
andname
as identifiers.type
should be a value fromResourceType
.For example, you can add an image as a resource in order to reference it from within the document:
document->addResource(QTextDocument::ImageResource, QUrl("mydata://image.png"), QVariant(image));
The image can be inserted into the document using the
QTextCursor
API:QTextImageFormat imageFormat; imageFormat.setName("mydata://image.png"); cursor.insertImage(imageFormat);
Alternatively, you can insert images using the HTML
img
tag:editor->append("<img src=\"mydata://image.png\" />");
-
PySide2.QtGui.QTextDocument.
adjustSize
()¶ Adjusts the document to a reasonable size.
See also
-
PySide2.QtGui.QTextDocument.
allFormats
()¶ - Return type
Returns a vector of text formats for all the formats used in the document.
-
PySide2.QtGui.QTextDocument.
availableRedoSteps
()¶ - Return type
int
Returns the number of available redo steps.
See also
-
PySide2.QtGui.QTextDocument.
availableUndoSteps
()¶ - Return type
int
Returns the number of available undo steps.
See also
-
PySide2.QtGui.QTextDocument.
baseUrl
()¶ - Return type
QUrl
See also
-
PySide2.QtGui.QTextDocument.
baseUrlChanged
(url)¶ - Parameters
url –
QUrl
-
PySide2.QtGui.QTextDocument.
begin
()¶ - Return type
Returns the document’s first text block.
See also
-
PySide2.QtGui.QTextDocument.
blockCount
()¶ - Return type
int
-
PySide2.QtGui.QTextDocument.
blockCountChanged
(newBlockCount)¶ - Parameters
newBlockCount –
int
-
PySide2.QtGui.QTextDocument.
characterAt
(pos)¶ - Parameters
pos –
int
- Return type
QChar
Returns the character at position
pos
, or a null character if the position is out of range.See also
-
PySide2.QtGui.QTextDocument.
characterCount
()¶ - Return type
int
Returns the number of characters of this document.
See also
-
PySide2.QtGui.QTextDocument.
clear
()¶ Clears the document.
-
PySide2.QtGui.QTextDocument.
clearUndoRedoStacks
([historyToClear=UndoAndRedoStacks])¶ - Parameters
historyToClear –
Stacks
Clears the stacks specified by
stacksToClear
.This method clears any commands on the undo stack, the redo stack, or both (the default). If commands are cleared, the appropriate signals are emitted,
undoAvailable()
orredoAvailable()
.See also
-
PySide2.QtGui.QTextDocument.
clone
([parent=None])¶ - Parameters
parent –
QObject
- Return type
Creates a new
QTextDocument
that is a copy of this text document.parent
is the parent of the returned text document.
-
PySide2.QtGui.QTextDocument.
contentsChange
(from, charsRemoved, charsAdded)¶ - Parameters
from –
int
charsRemoved –
int
charsAdded –
int
-
PySide2.QtGui.QTextDocument.
contentsChanged
()¶
-
PySide2.QtGui.QTextDocument.
createObject
(f)¶ - Parameters
f –
QTextFormat
- Return type
Creates and returns a new document object (a
QTextObject
), based on the givenformat
.QTextObjects will always get created through this method, so you must reimplement it if you use custom text objects inside your document.
-
PySide2.QtGui.QTextDocument.
cursorPositionChanged
(cursor)¶ - Parameters
cursor –
QTextCursor
-
PySide2.QtGui.QTextDocument.
defaultCursorMoveStyle
()¶ - Return type
CursorMoveStyle
The default cursor movement style is used by all
QTextCursor
objects created from the document. The default isLogicalMoveStyle
.See also
-
PySide2.QtGui.QTextDocument.
defaultFont
()¶ - Return type
Returns the default font to be used in the document layout.
See also
-
PySide2.QtGui.QTextDocument.
defaultStyleSheet
()¶ - Return type
unicode
See also
-
PySide2.QtGui.QTextDocument.
defaultTextOption
()¶ - Return type
The default text option is used on all
QTextLayout
objects in the document. This allows setting global properties for the document such as the default word wrap mode.See also
-
PySide2.QtGui.QTextDocument.
documentLayout
()¶ - Return type
Returns the document layout for this document.
See also
-
PySide2.QtGui.QTextDocument.
documentLayoutChanged
()¶
-
PySide2.QtGui.QTextDocument.
documentMargin
()¶ - Return type
qreal
See also
-
PySide2.QtGui.QTextDocument.
drawContents
(painter[, rect=QRectF()])¶ - Parameters
painter –
QPainter
rect –
QRectF
Draws the content of the document with painter
p
, clipped torect
. Ifrect
is a null rectangle (default) then the document is painted unclipped.
-
PySide2.QtGui.QTextDocument.
end
()¶ - Return type
This function returns a block to test for the end of the document while iterating over it.
it = doc.begin() while it != doc.end(): print it.text() it = it.next()
The block returned is invalid and represents the block after the last block in the document. You can use
lastBlock()
to retrieve the last valid block of the document.See also
-
PySide2.QtGui.QTextDocument.
find
(expr, cursor[, options=QTextDocument.FindFlags()])¶ - Parameters
expr –
QRegExp
cursor –
QTextCursor
options –
FindFlags
- Return type
-
PySide2.QtGui.QTextDocument.
find
(subString[, from=0[, options=QTextDocument.FindFlags()]]) - Parameters
subString – unicode
from –
int
options –
FindFlags
- Return type
-
PySide2.QtGui.QTextDocument.
find
(subString, cursor[, options=QTextDocument.FindFlags()]) - Parameters
subString – unicode
cursor –
QTextCursor
options –
FindFlags
- Return type
-
PySide2.QtGui.QTextDocument.
find
(expr[, from=0[, options=QTextDocument.FindFlags()]]) - Parameters
expr –
QRegularExpression
from –
int
options –
FindFlags
- Return type
-
PySide2.QtGui.QTextDocument.
find
(expr, cursor[, options=QTextDocument.FindFlags()]) - Parameters
expr –
QRegularExpression
cursor –
QTextCursor
options –
FindFlags
- Return type
-
PySide2.QtGui.QTextDocument.
find
(expr[, from=0[, options=QTextDocument.FindFlags()]]) - Parameters
expr –
QRegExp
from –
int
options –
FindFlags
- Return type
-
PySide2.QtGui.QTextDocument.
findBlock
(pos)¶ - Parameters
pos –
int
- Return type
Returns the text block that contains the
pos
-th character.
-
PySide2.QtGui.QTextDocument.
findBlockByLineNumber
(blockNumber)¶ - Parameters
blockNumber –
int
- Return type
Returns the text block that contains the specified
lineNumber
.See also
-
PySide2.QtGui.QTextDocument.
findBlockByNumber
(blockNumber)¶ - Parameters
blockNumber –
int
- Return type
Returns the text block with the specified
blockNumber
.See also
-
PySide2.QtGui.QTextDocument.
firstBlock
()¶ - Return type
Returns the document’s first text block.
-
PySide2.QtGui.QTextDocument.
frameAt
(pos)¶ - Parameters
pos –
int
- Return type
Returns the frame that contains the text cursor position
pos
.
-
PySide2.QtGui.QTextDocument.
idealWidth
()¶ - Return type
qreal
Returns the ideal width of the text document. The ideal width is the actually used width of the document without optional alignments taken into account. It is always <=
size()
. width() .See also
-
PySide2.QtGui.QTextDocument.
indentWidth
()¶ - Return type
qreal
See also
-
PySide2.QtGui.QTextDocument.
isEmpty
()¶ - Return type
bool
Returns
true
if the document is empty; otherwise returnsfalse
.
-
PySide2.QtGui.QTextDocument.
isModified
()¶ - Return type
bool
-
PySide2.QtGui.QTextDocument.
isRedoAvailable
()¶ - Return type
bool
Returns
true
if redo is available; otherwise returnsfalse
.See also
-
PySide2.QtGui.QTextDocument.
isUndoAvailable
()¶ - Return type
bool
Returns
true
if undo is available; otherwise returnsfalse
.See also
-
PySide2.QtGui.QTextDocument.
isUndoRedoEnabled
()¶ - Return type
bool
-
PySide2.QtGui.QTextDocument.
lastBlock
()¶ - Return type
Returns the document’s last (valid) text block.
-
PySide2.QtGui.QTextDocument.
lineCount
()¶ - Return type
int
Returns the number of lines of this document (if the layout supports this). Otherwise, this is identical to the number of blocks.
See also
-
PySide2.QtGui.QTextDocument.
loadResource
(type, name)¶ - Parameters
type –
int
name –
QUrl
- Return type
object
Loads data of the specified
type
from the resource with the givenname
.This function is called by the rich text engine to request data that isn’t directly stored by
QTextDocument
, but still associated with it. For example, images are referenced indirectly by the name attribute of aQTextImageFormat
object.When called by Qt,
type
is one of the values ofResourceType
.If the
QTextDocument
is a child object of aQObject
that has an invokable method such asQTextEdit
,QTextBrowser
or aQTextDocument
itself then the default implementation tries to retrieve the data from the parent.
-
PySide2.QtGui.QTextDocument.
markContentsDirty
(from, length)¶ - Parameters
from –
int
length –
int
Marks the contents specified by the given
position
andlength
as “dirty”, informing the document that it needs to be laid out again.
-
PySide2.QtGui.QTextDocument.
maximumBlockCount
()¶ - Return type
int
See also
-
PySide2.QtGui.QTextDocument.
metaInformation
(info)¶ - Parameters
info –
MetaInformation
- Return type
unicode
Returns meta information about the document of the type specified by
info
.See also
-
PySide2.QtGui.QTextDocument.
modificationChanged
(m)¶ - Parameters
m –
bool
-
PySide2.QtGui.QTextDocument.
object
(objectIndex)¶ - Parameters
objectIndex –
int
- Return type
Returns the text object associated with the given
objectIndex
.
-
PySide2.QtGui.QTextDocument.
objectForFormat
(arg__1)¶ - Parameters
arg__1 –
QTextFormat
- Return type
Returns the text object associated with the format
f
.
-
PySide2.QtGui.QTextDocument.
pageCount
()¶ - Return type
int
returns the number of pages in this document.
-
PySide2.QtGui.QTextDocument.
pageSize
()¶ - Return type
QSizeF
See also
-
PySide2.QtGui.QTextDocument.
print_
(printer)¶ - Parameters
printer –
QPagedPaintDevice
Prints the document to the given
printer
. TheQPagedPaintDevice
must be set up before being used with this function.This is only a convenience method to print the whole document to the printer.
If the document is already paginated through a specified height in the
pageSize()
property it is printed as-is.If the document is not paginated, like for example a document used in a
QTextEdit
, then a temporary copy of the document is created and the copy is broken into multiple pages according to the size of the paint device’s paperRect(). By default a 2 cm margin is set around the document contents. In addition the current page number is printed at the bottom of each page.See also
print()
-
PySide2.QtGui.QTextDocument.
redo
()¶ This is an overloaded function.
Redoes the last editing operation on the document if
redo is available
.
-
PySide2.QtGui.QTextDocument.
redo
(cursor) - Parameters
cursor –
QTextCursor
Redoes the last editing operation on the document if
redo is available
.The provided
cursor
is positioned at the end of the location where the edition operation was redone.
-
PySide2.QtGui.QTextDocument.
redoAvailable
(arg__1)¶ - Parameters
arg__1 –
bool
-
PySide2.QtGui.QTextDocument.
resource
(type, name)¶ - Parameters
type –
int
name –
QUrl
- Return type
object
Returns data of the specified
type
from the resource with the givenname
.This function is called by the rich text engine to request data that isn’t directly stored by
QTextDocument
, but still associated with it. For example, images are referenced indirectly by the name attribute of aQTextImageFormat
object.Resources are cached internally in the document. If a resource can not be found in the cache,
loadResource
is called to try to load the resource.loadResource
should then useaddResource
to add the resource to the cache.See also
ResourceType
-
PySide2.QtGui.QTextDocument.
revision
()¶ - Return type
int
Returns the document’s revision (if undo is enabled).
The revision is guaranteed to increase when a document that is not modified is edited.
See also
-
PySide2.QtGui.QTextDocument.
rootFrame
()¶ - Return type
Returns the document’s root frame.
-
PySide2.QtGui.QTextDocument.
setDefaultCursorMoveStyle
(style)¶ - Parameters
style –
CursorMoveStyle
Sets the default cursor movement style to the given
style
.See also
-
PySide2.QtGui.QTextDocument.
setDefaultFont
(font)¶ - Parameters
font –
QFont
Sets the default
font
to use in the document layout.See also
-
PySide2.QtGui.QTextDocument.
setDefaultStyleSheet
(sheet)¶ - Parameters
sheet – unicode
See also
-
PySide2.QtGui.QTextDocument.
setDefaultTextOption
(option)¶ - Parameters
option –
QTextOption
Sets the default text option to
option
.See also
-
PySide2.QtGui.QTextDocument.
setDocumentLayout
(layout)¶ - Parameters
layout –
QAbstractTextDocumentLayout
Sets the document to use the given
layout
. The previous layout is deleted.See also
-
PySide2.QtGui.QTextDocument.
setDocumentMargin
(margin)¶ - Parameters
margin –
qreal
See also
-
PySide2.QtGui.QTextDocument.
setHtml
(html)¶ - Parameters
html – unicode
Replaces the entire contents of the document with the given HTML-formatted text in the
html
string. The undo/redo history is reset when this function is called.The HTML formatting is respected as much as possible; for example, “<b>bold</b> text” will produce text where the first word has a font weight that gives it a bold appearance: “bold text”.
Note
It is the responsibility of the caller to make sure that the text is correctly decoded when a
QString
containing HTML is created and passed to .See also
-
PySide2.QtGui.QTextDocument.
setIndentWidth
(width)¶ - Parameters
width –
qreal
Sets the
width
used for text list and text block indenting.The indent properties of
QTextListFormat
andQTextBlockFormat
specify multiples of this value. The default indent width is 40 .See also
-
PySide2.QtGui.QTextDocument.
setMaximumBlockCount
(maximum)¶ - Parameters
maximum –
int
See also
-
PySide2.QtGui.QTextDocument.
setMetaInformation
(info, arg__2)¶ - Parameters
info –
MetaInformation
arg__2 – unicode
Sets the document’s meta information of the type specified by
info
to the givenstring
.See also
-
PySide2.QtGui.QTextDocument.
setModified
([m=true])¶ - Parameters
m –
bool
See also
-
PySide2.QtGui.QTextDocument.
setPageSize
(size)¶ - Parameters
size –
QSizeF
See also
-
PySide2.QtGui.QTextDocument.
setPlainText
(text)¶ - Parameters
text – unicode
Replaces the entire contents of the document with the given plain
text
. The undo/redo history is reset when this function is called.See also
-
PySide2.QtGui.QTextDocument.
setTextWidth
(width)¶ - Parameters
width –
qreal
See also
-
PySide2.QtGui.QTextDocument.
setUndoRedoEnabled
(enable)¶ - Parameters
enable –
bool
See also
-
PySide2.QtGui.QTextDocument.
setUseDesignMetrics
(b)¶ - Parameters
b –
bool
See also
-
PySide2.QtGui.QTextDocument.
size
()¶ - Return type
QSizeF
-
PySide2.QtGui.QTextDocument.
textWidth
()¶ - Return type
qreal
See also
-
PySide2.QtGui.QTextDocument.
toHtml
([encoding=QByteArray()])¶ - Parameters
encoding –
QByteArray
- Return type
unicode
Returns a string containing an HTML representation of the document.
The
encoding
parameter specifies the value for the charset attribute in the html header. For example if ‘utf-8’ is specified then the beginning of the generated html will look like this:plain = QString("#include <QtCore>") html = Qt::escape(plain) # html == "#include <QtCore>"
If no encoding is specified then no such meta information is generated.
If you later on convert the returned html string into a byte array for transmission over a network or when saving to disk you should specify the encoding you’re going to use for the conversion to a byte array here.
See also
-
PySide2.QtGui.QTextDocument.
toPlainText
()¶ - Return type
unicode
Returns the plain text contained in the document. If you want formatting information use a
QTextCursor
instead.This function returns the same as
toRawText()
, but will replace some unicode characters with ASCII alternatives. In particular, no-break space (U+00A0) is replaced by a regular space (U+0020), and both paragraph (U+2029) and line (U+2028) separators are replaced by line feed (U+000A). If you need the precise contents of the document, usetoRawText()
instead.Note
Embedded objects, such as images, are represented by a Unicode value U+FFFC (OBJECT REPLACEMENT CHARACTER).
See also
-
PySide2.QtGui.QTextDocument.
toRawText
()¶ - Return type
unicode
Returns the raw text contained in the document without any formatting information. If you want formatting information use a
QTextCursor
instead.See also
-
PySide2.QtGui.QTextDocument.
undo
()¶ This is an overloaded function.
-
PySide2.QtGui.QTextDocument.
undo
(cursor) - Parameters
cursor –
QTextCursor
Undoes the last editing operation on the document if undo is available. The provided
cursor
is positioned at the end of the location where the edition operation was undone.See the Qt Undo Framework documentation for details.
See also
-
PySide2.QtGui.QTextDocument.
undoAvailable
(arg__1)¶ - Parameters
arg__1 –
bool
-
PySide2.QtGui.QTextDocument.
undoCommandAdded
()¶
-
PySide2.QtGui.QTextDocument.
useDesignMetrics
()¶ - Return type
bool
See also
© 2018 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.