1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000-2005 David Faure <faure@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-only
6*/
7#ifndef __kbookmark_h
8#define __kbookmark_h
9
10#include <kbookmarks_export.h>
11
12#include <QDomElement>
13#include <QList>
14#include <QMetaType>
15#include <QString>
16#include <QUrl>
17
18class QMimeData;
19class KBookmarkGroup;
20
21/**
22 * @class KBookmark kbookmark.h KBookmark
23 *
24 * A class representing a bookmark.
25 */
26class KBOOKMARKS_EXPORT KBookmark
27{
28 friend class KBookmarkGroup;
29
30public:
31 enum MetaDataOverwriteMode {
32 OverwriteMetaData,
33 DontOverwriteMetaData,
34 };
35
36 /**
37 * KBookmark::List is a QList that contains bookmarks with a few
38 * convenience methods.
39 * @see KBookmark
40 * @see QList
41 */
42 class KBOOKMARKS_EXPORT List : public QList<KBookmark>
43 {
44 public:
45 List();
46
47 /**
48 * Adds this list of bookmark into the given QMimeData.
49 *
50 * @param mimeData the QMimeData instance used to drag or copy this bookmark
51 */
52 void populateMimeData(QMimeData *mimeData) const;
53
54 /**
55 * Return true if @p mimeData contains bookmarks
56 */
57 static bool canDecode(const QMimeData *mimeData);
58
59 /**
60 * Return the list of mimeTypes that can be decoded by fromMimeData
61 */
62 static QStringList mimeDataTypes();
63
64 /**
65 * Extract a list of bookmarks from the contents of @p mimeData.
66 * Decoding will fail if @p mimeData does not contain any bookmarks.
67 * @param mimeData the mime data to extract from; cannot be 0
68 * @param parentDocument pass an empty QDomDocument here, it will be used as
69 * container for the bookmarks. You just need to make sure it stays alive longer
70 * (or just as long) as the returned bookmarks.
71 * @return the list of bookmarks
72 * @since 4.3.2
73 */
74 static KBookmark::List fromMimeData(const QMimeData *mimeData, QDomDocument &parentDocument);
75 };
76
77 /**
78 * Constructs a null bookmark, i.e. a bookmark for which isNull() returns true
79 * If you want to create a new bookmark use eitehr KBookmarkGroup.addBookmark
80 * or if you want an interactive dialog use KBookmarkDialog.
81 */
82 KBookmark();
83
84 /**
85 * Creates the KBookmark wrapper for @param elem
86 * Mostly for internal usage.
87 */
88
89 explicit KBookmark(const QDomElement &elem);
90
91 /**
92 * Creates a stand alone bookmark. This is fairly expensive since a new QDom Tree is build.
93 */
94 static KBookmark standaloneBookmark(const QString &text, const QUrl &url, const QString &icon);
95
96 /**
97 * Whether the bookmark is a group or a normal bookmark
98 */
99 bool isGroup() const;
100
101 /**
102 * Whether the bookmark is a separator
103 */
104 bool isSeparator() const;
105
106 /**
107 * @return true if this is a null bookmark. This will never
108 * be the case for a real bookmark (in a menu), but it's used
109 * for instance as the end condition for KBookmarkGroup::next()
110 */
111 bool isNull() const;
112
113 /**
114 * @return true if bookmark is contained by a QDomDocument,
115 * if not it is most likely that it has become separated and
116 * is thus invalid and/or has been deleted from the bookmarks.
117 */
118 bool hasParent() const;
119
120 /**
121 * Text shown for the bookmark
122 * If bigger than 40, the text is shortened by
123 * replacing middle characters with "..." (see KStringHandler::csqueeze)
124 */
125 QString text() const;
126 /**
127 * Text shown for the bookmark, not truncated.
128 * You should not use this - this is mainly for keditbookmarks.
129 */
130 QString fullText() const;
131 /**
132 * Set the text shown for the bookmark.
133 *
134 * @param fullText the new bookmark title
135 */
136 void setFullText(const QString &fullText);
137 /**
138 * URL contained by the bookmark
139 */
140 QUrl url() const;
141 /**
142 * Set the URL of the bookmark
143 *
144 * @param url the new bookmark URL
145 */
146 void setUrl(const QUrl &url);
147
148 /**
149 * @return the pixmap file for this bookmark
150 * (i.e. the name of the icon)
151 */
152 QString icon() const;
153
154 /**
155 * Set the icon name of the bookmark
156 *
157 * @param icon the new icon name for this bookmark
158 */
159 void setIcon(const QString &icon);
160
161 /**
162 * @return Description of the bookmark
163 * @since 4.4
164 */
165 QString description() const;
166
167 /**
168 * Set the description of the bookmark
169 *
170 * @param description
171 * @since 4.4
172 */
173 void setDescription(const QString &description);
174
175 /**
176 * @return Mime-Type of this item
177 * @since 4.1
178 */
179 QString mimeType() const;
180
181 /**
182 * Set the Mime-Type of this item
183 *
184 * @param Mime-Type
185 * @since 4.1
186 */
187 void setMimeType(const QString &mimeType);
188
189 /**
190 * @return if the bookmark should be shown in the toolbar
191 * (used by the filtered toolbar)
192 *
193 */
194 bool showInToolbar() const;
195
196 /**
197 * Set whether this bookmark is show in a filterd toolbar
198 */
199 void setShowInToolbar(bool show);
200
201 /**
202 * @return the group containing this bookmark
203 */
204 KBookmarkGroup parentGroup() const;
205
206 /**
207 * Convert this to a group - do this only if
208 * isGroup() returns true.
209 */
210 KBookmarkGroup toGroup() const;
211
212 /**
213 * Return the "address" of this bookmark in the whole tree.
214 * This is used when telling other processes about a change
215 * in a given bookmark. The encoding of the address is "/4/2", for
216 * instance, to designate the 2nd child inside the 4th child of the
217 * root bookmark.
218 */
219 QString address() const;
220
221 /**
222 * Return the position in the parent, i.e. the last number in the address
223 */
224 int positionInParent() const;
225
226 /**
227 * @internal for KEditBookmarks
228 */
229 QDomElement internalElement() const;
230
231 /**
232 * Updates the bookmarks access metadata
233 * Call when a user accesses the bookmark
234 */
235 void updateAccessMetadata();
236
237 // Utility functions (internal)
238
239 /**
240 * @return address of parent
241 */
242 static QString parentAddress(const QString &address);
243
244 /**
245 * @return position in parent (e.g. /4/5/2 -> 2)
246 */
247 static uint positionInParent(const QString &address);
248
249 /**
250 * @return address of previous sibling (e.g. /4/5/2 -> /4/5/1)
251 * Returns QString() for a first child
252 */
253 static QString previousAddress(const QString &address);
254
255 /**
256 * @return address of next sibling (e.g. /4/5/2 -> /4/5/3)
257 * This doesn't check whether it actually exists
258 */
259 static QString nextAddress(const QString &address);
260
261 /**
262 * @return the common parent of both addresses which
263 * has the greatest depth
264 */
265 static QString commonParent(const QString &A, const QString &B);
266
267 /**
268 * @return the metadata container node for a certain metadata owner
269 * @since 4.1
270 */
271 QDomNode metaData(const QString &owner, bool create) const;
272
273 /**
274 * Get the value of a specific metadata item (owner = "http://www.kde.org").
275 * @param key Name of the metadata item
276 * @return Value of the metadata item. QString() is returned in case
277 * the specified key does not exist.
278 */
279 QString metaDataItem(const QString &key) const;
280
281 /**
282 * Change the value of a specific metadata item, or create the given item
283 * if it doesn't exist already (owner = "http://www.kde.org").
284 * @param key Name of the metadata item to change
285 * @param value Value to use for the specified metadata item
286 * @param mode Whether to overwrite the item's value if it exists already or not.
287 */
288 void setMetaDataItem(const QString &key, const QString &value, MetaDataOverwriteMode mode = OverwriteMetaData);
289
290 /**
291 * Adds this bookmark into the given QMimeData.
292 *
293 * WARNING: do not call this method multiple times, use KBookmark::List::populateMimeData instead.
294 *
295 * @param mimeData the QMimeData instance used to drag or copy this bookmark
296 */
297 void populateMimeData(QMimeData *mimeData) const;
298
299 /**
300 * Comparison operator
301 */
302 bool operator==(const KBookmark &rhs) const;
303
304protected:
305 QDomElement element;
306 // Note: you can't add new member variables here.
307 // The KBookmarks are created on the fly, as wrappers
308 // around internal QDomElements. Any additional information
309 // has to be implemented as an attribute of the QDomElement.
310};
311
312/**
313 * A group of bookmarks
314 */
315class KBOOKMARKS_EXPORT KBookmarkGroup : public KBookmark
316{
317public:
318 /**
319 * Create an invalid group. This is mostly for use in QList,
320 * and other places where we need a null group.
321 * Also used as a parent for a bookmark that doesn't have one
322 * (e.g. Netscape bookmarks)
323 */
324 KBookmarkGroup();
325
326 /**
327 * Create a bookmark group as specified by the given element
328 */
329 KBookmarkGroup(const QDomElement &elem);
330
331 /**
332 * @return true if the bookmark folder is opened in the bookmark editor
333 */
334 bool isOpen() const;
335
336 /**
337 * Return the first child bookmark of this group
338 */
339 KBookmark first() const;
340 /**
341 * Return the previous sibling of a child bookmark of this group
342 * @param current has to be one of our child bookmarks.
343 */
344 KBookmark previous(const KBookmark &current) const;
345 /**
346 * Return the next sibling of a child bookmark of this group
347 * @param current has to be one of our child bookmarks.
348 */
349 KBookmark next(const KBookmark &current) const;
350
351 /**
352 * Return the index of a child bookmark, -1 if not found
353 */
354 int indexOf(const KBookmark &child) const;
355
356 /**
357 * Create a new bookmark folder, as the last child of this group
358 * @param text for the folder.
359 * If you want an dialog use KBookmarkDialog
360 */
361 KBookmarkGroup createNewFolder(const QString &text);
362 /**
363 * Create a new bookmark separator
364 * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark );
365 */
366 KBookmark createNewSeparator();
367
368 /**
369 * Create a new bookmark, as the last child of this group
370 * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark );
371 * @param bm the bookmark to add
372 */
373 KBookmark addBookmark(const KBookmark &bm);
374
375 /**
376 * Create a new bookmark, as the last child of this group
377 * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark );
378 * @param text for the bookmark
379 * @param url the URL that the bookmark points to.
380 * It will be stored in its QUrl::FullyEncoded string format.
381 * @param icon the name of the icon to associate with the bookmark. A suitable default
382 * will be determined from the URL if not specified.
383 */
384 KBookmark addBookmark(const QString &text, const QUrl &url, const QString &icon);
385
386 /**
387 * Moves @p bookmark after @p after (which should be a child of ours).
388 * If after is null, @p bookmark is moved as the first child.
389 * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark );
390 */
391 bool moveBookmark(const KBookmark &bookmark, const KBookmark &after);
392
393 /**
394 * Delete a bookmark - it has to be one of our children !
395 * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark );
396 */
397 void deleteBookmark(const KBookmark &bk);
398
399 /**
400 * @return true if this is the toolbar group
401 */
402 bool isToolbarGroup() const;
403 /**
404 * @internal
405 */
406 QDomElement findToolbar() const;
407
408 /**
409 * @return the list of urls of bookmarks at top level of the group
410 */
411 QList<QUrl> groupUrlList() const;
412
413protected:
414 QDomElement nextKnownTag(const QDomElement &start, bool goNext) const;
415
416private:
417 // Note: you can't add other member variables here, except for caching info.
418 // The KBookmarks are created on the fly, as wrappers
419 // around internal QDomElements. Any additional information
420 // has to be implemented as an attribute of the QDomElement.
421};
422
423/**
424 * A class to traverse bookarm groups
425 */
426class KBOOKMARKS_EXPORT KBookmarkGroupTraverser
427{
428protected:
429 virtual ~KBookmarkGroupTraverser();
430 void traverse(const KBookmarkGroup &);
431 virtual void visit(const KBookmark &);
432 virtual void visitEnter(const KBookmarkGroup &);
433 virtual void visitLeave(const KBookmarkGroup &);
434};
435
436#define KIO_KBOOKMARK_METATYPE_DEFINED 1
437Q_DECLARE_METATYPE(KBookmark)
438
439#endif
440

source code of kbookmarks/src/kbookmark.h