[2] | 1 | /****************************************************************************
|
---|
| 2 | **
|
---|
[846] | 3 | ** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
|
---|
[561] | 4 | ** All rights reserved.
|
---|
| 5 | ** Contact: Nokia Corporation (qt-info@nokia.com)
|
---|
[2] | 6 | **
|
---|
| 7 | ** This file is part of the documentation of the Qt Toolkit.
|
---|
| 8 | **
|
---|
[846] | 9 | ** $QT_BEGIN_LICENSE:FDL$
|
---|
[2] | 10 | ** Commercial Usage
|
---|
| 11 | ** Licensees holding valid Qt Commercial licenses may use this file in
|
---|
| 12 | ** accordance with the Qt Commercial License Agreement provided with the
|
---|
[846] | 13 | ** Software or, alternatively, in accordance with the terms contained in a
|
---|
| 14 | ** written agreement between you and Nokia.
|
---|
[2] | 15 | **
|
---|
[846] | 16 | ** GNU Free Documentation License
|
---|
| 17 | ** Alternatively, this file may be used under the terms of the GNU Free
|
---|
| 18 | ** Documentation License version 1.3 as published by the Free Software
|
---|
| 19 | ** Foundation and appearing in the file included in the packaging of this
|
---|
| 20 | ** file.
|
---|
[2] | 21 | **
|
---|
[561] | 22 | ** If you have questions regarding the use of this file, please contact
|
---|
| 23 | ** Nokia at qt-info@nokia.com.
|
---|
[2] | 24 | ** $QT_END_LICENSE$
|
---|
| 25 | **
|
---|
| 26 | ****************************************************************************/
|
---|
| 27 |
|
---|
| 28 | /*!
|
---|
| 29 | \example xml/streambookmarks
|
---|
| 30 | \title QXmlStream Bookmarks Example
|
---|
| 31 |
|
---|
| 32 | The QXmlStream Bookmarks example provides a reader for XML Bookmark
|
---|
| 33 | Exchange Language (XBEL) files using Qt's QXmlStreamReader class
|
---|
| 34 | for reading, and QXmlStreamWriter class for writing the files.
|
---|
| 35 |
|
---|
| 36 | \image xmlstreamexample-screenshot.png
|
---|
| 37 |
|
---|
| 38 | \section1 XbelWriter Class Definition
|
---|
| 39 |
|
---|
[561] | 40 | The \c XbelWriter class contains a private instance of QXmlStreamWriter,
|
---|
| 41 | which provides an XML writer with a streaming API. \c XbelWriter also
|
---|
| 42 | has a reference to the QTreeWidget instance where the bookmark hierarchy
|
---|
| 43 | is stored.
|
---|
[2] | 44 |
|
---|
| 45 | \snippet examples/xml/streambookmarks/xbelwriter.h 0
|
---|
| 46 |
|
---|
| 47 | \section1 XbelWriter Class Implementation
|
---|
| 48 |
|
---|
| 49 | The \c XbelWriter constructor accepts a \a treeWidget to initialize within
|
---|
| 50 | its definition. We enable \l{QXmlStreamWriter}'s auto-formatting property
|
---|
| 51 | to ensure line-breaks and indentations are added automatically to empty
|
---|
| 52 | sections between elements, increasing readability as the data is split into
|
---|
| 53 | several lines.
|
---|
| 54 |
|
---|
| 55 | \snippet examples/xml/streambookmarks/xbelwriter.cpp 0
|
---|
| 56 |
|
---|
| 57 | The \c writeFile() function accepts a QIODevice object and sets it using
|
---|
| 58 | \c setDevice(). This function then writes the document type
|
---|
| 59 | definition(DTD), the start element, the version, and \c{treeWidget}'s
|
---|
| 60 | top-level items.
|
---|
| 61 |
|
---|
| 62 | \snippet examples/xml/streambookmarks/xbelwriter.cpp 1
|
---|
| 63 |
|
---|
[561] | 64 | The \c writeItem() function accepts a QTreeWidgetItem object and writes it
|
---|
[2] | 65 | to the stream, depending on its \c tagName, which can either be a "folder",
|
---|
| 66 | "bookmark", or "separator".
|
---|
| 67 |
|
---|
| 68 | \snippet examples/xml/streambookmarks/xbelwriter.cpp 2
|
---|
| 69 |
|
---|
| 70 | \section1 XbelReader Class Definition
|
---|
| 71 |
|
---|
[561] | 72 | The \c XbelReader contains a private instance of QXmlStreamReader, the
|
---|
| 73 | companion class to QXmlStreamWriter. \c XbelReader also contains a
|
---|
| 74 | reference to the QTreeWidget that is used to group the bookmarks according
|
---|
| 75 | to their hierarchy.
|
---|
[2] | 76 |
|
---|
| 77 | \snippet examples/xml/streambookmarks/xbelreader.h 0
|
---|
| 78 |
|
---|
| 79 | \section1 XbelReader Class Implementation
|
---|
| 80 |
|
---|
| 81 | The \c XbelReader constructor accepts a QTreeWidget to initialize the
|
---|
| 82 | \c treeWidget within its definition. A QStyle object is used to set
|
---|
| 83 | \c{treeWidget}'s style property. The \c folderIcon is set to QIcon::Normal
|
---|
| 84 | mode where the pixmap is only displayed when the user is not interacting
|
---|
| 85 | with the icon. The QStyle::SP_DirClosedIcon, QStyle::SP_DirOpenIcon, and
|
---|
| 86 | QStyle::SP_FileIcon correspond to standard pixmaps that follow the style
|
---|
| 87 | of your GUI.
|
---|
| 88 |
|
---|
| 89 | \snippet examples/xml/streambookmarks/xbelreader.cpp 0
|
---|
| 90 |
|
---|
| 91 | The \c read() function accepts a QIODevice and sets it using
|
---|
[561] | 92 | \l{QXmlStreamReader::}{setDevice()}. The actual process of reading only
|
---|
| 93 | takes place if the file is a valid XBEL 1.0 file. Note that the XML input
|
---|
| 94 | needs to be well-formed to be accepted by QXmlStreamReader. Otherwise, the
|
---|
| 95 | \l{QXmlStreamReader::}{raiseError()} function is used to display an error
|
---|
| 96 | message. Since the XBEL reader is only concerned with reading XML elements,
|
---|
| 97 | it makes extensive use of the \l{QXmlStreamReader::}{readNextStartElement()}
|
---|
| 98 | convenience function.
|
---|
[2] | 99 |
|
---|
| 100 | \snippet examples/xml/streambookmarks/xbelreader.cpp 1
|
---|
| 101 |
|
---|
[561] | 102 | The \c errorString() function is used if an error occurred, in order to
|
---|
| 103 | obtain a description of the error complete with line and column number
|
---|
| 104 | information.
|
---|
[2] | 105 |
|
---|
| 106 | \snippet examples/xml/streambookmarks/xbelreader.cpp 2
|
---|
| 107 |
|
---|
| 108 | The \c readXBEL() function reads the name of a startElement and calls
|
---|
| 109 | the appropriate function to read it, depending on whether if its a
|
---|
| 110 | "folder", "bookmark" or "separator". Otherwise, it calls
|
---|
[561] | 111 | \l{QXmlStreamReader::}{skipCurrentElement()}. The Q_ASSERT() macro is used
|
---|
| 112 | to provide a pre-condition for the function.
|
---|
[2] | 113 |
|
---|
| 114 | \snippet examples/xml/streambookmarks/xbelreader.cpp 3
|
---|
| 115 |
|
---|
| 116 | The \c readTitle() function reads the bookmark's title.
|
---|
| 117 |
|
---|
| 118 | \snippet examples/xml/streambookmarks/xbelreader.cpp 4
|
---|
| 119 |
|
---|
| 120 | The \c readSeparator() function creates a separator and sets its flags.
|
---|
[561] | 121 | The text is set to 30 "0xB7", the HEX equivalent for period. The element
|
---|
| 122 | is then skipped using \l{QXmlStreamReader::}{skipCurrentElement()}.
|
---|
[2] | 123 |
|
---|
| 124 | \snippet examples/xml/streambookmarks/xbelreader.cpp 5
|
---|
| 125 |
|
---|
| 126 | \section1 MainWindow Class Definition
|
---|
| 127 |
|
---|
| 128 | The \c MainWindow class is a subclass of QMainWindow, with a
|
---|
| 129 | \c File menu and a \c Help menu.
|
---|
| 130 |
|
---|
| 131 | \snippet examples/xml/streambookmarks/mainwindow.h 0
|
---|
| 132 |
|
---|
| 133 | \section1 MainWindow Class Implementation
|
---|
| 134 |
|
---|
| 135 | The \c MainWindow constructor instantiates the QTreeWidget object, \c
|
---|
| 136 | treeWidget and sets its header with a QStringList object, \c labels.
|
---|
| 137 | The constructor also invokes \c createActions() and \c createMenus()
|
---|
| 138 | to set up the menus and their corresponding actions. The \c statusBar()
|
---|
| 139 | is used to display the message "Ready" and the window's size is fixed
|
---|
| 140 | to 480x320 pixels.
|
---|
| 141 |
|
---|
| 142 | \snippet examples/xml/streambookmarks/mainwindow.cpp 0
|
---|
| 143 |
|
---|
| 144 | The \c open() function enables the user to open an XBEL file using
|
---|
| 145 | QFileDialog::getOpenFileName(). A warning message is displayed along
|
---|
| 146 | with the \c fileName and \c errorString if the file cannot be read or
|
---|
| 147 | if there is a parse error.
|
---|
| 148 |
|
---|
| 149 | \snippet examples/xml/streambookmarks/mainwindow.cpp 1
|
---|
| 150 |
|
---|
| 151 | The \c saveAs() function displays a QFileDialog, prompting the user for
|
---|
| 152 | a \c fileName using QFileDialog::getSaveFileName(). Similar to the
|
---|
| 153 | \c open() function, this function also displays a warning message if
|
---|
| 154 | the file cannot be written to.
|
---|
| 155 |
|
---|
| 156 | \snippet examples/xml/streambookmarks/mainwindow.cpp 2
|
---|
| 157 |
|
---|
| 158 | The \c about() function displays a QMessageBox with a brief description
|
---|
| 159 | of the example.
|
---|
| 160 |
|
---|
| 161 | \snippet examples/xml/streambookmarks/mainwindow.cpp 3
|
---|
| 162 |
|
---|
| 163 | In order to implement the \c open(), \c saveAs(), \c exit(), \c about()
|
---|
| 164 | and \c aboutQt() functions, we connect them to QAction objects and
|
---|
| 165 | add them to the \c fileMenu and \c helpMenu. The connections are as shown
|
---|
| 166 | below:
|
---|
| 167 |
|
---|
| 168 | \snippet examples/xml/streambookmarks/mainwindow.cpp 4
|
---|
| 169 |
|
---|
| 170 | The \c createMenus() function creates the \c fileMenu and \c helpMenu
|
---|
| 171 | and adds the QAction objects to them in order to create the menu shown
|
---|
| 172 | in the screenshot below:
|
---|
| 173 |
|
---|
| 174 | \table
|
---|
| 175 | \row
|
---|
| 176 | \o \inlineimage xmlstreamexample-filemenu.png
|
---|
| 177 | \o \inlineimage xmlstreamexample-helpmenu.png
|
---|
| 178 | \endtable
|
---|
| 179 |
|
---|
| 180 | \snippet examples/xml/streambookmarks/mainwindow.cpp 5
|
---|
| 181 |
|
---|
| 182 | \section1 \c{main()} Function
|
---|
| 183 |
|
---|
| 184 | The \c main() function instantiates \c MainWindow and invokes the \c show()
|
---|
| 185 | function.
|
---|
| 186 |
|
---|
| 187 | \snippet examples/xml/streambookmarks/main.cpp 0
|
---|
| 188 |
|
---|
| 189 | See the \l{http://pyxml.sourceforge.net/topics/xbel/}
|
---|
| 190 | {XML Bookmark Exchange Language Resource Page} for more information
|
---|
| 191 | about XBEL files.
|
---|
| 192 | */
|
---|