1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the documentation of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 /*!

    43     \example xml/streambookmarks

    44     \title QXmlStream Bookmarks Example

    45 

    46     The QXmlStream Bookmarks example provides a reader for XML Bookmark

    47     Exchange Language (XBEL) files using Qt's QXmlStreamReader class

    48     for reading, and QXmlStreamWriter class for writing the files.

    49 

    50     \image xmlstreamexample-screenshot.png

    51 

    52     \section1 XbelWriter Class Definition

    53 

    54     The \c XbelWriter class contains a private instance of QXmlStreamWriter,

    55     which provides an XML writer with a streaming API. \c XbelWriter also

    56     has a reference to the QTreeWidget instance where the bookmark hierarchy

    57     is stored.

    58 

    59     \snippet examples/xml/streambookmarks/xbelwriter.h 0

    60 

    61     \section1 XbelWriter Class Implementation

    62 

    63     The \c XbelWriter constructor accepts a \a treeWidget to initialize within

    64     its definition. We enable \l{QXmlStreamWriter}'s auto-formatting property

    65     to ensure line-breaks and indentations are added automatically to empty

    66     sections between elements, increasing readability as the data is split into

    67     several lines.

    68 

    69     \snippet examples/xml/streambookmarks/xbelwriter.cpp 0

    70 

    71     The \c writeFile() function accepts a QIODevice object and sets it using

    72     \c setDevice(). This function then writes the document type

    73     definition(DTD), the start element, the version, and \c{treeWidget}'s

    74     top-level items.

    75 

    76     \snippet examples/xml/streambookmarks/xbelwriter.cpp 1

    77 

    78     The \c writeItem() function accepts a QTreeWidgetItem object and writes it

    79     to the stream, depending on its \c tagName, which can either be a "folder",

    80     "bookmark", or "separator".

    81 

    82     \snippet examples/xml/streambookmarks/xbelwriter.cpp 2

    83 

    84     \section1 XbelReader Class Definition

    85 

    86     The \c XbelReader contains a private instance of QXmlStreamReader, the

    87     companion class to QXmlStreamWriter. \c XbelReader also contains a

    88     reference to the QTreeWidget that is used to group the bookmarks according

    89     to their hierarchy.

    90 

    91     \snippet examples/xml/streambookmarks/xbelreader.h 0

    92 

    93     \section1 XbelReader Class Implementation

    94 

    95     The \c XbelReader constructor accepts a QTreeWidget to initialize the

    96     \c treeWidget within its definition. A QStyle object is used to set

    97     \c{treeWidget}'s style property. The \c folderIcon is set to QIcon::Normal

    98     mode where the pixmap is only displayed when the user is not interacting

    99     with the icon. The QStyle::SP_DirClosedIcon, QStyle::SP_DirOpenIcon, and

   100     QStyle::SP_FileIcon correspond to standard pixmaps that follow the style

   101     of your GUI.

   102 

   103     \snippet examples/xml/streambookmarks/xbelreader.cpp 0

   104 

   105     The \c read() function accepts a QIODevice and sets it using

   106     \l{QXmlStreamReader::}{setDevice()}. The actual process of reading only

   107     takes place if the file is a valid XBEL 1.0 file. Note that the XML input

   108     needs to be well-formed to be accepted by QXmlStreamReader. Otherwise, the

   109     \l{QXmlStreamReader::}{raiseError()} function is used to display an error

   110     message. Since the XBEL reader is only concerned with reading XML elements,

   111     it makes extensive use of the \l{QXmlStreamReader::}{readNextStartElement()}

   112     convenience function.

   113 

   114     \snippet examples/xml/streambookmarks/xbelreader.cpp 1

   115 

   116     The \c errorString() function is used if an error occurred, in order to

   117     obtain a description of the error complete with line and column number

   118     information.

   119 

   120     \snippet examples/xml/streambookmarks/xbelreader.cpp 2

   121 

   122     The \c readXBEL() function reads the name of a startElement and calls

   123     the appropriate function to read it, depending on whether if its a

   124     "folder", "bookmark" or "separator". Otherwise, it calls

   125     \l{QXmlStreamReader::}{skipCurrentElement()}. The Q_ASSERT() macro is used

   126     to provide a pre-condition for the function.

   127 

   128     \snippet examples/xml/streambookmarks/xbelreader.cpp 3

   129 

   130     The \c readTitle() function reads the bookmark's title.

   131 

   132     \snippet examples/xml/streambookmarks/xbelreader.cpp 4

   133 

   134     The \c readSeparator() function creates a separator and sets its flags.

   135     The text is set to 30 "0xB7", the HEX equivalent for period. The element

   136     is then skipped using \l{QXmlStreamReader::}{skipCurrentElement()}.

   137 

   138     \snippet examples/xml/streambookmarks/xbelreader.cpp 5

   139 

   140     \section1 MainWindow Class Definition

   141 

   142     The \c MainWindow class is a subclass of QMainWindow, with a

   143     \c File menu and a \c Help menu.

   144 

   145     \snippet examples/xml/streambookmarks/mainwindow.h 0

   146 

   147     \section1 MainWindow Class Implementation

   148 

   149     The \c MainWindow constructor instantiates the QTreeWidget object, \c

   150     treeWidget and sets its header with a QStringList object, \c labels.

   151     The constructor also invokes \c createActions() and \c createMenus()

   152     to set up the menus and their corresponding actions. The \c statusBar()

   153     is used to display the message "Ready" and the window's size is fixed

   154     to 480x320 pixels.

   155 

   156     \snippet examples/xml/streambookmarks/mainwindow.cpp 0

   157 

   158     The \c open() function enables the user to open an XBEL file using

   159     QFileDialog::getOpenFileName(). A warning message is displayed along

   160     with the \c fileName and \c errorString if the file cannot be read or

   161     if there is a parse error.

   162 

   163     \snippet examples/xml/streambookmarks/mainwindow.cpp 1

   164 

   165     The \c saveAs() function displays a QFileDialog, prompting the user for

   166     a \c fileName using QFileDialog::getSaveFileName(). Similar to the

   167     \c open() function, this function also displays a warning message if

   168     the file cannot be written to.

   169 

   170     \snippet examples/xml/streambookmarks/mainwindow.cpp 2

   171 

   172     The \c about() function displays a QMessageBox with a brief description

   173     of the example.

   174 

   175     \snippet examples/xml/streambookmarks/mainwindow.cpp 3

   176 

   177     In order to implement the \c open(), \c saveAs(), \c exit(), \c about()

   178     and \c aboutQt() functions, we connect them to QAction objects and

   179     add them to the \c fileMenu and \c helpMenu. The connections are as shown

   180     below:

   181 

   182     \snippet examples/xml/streambookmarks/mainwindow.cpp 4

   183 

   184     The \c createMenus() function creates the \c fileMenu and \c helpMenu

   185     and adds the QAction objects to them in order to create the menu shown

   186     in the screenshot below:

   187 

   188     \table

   189     \row

   190          \o \inlineimage xmlstreamexample-filemenu.png

   191          \o \inlineimage xmlstreamexample-helpmenu.png

   192     \endtable

   193 

   194     \snippet examples/xml/streambookmarks/mainwindow.cpp 5

   195 

   196     \section1 \c{main()} Function

   197 

   198     The \c main() function instantiates \c MainWindow and invokes the \c show()

   199     function.

   200 

   201     \snippet examples/xml/streambookmarks/main.cpp 0

   202 

   203     See the \l{http://pyxml.sourceforge.net/topics/xbel/}

   204     {XML Bookmark Exchange Language Resource Page} for more information

   205     about XBEL files.

   206 */