Description

Overview

In this example we'll learn how to use the QXmlStreamReader and QXmlStreamWriter classes to parse, modify and generate an XML document. Additionally we'll see how to generate UI objects (that are described in a QML file) on-the-fly and how to access and modify their properties.

The UI

The UI of this sample application consists of three buttons and a container. The first two buttons allow the user to load two different XBEL documents and the third button allows the user to save the currently loaded XBEL document back to file system (including possible changes done to the bookmarks).

The container is the target location for the tree of controls, that visualize the structure of the XBEL document. The XBEL standard defines the elements

folder

bookmark

separator

The folder is represented by a Container with a folder icon and a title label (FolderItem.qml). It provides a custom property 'tagName' and a property 'title' that is aliased to the 'text' property of the titleField label. So whenever the 'title' property is changed, the 'text' property will be updated.

The bookmarks are visualized by a Container with a star icon, a title label and a TextField that contains the bookmark URL (BookmarkItem.qml). The TextField is invisible by default and will be faded in when the user clicks on the title label.

The container has the 'objectName' property set, so that it can be looked up from within C++.

App

Inside the constructor of App we load the main.qml file and retrieve the C++ object that represents the root node of the QML document. With the findChild() method we look up the Container object where we have assigned 'treeContainer' to the 'objectName' property.

Inside save() we try to open the file 'streambookmarks.xbel' inside the applications temp directory and then we use the XbelWriter class to iterate over the treeContainer, generate the XML document and store it to the file.

XbelWriter Class Definition

The XbelWriter class contains a private instance of QXmlStreamWriter, which provides an XML writer with a streaming API. XbelWriter also has a reference to the Container instance where the bookmark hierarchy is stored.

/**
* The XbelWriter is responsible for generating a XBEL document from the
* controls in the tree container.
*
* To generate the XBEL document the XbelWriter uses the QXmlStreamWriter class from Qt.
*/class XbelWriter
{
public:
XbelWriter(bb::cascades::Container *treeContainer);
// Starts the generation of the XBEL documentbool writeFile(QIODevice*device);
private:
// A helper method that generates an element in the XBEL document for the current controlvoid writeItem(bb::cascades::Control *item);
// The XML stream writer that is used to generate the XBEL documentQXmlStreamWriter m_xml;
// The container object the controls are located inQPointer<bb::cascades::Container> m_treeContainer;
};

XbelWriter Class Implementation

The XbelWriter constructor accepts a treeContainer to initialize within its definition. We enable QXmlStreamWriter's auto-formatting property to ensure line-breaks and indentations are added automatically to empty sections between elements, increasing readability as the data is split into several lines.

The writeFile() function accepts a QIODevice object and sets it using setDevice(). This function then writes the document type definition(DTD), the start element, the version, and treeContainer's top-level items.

bool XbelWriter::writeFile(QIODevice*device)
{
m_xml.setDevice(device);
// Start the creation of the document
m_xml.writeStartDocument();
m_xml.writeDTD("<!DOCTYPE xbel>");
// Add the root element with the necessary 'xbel' element and version attribute
m_xml.writeStartElement("xbel");
m_xml.writeAttribute("version","1.0");
// Iterate over the controls of the tree container and generate an XBEL element for each of themfor (int i =0; i < m_treeContainer->count(); ++i)
writeItem(m_treeContainer->at(i));
m_xml.writeEndDocument();
returntrue;
}

The writeItem() function accepts a Control object and writes it to the stream, depending on its tagName, which can either be a "folder", "bookmark", or "separator".

XbelReader Class Definition

The XbelReader contains a private instance of QXmlStreamReader, the companion class to QXmlStreamWriter. XbelReader also contains a reference to the Container that is used to group the bookmarks according to their hierarchy.

/**
* The XbelReader is responsible for parsing a XBEL file and generating
* controls, that represent the bookmark entries, on the tree container.
*
* To parse the XBEL document the XbelReader uses the QXmlStreamReader class from Qt.
*/class XbelReader
{
public:
XbelReader(bb::cascades::Container *treeContainer);
// Starts the parsing of the XBEL documentbool read(QIODevice*device);
// Returns a textual representation of the error if one occurredQString errorString() const;
private:
// A helper method that parses the root element of a XBEL documentvoid readXBEL();
// A helper method that parses the title attribute of the current elementvoid readTitle(bb::cascades::Container *item);
// A helper method that parses a separator elementvoid readSeparator(bb::cascades::Container *item);
// A helper method that parses a folder elementvoid readFolder(bb::cascades::Container *item);
// A helper method that parses a bookmark elementvoid readBookmark(bb::cascades::Container *item);
// A helper method that generates a control for the current XBEL element
bb::cascades::Container *createChildItem(bb::cascades::Container *parent);
// The XML stream reader that is used to parse the XBEL documentQXmlStreamReader m_xml;
// The container object the controls are created inQPointer<bb::cascades::Container> m_treeContainer;
};

XbelReader Class Implementation

The XbelReader constructor accepts a Container to initialize the treeContainer within its definition.

The read() function accepts a QIODevice and sets it using setDevice(). The actual process of reading only takes place if the file is a valid XBEL 1.0 file. Note that the XML input needs to be well-formed to be accepted by QXmlStreamReader. Otherwise, the raiseError() function is used to display an error message. Since the XBEL reader is only concerned with reading XML elements, it makes extensive use of the readNextStartElement() convenience function.

bool XbelReader::read(QIODevice*device)
{
// Set the XBEL document as input data to the XML stream reader
m_xml.setDevice(device);
// Read the first element ...if (m_xml.readNextStartElement()) {
// ... and check whether this is a valid XBEL file in the correct versionif (m_xml.name() =="xbel"&& m_xml.attributes().value("version") =="1.0")
readXBEL(); // Start to parse the documentelse
m_xml.raiseError(QObject::tr("The file is not an XBEL version 1.0 file."));
}
return!m_xml.error();
}

The errorString() function is used if an error occurred, in order to obtain a description of the error complete with line and column number information.

The readXBEL() function reads the name of a startElement and calls the appropriate function to read it, depending on whether if its a "folder", "bookmark" or "separator". Otherwise, it calls skipCurrentElement(). The Q_ASSERT() macro is used to provide a pre-condition for the function.

All other trademarks are property of their respective owners. Privacy Policy

Licensees holding valid Qt Commercial licenses may use this document in accordance with the Qt Commercial License Agreement provided with the Software or, alternatively, in accordance with the terms contained in a written agreement between you and Nokia.