Класс QTextDocument

Класс QTextDocument хранит форматированный текст. Подробнее...

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

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

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

Свойства

• 1 свойство унаследовано от QObject

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

• 31 публичные функции, унаследованные от QObject

Публичные слоты

• 1 публичный слот, унаследованный от QObject

Сигналы

• 2 сигнала, унаследованные от QObject

Защищённые функции

• 9 защищённых функций, унаследованных от QObject

Дополнительные унаследованные члены

• 11 статических публичных членов, унаследованных от QObject

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

Класс QTextDocument хранит форматированный текст.

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

Каждый элемент документа описывается связанным объектом формата. Каждый объект формата обрабатывается QTextDocuments как уникальный объект и может быть передан в objectForFormat(), чтобы получить элемент документа, к которому он применяется.

QTextDocument может быть изменён программно с помощью QTextCursor, а его содержимое может быть просмотрено путём обхода структуры документа. Вся структура документа хранится как иерархия элементов документа под корневым фреймом, найденная функцией rootFrame(). В качестве альтернативы, если вы просто хотите пройтись по текстовому содержимому документа, вы можете использовать begin(), end() и findBlock() для получения текстовых блоков, которые вы можете просмотреть и пройтись по ним.

Макет документа определяется documentLayout; вы можете создать свой собственный подкласс QAbstractTextDocumentLayout и установить его с помощью setDocumentLayout(), если вы хотите использовать свою собственную логику макета. Заголовок документа и другую метаинформацию можно получить, вызвав функцию metaInformation(). Для документов, которые доступны пользователям через класс QTextEdit, заголовок документа также доступен через функцию QTextEdit::documentTitle().

Функции toPlainText() и toHtml() позволяют получить содержимое документа как простой текст и HTML. Текст документа можно искать с помощью функций find().

Откат/повтор операций, выполненных над документом, можно контролировать с помощью функции setUndoRedoEnabled(). Систему отката/повтора можно управлять с помощью виджета редактора через слоты undo() и redo(); документ также предоставляет сигналы contentsChanged(), undoAvailable() и redoAvailable(), которые информируют подключённые виджеты редактора о состоянии системы отката/повтора. Вот операции отката/повтора в QTextDocument:

• Вставка или удаление символов. Последовательность вставок или удалений в пределах одного текстового блока рассматривается как одна операция отката/повтора.
• Вставка или удаление текстовых блоков. Последовательности вставки или удаления в одной операции (например, выбор и последующее удаление текста) считаются одной операцией отката/повтора.
• Изменения формата символов текста.
• Изменения формата текстовых блоков.
• Изменения формата группы текстовых блоков.

См. также QTextCursor, QTextEdit, Обработка форматированного текста и Пример объекта текста.

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

Перечисление QTextDocument::FindFlagflags QTextDocument::FindFlags

Это перечисление описывает доступные опции для функции поиска QTextDocument. Опции могут быть объединены по оператору ИЛИ из следующего списка:

Тип FindFlags является псевдонимом для QFlags<FindFlag>. Он хранит логическое ИЛИ сочетание значений FindFlag.

enum QTextDocument::MetaInformation

Этот перечисление описывает различные типы метаданных, которые могут быть добавлены в документ.

См. также metaInformation() и setMetaInformation().

enum QTextDocument::ResourceType

Это перечисление описывает типы ресурсов, которые могут быть загружены функцией QTextDocument's loadResource().

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

enum QTextDocument::Stacks

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

QTextDocument::QTextDocument(QObject *parent = Q_NULLPTR)

Конструирует пустой QTextDocument с заданным parent.

QTextDocument::QTextDocument(const QString &text, QObject *parent = Q_NULLPTR)

Конструирует QTextDocument, содержащий указанный простой (неформатированный) текст text, и с заданным parent.

QTextDocument::~QTextDocument()

Удаляет документ.

void QTextDocument::addResource(int type, const QUrl &name, const QVariant &resource)

Добавляет ресурс resource в кэш ресурсов, используя type и name в качестве идентификаторов. type должен быть значением из QTextDocument::ResourceType.

Например, вы можете добавить изображение как ресурс для ссылки на него внутри документа:

    document->addResource(QTextDocument::ImageResource,
        QUrl("mydata://image.png"), QVariant(image));

