Класс QTextCursor

Класс QTextCursor предоставляет API для доступа и изменения QTextDocuments. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются повторно входящими.

Открытые типы

Открытые функции

Подробное описание

Курсоры текста — это объекты, используемые для доступа к содержимому и внутренней структуре текстовых документов с помощью программного интерфейса, имитирующего поведение курсора в текстовом редакторе. QTextCursor содержит информацию как о позиции курсора в QTextDocument, так и о произведенном им выделении.

QTextCursor моделируется поведением курсора в текстовом редакторе, предоставляя программный способ выполнения стандартных действий через пользовательский интерфейс. Документ можно рассматривать как одну длинную строку символов. Текущая позиция курсора (position()) всегда расположена либо между двумя последовательными символами в строке, либо перед первым символом, либо после последнего символа в строке. Документы могут также содержать таблицы, списки, изображения и другие объекты помимо текста, но с точки зрения разработчика документ можно рассматривать как одну длинную строку. Некоторые части этой строки могут находиться внутри определенных блоков (например, абзацев), ячеек таблицы, элементов списка или других структурных элементов. Когда мы говорим о «текущем символе», мы имеем в виду символ, непосредственно перед позицией курсора (position()) в документе. Аналогично, «текущий блок» — это блок, содержащий позицию курсора (position()).

QTextCursor также имеет позицию якоря (anchor()). Текст между позицией якоря (anchor()) и позицией курсора (position()) является выделенным. Если anchor() == position(), выделения нет.

Положение курсора можно программно изменить, используя setPosition() и movePosition(); последнее также можно использовать для выделения текста. Для выделений см. selectionStart(), selectionEnd(), hasSelection(), clearSelection() и removeSelectedText().

Если позиция (position()) находится в начале блока, atBlockStart() возвращает true; а если в конце блока, atBlockEnd() возвращает true. Формат текущего символа возвращается функцией charFormat(), а формат текущего блока — функцией blockFormat().

Форматирование можно применить к текущему документу, используя функции setCharFormat(), mergeCharFormat(), setBlockFormat() и mergeBlockFormat(). Функции «set» заменяют текущий формат символа или блока курсора, а функции «merge» добавляют свойства заданного формата к текущему формату курсора. Если у курсора есть выделение, заданный формат применяется к выделенному тексту. Обратите внимание, что когда выделена только часть блока, формат блока применяется ко всему блоку. Текст в текущей позиции символа можно преобразовать в список, используя createList().

Удаление можно выполнить с помощью deleteChar(), deletePreviousChar() и removeSelectedText().

Вставки строк текста выполняются с помощью функции insertText(), блоков (представляющих новые абзацы) — с помощью insertBlock().

Существующие фрагменты текста можно вставлять с помощью insertFragment(), но если нужно вставить фрагменты текста в различных форматах, обычно проще использовать insertText() и указать формат символов.

Различные типы структур более высокого уровня также можно вставить в документ с помощью курсора:

• Списки — упорядоченные последовательности блочных элементов, которые оформляются маркерами или символами. Вставляются в заданном формате с помощью insertList().
• Таблицы вставляются с помощью функции insertTable() и могут быть заданы с дополнительным форматом. Они содержат массив ячеек, по которым можно перемещаться с помощью курсора.
• Встраиваемые изображения вставляются с помощью insertImage(). Используемое изображение можно указать в формате изображения или по имени.
• Фреймы вставляются вызовом insertFrame() с указанным форматом.

Действия можно группировать (т. е. обрабатывать как одно действие для отмены/повторной обработки) с помощью beginEditBlock() и endEditBlock().

Перемещения курсора ограничены допустимыми позициями курсора. В латинском письме это место между любыми двумя последовательными символами в тексте, перед первым символом или после последнего. В некоторых других системах письма перемещения курсора ограничены «кластерами» (например, слогом в деванагари или базовой буквой с диакритическими знаками). Функции, такие как movePosition() и deleteChar(), ограничивают перемещение курсора этими допустимыми позициями.

См. такжеОбработка форматированного текста.

Документация по типам членов

перечисление QTextCursor::MoveMode

Если якорь (anchor()) остается на месте, а позиция (position()) перемещается, то текст между ними будет выделен.

перечисление QTextCursor::MoveOperation

См. также movePosition().

Перечисление QTextCursor::SelectionType

Это перечисление описывает типы выделения, которые могут быть применены с помощью функции select().

Документация функций-членов

QTextCursor::QTextCursor(const QTextCursor &cursor)

Создает новый курсор, являющийся копией cursor.

QTextCursor::QTextCursor(const QTextBlock &block)

Создает курсор, указывающий на начало block.

QTextCursor::QTextCursor(QTextFrame *frame)

