1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000, 2006 David Faure <faure@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-only
6*/
7#ifndef KBOOKMARK_OWNER_H
8#define KBOOKMARK_OWNER_H
9
10#include "kbookmark.h"
11
12#include <QSharedDataPointer>
13#include <QString>
14
15class QWidget;
16
17class KBookmarkGroup;
18
19/*!
20 * \class KBookmarkOwner
21 * \inmodule KBookmarks
22 *
23 * The KBookmarkMenu and KBookmarkBar classes gives the user
24 * the ability to either edit bookmarks or add their own. In the
25 * first case, the app may want to open the bookmark in a special way.
26 * In the second case, the app must supply the name and the
27 * URL for the bookmark.
28 *
29 * This class gives the app this callback-like ability.
30 *
31 * If your app does not give the user the ability to add bookmarks and
32 * you don't mind using the default bookmark editor to edit your
33 * bookmarks, then you don't need to overload this class at all.
34 * Rather, just use something like:
35 *
36 * \code
37 * bookmarks = new KBookmarkMenu(manager, nullptr, menu);
38 * \endcode
39 *
40 * If you wish to use your own editor or allow the user to add
41 * bookmarks, you must overload this class.
42 */
43class KBOOKMARKS_EXPORT KBookmarkOwner
44{
45public:
46 /*!
47 *
48 */
49 KBookmarkOwner();
50 virtual ~KBookmarkOwner();
51
52 /*!
53 * This function is called whenever the user wants to add the
54 * current page to the bookmarks list. The title will become the
55 * "name" of the bookmark. You must overload this function if you
56 * wish to give your users the ability to add bookmarks.
57 * The default returns an empty string.
58 *
59 * Returns the title of the current page.
60 */
61 virtual QString currentTitle() const
62 {
63 return QString();
64 }
65
66 /*!
67 * This function is called whenever the user wants to add the
68 * current page to the bookmarks list. The URL will become the URL
69 * of the bookmark. You must overload this function if you wish to
70 * give your users the ability to add bookmarks.
71 * The default returns an empty string.
72 *
73 * Returns the URL of the current page.
74 *
75 * Since 5.0 this method returns a QUrl. While porting it, remember to implement currentIcon too.
76 */
77 virtual QUrl currentUrl() const
78 {
79 return QUrl();
80 }
81
82 /*!
83 * This function is called whenever the user wants to add the
84 * current page to the bookmarks list. The icon will become the icon
85 * of the bookmark. You must overload this function if you wish to
86 * give your users the ability to add bookmarks.
87 * The default returns an empty string.
88 *
89 * A very common implementation for this method is
90 * return KIO::iconNameForUrl(currentUrl());
91 *
92 * Returns the icon name of the current page.
93 *
94 * \since 5.0
95 */
96 virtual QString currentIcon() const
97 {
98 return QString();
99 }
100
101 /*!
102 * This function returns whether the owner supports tabs.
103 * The default returns \c false.
104 */
105 virtual bool supportsTabs() const
106 {
107 return false;
108 }
109
110 class FutureBookmarkPrivate;
111 /*!
112 * \class KBookmarkOwner::FutureBookmark
113 * \inmodule KBookmarks
114 *
115 * \brief Represents the data for a bookmark that will be added.
116 * \since 5.0
117 */
118 class KBOOKMARKS_EXPORT FutureBookmark
119 {
120 public:
121 /*!
122 */
123 FutureBookmark(const QString &title, const QUrl &url, const QString &icon);
124 ~FutureBookmark();
125 FutureBookmark(const FutureBookmark &other);
126 FutureBookmark &operator=(const FutureBookmark &other);
127
128 /*!
129 */
130 QString title() const;
131
132 /*!
133 */
134 QUrl url() const;
135
136 /*!
137 */
138 QString icon() const;
139
140 private:
141 QSharedDataPointer<FutureBookmarkPrivate> d;
142 };
143
144 /*!
145 * Returns a list of bookmark data for the open tabs.
146 * The default returns an empty list.
147 */
148 virtual QList<FutureBookmark> currentBookmarkList() const
149 {
150 return QList<FutureBookmark>();
151 }
152
153 /*!
154 * \value ShowAddBookmark
155 * \value ShowEditBookmark
156 */
157 enum BookmarkOption { ShowAddBookmark, ShowEditBookmark };
158
159 // TODO ContextMenuAction? to disable the contextMenu? Delete and Properties to disable those in the context menu?
160 /*! Returns true if \a action should be shown in the menu
161 * The default is to show both a add and editBookmark Entry
162 */
163 virtual bool enableOption(BookmarkOption option) const;
164
165 /*!
166 * Called if a bookmark is selected. You need to override this.
167 */
168 virtual void openBookmark(const KBookmark &bm, Qt::MouseButtons mb, Qt::KeyboardModifiers km) = 0;
169
170 /*!
171 * Called if the user wants to open every bookmark in this folder in a new tab.
172 * The default implementation does nothing.
173 * This is only called if supportsTabs() returns true
174 */
175 virtual void openFolderinTabs(const KBookmarkGroup &bm);
176
177 /*!
178 * Called when a bookmark should be opened in a new tab.
179 * The default implementation calls openBookmark.
180 * \since 5.0
181 */
182 virtual void openInNewTab(const KBookmark &bm);
183
184 /*!
185 * Called when a bookmark should be opened in a new window.
186 * The default implementation calls openBookmark.
187 * \since 5.0
188 */
189 virtual void openInNewWindow(const KBookmark &bm);
190
191private:
192 class KBookmarkOwnerPrivate;
193 KBookmarkOwnerPrivate *d;
194};
195
196#endif
197

source code of kbookmarks/src/kbookmarkowner.h