// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \example dombookmarks
    \title DOM Bookmarks Application
    \examplecategory {Data Processing & I/O}
    \ingroup xml-examples
    \meta tag {xml}
    \brief Provides a reader for XML Bookmark Exchange Language files.

    The DOM Bookmarks Application provides a reader for XML Bookmark Exchange
    Language (XBEL) files that uses Qt's DOM-based XML API to read and parse
    the files. The \l {QXmlStream Bookmarks Example} provides an alternative
    way to read this type of file.

    \image screenshot.png

    \section1 The XbelTree Class Definition

    The XbelTree class has functions for reading and writing to the filesystem.
    It inherits from the QTreeWidget class, contains the model for the
    displaying of the bookmarks, and allows it to be edited.

    \snippet dombookmarks/xbeltree.h 0

    \section1 The XbelTree Class Implementation

    The \c XbelTree constructor accepts a QWidget within which it is placed.
    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 dombookmarks/xbeltree.cpp 0

    The \c read() function opens the given QIODevice using
    QDomDocument::setContent. If it succeeds  opening the file and the top
    level headers are verified, the contents of the class is cleared before
    the file contents is parsed by iterating all the top level XML nodes and
    calling \c parseFolderElement() on each of them.

    \snippet dombookmarks/xbeltree.cpp 1

    The \c parseFolderElement() function handles the different element types
    and calls itself recursively if the element is a subfolder.

    \snippet dombookmarks/xbeltree.cpp 3

    The \c write() function saves the domDocument to the given QIODevice using
    QDomDocument::save.

    \snippet dombookmarks/xbeltree.cpp 2

    \section1 The MainWindow Class Definition

    The \c MainWindow class is a subclass of QMainWindow, with a
    \c File menu and a \c Help menu.

    \snippet dombookmarks/mainwindow.h 0

    \section1 The MainWindow Class Implementation

    The \c MainWindow constructor instantiates the member XbelTree object,
    and sets its header with a QStringList object, \c labels.
    The constructor also invokes \c createMenus() to set up the menus.
    The \c statusBar() is used to display the message "Ready".

    \snippet dombookmarks/mainwindow.cpp 0

    The \c createMenus() function populates the menus and sets keyboard
    shortcuts.

    \snippet dombookmarks/mainwindow.cpp 4

    The \c open() function enables the user to open an XBEL file using
    QFileDialog. 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. If it succeeds it calls \c XbelTree::read().

    \snippet dombookmarks/mainwindow.cpp 1

    The \c saveAs() function displays a QFileDialog, prompting the user for
    a \c fileName. Similar to the \c open() function, this function also
    displays a warning message if the file cannot be written to. If this
    succeeds it calls \c XbelTree::write().

    \snippet dombookmarks/mainwindow.cpp 2

    The \c about() function displays a QMessageBox with a brief description
    of the example.

    \snippet dombookmarks/mainwindow.cpp 3

    See the \l{http://pyxml.sourceforge.net/topics/xbel/}{XML Bookmark Exchange Language
    Resource Page} for more information about XBEL files.
*/