KBookmarks

kbookmarkowner.h
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:
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);
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:
123 };
124
125 /**
126 * Returns a list of bookmark data for the open tabs.
127 * The default returns an empty list.
128 */
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 */
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
A group of bookmarks.
Definition kbookmark.h:316
Represents the data for a bookmark that will be added.
The KBookmarkMenu and KBookmarkBar classes gives the user the ability to either edit bookmarks or add...
virtual QList< FutureBookmark > currentBookmarkList() const
Returns a list of bookmark data for the open tabs.
virtual QString currentIcon() const
This function is called whenever the user wants to add the current page to the bookmarks list.
virtual QString currentTitle() const
This function is called whenever the user wants to add the current page to the bookmarks list.
virtual bool supportsTabs() const
This function returns whether the owner supports tabs.
virtual void openBookmark(const KBookmark &bm, Qt::MouseButtons mb, Qt::KeyboardModifiers km)=0
Called if a bookmark is selected.
virtual QUrl currentUrl() const
This function is called whenever the user wants to add the current page to the bookmarks list.
A class representing a bookmark.
Definition kbookmark.h:27
typedef KeyboardModifiers
typedef MouseButtons
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 11 2024 12:16:34 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.