QTextCursor 类

成员函数文档

QTextCursor::QTextCursor()

构建一个空光标。

[显式构造函数] QTextCursor::QTextCursor(QTextDocument *document)

构建一个指向document起始位置的光标。

[显式构造函数] QTextCursor::QTextCursor(QTextFrame *frame)

构建一个指向frame起始位置的光标。

[显式构造函数] 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

返回光标前立即的字符的格式。如果光标位于非空文本块的开始处，则返回光标后立即的字符的格式。

参见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

如果光标的位置在列表的某个区块内，则返回当前列表；否则返回 nullptr。

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

QTextTable *QTextCursor::currentTable() const

如果光标的位置在表格的某个区块内，则返回对当前表格的指针；否则返回 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 的框架，将光标移动到框架内部，并返回框架。

如果光标包含选区，整个选区将移动到框架内。

另请参阅hasSelection（）。

void QTextCursor::insertHtml(const QString &html)

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

void QTextCursor::insertImage(const QTextImageFormat &format)

在当前位置插入由format定义的图像。

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

这是一个重载函数。

将指定的图像alignment插入到光标当前位置。

另请参阅where。

void QTextCursor::insertImage(const QString &name)

这是一个重载函数。

方便方法，用于在当前位置插入具有给定name的图像。

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

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

这是一个重载函数。

向当前位置插入具有可选name的给定图像的便利函数。

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

在当前位置插入一个新段落，并将其设置为具有给定format的新列表的第一个列表项。返回创建的列表。

另请参阅当前列表， 创建列表 和 插入段落。

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

这是一个重载函数。

在当前位置插入一个新段落，并将其设置为具有给定style的新列表的第一个列表项。返回创建的列表。

另请参阅当前列表， 创建列表 和 插入段落。

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

在当前位置插入带有指定Markdown features的Markdown文本。默认值是GitHub方言。

此功能自Qt 6.4版开始。

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

创建一个具有给定行数和列数的表格，在文档中的当前位置插入它，并返回表格对象。光标移至第一个单元格的开始位置。

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

另请参阅 currentTable()。

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

这是一个重载函数。

创建一个具有指定 rows 行和 columns 列的新表格，将其插入到文档当前光标位置 ()，并返回表格对象。光标移动到第一行的开头。

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

另请参阅 currentTable()。

void QTextCursor::insertText(const QString &text)

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

如果有选择项，则删除选择项并用 text 替换，例如

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

这会清除任何现有选择，选中光标处的单词（即从 () 开始），并替换为短语“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();

撤销 () 调用会将所有三个插入操作都撤销。

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

另请参阅where。

void QTextCursor::removeSelectedText()

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

另请参阅hasSelection（）。

void QTextCursor::select(QTextCursor::SelectionType 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)

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

另请参阅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为真，则当文本插入到光标位置时，光标将保持其当前位置。如果b为假，则光标将随插入的文本移动。

默认情况下为假。

请注意，每当文本插入到光标当前位置之前时，光标总是移动，而当文本插入到光标当前位置之后时，光标始终保持在当前位置。

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

如果其他光标位于文档中比此光标更早或相同的的位置，则返回 true；否则返回 false。