QTextCursor Class

成员函数文档

QTextCursor::QTextCursor()

构造一个空游标。

[explicit] QTextCursor::QTextCursor(QTextDocument *document)

构造一个光标，指向document 的开头。

[explicit] QTextCursor::QTextCursor(QTextFrame *frame)

构造一个光标，指向frame 的开头。

[explicit] QTextCursor::QTextCursor(const QTextBlock &block)

构造一个光标，指向block 的开头。

QTextCursor::QTextCursor(const QTextCursor &cursor)

构造一个新游标，它是cursor 的副本。

[noexcept] QTextCursor::~QTextCursor()

摧毁QTextCursor.

int QTextCursor::anchor() const

返回锚点位置；这与position() 相同，除非存在选区，在这种情况下，position() 标记选区的一端，anchor() 标记另一端。与光标位置一样，锚点位置也在字符之间。

另请参阅 position()、setPosition()、movePosition()、selectionStart() 和selectionEnd()。

bool QTextCursor::atBlockEnd() const

如果光标位于程序块的末尾，则返回true ；否则返回false 。

另请参阅 atBlockStart() 和atEnd() 。

bool QTextCursor::atBlockStart() const

如果光标位于程序块的起始位置，则返回true ；否则返回false 。

另请参见 atBlockEnd() 和atStart()。

bool QTextCursor::atEnd() const

如果光标位于文档末尾，则返回true ；否则返回false 。

另请参阅 atStart() 和atBlockEnd()。

bool QTextCursor::atStart() const

如果光标位于文档的起始位置，则返回true ；否则返回false 。

另请参阅 atBlockStart() 和atEnd()。

void QTextCursor::beginEditBlock()

表示文档上编辑操作块的开始，从撤消/重做的角度看，这些操作应显示为单个操作。

例如

QTextCursor cursor(textDocument);
cursor.beginEditBlock();
cursor.insertText("Hello");
cursor.insertText("World");
cursor.endEditBlock();

textDocument->undo();

调用 undo() 将撤销两个插入操作，从而删除 "World "和 "Hello"。

可以嵌套调用 beginEditBlock 和endEditBlock 。最上面的一对将决定撤销/重做操作的范围。

另请参阅 endEditBlock() 。

QTextBlock QTextCursor::block() const

返回包含游标的数据块。

QTextCharFormat QTextCursor::blockCharFormat() const

返回光标所在块的块字符格式。

块字符格式是在空块开头插入文本时使用的格式。

另请参阅 setBlockCharFormat()。

QTextBlockFormat QTextCursor::blockFormat() const

返回光标所在块的块格式。

另请参阅 setBlockFormat() 和charFormat()。

int QTextCursor::blockNumber() const

返回游标所在块的编号，如果游标无效，则返回 0。

请注意，该函数只适用于没有表格或框架等复杂对象的文档。

QTextCharFormat QTextCursor::charFormat() const

返回光标position() 前的字符格式。如果光标位于非空文本块的开头，则返回光标后面字符的格式。

另请参阅 setCharFormat()、insertText() 和blockFormat()。

void QTextCursor::clearSelection()

通过将锚点设置到光标位置来清除当前选区。

请注意，它不会删除选区的文本。

另请参阅 removeSelectedText() 和hasSelection()。

int QTextCursor::columnNumber() const

返回光标在其包含行中的位置。

请注意，这是相对于包裹行的列数，而不是相对于块（即段落）的列数。

您可能需要调用positionInBlock() 来代替。

另请参阅 positionInBlock()。

QTextList *QTextCursor::createList(const QTextListFormat &format)

以给定的format 创建并返回一个新的列表，并将当前段落作为光标所在的第一个列表项。

另请参阅 insertList() 和currentList()。

QTextList *QTextCursor::createList(QTextListFormat::Style style)

这是一个重载函数。

使用给定的style 创建并返回一个新的列表，并将光标的当前段落作为列表的第一项。

使用的样式由QTextListFormat::Style 枚举定义。

另请参阅 insertList() 和currentList()。

QTextFrame *QTextCursor::currentFrame() const

返回指向当前帧的指针。如果光标无效，则返回nullptr 。

另请参阅 insertFrame().

QTextList *QTextCursor::currentList() const

如果光标position() 位于属于列表一部分的块内，则返回当前列表；否则返回nullptr 。

另请参阅 insertList() 和createList()。

QTextTable *QTextCursor::currentTable() const

如果游标position() 位于属于表格一部分的数据块内，则返回指向当前表格的指针；否则返回nullptr 。

另请参见 insertTable()。

