Класс QTextCursor

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

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

Примечание: Все функции в этом классе являются реентерабельными.

Публичные типы

Публичные функции

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

Класс 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().

enum QTextCursor::SelectionType

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

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

QTextCursor::QTextCursor()

Создаёт пустой курсор.

QTextCursor::QTextCursor(QTextDocument *document)

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

QTextCursor::QTextCursor(QTextFrame *frame)

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

QTextCursor::QTextCursor(const QTextBlock &block)

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

QTextCursor::QTextCursor(const QTextCursor &cursor)

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

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.

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

См. также 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, если курсор недействителен.

Обратите внимание, что эта функция имеет смысл только в документах без сложных объектов, таких как таблицы или фреймы.

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

QTextCharFormat QTextCursor::charFormat() const

Возвращает форматирование символа, расположенного непосредственно перед позицией курсора position(). Если курсор находится в начале непустого блока текста, возвращает форматирование символа, расположенного сразу после курсора.

См. также setCharFormat(), insertText() и blockFormat().

void QTextCursor::clearSelection()

Очищает текущую выделенную область, установив якорь в позицию курсора.

Обратите внимание, что текст выделения при этом не удаляется.

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

int QTextCursor::columnNumber() const

Возвращает позицию курсора в строке.

Обратите внимание, что это номер столбца относительно переносимой строки, а не относительно блока (т. е. абзаца).

Вероятно, вам нужно вызвать positionInBlock() вместо этого.

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

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

Возвращает указатель на текущую область. Возвращает 0, если курсор недействителен.

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

QTextList *QTextCursor::currentList() const

Возвращает текущий список, если позиция курсора position() находится внутри блока, являющегося частью списка; в противном случае возвращает 0.

См. также insertList() и createList().

QTextTable *QTextCursor::currentTable() const

Возвращает указатель на текущую таблицу, если позиция курсора position() находится внутри блока, являющегося частью таблицы; в противном случае возвращает 0.

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

void QTextCursor::deleteChar()

Если текст не выделен, удаляет символ в текущей позиции курсора; в противном случае удаляет выделенный текст.

См. также deletePreviousChar(), hasSelection() и clearSelection().

void QTextCursor::deletePreviousChar()

Если текст не выделен, удаляет символ перед текущей позицией курсора; в противном случае удаляет выделенный текст.

См. также deleteChar(), hasSelection() и clearSelection().

QTextDocument *QTextCursor::document() const

Возвращает документ, с которым связан этот курсор.

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

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)

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

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

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

void QTextCursor::insertHtml(const QString &html)

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

Примечание: При использовании этой функции со стилем, стиль будет применяться только к текущему блоку в документе. Для применения стиля по всему документу используйте QTextDocument::setDefaultStyleSheet() вместо этого.

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

void QTextCursor::insertImage(const QTextImageFormat &format)

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

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

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

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

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

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

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

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 если курсор null; в противном случае возвращает 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.

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

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

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

См. также 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() вместо этого.

Примечание: Если выделение, полученное от редактора, охватывает разрыв строки, текст будет содержать символ параграфа Юникода U+2029 вместо символа новой строки \n . Используйте QString::replace(), чтобы заменить эти символы на символы новой строки.

QTextDocumentFragment QTextCursor::selection() const

Возвращает текущее выделение (которое может быть пустым) со всей информацией о форматировании. Если вам нужен только выбранный текст (т.е. обычный текст), используйте selectedText() вместо этого.

Примечание: В отличие от QTextDocumentFragment::toPlainText(), selectedText() может включать специальные символы Юникода, такие как QChar::ParagraphSeparator.

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

Обратите внимание, что курсор всегда перемещается при вставке текста перед текущей позицией курсора, и всегда сохраняет свое положение при вставке текста после текущей позиции курсора.

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

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

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

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

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

void QTextCursor::setVerticalMovementX(int x)

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

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

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

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

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

void QTextCursor::setVisualNavigation(bool b)

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

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

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

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

void QTextCursor::swap(QTextCursor &other)

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

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

int QTextCursor::verticalMovementX() const

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

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

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

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

bool QTextCursor::visualNavigation() const

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

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

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

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

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

Оператор присваивания с перемещением.

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

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

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.