KBookmarks

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

KDE's Doxygen guidelines are available online.