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

source code of kbookmarks/src/kbookmarkowner.h