File indexing completed on 2024-03-24 03:55:25

0001 //  -*- c-basic-offset:4; indent-tabs-mode:nil -*-
0002 /*
0003     This file is part of the KDE libraries
0004     SPDX-FileCopyrightText: 2000, 2006 David Faure <faure@kde.org>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-only
0007 */
0008 #ifndef __kbookmarkmanager_h
0009 #define __kbookmarkmanager_h
0010 
0011 #include <QDomDocument>
0012 #include <QObject>
0013 #include <QString>
0014 
0015 #include <memory>
0016 
0017 class KBookmarkManagerPrivate;
0018 
0019 #include "kbookmark.h"
0020 
0021 class KBookmarkGroup;
0022 
0023 /**
0024  * @class KBookmarkManager kbookmarkmanager.h KBookmarkManager
0025  *
0026  * This class implements the reading/writing of bookmarks in XML.
0027  * The bookmarks file is read and written using the XBEL standard
0028  * (http://pyxml.sourceforge.net/topics/xbel/)
0029  *
0030  * A sample file looks like this :
0031  * \code
0032  * <xbel>
0033  *   <bookmark href="http://techbase.kde.org"><title>Developer Web Site</title></bookmark>
0034  *   <folder folded="no">
0035  *     <title>Title of this folder</title>
0036  *     <bookmark icon="kde" href="http://www.kde.org"><title>KDE Web Site</title></bookmark>
0037  *     <folder toolbar="yes">
0038  *       <title>My own bookmarks</title>
0039  *       <bookmark href="http://www.koffice.org"><title>KOffice Web Site</title></bookmark>
0040  *       <separator/>
0041  *       <bookmark href="http://www.kdevelop.org"><title>KDevelop Web Site</title></bookmark>
0042  *     </folder>
0043  *   </folder>
0044  * </xbel>
0045  * \endcode
0046  */
0047 class KBOOKMARKS_EXPORT KBookmarkManager : public QObject
0048 {
0049     Q_OBJECT
0050 
0051 public:
0052     /**
0053      * Create a KBookmarkManager responsible for the given @p bookmarksFile.
0054      *
0055      * The manager watches the file for change detection.
0056      *
0057      * @param bookmarksFile full path to the bookmarks file,
0058      * Use ~/.kde/share/apps/konqueror/bookmarks.xml for the konqueror bookmarks
0059      *
0060      * @since 6.0
0061      *
0062      */
0063     explicit KBookmarkManager(const QString &bookmarksFile, QObject *parent = nullptr);
0064 
0065     /**
0066      * Destructor
0067      */
0068     ~KBookmarkManager() override;
0069 
0070     /**
0071      * Save the bookmarks to the given XML file on disk.
0072      * @param filename full path to the desired bookmarks file location
0073      * @param toolbarCache iff true save a cache of the toolbar folder, too
0074      * @return true if saving was successful
0075      */
0076     // KF6 TODO: Use an enum and not a bool
0077     bool saveAs(const QString &filename, bool toolbarCache = true) const;
0078 
0079     /**
0080      * Update access time stamps for a given url.
0081      * @param url the viewed url
0082      * @return true if any metadata was modified (bookmarks file is not saved automatically)
0083      */
0084     bool updateAccessMetadata(const QString &url);
0085 
0086     /**
0087      * This will return the path that this manager is using to read
0088      * the bookmarks.
0089      * @internal
0090      * @return the path containing the bookmarks
0091      */
0092     QString path() const;
0093 
0094     /**
0095      * This will return the root bookmark.  It is used to iterate
0096      * through the bookmarks manually.  It is mostly used internally.
0097      *
0098      * @return the root (top-level) bookmark
0099      */
0100     KBookmarkGroup root() const;
0101 
0102     /**
0103      * This returns the root of the toolbar menu.
0104      * In the XML, this is the group with the attribute toolbar=yes
0105      *
0106      * @return the toolbar group
0107      */
0108     KBookmarkGroup toolbar();
0109 
0110     /**
0111      * @return the bookmark designated by @p address
0112      * @param address the address belonging to the bookmark you're looking for
0113      * @param tolerate when true tries to find the most tolerable bookmark position
0114      * @see KBookmark::address
0115      */
0116     KBookmark findByAddress(const QString &address);
0117 
0118     /**
0119      * Saves the bookmark file and notifies everyone.
0120      *
0121      **/
0122     void emitChanged();
0123 
0124     /**
0125      * Saves the bookmark file and notifies everyone.
0126      * @param group the parent of all changed bookmarks
0127      */
0128     void emitChanged(const KBookmarkGroup &group);
0129 
0130     /**
0131      * Save the bookmarks to an XML file on disk.
0132      * You should use emitChanged() instead of this function, it saves
0133      * and notifies everyone that the file has changed.
0134      * Only use this if you don't want the emitChanged signal.
0135      * @param toolbarCache iff true save a cache of the toolbar folder, too
0136      * @return true if saving was successful
0137      */
0138     // KF6 TODO: Use an enum and not a bool
0139     bool save(bool toolbarCache = true) const;
0140 
0141     /**
0142      * @internal
0143      */
0144     QDomDocument internalDocument() const;
0145 
0146 Q_SIGNALS:
0147     /**
0148      * Signals that the group (or any of its children) with the address
0149      * @p groupAddress (e.g. "/4/5")
0150      * has been modified.
0151      * connect to this
0152      */
0153     void changed(const QString &groupAddress);
0154 
0155     /**
0156      * Emitted when an error occurs.
0157      * Contains the translated error message.
0158      * @since 4.6
0159      */
0160     void error(const QString &errorMessage);
0161 
0162 private Q_SLOTS:
0163     KBOOKMARKS_NO_EXPORT void slotFileChanged(const QString &path); // external bookmarks
0164 
0165 private:
0166     // consts added to avoid a copy-and-paste of internalDocument
0167     KBOOKMARKS_NO_EXPORT void parse() const;
0168 
0169     KBOOKMARKS_NO_EXPORT void startKEditBookmarks(const QStringList &args);
0170 
0171 private:
0172     std::unique_ptr<KBookmarkManagerPrivate> const d;
0173 
0174     friend class KBookmarkGroup;
0175 };
0176 
0177 #endif