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

Пример закладок потока QXml демонстрирует, как использовать записывающее устройство потока для записи файла закладок 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();