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

source code of kbookmarks/src/kbookmark.h