Изображение можно вставить в документ с помощью API QTextCursor:

    QTextImageFormat imageFormat;
    imageFormat.setName("mydata://image.png");
    cursor.insertImage(imageFormat);

Кроме того, вы можете вставлять изображения с помощью HTML-тега img:

    editor->append("<img src=\"mydata://image.png\" />");

void QTextDocument::adjustSize()

Настраивает размер документа на разумное значение.

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

См. также idealWidth(), textWidth и size.

QVector<QTextFormat> QTextDocument::allFormats() const

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

int QTextDocument::availableRedoSteps() const

Возвращает количество доступных шагов повтора.

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

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

int QTextDocument::availableUndoSteps() const

Возвращает количество доступных шагов отмены.

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

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

QTextBlock QTextDocument::begin() const

Возвращает первый блок текста документа.

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

[signal] void QTextDocument::blockCountChanged(int newBlockCount)

Этот сигнал испускается, когда общее количество блоков текста в документе изменяется. Переданное значение newBlockCount — это новое общее количество.

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

QChar QTextDocument::characterAt(int pos) const

Возвращает символ в позиции pos или нулевой символ, если позиция находится вне диапазона.

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

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

int QTextDocument::characterCount() const

Возвращает количество символов в этом документе.

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

См. также blockCount() и characterAt().

[virtual] void QTextDocument::clear()

Очищает документ.

void QTextDocument::clearUndoRedoStacks(Stacks stacksToClear = UndoAndRedoStacks)

Очищает стеки, указанные stacksToClear.

Этот метод очищает все команды в стеке отмены, стеке повтора или обоих (по умолчанию). Если команды очищены, испускаются соответствующие сигналы, QTextDocument::undoAvailable() или QTextDocument::redoAvailable().

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

См. также QTextDocument::undoAvailable() и QTextDocument::redoAvailable().

QTextDocument *QTextDocument::clone(QObject *parent = Q_NULLPTR) const

Создаёт новый QTextDocument, который является копией этого текстового документа. parent — родитель возвращаемого текстового документа.

[signal] void QTextDocument::contentsChange(int position, int charsRemoved, int charsAdded)

Этот сигнал испускается всякий раз, когда содержимое документа изменяется; например, при вставке или удалении текста или при применении форматирования.

Предоставляется информация о позиции символа в документе, где произошли изменения (position), количестве удаленных символов (charsRemoved) и количестве добавленных символов (charsAdded).

Сигнал испускается перед тем, как менеджер выравнивания документа получает уведомление об изменении. Этот крючок позволяет реализовать подсветку синтаксиса для документа.

См. также QAbstractTextDocumentLayout::documentChanged() и contentsChanged().

[signal] void QTextDocument::contentsChanged()

Этот сигнал испускается всякий раз, когда содержимое документа изменяется; например, при вставке или удалении текста или при применении форматирования.

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

[virtual protected] QTextObject *QTextDocument::createObject(const QTextFormat &format)

Создаёт и возвращает новый объект документа (объект QTextObject) на основе заданного format.

QTextObjects всегда создаются с помощью этого метода, поэтому вы должны переопределить его, если используете пользовательские текстовые объекты внутри документа.

[signal] void QTextDocument::cursorPositionChanged(const QTextCursor &cursor)

Этот сигнал испускается всякий раз, когда положение курсора изменяется в результате операции редактирования. Курсор, который изменился, передаётся в cursor. Если документ используется с классом QTextEdit, и вам нужен сигнал при перемещении курсора с помощью клавиш со стрелками, вы можете использовать сигнал cursorPositionChanged() в классе QTextEdit.

Qt::CursorMoveStyle QTextDocument::defaultCursorMoveStyle() const

Стиль перемещения курсора по умолчанию используется всеми объектами QTextCursor, созданными из документа. По умолчанию это Qt::LogicalMoveStyle.

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

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

QFont QTextDocument::defaultFont() const

Возвращает шрифт по умолчанию, используемый в макете документа.

Примечание: Функция-геттер для свойства defaultFont.

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

QTextOption QTextDocument::defaultTextOption() const

Параметр текста по умолчанию используется для всех объектов QTextLayout в документе. Это позволяет задавать глобальные свойства для документа, такие как режим перевода слов по умолчанию.

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