void QTextCursor::deleteChar()

如果没有选定文本，则删除当前光标位置上的字符；否则删除选定文本。

另请参阅 deletePreviousChar()、hasSelection() 和clearSelection()。

void QTextCursor::deletePreviousChar()

如果没有选定文本，则删除当前光标位置之前的字符；否则删除选定文本。

另请参阅 deleteChar()、hasSelection() 和clearSelection()。

QTextDocument *QTextCursor::document() const

返回与该游标相关联的文档。

void QTextCursor::endEditBlock()

表示文档上编辑操作块的结束，从撤消/重做的角度看，这些操作应显示为单个操作。

另请参见 beginEditBlock()。

bool QTextCursor::hasComplexSelection() const

如果游标包含的选区不是从selectionStart() 到selectionEnd() 的简单范围，则返回true ；否则返回false 。

复杂选区是指在表格中至少跨越两个单元格的选区；其范围由selectedTableCells() 指定。

bool QTextCursor::hasSelection() const

如果游标包含一个选区，则返回true ；否则返回false 。

void QTextCursor::insertBlock()

在光标position() 处插入一个新的空数据块，当前数据块为blockFormat() 和charFormat()。

另请参阅 setBlockFormat()。

void QTextCursor::insertBlock(const QTextBlockFormat &format)

这是一个重载函数。

在光标position() 处插入一个新的空块，块格式为format ，当前的charFormat() 为块字符格式。

另请参见 setBlockFormat()。

void QTextCursor::insertBlock(const QTextBlockFormat &format, const QTextCharFormat &charFormat)

这是一个重载函数。

在光标position() 处插入一个新的空块，块格式为format ，块字符格式为charFormat 。

另请参阅 setBlockFormat() 。

void QTextCursor::insertFragment(const QTextDocumentFragment &fragment)

在当前position() 处插入文本fragment 。

QTextFrame *QTextCursor::insertFrame(const QTextFrameFormat &format)

在当前光标position() 处插入一个带有给定format 的框架，将光标position() 移至框架内，然后返回框架。

如果光标包含一个选区，则整个选区都会被移到框架内。

另请参阅 hasSelection() 。

void QTextCursor::insertHtml(const QString &html)

在当前position() 处插入文本html 。文本被解释为 HTML。

void QTextCursor::insertImage(const QTextImageFormat &format)

在当前position() 处插入由format 定义的图像。

void QTextCursor::insertImage(const QString &name)

这是一个重载函数。

在当前position() 处插入带有给定name 的图像的方便方法。

QImage img;
textDocument->addResource(QTextDocument::ImageResource, QUrl("myimage"), img);
cursor.insertImage("myimage");

void QTextCursor::insertImage(const QImage &image, const QString &name = QString())

这是一个重载函数。

方便函数，用于在当前position() 处插入给定的image 和可选的name 。

void QTextCursor::insertImage(const QTextImageFormat &format, QTextFrameFormat::Position alignment)

这是一个重载函数。

用指定的alignment 在光标的当前位置插入由给定的format 定义的图像。

另请参阅 position().

QTextList *QTextCursor::insertList(const QTextListFormat &format)

在当前位置插入一个新块，并使其成为新创建列表的第一个列表项，列表项的给定值为format 。返回创建的列表。

另请参阅 currentList()、createList() 和insertBlock()。

QTextList *QTextCursor::insertList(QTextListFormat::Style style)

这是一个重载函数。

在当前位置插入一个新块，并使其成为新创建列表的第一个列表项，列表项的给定值为style 。返回创建的列表。

另请参阅 currentList()、createList() 和insertBlock()。

[since 6.4] void QTextCursor::insertMarkdown(const QString &markdown, QTextDocument::MarkdownFeatures features = QTextDocument::MarkdownDialectGitHub)

在当前position() 插入markdown 文本，并使用指定的 Markdownfeatures 。默认为 GitHub 方言。

此函数在 Qt 6.4 中引入。

QTextTable *QTextCursor::insertTable(int rows, int columns, const QTextTableFormat &format)

在指定的format 中以给定的rows 和columns 数量创建一个新表格，将其插入文档中当前光标position() 处，并返回表格对象。光标将移动到第一个单元格的起始位置。

表格中必须至少有一行和一列。

另请参见 currentTable()。

QTextTable *QTextCursor::insertTable(int rows, int columns)

这是一个重载函数。

使用给定的rows 和columns 数量创建一个新表格，将其插入文档中当前光标position() 处，并返回表格对象。光标将移动到第一个单元格的起始位置。

表格中必须至少有一行和一列。

另请参阅 currentTable()。

