Класс QXmlStreamWriter

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

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

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

Свойства

• autoFormatting : bool
• autoFormattingIndent : int

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

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

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

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, и последующие записи игнорируются.

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

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

QXmlStreamWriter::QXmlStreamWriter()

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

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

QXmlStreamWriter::QXmlStreamWriter(QIODevice *device)

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

QXmlStreamWriter::QXmlStreamWriter(QByteArray *array)

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

QXmlStreamWriter::QXmlStreamWriter(QString *string)

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

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().

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

void QXmlStreamWriter::setCodec(const char *codecName)

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

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