KBookmarks

kbookmarkmanager.h
1 // -*- c-basic-offset:4; indent-tabs-mode:nil -*-
2 /*
3  This file is part of the KDE libraries
4  SPDX-FileCopyrightText: 2000, 2006 David Faure <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-only
7 */
8 #ifndef __kbookmarkmanager_h
9 #define __kbookmarkmanager_h
10 
11 #include <QDomDocument>
12 #include <QObject>
13 #include <QString>
14 
15 #include <memory>
16 
17 class KBookmarkManagerPrivate;
18 
19 #include "kbookmark.h"
20 #if KBOOKMARKS_ENABLE_DEPRECATED_SINCE(5, 79)
21 #include "kbookmarkowner.h" // for SC reasons
22 #endif
23 
24 class KBookmarkGroup;
25 class QDBusMessage;
26 
27 /**
28  * @class KBookmarkManager kbookmarkmanager.h KBookmarkManager
29  *
30  * This class implements the reading/writing of bookmarks in XML.
31  * The bookmarks file is read and written using the XBEL standard
32  * (http://pyxml.sourceforge.net/topics/xbel/)
33  *
34  * A sample file looks like this :
35  * \code
36  * <xbel>
37  * <bookmark href="http://techbase.kde.org"><title>Developer Web Site</title></bookmark>
38  * <folder folded="no">
39  * <title>Title of this folder</title>
40  * <bookmark icon="kde" href="http://www.kde.org"><title>KDE Web Site</title></bookmark>
41  * <folder toolbar="yes">
42  * <title>My own bookmarks</title>
43  * <bookmark href="http://www.koffice.org"><title>KOffice Web Site</title></bookmark>
44  * <separator/>
45  * <bookmark href="http://www.kdevelop.org"><title>KDevelop Web Site</title></bookmark>
46  * </folder>
47  * </folder>
48  * </xbel>
49  * \endcode
50  */
51 class KBOOKMARKS_EXPORT KBookmarkManager : public QObject
52 {
53  Q_OBJECT
54 private:
55  /**
56  * Creates a bookmark manager with a path to the bookmarks. By
57  * default, it will use the KDE standard dirs to find and create the
58  * correct location. If you are using your own app-specific
59  * bookmarks directory, you must instantiate this class with your
60  * own path <em>before</em> KBookmarkManager::managerForFile() is ever
61  * called.
62  *
63  * @param bookmarksFile full path to the bookmarks file,
64  * Use ~/.kde/share/apps/konqueror/bookmarks.xml for the konqueror bookmarks
65  *
66  * @param dbusObjectName a unique name that represents this bookmark collection,
67  * usually your component (e.g. application) name. This is "konqueror" for the
68  * konqueror bookmarks, "kfile" for KFileDialog bookmarks, etc.
69  * The final D-Bus object path is /KBookmarkManager/dbusObjectName
70  * An empty @p dbusObjectName disables the registration to D-Bus (used for temporary managers)
71  */
72  KBOOKMARKS_NO_EXPORT KBookmarkManager(const QString &bookmarksFile, const QString &dbusObjectName);
73 
74  /**
75  * Creates a bookmark manager for an external file
76  * (Using QFileSystemWatcher for change monitoring)
77  * @since 4.1
78  */
79  KBOOKMARKS_NO_EXPORT explicit KBookmarkManager(const QString &bookmarksFile);
80 
81  /**
82  * Creates a temp bookmark manager
83  */
84  KBOOKMARKS_NO_EXPORT KBookmarkManager();
85 
86 public:
87  /**
88  * Destructor
89  */
90  ~KBookmarkManager() override;
91 
92  /**
93  * Check whether auto error handling is enabled.
94  * If enabled, it will show an error dialog to the user when an
95  * error occurs. It is turned on by default.
96  * @return true if auto error handling is enabled, false otherwise
97  * @note dialogs will only be displayed if the current thread is the gui thread
98  * @since 4.6
99  * @see setAutoErrorHandlingEnabled()
100  */
101  bool autoErrorHandlingEnabled() const;
102 
103  /**
104  * Enable or disable auto error handling is enabled.
105  * If enabled, it will show an error dialog to the user when an
106  * error occurs. It is turned on by default.
107  * If disabled, the application should react on the error() signal.
108  * @param enable true to enable auto error handling, false to disable
109  * @param parent the parent widget for the error dialogs, can be @c nullptr for
110  * top-level
111  * @since 4.6
112  * @see autoErrorHandlingEnabled()
113  */
114  void setAutoErrorHandlingEnabled(bool enable, QWidget *parent);
115 
116  /**
117  * Set the update flag. Defaults to true.
118  * @param update if true then KBookmarkManager will listen to D-Bus update requests.
119  */
120  void setUpdate(bool update);
121 
122  /**
123  * Save the bookmarks to the given XML file on disk.
124  * @param filename full path to the desired bookmarks file location
125  * @param toolbarCache iff true save a cache of the toolbar folder, too
126  * @return true if saving was successful
127  */
128  // KF6 TODO: Use an enum and not a bool
129  bool saveAs(const QString &filename, bool toolbarCache = true) const;
130 
131  /**
132  * Update access time stamps for a given url.
133  * @param url the viewed url
134  * @return true if any metadata was modified (bookmarks file is not saved automatically)
135  */
136  bool updateAccessMetadata(const QString &url);
137 
138  /*
139  * NB. currently *unimplemented*
140  *
141  * Update favicon url for a given url.
142  * @param url the viewed url
143  * @param faviconurl the favicion url
144  */
145  void updateFavicon(const QString &url, const QString &faviconurl);
146 
147  /**
148  * This will return the path that this manager is using to read
149  * the bookmarks.
150  * @internal
151  * @return the path containing the bookmarks
152  */
153  QString path() const;
154 
155  /**
156  * This will return the root bookmark. It is used to iterate
157  * through the bookmarks manually. It is mostly used internally.
158  *
159  * @return the root (top-level) bookmark
160  */
161  KBookmarkGroup root() const;
162 
163  /**
164  * This returns the root of the toolbar menu.
165  * In the XML, this is the group with the attribute toolbar=yes
166  *
167  * @return the toolbar group
168  */
169  KBookmarkGroup toolbar();
170 
171  /**
172  * @return the bookmark designated by @p address
173  * @param address the address belonging to the bookmark you're looking for
174  * @param tolerate when true tries to find the most tolerable bookmark position
175  * @see KBookmark::address
176  */
177  KBookmark findByAddress(const QString &address);
178 
179  /**
180  * Saves the bookmark file and notifies everyone.
181  *
182  **/
183  void emitChanged();
184 
185  /**
186  * Saves the bookmark file and notifies everyone.
187  * @param group the parent of all changed bookmarks
188  */
189  void emitChanged(const KBookmarkGroup &group);
190 
191  /**
192  * Save the bookmarks to an XML file on disk.
193  * You should use emitChanged() instead of this function, it saves
194  * and notifies everyone that the file has changed.
195  * Only use this if you don't want the emitChanged signal.
196  * @param toolbarCache iff true save a cache of the toolbar folder, too
197  * @return true if saving was successful
198  */
199  // KF6 TODO: Use an enum and not a bool
200  bool save(bool toolbarCache = true) const;
201 
202  void emitConfigChanged();
203 
204  /**
205  * Set options with which slotEditBookmarks called keditbookmarks
206  * this can be used to change the appearance of the keditbookmarks
207  * in order to provide a slightly differing outer shell depending
208  * on the bookmarks file / app which calls it.
209  * @param caption the --caption string, for instance "Konsole"
210  * @param browser iff false display no browser specific
211  * menu items in keditbookmarks :: --nobrowser
212  */
213  // KF6 TODO: Use an enum and not a bool
214  void setEditorOptions(const QString &caption, bool browser);
215 
216  /**
217  * This static function will return an instance of the
218  * KBookmarkManager, responsible for the given @p bookmarksFile.
219  * If you do not instantiate this class either
220  * natively or in a derived class, then it will return an object
221  * with the default behaviors. If you wish to use different
222  * behaviors, you <em>must</em> derive your own class and
223  * instantiate it before this method is ever called.
224  *
225  * @param bookmarksFile full path to the bookmarks file,
226  * Use ~/.kde/share/apps/konqueror/bookmarks.xml for the konqueror bookmarks
227  *
228  * @param dbusObjectName a unique name that represents this bookmark collection,
229  * usually your component (e.g. application) name. This is "konqueror" for the
230  * konqueror bookmarks, "kfile" for KFileDialog bookmarks, etc.
231  * The final D-Bus object path is /KBookmarkManager/dbusObjectName
232  * An empty @p dbusObjectName disables the registration to D-Bus (used for temporary managers)
233  *
234  */
235  static KBookmarkManager *managerForFile(const QString &bookmarksFile, const QString &dbusObjectName);
236 
237  /**
238  * Returns a KBookmarkManager, which will use QFileSystemWatcher for change detection
239  * This is important when sharing bookmarks with other Desktops.
240  * @param bookmarksFile full path to the bookmarks file
241  * @since 4.1
242  */
243  static KBookmarkManager *managerForExternalFile(const QString &bookmarksFile);
244 
245  /**
246  * only used for KBookmarkBar
247  */
248  static KBookmarkManager *createTempManager();
249 
250  /**
251  * Returns a pointer to the user's main (konqueror) bookmark collection.
252  */
253  static KBookmarkManager *userBookmarksManager();
254 
255  /**
256  * @internal
257  */
258  QDomDocument internalDocument() const;
259 
260 public Q_SLOTS:
261  void slotEditBookmarks();
262  void slotEditBookmarksAtAddress(const QString &address);
263 
264  /**
265  * Reparse the whole bookmarks file and notify about the change
266  * Doesn't send signal over D-Bus to the other Bookmark Managers
267  * You probably want to use emitChanged()
268  *
269  */
270  void notifyCompleteChange(const QString &caller);
271 
272 #ifndef KBOOKMARKS_NO_DBUS
273  /**
274  * Emit the changed signal for the group whose address is given
275  * @see KBookmark::address()
276  * Called by the process that saved the file after
277  * a small change (new bookmark or new folder).
278  * Does not send signal over D-Bus to the other Bookmark Managers
279  * You probably want to call emitChanged()
280  */
281  void notifyChanged(const QString &groupAddress, const QDBusMessage &msg);
282 #endif
283 
284  void notifyConfigChanged();
285 
286 Q_SIGNALS:
287  /**
288  * Signal send over D-Bus
289  */
290  void bookmarkCompleteChange(QString caller);
291 
292  /**
293  * Signal send over D-Bus
294  */
295  void bookmarksChanged(QString groupAddress);
296 
297  /**
298  * Signal send over D-Bus
299  */
300  void bookmarkConfigChanged();
301 
302  /**
303  * Signals that the group (or any of its children) with the address
304  * @p groupAddress (e.g. "/4/5")
305  * has been modified by the caller @p caller.
306  * connect to this
307  */
308  void changed(const QString &groupAddress, const QString &caller);
309 
310  /**
311  * Signals that the config changed
312  */
313  void configChanged();
314 
315  /**
316  * Emitted when an error occurs.
317  * Contains the translated error message.
318  * @since 4.6
319  */
320  void error(const QString &errorMessage);
321 
322 private Q_SLOTS:
323  KBOOKMARKS_NO_EXPORT void slotFileChanged(const QString &path); // external bookmarks
324 
325 private:
326  // consts added to avoid a copy-and-paste of internalDocument
327  KBOOKMARKS_NO_EXPORT void parse() const;
328  KBOOKMARKS_NO_EXPORT void init(const QString &dbusPath);
329 
330  KBOOKMARKS_NO_EXPORT void startKEditBookmarks(const QStringList &args);
331 
332 private:
333  std::unique_ptr<KBookmarkManagerPrivate> const d;
334 
335  friend class KBookmarkGroup;
336 };
337 
338 #endif
Q_SLOTSQ_SLOTS
QString caption()
KCALUTILS_EXPORT QString errorMessage(const KCalendarCore::Exception &exception)
Q_SIGNALSQ_SIGNALS
A group of bookmarks.
Definition: kbookmark.h:322
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Nov 29 2023 03:59:24 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.