void QTextCursor::insertText(const QString &text)

在当前位置插入text ，使用当前字符格式。

如果有选区，该选区将被删除，取而代之的是text ，例如：

cursor.clearSelection();
cursor.movePosition(QTextCursor::NextWord, QTextCursor::KeepAnchor);
cursor.insertText("Hello World");

这将清除任何现有选区，选择光标处的单词（即从position() 开始），并用短语 "Hello World "替换选区。

插入文本中的任何 ASCII 换行符 (\n) 都会转换为 unicode 块分隔符，对应于insertBlock() 调用。

另请参见 charFormat() 和hasSelection()。

void QTextCursor::insertText(const QString &text, const QTextCharFormat &format)

这是一个重载函数。

使用给定的format 在当前位置插入text 。

bool QTextCursor::isCopyOf(const QTextCursor &other) const

如果该游标和other 是彼此的副本，即其中一个游标是作为另一个游标的副本创建的，并且此后都没有移动过，则返回true 。这比相等严格得多。

另请参阅 operator=() 和operator==()。

bool QTextCursor::isNull() const

如果游标为空，则返回true ；否则返回false 。空游标由默认构造函数创建。

void QTextCursor::joinPreviousEditBlock()

与beginEditBlock() 一样，它表示一个编辑操作块的开始，这些操作应作为撤消/重做的单个操作出现。不过，与beginEditBlock() 不同的是，它不会启动一个新的编辑块，而是反转之前对endEditBlock() 的调用，从而使后续操作成为之前创建的编辑块的一部分。

例如

QTextCursor cursor(textDocument);
cursor.beginEditBlock();
cursor.insertText("Hello");
cursor.insertText("World");
cursor.endEditBlock();

// ...

cursor.joinPreviousEditBlock();
cursor.insertText("Hey");
cursor.endEditBlock();

textDocument->undo();

调用 undo() 将导致撤销所有三个插入操作。

另请参见 beginEditBlock() 和endEditBlock()。

bool QTextCursor::keepPositionOnInsert() const

返回在光标位置插入文本时，光标是否应保持当前位置。

默认值为 false；

另请参阅 setKeepPositionOnInsert().

void QTextCursor::mergeBlockCharFormat(const QTextCharFormat &modifier)

用modifier 指定的块格式修改当前块（或选中的所有块）的块字符格式。

另请参阅 setBlockCharFormat() 。

void QTextCursor::mergeBlockFormat(const QTextBlockFormat &modifier)

用modifier 指定的块格式修改当前块（或选择中包含的所有块）的块格式。

另请参阅 setBlockFormat() 和blockFormat()。

void QTextCursor::mergeCharFormat(const QTextCharFormat &modifier)

将游标当前的字符格式与格式modifier 所描述的属性合并。如果游标上有选区，则该函数会将modifier 中设置的所有属性应用于选区中的所有字符格式。

另请参阅 hasSelection() 和setCharFormat() 。

bool QTextCursor::movePosition(QTextCursor::MoveOperation operation, QTextCursor::MoveMode mode = MoveAnchor, int n = 1)

通过执行给定的operation n 次，使用指定的mode 移动光标，如果所有操作都成功完成，则返回true ；否则返回false 。

例如，如果反复使用该函数来查找下一个单词的末尾，那么当到达文档末尾时，该函数将最终失败。

默认情况下，移动操作只执行一次（n = 1）。

如果mode 为KeepAnchor ，则光标会选择其移动过的文本。这与用户按住 Shift 键并使用光标键移动光标时的效果相同。

另请参阅 setVisualNavigation() 。

int QTextCursor::position() const

返回光标在文档中的绝对位置。光标在字符之间定位。

另请参见 setPosition()、movePosition()、anchor() 和positionInBlock()。

int QTextCursor::positionInBlock() const

返回光标在块中的相对位置。光标位于字符之间。

这等同于position() - block().position() 。

另请参见 position()。

void QTextCursor::removeSelectedText()

如果有选择，则删除其内容；否则什么也不做。

另请参见 hasSelection().

void QTextCursor::select(QTextCursor::SelectionType selection)

根据给定的selection 选择文档中的文本。

void QTextCursor::selectedTableCells(int *firstRow, int *numRows, int *firstColumn, int *numColumns) const

如果选区跨越了表格单元格，firstRow 将填入选区中第一行的编号，firstColumn 将填入选区中第一列的编号，numRows 和numColumns 将填入选区中行和列的编号。如果选区没有跨过任何表格单元格，结果将是无害但未定义的。

QString QTextCursor::selectedText() const

