1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 1998, 1999 Torben Weis <weis@kde.org>
4 SPDX-FileCopyrightText: 2006 Daniel Teske <teske@squorn.de>
5
6 SPDX-License-Identifier: LGPL-2.0-or-later
7*/
8
9#ifndef __kbookmarkmenu_h__
10#define __kbookmarkmenu_h__
11
12#include <kbookmarkswidgets_export.h>
13
14#include <QObject>
15#include <memory>
16
17class QAction;
18class QMenu;
19class KBookmark;
20class KBookmarkManager;
21class KBookmarkOwner;
22class KBookmarkMenu;
23
24class KBookmarkMenuPrivate;
25
26/*!
27 * \class KBookmarkMenu
28 * \inmodule KBookmarksWidgets
29 *
30 * \brief This class provides a bookmark menu.
31 *
32 * It is typically used in cooperation with KActionMenu but doesn't have to be.
33 *
34 * If you use this class by itself, then it will use KDE defaults for
35 * everything -- the bookmark path, bookmark editor, bookmark launcher..
36 * everything. These defaults reside in the classes
37 * KBookmarkOwner (editing bookmarks) and KBookmarkManager
38 * (almost everything else). If you wish to change the defaults in
39 * any way, you must reimplement either this class or KBookmarkOwner.
40 *
41 * Using this class is very simple:
42 *
43 * 1) Create a popup menu (either KActionMenu or QMenu will do)
44 * 2) Instantiate a new KBookmarkMenu object using the above popup
45 * menu as a parameter
46 * 3) Insert your (now full) popup menu wherever you wish
47 *
48 * The functionality of this class can be disabled with the "action/bookmarks"
49 * Kiosk action (see the KAuthorized namespace).
50 */
51class KBOOKMARKSWIDGETS_EXPORT KBookmarkMenu : public QObject
52{
53 Q_OBJECT
54public:
55 /*!
56 * Fills a bookmark menu
57 * (one instance of KBookmarkMenu is created for the toplevel menu,
58 * but also one per submenu).
59 *
60 * \a manager the bookmark manager to use (i.e. for reading and writing)
61 *
62 * \a owner implementation of the KBookmarkOwner callback interface.
63 * \note If you pass a null KBookmarkOwner to the constructor, the
64 * openBookmark signal is not emitted, instead QDesktopServices::openUrl is used to open the bookmark.
65 *
66 * \a parentMenu menu to be filled
67 *
68 * \since 5.69
69 */
70 KBookmarkMenu(KBookmarkManager *manager, KBookmarkOwner *owner, QMenu *parentMenu);
71
72 // TODO KF6: give ownership of the bookmarkmenu to another qobject, e.g. parentMenu.
73 /*!
74 * Creates a bookmark submenu
75 *
76 * Currently this is a QObject without a parent, use setParent to benefit from automatic deletion.
77 */
78 KBookmarkMenu(KBookmarkManager *mgr, KBookmarkOwner *owner, QMenu *parentMenu, const QString &parentAddress);
79
80 ~KBookmarkMenu() override;
81
82 /*!
83 * Call ensureUpToDate() if you need KBookmarkMenu to adjust to its
84 * final size before it is executed.
85 */
86 void ensureUpToDate();
87
88 /*!
89 * Returns the action for adding a bookmark. If you are using KXmlGui, you can add it to your
90 * action collection.
91 * \code
92 * KBookmarkMenu *menu = new KBookmarkMenu(manager, owner, parentMenu);
93 * QAction *addAction = menu->addBookmarkAction();
94 * actionCollection()->addAction(addAction->objectName(), addAction);
95 * \endcode
96 * Returns the action for adding a bookmark.
97 * \since 5.69
98 */
99 QAction *addBookmarkAction() const;
100
101 /*!
102 * Returns the action for adding all current tabs as bookmarks. If you are using KXmlGui, you can
103 * add it to your action collection.
104 * \code
105 * KBookmarkMenu *menu = new KBookmarkMenu(manager, owner, parentMenu);
106 * QAction *bookmarkTabsAction = menu->bookmarkTabsAsFolderAction();
107 * actionCollection()->addAction(bookmarkTabsAction->objectName(), bookmarkTabsAction);
108 * \endcode
109 * Returns the action for adding all current tabs as bookmarks.
110 * \since 5.69
111 */
112 QAction *bookmarkTabsAsFolderAction() const;
113
114 /*!
115 * Returns the action for adding a new bookmarks folder. If you are using KXmlGui, you can add it
116 * to your action collection.
117 * \code
118 * KBookmarkMenu *menu = new KBookmarkMenu(manager, owner, parentMenu);
119 * QAction *newBookmarkFolderAction = menu->bookmarkTabsAsFolderAction();
120 * actionCollection()->addAction(newBookmarkFolderAction->objectName(), newBookmarkFolderAction);
121 * \endcode
122 * Returns the action for adding a new bookmarks folder
123 * \since 5.70
124 */
125 QAction *newBookmarkFolderAction() const;
126
127 /*!
128 * Returns the action for editing bookmarks. If you are using KXmlGui, you can add it to your
129 * action collection.
130 * \code
131 * KBookmarkMenu *menu = new KBookmarkMenu(manager, owner, parentMenu);
132 * QAction *editAction = menu->editBookmarksAction();
133 * actionCollection()->addAction(editAction->objectName(), editAction);
134 * \endcode
135 * Returns the action for editing bookmarks.
136 * \since 5.69
137 */
138 QAction *editBookmarksAction() const;
139
140 /*!
141 * Set this to true to make any "Edit Bookmarks" dialog
142 * show UI elements that are specific to browsers.
143 *
144 * \since 6.0
145 */
146 void setBrowserMode(bool browserMode);
147
148 /*!
149 * Whether any "Edit Bookmarks" dialog shows UI elements
150 * that are specific to browsers.
151 *
152 * \since 6.0
153 */
154 bool browserMode() const;
155
156public Q_SLOTS:
157 // public for KonqBookmarkBar
158 void slotBookmarksChanged(const QString &);
159
160protected Q_SLOTS:
161 /*
162 */
163 void slotAboutToShow();
164
165 /*
166 */
167 void slotAddBookmarksList();
168
169 /*
170 */
171 void slotAddBookmark();
172
173 /*
174 */
175 void slotNewFolder();
176
177 /*
178 */
179 void slotOpenFolderInTabs();
180
181protected:
182 /*
183 */
184 virtual void clear();
185
186 /*
187 */
188 virtual void refill();
189
190 /*
191 */
192 virtual QAction *actionForBookmark(const KBookmark &bm);
193
194 /*
195 */
196 virtual QMenu *contextMenu(QAction *action);
197
198 /*
199 */
200 void addActions();
201
202 /*
203 */
204 void fillBookmarks();
205
206 /*
207 */
208 void addAddBookmark();
209
210 /*
211 */
212 void addAddBookmarksList();
213
214 /*
215 */
216 void addEditBookmarks();
217
218 /*
219 */
220 void addNewFolder();
221
222 /*
223 */
224 void addOpenInTabs();
225
226 /*
227 */
228 bool isRoot() const;
229
230 /*
231 */
232 bool isDirty() const;
233
234 /*!
235 * Parent bookmark for this menu.
236 */
237 QString parentAddress() const;
238
239 /*!
240 */
241 KBookmarkManager *manager() const;
242
243 /*!
244 *
245 */
246 KBookmarkOwner *owner() const;
247
248 /*!
249 * The menu in which we insert our actions
250 * Supplied in the constructor.
251 */
252 QMenu *parentMenu() const;
253
254 /*
255 * List of our sub menus
256 */
257 QList<KBookmarkMenu *> m_lstSubMenus;
258
259 /*
260 * List of our actions.
261 */
262 QList<QAction *> m_actions;
263
264private Q_SLOTS:
265 KBOOKMARKSWIDGETS_NO_EXPORT void slotCustomContextMenu(const QPoint &);
266
267private:
268 void slotEditBookmarks();
269 KBOOKMARKSWIDGETS_NO_EXPORT void init();
270
271private:
272 std::unique_ptr<KBookmarkMenuPrivate> const d;
273};
274
275#endif
276

source code of kbookmarks/src/widgets/kbookmarkmenu.h