qt 6.5.1 original

examples/corelib/serialization/streambookmarks/doc/src/qxmlstreambookmarks.qdoc

@@ -0,0 +1,171 @@
+// Copyright (C) 2016 The Qt Company Ltd.
+// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
+
+/*!
+    \example serialization/streambookmarks
+    \title QXmlStream Bookmarks Example
+    \examplecategory {Input/Output}
+    \brief Demonstrates how to read and write to XBEL files.
+    \ingroup xml-examples
+
+    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 serialization/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 serialization/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 serialization/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 serialization/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 serialization/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 serialization/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 serialization/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 serialization/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 serialization/streambookmarks/xbelreader.cpp 3
+
+    The \c readTitle() function reads the bookmark's title.
+
+    \snippet serialization/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 serialization/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 serialization/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 serialization/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 serialization/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 serialization/streambookmarks/mainwindow.cpp 2
+
+    The \c about() function displays a QMessageBox with a brief description
+    of the example.
+
+    \snippet serialization/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 serialization/streambookmarks/mainwindow.cpp 5
+
+    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
+         \li \inlineimage xmlstreamexample-filemenu.png
+         \li \inlineimage xmlstreamexample-helpmenu.png
+    \endtable
+
+    \snippet serialization/streambookmarks/mainwindow.cpp 5
+
+    \section1 \c{main()} Function
+
+    The \c main() function instantiates \c MainWindow and invokes the \c show()
+    function.
+
+    \snippet serialization/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.
+*/