Примечание: Функция-геттер для свойства defaultTextOption.

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

QAbstractTextDocumentLayout *QTextDocument::documentLayout() const

Возвращает макет документа для этого документа.

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

[signal] void QTextDocument::documentLayoutChanged()

Этот сигнал испускается при установке нового макета документа.

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

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

void QTextDocument::drawContents(QPainter *p, const QRectF &rect = QRectF())

Рисует содержимое документа с помощью painter p, ограниченного прямоугольником rect. Если rect — это нулевой прямоугольник (по умолчанию), то документ рисуется без обрезки.

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

QTextBlock QTextDocument::end() const

Эта функция возвращает блок для проверки конца документа при итерации по нему.

    for (QTextBlock it = doc->begin(); it != doc->end(); it = it.next())
        cout << it.text().toStdString() << endl;

Возвращаемый блок недействителен и представляет блок после последнего блока в документе. Вы можете использовать lastBlock() для получения последнего действительного блока документа.

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

QTextCursor QTextDocument::find(const QString &subString, const QTextCursor &cursor, FindFlags options = FindFlags()) const

Ищет следующее вхождение строки subString в документе. Поиск начинается с позиции заданного cursor и продолжается вперёд по документу, если не указано иначе в параметрах поиска. Параметр options управляет типом выполняемого поиска.

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

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

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

QTextCursor QTextDocument::find(const QString &subString, int position = 0, FindFlags options = FindFlags()) const

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

Ищет следующее вхождение строки subString в документе. Поиск начинается с заданной позиции position и продолжается вперёд по документу, если не указано иначе в параметрах поиска. Параметр options управляет типом выполняемого поиска.

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

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

QTextCursor QTextDocument::find(const QRegExp &expr, int from = 0, FindFlags options = FindFlags()) const

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

Ищет следующее вхождение, соответствующее заданному регулярному выражению expr, в том же абзаце документа.

Поиск начинается с заданной позиции from и продолжается вперёд по документу, если не указано иначе в параметрах поиска. Параметр options управляет типом выполняемого поиска. Опция FindCaseSensitively игнорируется для этой перегрузки, используйте QRegExp::caseSensitivity вместо неё.

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

Если позиция from равна 0 (по умолчанию), поиск начинается с начала документа; в противном случае он начинается с указанной позиции.

QTextCursor QTextDocument::find(const QRegExp &expr, const QTextCursor &cursor, FindFlags options = FindFlags()) const

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

Ищет следующее вхождение, соответствующее заданному регулярному выражению expr, в том же абзаце документа.

Поиск начинается с позиции заданного cursor и продолжается вперёд по документу, если не указано иначе в параметрах поиска. Параметр options управляет типом выполняемого поиска. Опция FindCaseSensitively игнорируется для этой перегрузки, используйте QRegExp::caseSensitivity вместо неё.

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

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

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

QTextCursor QTextDocument::find(const QRegularExpression &expr, int from = 0, FindFlags options = FindFlags()) const

Ищет следующее вхождение, соответствующее заданному регулярному выражению expr, в том же абзаце документа.

Поиск начинается с заданной позиции from и продолжается вперёд по документу, если не указано иначе в параметрах поиска. Параметр options управляет типом выполняемого поиска.

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

Если позиция from равна 0 (по умолчанию), поиск начинается с начала документа; в противном случае он начинается с указанной позиции.

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

QTextCursor QTextDocument::find(const QRegularExpression &expr, const QTextCursor &cursor, FindFlags options = FindFlags()) const

Ищет следующее вхождение, соответствующее заданному регулярному выражению expr, в том же абзаце документа.

Поиск начинается с позиции заданного cursor и продолжается вперёд по документу, если не указано иначе в параметрах поиска. Параметр options управляет типом выполняемого поиска.

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

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

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

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

QTextBlock QTextDocument::findBlock(int pos) const

Возвращает блок текста, содержащий символ с номером pos.

QTextBlock QTextDocument::findBlockByLineNumber(int lineNumber) const

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

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

См. также QTextBlock::firstLineNumber().

QTextBlock QTextDocument::findBlockByNumber(int blockNumber) const