返回当前选区的文本（可能为空）。它只返回文本，不包含富文本格式信息。如果您需要文档片段（即格式化的富文本），请使用selection() 代替。

QTextDocumentFragment QTextCursor::selection() const

返回当前选中文本（可能为空）及其所有格式信息。如果只想要所选文本（即纯文本），请使用selectedText() 代替。

另请参阅 QTextDocumentFragment::toPlainText()。

int QTextCursor::selectionEnd() const

返回选区的结束位置，如果光标没有选区，则返回position() 。

另请参阅 selectionStart()、position() 和anchor()。

int QTextCursor::selectionStart() const

返回选区的起始位置，如果光标没有选区，则返回position() 。

另请参阅 selectionEnd()、position() 和anchor()。

void QTextCursor::setBlockCharFormat(const QTextCharFormat &format)

将当前块（或选中的所有块）的块字符格式设置为format 。

另请参阅 blockCharFormat() 。

void QTextCursor::setBlockFormat(const QTextBlockFormat &format)

将当前区块（或选中的所有区块）的区块格式设置为format 。

另请参阅 blockFormat() 和mergeBlockFormat()。

void QTextCursor::setCharFormat(const QTextCharFormat &format)

将光标当前的字符格式设置为给定的format 。如果光标上有选区，则format 将应用于当前选区。

另请参阅 charFormat()、hasSelection() 和mergeCharFormat()。

void QTextCursor::setKeepPositionOnInsert(bool b)

定义在光标的当前位置插入文本时，光标是否应保持当前位置。

如果b 为 "true"，则在光标位置插入文本时，光标会保持当前位置。如果b 为 false，则光标会随着插入的文本移动。

默认为假。

请注意，在光标的当前位置之前插入文本时，光标总是移动；在光标的当前位置之后插入文本时，光标总是保持其位置。

另请参阅 keepPositionOnInsert()。

void QTextCursor::setPosition(int pos, QTextCursor::MoveMode m = MoveAnchor)

使用m 指定的MoveMode ，将光标移动到pos 指定的文档中的绝对位置。光标位于字符之间。

另请参见 position()、movePosition() 和anchor()。

void QTextCursor::setVerticalMovementX(int x)

将光标垂直移动时的视觉 x 位置设置为x 。

光标水平移动时，垂直移动 x 位置会自动清除，光标垂直移动时则保持不变。该机制允许光标在视觉直线上按比例字体上下移动，并在短线上轻轻 "跳跃"。

值为 -1 表示没有预定义的 x 位置。当光标下一次向上或向下移动时，X 位置将自动设置。

另请参见 verticalMovementX()。

void QTextCursor::setVisualNavigation(bool b)

将可视化导航设置为b 。

可视化导航是指跳过隐藏的文本段落。默认值为 false。

另请参阅 visualNavigation() 和movePosition()。

[noexcept] void QTextCursor::swap(QTextCursor &other)

将此文本游标实例与other 互换。该操作速度非常快，而且从未出现过故障。

int QTextCursor::verticalMovementX() const

返回垂直移动光标时的可视 x 位置。

值为 -1 表示没有预定义的 x 位置。下一次光标向上或向下移动时，X 位置将自动设置。

另请参阅 setVerticalMovementX()。

bool QTextCursor::visualNavigation() const

如果光标进行视觉导航，则返回true ；否则返回false 。

可视化导航是指跳过隐藏的文本段落。默认值为 false。

另请参阅 setVisualNavigation() 和movePosition() 。

bool QTextCursor::operator!=(const QTextCursor &other) const

如果other 光标在文档中的位置与此光标不同，则返回true ；否则返回false 。

bool QTextCursor::operator<(const QTextCursor &other) const

如果other 光标在文档中的位置比该光标晚，则返回true ；否则返回false 。

bool QTextCursor::operator<=(const QTextCursor &other) const

如果other 光标在文档中的位置在此光标之后或相同，则返回true ；否则返回 false。

QTextCursor &QTextCursor::operator=(const QTextCursor &cursor)

复制cursor 并将其赋值给QTextCursor 。请注意，QTextCursor 是一个隐式共享类。

bool QTextCursor::operator==(const QTextCursor &other) const

如果other 光标与该光标位于文档中的相同位置，则返回true ；否则返回false 。

bool QTextCursor::operator>(const QTextCursor &other) const

如果other 光标在文档中的位置比该光标早，则返回true ；否则返回false 。

bool QTextCursor::operator>=(const QTextCursor &other) const

如果other 光标在文档中的位置与此光标相同或更早，则返回true ；否则返回 false。