File indexing completed on 2024-03-24 15:25:02

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