Возвращает блок текста с указанным номером blockNumber.

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

См. также QTextBlock::blockNumber().

QTextBlock QTextDocument::firstBlock() const

Возвращает первый блок текста документа.

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

qreal QTextDocument::idealWidth() const

Возвращает идеальную ширину текстового документа. Идеальная ширина — это фактически используемая ширина документа без учёта дополнительных выравниваний. Она всегда <= size().width().

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

См. также adjustSize() и textWidth.

bool QTextDocument::isEmpty() const

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

bool QTextDocument::isRedoAvailable() const

Возвращает true если повторное действие доступно; в противном случае возвращает false.

См. также isUndoAvailable() и availableRedoSteps().

bool QTextDocument::isUndoAvailable() const

Возвращает true если действие отмены доступно; в противном случае возвращает false.

См. также isRedoAvailable() и availableUndoSteps().

QTextBlock QTextDocument::lastBlock() const

Возвращает последний (действительный) блок текста документа.

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

int QTextDocument::lineCount() const

Возвращает количество строк в этом документе (если макет поддерживает это). В противном случае, это идентично количеству блоков.

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

См. также blockCount() и characterCount().

[virtual protected] QVariant QTextDocument::loadResource(int type, const QUrl &name)

Загружает данные указанного типа type из ресурса с заданным именем name.

Эта функция вызывается движком форматирования Rich Text для запроса данных, которые не хранятся напрямую в QTextDocument, но всё ещё связаны с ним. Например, изображения косвенно ссылаются на атрибут имени объекта QTextImageFormat.

При вызове Qt, type является одним из значений перечисления QTextDocument::ResourceType.

Если QTextDocument является дочерним объектом объекта QObject, который имеет вызываемый метод loadResource, такой как QTextEdit, QTextBrowser или сам QTextDocument, то реализация по умолчанию пытается извлечь данные из родителя.

void QTextDocument::markContentsDirty(int position, int length)

Помечает содержимое, заданное заданным position и length, как «грязное», сообщая документу, что его необходимо снова выложить.

QString QTextDocument::metaInformation(MetaInformation info) const

Возвращает метаинформацию о документе указанного типа info.

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

[signal] void QTextDocument::modificationChanged(bool changed)

Этот сигнал излучается всякий раз, когда содержимое документа изменяется таким образом, что влияет на состояние изменения. Если changed истинно, документ был изменён; в противном случае это ложь.

Например, вызов setModified(false) для документа, а затем вставка текста, вызывает излучение сигнала. Если вы отменяете эту операцию, возвращая документ к его исходному неизменённому состоянию, сигнал снова излучается.

QTextObject *QTextDocument::object(int objectIndex) const

Возвращает текстовый объект, связанный с данным objectIndex.

QTextObject *QTextDocument::objectForFormat(const QTextFormat &f) const

Возвращает текстовый объект, связанный с форматом f.

int QTextDocument::pageCount() const

Возвращает количество страниц в этом документе.

void QTextDocument::print(QPagedPaintDevice *printer) const

Печатает документ в заданный printer. QPageablePaintDevice должен быть настроен перед использованием с этой функцией.

Это только удобный метод для печати всего документа в принтер.

Если документ уже распечатан на определённую высоту в свойстве pageSize(), он печатается как есть.

Если документ не постраничен, например, документ, используемый в QTextEdit, то создаётся временная копия документа, и копия разбивается на несколько страниц в соответствии с размером свойства paint device's paperRect(). По умолчанию устанавливается отступ в 2 см вокруг содержимого документа. Кроме того, текущий номер страницы печатается внизу каждой страницы.

См. также QTextEdit::print().

void QTextDocument::redo(QTextCursor *cursor)

Повторяет последнюю операцию редактирования в документе, если повторное действие доступно.

Предоставленный cursor позиционируется в конце места, где операция редактирования была повторена.

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

[slot] void QTextDocument::redo()

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

Повторяет последнюю операцию редактирования в документе, если повторное действие доступно.

[signal] void QTextDocument::redoAvailable(bool available)

Этот сигнал излучается всякий раз, когда операции повтора становятся доступными (available истина) или недоступными (available ложь).

QVariant QTextDocument::resource(int type, const QUrl &name) const

