Класс 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(), ограничивают движение курсора до этих допустимых позиций.

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

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

enum QTextCursor::MoveMode

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

enum 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)

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

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

QTextList *QTextCursor::createList(QTextListFormat::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)

Вставляет область с заданным форматом в текущую позицию курсора 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)

Это перегруженная функция.

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

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

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

void QTextCursor::insertImage(const QString &name)

Это перегруженная функция.

Удобный метод для вставки изображения с заданным именем в текущую позицию position().

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

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

Это перегруженная функция.

Удобная функция для вставки данного изображения с необязательным именем в текущую позицию position().

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

QTextList *QTextCursor::insertList(const QTextListFormat &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() вперёд) и заменяет выделение фразой "Привет мир".

Любые символы 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(MoveOperation operation, 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(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 истинно, курсор сохраняет свою текущую позицию при вставке текста в позицию курсора. Если b ложно, курсор перемещается вместе с вставленным текстом.

По умолчанию ложно.

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

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

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

void QTextCursor::setPosition(int pos, 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.

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

Эта функция была добавлена в 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.

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

Эта функция была добавлена в 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.