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 <faure@kde.org>
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
17class KBookmarkManagerPrivate;
18
19#include "kbookmark.h"
20
21class KBookmarkGroup;
22
23/**
24 * @class KBookmarkManager kbookmarkmanager.h KBookmarkManager
25 *
26 * This class implements the reading/writing of bookmarks in XML.
27 * The bookmarks file is read and written using the XBEL standard
28 * (http://pyxml.sourceforge.net/topics/xbel/)
29 *
30 * A sample file looks like this :
31 * \code
32 * <xbel>
33 * <bookmark href="http://techbase.kde.org"><title>Developer Web Site</title></bookmark>
34 * <folder folded="no">
35 * <title>Title of this folder</title>
36 * <bookmark icon="kde" href="http://www.kde.org"><title>KDE Web Site</title></bookmark>
37 * <folder toolbar="yes">
38 * <title>My own bookmarks</title>
39 * <bookmark href="http://www.koffice.org"><title>KOffice Web Site</title></bookmark>
40 * <separator/>
41 * <bookmark href="http://www.kdevelop.org"><title>KDevelop Web Site</title></bookmark>
42 * </folder>
43 * </folder>
44 * </xbel>
45 * \endcode
46 */
47class KBOOKMARKS_EXPORT KBookmarkManager : public QObject
48{
49 Q_OBJECT
50
51public:
52 /**
53 * Create a KBookmarkManager responsible for the given @p bookmarksFile.
54 *
55 * The manager watches the file for change detection.
56 *
57 * @param bookmarksFile full path to the bookmarks file,
58 * Use ~/.kde/share/apps/konqueror/bookmarks.xml for the konqueror bookmarks
59 *
60 * @since 6.0
61 *
62 */
63 explicit KBookmarkManager(const QString &bookmarksFile, QObject *parent = nullptr);
64
65 /**
66 * Destructor
67 */
68 ~KBookmarkManager() override;
69
70 /**
71 * Save the bookmarks to the given XML file on disk.
72 * @param filename full path to the desired bookmarks file location
73 * @param toolbarCache iff true save a cache of the toolbar folder, too
74 * @return true if saving was successful
75 */
76 // KF6 TODO: Use an enum and not a bool
77 bool saveAs(const QString &filename, bool toolbarCache = true) const;
78
79 /**
80 * Update access time stamps for a given url.
81 * @param url the viewed url
82 * @return true if any metadata was modified (bookmarks file is not saved automatically)
83 */
84 bool updateAccessMetadata(const QString &url);
85
86 /**
87 * This will return the path that this manager is using to read
88 * the bookmarks.
89 * @internal
90 * @return the path containing the bookmarks
91 */
92 QString path() const;
93
94 /**
95 * This will return the root bookmark. It is used to iterate
96 * through the bookmarks manually. It is mostly used internally.
97 *
98 * @return the root (top-level) bookmark
99 */
100 KBookmarkGroup root() const;
101
102 /**
103 * This returns the root of the toolbar menu.
104 * In the XML, this is the group with the attribute toolbar=yes
105 *
106 * @return the toolbar group
107 */
108 KBookmarkGroup toolbar();
109
110 /**
111 * @return the bookmark designated by @p address
112 * @param address the address belonging to the bookmark you're looking for
113 * @param tolerate when true tries to find the most tolerable bookmark position
114 * @see KBookmark::address
115 */
116 KBookmark findByAddress(const QString &address);
117
118 /**
119 * Saves the bookmark file and notifies everyone.
120 *
121 **/
122 void emitChanged();
123
124 /**
125 * Saves the bookmark file and notifies everyone.
126 * @param group the parent of all changed bookmarks
127 */
128 void emitChanged(const KBookmarkGroup &group);
129
130 /**
131 * Save the bookmarks to an XML file on disk.
132 * You should use emitChanged() instead of this function, it saves
133 * and notifies everyone that the file has changed.
134 * Only use this if you don't want the emitChanged signal.
135 * @param toolbarCache iff true save a cache of the toolbar folder, too
136 * @return true if saving was successful
137 */
138 // KF6 TODO: Use an enum and not a bool
139 bool save(bool toolbarCache = true) const;
140
141 /**
142 * @internal
143 */
144 QDomDocument internalDocument() const;
145
146Q_SIGNALS:
147 /**
148 * Signals that the group (or any of its children) with the address
149 * @p groupAddress (e.g. "/4/5")
150 * has been modified.
151 * connect to this
152 */
153 void changed(const QString &groupAddress);
154
155 /**
156 * Emitted when an error occurs.
157 * Contains the translated error message.
158 * @since 4.6
159 */
160 void error(const QString &errorMessage);
161
162private Q_SLOTS:
163 KBOOKMARKS_NO_EXPORT void slotFileChanged(const QString &path); // external bookmarks
164
165private:
166 // consts added to avoid a copy-and-paste of internalDocument
167 KBOOKMARKS_NO_EXPORT void parse() const;
168
169 KBOOKMARKS_NO_EXPORT void startKEditBookmarks(const QStringList &args);
170
171private:
172 std::unique_ptr<KBookmarkManagerPrivate> const d;
173
174 friend class KBookmarkGroup;
175};
176
177#endif
178

source code of kbookmarks/src/kbookmarkmanager.h