Класс QXmlStreamWriter

Класс QXmlStreamWriter предоставляет API для записи XML с простой потоковой обработкой. Подробнее...

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

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

Свойства

• autoFormatting : bool
• autoFormattingIndent : int

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

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

Класс QXmlStreamWriter предоставляет API для записи XML с простой потоковой обработкой.

QXmlStreamWriter является аналогом QXmlStreamReader для записи XML. Как и родственный класс, он работает с QIODevice, задаваемым с помощью setDevice(). API простой и понятный: для каждого XML-токена или события, который вы хотите записать, предоставляется специализированная функция.

Вы начинаете документ с помощью writeStartDocument() и заканчиваете его с помощью writeEndDocument(). Это неявно закроет все оставшиеся открытые теги.

Теги элементов открываются с помощью writeStartElement(), за которым следуют writeAttribute() или writeAttributes(), содержимое элемента, а затем writeEndElement(). Более короткая форма writeEmptyElement() может использоваться для записи пустых элементов, за которыми следуют writeAttributes().

Содержимое элемента состоит из символов, ссылок на сущности или вложенных элементов. Оно записывается с помощью writeCharacters(), который также обрабатывает экранирование всех запрещенных символов и последовательностей символов, writeEntityReference() или последующих вызовов writeStartElement(). Удобный метод writeTextElement() может использоваться для записи конечных элементов, которые содержат только текст.

Следующий сокращенный фрагмент кода показывает основное использование класса для записи форматированного XML с отступами:

    QXmlStreamWriter stream(&output);
    stream.setAutoFormatting(true);
    stream.writeStartDocument();
    ...
    stream.writeStartElement("bookmark");
    stream.writeAttribute("href", "http://qt-project.org/");
    stream.writeTextElement("title", "Qt Project");
    stream.writeEndElement(); // bookmark
    ...
    stream.writeEndDocument();

QXmlStreamWriter заботится о префиксации пространств имён, всё, что вам нужно сделать, это указать namespaceUri при записи элементов или атрибутов. Если вы должны придерживаться определённых префиксов, вы можете заставить писателя использовать их, вручную объявив пространства имён с помощью writeNamespace() или writeDefaultNamespace(). В качестве альтернативы, вы можете обойти поддержку пространств имён писателя потока и использовать перегруженные методы, которые принимают квалифицированное имя вместо этого. Пространство имён http://www.w3.org/XML/1998/namespace является неявным и сопоставлено с префиксом xml.

Писатель потока может автоматически форматировать сгенерированные XML-данные, добавляя переводы строк и отступы в пустые разделы между элементами, что делает XML-данные более читаемыми для человека и удобнее для работы с большинством систем управления исходным кодом. Функция может быть включена с помощью свойства autoFormatting и настраивается с помощью свойства autoFormattingIndent.

Другие функции — writeCDATA(), writeComment(), writeProcessingInstruction() и writeDTD(). Поддерживается цепочная запись XML-потоков с помощью writeCurrentToken().

По умолчанию QXmlStreamWriter кодирует XML в UTF-8. Различные кодировки могут быть принудительно установлены с помощью setCodec().

Если при записи в базовое устройство возникает ошибка, hasError() начинает возвращать true, а последующие записи игнорируются.

Пример использования QXmlStreamWriter для создания файла XML-закладок (XBEL) показан в примере QXmlStream Bookmarks, который ранее был прочитан с помощью QXmlStreamReader.

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

QXmlStreamWriter::QXmlStreamWriter()

Создаёт писателя потока.

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

QXmlStreamWriter::QXmlStreamWriter(QIODevice *device)

Создаёт писателя потока, который записывает в device;

QXmlStreamWriter::QXmlStreamWriter(QByteArray *array)

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

QXmlStreamWriter::QXmlStreamWriter(QString *string)

Создаёт писателя потока, который записывает в string.

Обратите внимание, что при записи в QString, QXmlStreamWriter игнорирует кодировку, установленную с помощью setCodec(). См. эту функцию для получения дополнительной информации.

QXmlStreamWriter::~QXmlStreamWriter()

Деструктор.

bool QXmlStreamWriter::autoFormatting() const

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

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

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

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

QTextCodec *QXmlStreamWriter::codec() const

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

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

QIODevice *QXmlStreamWriter::device() const

