File indexing completed on 2024-11-10 12:17:56
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