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