Создает курсор, указывающий на начало frame.

QTextCursor::QTextCursor(QTextDocument *document)

Создает курсор, указывающий на начало document.

QTextCursor::QTextCursor()

Создает курсор без значения.

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

Создает копию cursor и присваивает её этому QTextCursor. Обратите внимание, что QTextCursor — это класс с неявным совместным использованием.

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)

Создает и возвращает новый список с заданным форматом и делает текущий абзац, в котором находится курсор, первой строкой списка.

См. также 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

Возвращает true если курсор содержит выделение, которое не является просто диапазоном от selectionStart() до selectionEnd(); в противном случае возвращает 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)

Вставляет текст fragment в текущую позицию position().

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

Вставляет фрейм с заданным форматом в текущую позицию курсора position(), перемещает позицию курсора position() внутрь фрейма и возвращает фрейм.

Если курсор содержит выделение, всё выделение перемещается внутрь фрейма.

См. также hasSelection().

void QTextCursor::insertHtml(const QString &html)

Вставляет текст html в текущую позицию position(). Текст интерпретируется как HTML.

void QTextCursor::insertImage(const QTextImageFormat &format)

Вставляет изображение, определённое format, в текущую позицию position().

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

Это перегруженный метод.

Вставляет изображение, определённое заданным format, в текущую позицию курсора с указанным alignment.

См. также 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().

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

Вставляет новый блок в текущую позицию и делает его первым элементом списка, созданного с заданным форматом format. Возвращает созданный список.

См. также currentList(), createList(), и insertBlock().

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

Это перегруженный метод.

Вставляет новый блок в текущую позицию и делает его первым элементом списка, созданного с заданным стилем style. Возвращает созданный список.

См. также currentList(), createList(), и insertBlock().

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) во вставленном тексте преобразуются в разделители блоков Юникода, соответствующие вызовам insertBlock().

См. также charFormat() и hasSelection().

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

Это перегруженный метод.

Вставляет text в текущую позицию с заданным форматом format.

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

Возвращает true если этот курсор и other являются копиями друг друга, т.е. один из них был создан как копия другого и ни один из них не перемещался с тех пор. Это значительно строже, чем равенство.

См. также 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)

Перемещает курсор в абсолютную позицию в документе, указанную параметром pos, используя способ, определённый в m. Курсор размещается между символами.

См. также position(), movePosition() и anchor().

void QTextCursor::setVerticalMovementX(int x)

Устанавливает визуальное положение x для вертикальных перемещений курсора на x.

Визуальное положение x для вертикальных перемещений курсора очищается автоматически при горизонтальном перемещении курсора и остается неизменным при вертикальном перемещении курсора. Механизм позволяет курсору перемещаться вверх и вниз по визуально прямой линии с пропорциональными шрифтами и плавно «перепрыгивать» короткие строки.

Значение -1 указывает на отсутствие заданного положения x. Оно будет автоматически установлено при следующем перемещении курсора вверх или вниз.

См. также verticalMovementX().

void QTextCursor::setVisualNavigation(bool b)

Устанавливает визуальную навигацию на b.

Визуальная навигация означает пропуск скрытых абзацев текста. По умолчанию значение равно false.

См. также visualNavigation() и movePosition().

[since 5.0] void QTextCursor::swap(QTextCursor &other)

Меняет местами этот экземпляр курсора текста с other. Эта функция очень быстрая и никогда не завершается ошибкой.

Эта функция была добавлена в Qt 5.0.

int QTextCursor::verticalMovementX() const

Возвращает визуальное положение x для вертикальных перемещений курсора.

Значение -1 указывает на отсутствие заданного положения x. Оно будет автоматически установлено при следующем перемещении курсора вверх или вниз.

См. также setVerticalMovementX().

bool QTextCursor::visualNavigation() const

Возвращает true если курсор выполняет визуальную навигацию, иначе возвращает false.

Визуальная навигация означает пропуск скрытых абзацев текста. По умолчанию значение равно false.

См. также setVisualNavigation() и movePosition().

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

Возвращает true если курсор other находится в другой позиции в документе по сравнению с этим курсором, иначе возвращает false.

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

Возвращает true если курсор other расположен позже в документе, чем этот курсор; в противном случае возвращает false.

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

Возвращает true если курсор other расположен позже или в той же позиции в документе, что и этот курсор; в противном случае возвращает false.

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

Возвращает true если курсор other находится в той же позиции в документе, что и этот курсор; в противном случае возвращает false.

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

Возвращает true если курсор other расположен раньше в документе, чем этот курсор; в противном случае возвращает false.

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

Возвращает true если курсор other расположен раньше или в той же позиции в документе, что и этот курсор; в противном случае возвращает false.