Возвращает данные указанного типа type из ресурса с заданным именем name.

Эта функция вызывается движком форматирования Rich Text для запроса данных, которые не хранятся напрямую в QTextDocument, но всё ещё связаны с ним. Например, изображения косвенно ссылаются на атрибут имени объекта QTextImageFormat.

Ресурсы кешируются внутри документа. Если ресурс не найден в кэше, вызывается loadResource для попытки загрузки ресурса. loadResource должен затем использовать addResource для добавления ресурса в кэш.

См. также QTextDocument::ResourceType.

int QTextDocument::revision() const

Возвращает версию документа (если включена отмена).

Гарантируется, что версия увеличится, когда документ, который не изменён, редактируется.

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

См. также QTextBlock::revision() и isModified().

QTextFrame *QTextDocument::rootFrame() const

Возвращает корневой фрейм документа.

void QTextDocument::setDefaultCursorMoveStyle(Qt::CursorMoveStyle style)

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

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

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

void QTextDocument::setDefaultFont(const QFont &font)

Устанавливает шрифт по умолчанию для использования в макете документа.

Примечание: Метод-сеттер для свойства defaultFont.

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

void QTextDocument::setDefaultTextOption(const QTextOption &option)

Устанавливает опцию текста по умолчанию в option.

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

Примечание: Метод-сеттер для свойства defaultTextOption.

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

void QTextDocument::setDocumentLayout(QAbstractTextDocumentLayout *layout)

Устанавливает для документа заданный layout. Предыдущий макет удаляется.

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

void QTextDocument::setHtml(const QString &html)

Заменяет всё содержимое документа заданным HTML-форматированным текстом в строке html. История отмены/повтора сбрасывается при вызове этой функции.

Форматирование HTML учитывается по возможности; например, "<b>жирный</b> текст" создаст текст, где первое слово имеет начертание, придающее ему жирный вид: "жирный текст".

Примечание: Ответственность за корректное декодирование текста ложится на вызывающую сторону, когда создаётся QString содержащий HTML и передаётся в setHtml().

См. также setPlainText() и Поддерживаемый подмножество HTML.

void QTextDocument::setIndentWidth(qreal width)

Устанавливает width, используемый для отступа списков и блоков текста.

Свойства отступа QTextListFormat и QTextBlockFormat задают кратные этому значению. Значение отступа по умолчанию составляет 40.

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

Примечание: Функция-сеттер для свойства indentWidth.

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

void QTextDocument::setMetaInformation(MetaInformation info, const QString &string)

Устанавливает метаданные документа типа, указанного info, заданному значению string.

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

void QTextDocument::setPlainText(const QString &text)

Заменяет все содержимое документа заданным простым текстом text. История отмены/повторения сброшена при вызове этой функции.

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

QString QTextDocument::toHtml(const QByteArray &encoding = QByteArray()) const

Возвращает строку, содержащую HTML-представление документа.

Параметр encoding задает значение для атрибута charset в заголовке html. Например, если указано 'utf-8', то начало сгенерированного html будет выглядеть так:

<html><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"></head><body>...

Если кодировка не указана, такая метаинформация не генерируется.

Если позже вы преобразуете возвращенную строку html в массив байтов для передачи по сети или сохранения на диск, вы должны указать кодировку, которую вы собираетесь использовать для преобразования в массив байтов здесь.

См. также Поддерживаемый подмножество HTML.

QString QTextDocument::toPlainText() const

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

Примечание: Встроенные объекты, такие как изображения, представляются значением Unicode U+FFFC (символ замены объекта).

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

void QTextDocument::undo(QTextCursor *cursor)

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

См. документацию по Qt Undo Framework для получения подробностей.

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

См. также undoAvailable() и isUndoRedoEnabled().

[slot] void QTextDocument::undo()

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

[signal] void QTextDocument::undoAvailable(bool available)

Этот сигнал подаётся всякий раз, когда операции отмены становятся доступными (available истинно) или недоступными (available ложно).

См. документацию по Qt Undo Framework для получения подробностей.

См. также undo() и isUndoRedoEnabled().

[signal] void QTextDocument::undoCommandAdded()

Этот сигнал подаётся каждый раз, когда к QTextDocument добавляется новый уровень отмены.

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