--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/src/examples/qxmlstreambookmarks.qdoc Thu Apr 08 14:19:33 2010 +0300
@@ -0,0 +1,206 @@
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file. Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights. These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+ \example xml/streambookmarks
+ \title QXmlStream Bookmarks Example
+
+ The QXmlStream Bookmarks example provides a reader for XML Bookmark
+ Exchange Language (XBEL) files using Qt's QXmlStreamReader class
+ for reading, and QXmlStreamWriter class for writing the files.
+
+ \image xmlstreamexample-screenshot.png
+
+ \section1 XbelWriter Class Definition
+
+ The \c XbelWriter class contains a private instance of QXmlStreamWriter,
+ which provides an XML writer with a streaming API. \c XbelWriter also
+ has a reference to the QTreeWidget instance where the bookmark hierarchy
+ is stored.
+
+ \snippet examples/xml/streambookmarks/xbelwriter.h 0
+
+ \section1 XbelWriter Class Implementation
+
+ The \c XbelWriter constructor accepts a \a treeWidget to initialize within
+ its definition. We enable \l{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.
+
+ \snippet examples/xml/streambookmarks/xbelwriter.cpp 0
+
+ The \c writeFile() function accepts a QIODevice object and sets it using
+ \c setDevice(). This function then writes the document type
+ definition(DTD), the start element, the version, and \c{treeWidget}'s
+ top-level items.
+
+ \snippet examples/xml/streambookmarks/xbelwriter.cpp 1
+
+ The \c writeItem() function accepts a QTreeWidgetItem object and writes it
+ to the stream, depending on its \c tagName, which can either be a "folder",
+ "bookmark", or "separator".
+
+ \snippet examples/xml/streambookmarks/xbelwriter.cpp 2
+
+ \section1 XbelReader Class Definition
+
+ The \c XbelReader contains a private instance of QXmlStreamReader, the
+ companion class to QXmlStreamWriter. \c XbelReader also contains a
+ reference to the QTreeWidget that is used to group the bookmarks according
+ to their hierarchy.
+
+ \snippet examples/xml/streambookmarks/xbelreader.h 0
+
+ \section1 XbelReader Class Implementation
+
+ The \c XbelReader constructor accepts a QTreeWidget to initialize the
+ \c treeWidget within its definition. A QStyle object is used to set
+ \c{treeWidget}'s style property. The \c folderIcon is set to QIcon::Normal
+ mode where the pixmap is only displayed when the user is not interacting
+ with the icon. The QStyle::SP_DirClosedIcon, QStyle::SP_DirOpenIcon, and
+ QStyle::SP_FileIcon correspond to standard pixmaps that follow the style
+ of your GUI.
+
+ \snippet examples/xml/streambookmarks/xbelreader.cpp 0
+
+ The \c read() function accepts a QIODevice and sets it using
+ \l{QXmlStreamReader::}{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
+ \l{QXmlStreamReader::}{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 \l{QXmlStreamReader::}{readNextStartElement()}
+ convenience function.
+
+ \snippet examples/xml/streambookmarks/xbelreader.cpp 1
+
+ The \c errorString() function is used if an error occurred, in order to
+ obtain a description of the error complete with line and column number
+ information.
+
+ \snippet examples/xml/streambookmarks/xbelreader.cpp 2
+
+ The \c 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
+ \l{QXmlStreamReader::}{skipCurrentElement()}. The Q_ASSERT() macro is used
+ to provide a pre-condition for the function.
+
+ \snippet examples/xml/streambookmarks/xbelreader.cpp 3
+
+ The \c readTitle() function reads the bookmark's title.
+
+ \snippet examples/xml/streambookmarks/xbelreader.cpp 4
+
+ The \c readSeparator() function creates a separator and sets its flags.
+ The text is set to 30 "0xB7", the HEX equivalent for period. The element
+ is then skipped using \l{QXmlStreamReader::}{skipCurrentElement()}.
+
+ \snippet examples/xml/streambookmarks/xbelreader.cpp 5
+
+ \section1 MainWindow Class Definition
+
+ The \c MainWindow class is a subclass of QMainWindow, with a
+ \c File menu and a \c Help menu.
+
+ \snippet examples/xml/streambookmarks/mainwindow.h 0
+
+ \section1 MainWindow Class Implementation
+
+ The \c MainWindow constructor instantiates the QTreeWidget object, \c
+ treeWidget and sets its header with a QStringList object, \c labels.
+ The constructor also invokes \c createActions() and \c createMenus()
+ to set up the menus and their corresponding actions. The \c statusBar()
+ is used to display the message "Ready" and the window's size is fixed
+ to 480x320 pixels.
+
+ \snippet examples/xml/streambookmarks/mainwindow.cpp 0
+
+ The \c open() function enables the user to open an XBEL file using
+ QFileDialog::getOpenFileName(). A warning message is displayed along
+ with the \c fileName and \c errorString if the file cannot be read or
+ if there is a parse error.
+
+ \snippet examples/xml/streambookmarks/mainwindow.cpp 1
+
+ The \c saveAs() function displays a QFileDialog, prompting the user for
+ a \c fileName using QFileDialog::getSaveFileName(). Similar to the
+ \c open() function, this function also displays a warning message if
+ the file cannot be written to.
+
+ \snippet examples/xml/streambookmarks/mainwindow.cpp 2
+
+ The \c about() function displays a QMessageBox with a brief description
+ of the example.
+
+ \snippet examples/xml/streambookmarks/mainwindow.cpp 3
+
+ In order to implement the \c open(), \c saveAs(), \c exit(), \c about()
+ and \c aboutQt() functions, we connect them to QAction objects and
+ add them to the \c fileMenu and \c helpMenu. The connections are as shown
+ below:
+
+ \snippet examples/xml/streambookmarks/mainwindow.cpp 4
+
+ The \c createMenus() function creates the \c fileMenu and \c helpMenu
+ and adds the QAction objects to them in order to create the menu shown
+ in the screenshot below:
+
+ \table
+ \row
+ \o \inlineimage xmlstreamexample-filemenu.png
+ \o \inlineimage xmlstreamexample-helpmenu.png
+ \endtable
+
+ \snippet examples/xml/streambookmarks/mainwindow.cpp 5
+
+ \section1 \c{main()} Function
+
+ The \c main() function instantiates \c MainWindow and invokes the \c show()
+ function.
+
+ \snippet examples/xml/streambookmarks/main.cpp 0
+
+ See the \l{http://pyxml.sourceforge.net/topics/xbel/}
+ {XML Bookmark Exchange Language Resource Page} for more information
+ about XBEL files.
+*/