Класс 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 при записи элементов или атрибутов. Если вам необходимо придерживаться определённых префиксов, вы можете принудительно заставить writer использовать их, вручную объявив пространства имён с помощью writeNamespace() или writeDefaultNamespace(). В качестве альтернативы, вы можете обойти поддержку пространств имён stream writer и использовать перегруженные методы, которые принимают полное имя вместо этого. Пространство имён http://www.w3.org/XML/1998/namespace является неявным и сопоставлено с префиксом xml.

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

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

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

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

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

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

QXmlStreamWriter::QXmlStreamWriter()

Конструктор stream writer.

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

QXmlStreamWriter::QXmlStreamWriter(QIODevice *device)

Конструктор stream writer, который записывает в device;

QXmlStreamWriter::QXmlStreamWriter(QByteArray *array)

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

QXmlStreamWriter::QXmlStreamWriter(QString *string)

Конструктор stream writer, который записывает в 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 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();