File indexing completed on 2024-02-25 03:57:43

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 &current) 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 &current) 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