File indexing completed on 2024-07-07 14:13:42

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2000, 2006 David Faure <faure@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-only
0006 */
0007 #ifndef KBOOKMARK_OWNER_H
0008 #define KBOOKMARK_OWNER_H
0009 
0010 #include "kbookmark.h"
0011 
0012 #include <QSharedDataPointer>
0013 #include <QString>
0014 
0015 class QWidget;
0016 
0017 class KBookmarkGroup;
0018 class KBookmarkDialog;
0019 
0020 /**
0021  * @class KBookmarkOwner kbookmarkowner.h KBookmarkOwner
0022  *
0023  * The KBookmarkMenu and KBookmarkBar classes gives the user
0024  * the ability to either edit bookmarks or add their own.  In the
0025  * first case, the app may want to open the bookmark in a special way.
0026  * In the second case, the app @em must supply the name and the
0027  * URL for the bookmark.
0028  *
0029  * This class gives the app this callback-like ability.
0030  *
0031  * If your app does not give the user the ability to add bookmarks and
0032  * you don't mind using the default bookmark editor to edit your
0033  * bookmarks, then you don't need to overload this class at all.
0034  * Rather, just use something like:
0035  *
0036  * @code
0037  * bookmarks = new KBookmarkMenu(manager, nullptr, menu, actionCollection);
0038  * @endcode
0039  *
0040  * If you wish to use your own editor or allow the user to add
0041  * bookmarks, you must overload this class.
0042  */
0043 class KBOOKMARKS_EXPORT KBookmarkOwner
0044 {
0045 public:
0046     // TODO KF6: add non-inline constructor, de-inline destructor. Otherwise the d pointer cannot be used.
0047     virtual ~KBookmarkOwner()
0048     {
0049     }
0050 
0051     /**
0052      * This function is called whenever the user wants to add the
0053      * current page to the bookmarks list.  The title will become the
0054      * "name" of the bookmark.  You must overload this function if you
0055      * wish to give your users the ability to add bookmarks.
0056      * The default returns an empty string.
0057      *
0058      * @return the title of the current page.
0059      */
0060     virtual QString currentTitle() const
0061     {
0062         return QString();
0063     }
0064 
0065     /**
0066      * This function is called whenever the user wants to add the
0067      * current page to the bookmarks list.  The URL will become the URL
0068      * of the bookmark.  You must overload this function if you wish to
0069      * give your users the ability to add bookmarks.
0070      * The default returns an empty string.
0071      *
0072      * @return the URL of the current page.
0073      * Since 5.0 this method returns a QUrl. While porting it, remember to implement currentIcon too.
0074      */
0075     virtual QUrl currentUrl() const
0076     {
0077         return QUrl();
0078     }
0079 
0080     /**
0081      * This function is called whenever the user wants to add the
0082      * current page to the bookmarks list.  The icon will become the icon
0083      * of the bookmark.  You must overload this function if you wish to
0084      * give your users the ability to add bookmarks.
0085      * The default returns an empty string.
0086      *
0087      * A very common implementation for this method is
0088      * return KIO::iconNameForUrl(currentUrl());
0089      *
0090      * @return the icon name of the current page.
0091      * @since 5.0
0092      */
0093     virtual QString currentIcon() const
0094     {
0095         return QString();
0096     }
0097 
0098     /**
0099      * This function returns whether the owner supports tabs.
0100      * The default returns @c false.
0101      */
0102     virtual bool supportsTabs() const
0103     {
0104         return false;
0105     }
0106 
0107     class FutureBookmarkPrivate;
0108     /**
0109      * Represents the data for a bookmark that will be added.
0110      * @since 5.0
0111      */
0112     class KBOOKMARKS_EXPORT FutureBookmark
0113     {
0114     public:
0115         FutureBookmark(const QString &title, const QUrl &url, const QString &icon);
0116         ~FutureBookmark();
0117         FutureBookmark(const FutureBookmark &other);
0118         FutureBookmark &operator=(const FutureBookmark &other);
0119 
0120         QString title() const;
0121         QUrl url() const;
0122         QString icon() const;
0123 
0124     private:
0125         QSharedDataPointer<FutureBookmarkPrivate> d;
0126     };
0127 
0128     /**
0129      * Returns a list of bookmark data for the open tabs.
0130      * The default returns an empty list.
0131      */
0132     virtual QList<FutureBookmark> currentBookmarkList() const
0133     {
0134         return QList<FutureBookmark>();
0135     }
0136 
0137     enum BookmarkOption { ShowAddBookmark, ShowEditBookmark };
0138 
0139     /** Returns true if \p action should be shown in the menu
0140      *  The default is to show both a add and editBookmark Entry
0141      *  //TODO ContextMenuAction? to disable the contextMenu?
0142      *         Delete and Properties to disable those in the
0143      *         context menu?
0144      */
0145     virtual bool enableOption(BookmarkOption option) const;
0146 
0147     /**
0148      * Called if a bookmark is selected. You need to override this.
0149      */
0150     virtual void openBookmark(const KBookmark &bm, Qt::MouseButtons mb, Qt::KeyboardModifiers km) = 0;
0151 
0152     /**
0153      * Called if the user wants to open every bookmark in this folder in a new tab.
0154      * The default implementation does nothing.
0155      * This is only called if supportsTabs() returns true
0156      */
0157     virtual void openFolderinTabs(const KBookmarkGroup &bm);
0158 
0159     virtual KBookmarkDialog *bookmarkDialog(KBookmarkManager *mgr, QWidget *parent);
0160 
0161     /**
0162      * Called when a bookmark should be opened in a new tab.
0163      * The default implementation calls openBookmark.
0164      * @since 5.0
0165      */
0166     virtual void openInNewTab(const KBookmark &bm);
0167 
0168     /**
0169      * Called when a bookmark should be opened in a new window.
0170      * The default implementation calls openBookmark.
0171      * @since 5.0
0172      */
0173     virtual void openInNewWindow(const KBookmark &bm);
0174 
0175 private:
0176     class KBookmarkOwnerPrivate;
0177     KBookmarkOwnerPrivate *d;
0178 };
0179 
0180 #endif