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)

在当前光标位置插入一个具有指定format 的框架position()，将光标position()移动到框架内部，并返回该框架。

如果光标选中了内容，则将整个选区移入帧内。

另请参阅 hasSelection()。

void QTextCursor::insertHtml(const QString &html)

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

void QTextCursor::insertImage(const QTextImageFormat &format)

将由format 定义的图像插入到当前的position()中。

void QTextCursor::insertImage(const QString &name)

一种便捷方法，用于将具有给定name 的图像插入到当前position()中。

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

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

一个便捷函数，用于将给定的image （可选的name ）插入到当前的position()中。

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

将由给定的format 定义的图像，以指定的alignment 插入到光标当前位置。

另请参阅 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)

创建一个新表格，其中包含指定数量的rows 和columns ，并位于指定的format 中；将其插入到文档中当前光标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)

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

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，光标将随插入的文本一起移动。

默认值为 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 位置。此时，该位置将在光标下次向上或向下移动时自动设置。

另请参阅 verticalMovementX()。

void QTextCursor::setVisualNavigation(bool b)

将可视导航设置为b 。

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

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

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

将此文本光标实例与other 互换。此操作非常快速，且绝不会失败。

int QTextCursor::verticalMovementX() const

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

值为 -1 表示未预定义 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。