Возвращает текущее устройство, связанное с QXmlStreamWriter, или 0, если устройство не назначено.

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

bool QXmlStreamWriter::hasError() const

Возвращает true если запись не удалась.

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

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

void QXmlStreamWriter::setAutoFormatting(bool enable)

Включает автоматическое форматирование, если enable равно true, в противном случае отключает его.

Значение по умолчанию — false.

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

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

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

void QXmlStreamWriter::setCodec(QTextCodec *codec)

Устанавливает кодировку для этого потока в codec. Кодировка используется для кодирования любых данных, которые записываются. По умолчанию QXmlStreamWriter использует UTF-8.

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

Примечание: При записи XML в QString информация о кодировке игнорируется, и заголовок XML не будет содержать никакой информации о кодировке, так как все QStrings — UTF-16. Если вы позже преобразуете QString в 8-битный формат, вам необходимо организовать передачу информации о кодировке вне потока.

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

void QXmlStreamWriter::setCodec(const char *codecName)

Устанавливает кодировку для этого потока в QTextCodec для кодировки, указанной codecName. Общие значения для codecName включают "ISO 8859-1", "UTF-8" и "UTF-16". Если кодировка не распознаётся, ничего не происходит.

Примечание: При записи XML в QString информация о кодировке игнорируется, и заголовок XML не будет содержать никакой информации о кодировке, так как все QStrings — UTF-16. Если вы позже преобразуете QString в 8-битный формат, вам необходимо организовать передачу информации о кодировке вне потока.

См. также QTextCodec::codecForName().

void QXmlStreamWriter::setDevice(QIODevice *device)

Устанавливает текущее устройство в device. Если вы хотите, чтобы поток записывал в QByteArray, вы можете создать устройство QBuffer.

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

void QXmlStreamWriter::writeAttribute(const QString &namespaceUri, const QString &name, const QString &value)

Записывает атрибут с name и value, с префиксом для указанного namespaceUri. Если пространство имён ещё не объявлено, QXmlStreamWriter сгенерирует объявление пространства имён для него.

Эта функция может быть вызвана только после writeStartElement() перед записью каких-либо данных или после writeEmptyElement().

void QXmlStreamWriter::writeAttribute(const QString &qualifiedName, const QString &value)

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

Записывает атрибут с qualifiedName и value.

Эту функцию можно вызывать только после writeStartElement() перед записью любого содержимого или после writeEmptyElement().

void QXmlStreamWriter::writeAttribute(const QXmlStreamAttribute &attribute)

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

Записывает атрибут attribute.

Эту функцию можно вызывать только после writeStartElement() перед записью любого содержимого или после writeEmptyElement().

void QXmlStreamWriter::writeAttributes(const QXmlStreamAttributes &attributes)

Записывает вектор атрибутов attributes. Если пространство имён, упоминаемое в атрибуте, ещё не объявлено, QXmlStreamWriter сгенерирует объявление пространства имён для него.

Эту функцию можно вызывать только после writeStartElement() перед записью любого содержимого или после writeEmptyElement().

См. также writeAttribute() и writeNamespace().

void QXmlStreamWriter::writeCDATA(const QString &text)

Записывает text как секцию CDATA. Если text содержит запрещённую последовательность символов "]]>", она разбивается на разные секции CDATA.

Эта функция в основном существует для полноты. Обычно её использовать не нужно, так как writeCharacters() автоматически экранирует все несоответствующие символы.

void QXmlStreamWriter::writeCharacters(const QString &text)

