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

source code of kbookmarks/src/kbookmarkmanager.h