File indexing completed on 2024-12-08 06:37:41
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 2000-2005 David Faure <faure@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-only 0006 */ 0007 #ifndef __kbookmark_h 0008 #define __kbookmark_h 0009 0010 #include <kbookmarks_export.h> 0011 0012 #include <QDomElement> 0013 #include <QList> 0014 #include <QMetaType> 0015 #include <QString> 0016 #include <QUrl> 0017 0018 class QMimeData; 0019 class KBookmarkGroup; 0020 0021 /** 0022 * @class KBookmark kbookmark.h KBookmark 0023 * 0024 * A class representing a bookmark. 0025 */ 0026 class KBOOKMARKS_EXPORT KBookmark 0027 { 0028 friend class KBookmarkGroup; 0029 0030 public: 0031 enum MetaDataOverwriteMode { 0032 OverwriteMetaData, 0033 DontOverwriteMetaData, 0034 }; 0035 0036 /** 0037 * KBookmark::List is a QList that contains bookmarks with a few 0038 * convenience methods. 0039 * @see KBookmark 0040 * @see QList 0041 */ 0042 class KBOOKMARKS_EXPORT List : public QList<KBookmark> 0043 { 0044 public: 0045 List(); 0046 0047 /** 0048 * Adds this list of bookmark into the given QMimeData. 0049 * 0050 * @param mimeData the QMimeData instance used to drag or copy this bookmark 0051 */ 0052 void populateMimeData(QMimeData *mimeData) const; 0053 0054 /** 0055 * Return true if @p mimeData contains bookmarks 0056 */ 0057 static bool canDecode(const QMimeData *mimeData); 0058 0059 /** 0060 * Return the list of mimeTypes that can be decoded by fromMimeData 0061 */ 0062 static QStringList mimeDataTypes(); 0063 0064 /** 0065 * Extract a list of bookmarks from the contents of @p mimeData. 0066 * Decoding will fail if @p mimeData does not contain any bookmarks. 0067 * @param mimeData the mime data to extract from; cannot be 0 0068 * @param parentDocument pass an empty QDomDocument here, it will be used as 0069 * container for the bookmarks. You just need to make sure it stays alive longer 0070 * (or just as long) as the returned bookmarks. 0071 * @return the list of bookmarks 0072 * @since 4.3.2 0073 */ 0074 static KBookmark::List fromMimeData(const QMimeData *mimeData, QDomDocument &parentDocument); 0075 }; 0076 0077 /** 0078 * Constructs a null bookmark, i.e. a bookmark for which isNull() returns true 0079 * If you want to create a new bookmark use eitehr KBookmarkGroup.addBookmark 0080 * or if you want an interactive dialog use KBookmarkDialog. 0081 */ 0082 KBookmark(); 0083 0084 /** 0085 * Creates the KBookmark wrapper for @param elem 0086 * Mostly for internal usage. 0087 */ 0088 0089 explicit KBookmark(const QDomElement &elem); 0090 0091 /** 0092 * Creates a stand alone bookmark. This is fairly expensive since a new QDom Tree is build. 0093 */ 0094 static KBookmark standaloneBookmark(const QString &text, const QUrl &url, const QString &icon); 0095 0096 /** 0097 * Whether the bookmark is a group or a normal bookmark 0098 */ 0099 bool isGroup() const; 0100 0101 /** 0102 * Whether the bookmark is a separator 0103 */ 0104 bool isSeparator() const; 0105 0106 /** 0107 * @return true if this is a null bookmark. This will never 0108 * be the case for a real bookmark (in a menu), but it's used 0109 * for instance as the end condition for KBookmarkGroup::next() 0110 */ 0111 bool isNull() const; 0112 0113 /** 0114 * @return true if bookmark is contained by a QDomDocument, 0115 * if not it is most likely that it has become separated and 0116 * is thus invalid and/or has been deleted from the bookmarks. 0117 */ 0118 bool hasParent() const; 0119 0120 /** 0121 * Text shown for the bookmark 0122 * If bigger than 40, the text is shortened by 0123 * replacing middle characters with "..." (see KStringHandler::csqueeze) 0124 */ 0125 QString text() const; 0126 /** 0127 * Text shown for the bookmark, not truncated. 0128 * You should not use this - this is mainly for keditbookmarks. 0129 */ 0130 QString fullText() const; 0131 /** 0132 * Set the text shown for the bookmark. 0133 * 0134 * @param fullText the new bookmark title 0135 */ 0136 void setFullText(const QString &fullText); 0137 /** 0138 * URL contained by the bookmark 0139 */ 0140 QUrl url() const; 0141 /** 0142 * Set the URL of the bookmark 0143 * 0144 * @param url the new bookmark URL 0145 */ 0146 void setUrl(const QUrl &url); 0147 0148 /** 0149 * @return the pixmap file for this bookmark 0150 * (i.e. the name of the icon) 0151 */ 0152 QString icon() const; 0153 0154 /** 0155 * Set the icon name of the bookmark 0156 * 0157 * @param icon the new icon name for this bookmark 0158 */ 0159 void setIcon(const QString &icon); 0160 0161 /** 0162 * @return Description of the bookmark 0163 * @since 4.4 0164 */ 0165 QString description() const; 0166 0167 /** 0168 * Set the description of the bookmark 0169 * 0170 * @param description 0171 * @since 4.4 0172 */ 0173 void setDescription(const QString &description); 0174 0175 /** 0176 * @return Mime-Type of this item 0177 * @since 4.1 0178 */ 0179 QString mimeType() const; 0180 0181 /** 0182 * Set the Mime-Type of this item 0183 * 0184 * @param Mime-Type 0185 * @since 4.1 0186 */ 0187 void setMimeType(const QString &mimeType); 0188 0189 /** 0190 * @return if the bookmark should be shown in the toolbar 0191 * (used by the filtered toolbar) 0192 * 0193 */ 0194 bool showInToolbar() const; 0195 0196 /** 0197 * Set whether this bookmark is show in a filterd toolbar 0198 */ 0199 void setShowInToolbar(bool show); 0200 0201 /** 0202 * @return the group containing this bookmark 0203 */ 0204 KBookmarkGroup parentGroup() const; 0205 0206 /** 0207 * Convert this to a group - do this only if 0208 * isGroup() returns true. 0209 */ 0210 KBookmarkGroup toGroup() const; 0211 0212 /** 0213 * Return the "address" of this bookmark in the whole tree. 0214 * This is used when telling other processes about a change 0215 * in a given bookmark. The encoding of the address is "/4/2", for 0216 * instance, to designate the 2nd child inside the 4th child of the 0217 * root bookmark. 0218 */ 0219 QString address() const; 0220 0221 /** 0222 * Return the position in the parent, i.e. the last number in the address 0223 */ 0224 int positionInParent() const; 0225 0226 /** 0227 * @internal for KEditBookmarks 0228 */ 0229 QDomElement internalElement() const; 0230 0231 /** 0232 * Updates the bookmarks access metadata 0233 * Call when a user accesses the bookmark 0234 */ 0235 void updateAccessMetadata(); 0236 0237 // Utility functions (internal) 0238 0239 /** 0240 * @return address of parent 0241 */ 0242 static QString parentAddress(const QString &address); 0243 0244 /** 0245 * @return position in parent (e.g. /4/5/2 -> 2) 0246 */ 0247 static uint positionInParent(const QString &address); 0248 0249 /** 0250 * @return address of previous sibling (e.g. /4/5/2 -> /4/5/1) 0251 * Returns QString() for a first child 0252 */ 0253 static QString previousAddress(const QString &address); 0254 0255 /** 0256 * @return address of next sibling (e.g. /4/5/2 -> /4/5/3) 0257 * This doesn't check whether it actually exists 0258 */ 0259 static QString nextAddress(const QString &address); 0260 0261 /** 0262 * @return the common parent of both addresses which 0263 * has the greatest depth 0264 */ 0265 static QString commonParent(const QString &A, const QString &B); 0266 0267 /** 0268 * @return the metadata container node for a certain metadata owner 0269 * @since 4.1 0270 */ 0271 QDomNode metaData(const QString &owner, bool create) const; 0272 0273 /** 0274 * Get the value of a specific metadata item (owner = "http://www.kde.org"). 0275 * @param key Name of the metadata item 0276 * @return Value of the metadata item. QString() is returned in case 0277 * the specified key does not exist. 0278 */ 0279 QString metaDataItem(const QString &key) const; 0280 0281 /** 0282 * Change the value of a specific metadata item, or create the given item 0283 * if it doesn't exist already (owner = "http://www.kde.org"). 0284 * @param key Name of the metadata item to change 0285 * @param value Value to use for the specified metadata item 0286 * @param mode Whether to overwrite the item's value if it exists already or not. 0287 */ 0288 void setMetaDataItem(const QString &key, const QString &value, MetaDataOverwriteMode mode = OverwriteMetaData); 0289 0290 /** 0291 * Adds this bookmark into the given QMimeData. 0292 * 0293 * WARNING: do not call this method multiple times, use KBookmark::List::populateMimeData instead. 0294 * 0295 * @param mimeData the QMimeData instance used to drag or copy this bookmark 0296 */ 0297 void populateMimeData(QMimeData *mimeData) const; 0298 0299 /** 0300 * Comparison operator 0301 */ 0302 bool operator==(const KBookmark &rhs) const; 0303 0304 protected: 0305 QDomElement element; 0306 // Note: you can't add new member variables here. 0307 // The KBookmarks are created on the fly, as wrappers 0308 // around internal QDomElements. Any additional information 0309 // has to be implemented as an attribute of the QDomElement. 0310 }; 0311 0312 /** 0313 * A group of bookmarks 0314 */ 0315 class KBOOKMARKS_EXPORT KBookmarkGroup : public KBookmark 0316 { 0317 public: 0318 /** 0319 * Create an invalid group. This is mostly for use in QList, 0320 * and other places where we need a null group. 0321 * Also used as a parent for a bookmark that doesn't have one 0322 * (e.g. Netscape bookmarks) 0323 */ 0324 KBookmarkGroup(); 0325 0326 /** 0327 * Create a bookmark group as specified by the given element 0328 */ 0329 KBookmarkGroup(const QDomElement &elem); 0330 0331 /** 0332 * @return true if the bookmark folder is opened in the bookmark editor 0333 */ 0334 bool isOpen() const; 0335 0336 /** 0337 * Return the first child bookmark of this group 0338 */ 0339 KBookmark first() const; 0340 /** 0341 * Return the previous sibling of a child bookmark of this group 0342 * @param current has to be one of our child bookmarks. 0343 */ 0344 KBookmark previous(const KBookmark ¤t) const; 0345 /** 0346 * Return the next sibling of a child bookmark of this group 0347 * @param current has to be one of our child bookmarks. 0348 */ 0349 KBookmark next(const KBookmark ¤t) const; 0350 0351 /** 0352 * Return the index of a child bookmark, -1 if not found 0353 */ 0354 int indexOf(const KBookmark &child) const; 0355 0356 /** 0357 * Create a new bookmark folder, as the last child of this group 0358 * @param text for the folder. 0359 * If you want an dialog use KBookmarkDialog 0360 */ 0361 KBookmarkGroup createNewFolder(const QString &text); 0362 /** 0363 * Create a new bookmark separator 0364 * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark ); 0365 */ 0366 KBookmark createNewSeparator(); 0367 0368 /** 0369 * Create a new bookmark, as the last child of this group 0370 * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark ); 0371 * @param bm the bookmark to add 0372 */ 0373 KBookmark addBookmark(const KBookmark &bm); 0374 0375 /** 0376 * Create a new bookmark, as the last child of this group 0377 * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark ); 0378 * @param text for the bookmark 0379 * @param url the URL that the bookmark points to. 0380 * It will be stored in its QUrl::FullyEncoded string format. 0381 * @param icon the name of the icon to associate with the bookmark. A suitable default 0382 * will be determined from the URL if not specified. 0383 */ 0384 KBookmark addBookmark(const QString &text, const QUrl &url, const QString &icon); 0385 0386 /** 0387 * Moves @p bookmark after @p after (which should be a child of ours). 0388 * If after is null, @p bookmark is moved as the first child. 0389 * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark ); 0390 */ 0391 bool moveBookmark(const KBookmark &bookmark, const KBookmark &after); 0392 0393 /** 0394 * Delete a bookmark - it has to be one of our children ! 0395 * Don't forget to use KBookmarkManager::self()->emitChanged( parentBookmark ); 0396 */ 0397 void deleteBookmark(const KBookmark &bk); 0398 0399 /** 0400 * @return true if this is the toolbar group 0401 */ 0402 bool isToolbarGroup() const; 0403 /** 0404 * @internal 0405 */ 0406 QDomElement findToolbar() const; 0407 0408 /** 0409 * @return the list of urls of bookmarks at top level of the group 0410 */ 0411 QList<QUrl> groupUrlList() const; 0412 0413 protected: 0414 QDomElement nextKnownTag(const QDomElement &start, bool goNext) const; 0415 0416 private: 0417 // Note: you can't add other member variables here, except for caching info. 0418 // The KBookmarks are created on the fly, as wrappers 0419 // around internal QDomElements. Any additional information 0420 // has to be implemented as an attribute of the QDomElement. 0421 }; 0422 0423 /** 0424 * A class to traverse bookarm groups 0425 */ 0426 class KBOOKMARKS_EXPORT KBookmarkGroupTraverser 0427 { 0428 protected: 0429 virtual ~KBookmarkGroupTraverser(); 0430 void traverse(const KBookmarkGroup &); 0431 virtual void visit(const KBookmark &); 0432 virtual void visitEnter(const KBookmarkGroup &); 0433 virtual void visitLeave(const KBookmarkGroup &); 0434 }; 0435 0436 #define KIO_KBOOKMARK_METATYPE_DEFINED 1 0437 Q_DECLARE_METATYPE(KBookmark) 0438 0439 #endif