Записывает text. Символы "<", "&", и """ экранируются как сущности "&lt;", "&amp;", и "&quot;". Чтобы избежать запрещённой последовательности "]]>", ">" также экранируется как "&gt;".

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

void QXmlStreamWriter::writeComment(const QString &text)

Записывает text как XML комментарий, где text не должен содержать запрещённую последовательность "--" или заканчиваться на "-". Обратите внимание, что XML не предоставляет способов экранировать "-" в комментарии.

void QXmlStreamWriter::writeCurrentToken(const QXmlStreamReader &reader)

Записывает текущее состояние reader. Поддерживаются все возможные корректные состояния.

Цель этой функции — поддерживать цепочечную обработку XML-данных.

См. также QXmlStreamReader::tokenType().

void QXmlStreamWriter::writeDTD(const QString &dtd)

Записывает секцию DTD. dtd представляет собой все производство doctypedecl из спецификации XML 1.0.

void QXmlStreamWriter::writeDefaultNamespace(const QString &namespaceUri)

Записывает объявление стандартного пространства имён для namespaceUri.

Если была вызвана writeStartElement() или writeEmptyElement(), объявление применяется к текущему элементу; в противном случае оно применяется к следующему дочернему элементу.

Обратите внимание, что пространства имён http://www.w3.org/XML/1998/namespace (связанное с xmlns) и http://www.w3.org/2000/xmlns/ (связанное с xml) по определению не могут быть объявлены стандартными.

void QXmlStreamWriter::writeEmptyElement(const QString &namespaceUri, const QString &name)

Записывает пустой элемент с именем name, префикс которого соответствует заданному namespaceUri. Если пространство имён не объявлено, QXmlStreamWriter сгенерирует его объявление. Последующие вызовы writeAttribute() добавят атрибуты к этому элементу.

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

void QXmlStreamWriter::writeEmptyElement(const QString &qualifiedName)

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

Записывает пустой элемент с квалифицированным именем qualifiedName. Последующие вызовы writeAttribute() добавят атрибуты к этому элементу.

void QXmlStreamWriter::writeEndDocument()

Закрывает все открытые начальные элементы и записывает новую строку.

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

void QXmlStreamWriter::writeEndElement()

Закрывает предыдущий начальный элемент.

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

void QXmlStreamWriter::writeEntityReference(const QString &name)

Записывает ссылку на сущность name в поток как "&name;".

void QXmlStreamWriter::writeNamespace(const QString &namespaceUri, const QString &prefix = QString())

Записывает объявление пространства имён для namespaceUri с prefix. Если prefix пусто, QXmlStreamWriter присваивает уникальный префикс, состоящий из буквы 'n' и числа.

Если была вызвана writeStartElement() или writeEmptyElement(), объявление применяется к текущему элементу; в противном случае оно применяется к следующему дочернему элементу.

Обратите внимание, что префикс xml предопределён и зарезервирован для http://www.w3.org/XML/1998/namespace, который в свою очередь не может быть привязан к другому префиксу. Префикс xmlns и его URI http://www.w3.org/2000/xmlns/ используются для механизма пространств имён и поэтому полностью запрещены в объявлениях.

void QXmlStreamWriter::writeProcessingInstruction(const QString &target, const QString &data = QString())

Записывает XML инструкцию обработки с target и data, где data не должна содержать последовательность "?>".

void QXmlStreamWriter::writeStartDocument(const QString &version)

Записывает начало документа с номером версии XML version.

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

void QXmlStreamWriter::writeStartDocument()

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

Записывает начало документа с номером версии XML "1.0". Также записывает информацию об кодировке.

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

См. также writeEndDocument() и setCodec().

void QXmlStreamWriter::writeStartDocument(const QString &version, bool standalone)

Записывает начало документа с номером версии XML version и атрибутом автономности standalone.

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

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

void QXmlStreamWriter::writeStartElement(const QString &namespaceUri, const QString &name)

Записывает начальный элемент с именем name, префикс которого соответствует заданному namespaceUri. Если пространство имён ещё не объявлено, QXmlStreamWriter сгенерирует его объявление. Последующие вызовы writeAttribute() добавят атрибуты к этому элементу.

См. также writeNamespace(), writeEndElement(), и writeEmptyElement().

void QXmlStreamWriter::writeStartElement(const QString &qualifiedName)

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

Записывает начальный элемент с квалифицированным именем qualifiedName. Последующие вызовы writeAttribute() добавят атрибуты к этому элементу.

См. также writeEndElement() и writeEmptyElement().

void QXmlStreamWriter::writeTextElement(const QString &namespaceUri, const QString &name, const QString &text)

Записывает текстовый элемент с именем name, префикс которого соответствует заданному namespaceUri, и text. Если пространство имён ещё не объявлено, QXmlStreamWriter сгенерирует его объявление.

Это удобная функция, эквивалентная:

        writeStartElement(namespaceUri, name);
        writeCharacters(text);
        writeEndElement();

void QXmlStreamWriter::writeTextElement(const QString &qualifiedName, const QString &text)

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

Записывает текстовый элемент с qualifiedName и text.

Это удобная функция, эквивалентная:

        writeStartElement(qualifiedName);
        writeCharacters(text);
        writeEndElement();