KBookmarks

kbookmarkmenu.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 1998, 1999 Torben Weis <[email protected]>
4  SPDX-FileCopyrightText: 2006 Daniel Teske <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef __kbookmarkmenu_h__
10 #define __kbookmarkmenu_h__
11 
12 #include <kbookmarks_export.h>
13 
14 #include <QObject>
15 #include <memory>
16 
17 class QAction;
18 class QMenu;
19 class KBookmark;
20 class KActionCollection;
21 class KBookmarkManager;
22 class KBookmarkOwner;
23 class KBookmarkMenu;
24 
25 class KBookmarkMenuPrivate;
26 
27 /**
28  * @class KBookmarkMenu kbookmarkmenu.h KBookmarkMenu
29  *
30  * This class provides a bookmark menu. It is typically used in
31  * cooperation with KActionMenu but doesn't have to be.
32  *
33  * If you use this class by itself, then it will use KDE defaults for
34  * everything -- the bookmark path, bookmark editor, bookmark launcher..
35  * everything. These defaults reside in the classes
36  * KBookmarkOwner (editing bookmarks) and KBookmarkManager
37  * (almost everything else). If you wish to change the defaults in
38  * any way, you must reimplement either this class or KBookmarkOwner.
39  *
40  * Using this class is very simple:
41  *
42  * 1) Create a popup menu (either KActionMenu or QMenu will do)
43  * 2) Instantiate a new KBookmarkMenu object using the above popup
44  * menu as a parameter
45  * 3) Insert your (now full) popup menu wherever you wish
46  *
47  * The functionality of this class can be disabled with the "action/bookmarks"
48  * Kiosk action (see the KAuthorized namespace).
49  */
50 class KBOOKMARKS_EXPORT KBookmarkMenu : public QObject
51 {
52  Q_OBJECT
53 public:
54 #if KBOOKMARKS_ENABLE_DEPRECATED_SINCE(5, 69)
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  * @param mgr The bookmark manager to use (i.e. for reading and writing)
61  * @param owner implementation of the KBookmarkOwner callback interface.
62  * Note: If you pass a null KBookmarkOwner to the constructor, the
63  * openBookmark signal is not emitted, instead QDesktopServices::openUrl is used to open the bookmark.
64  * @param parentMenu menu to be filled
65  * @param collec parent collection for the KActions.
66  *
67  * @todo KDE 5: give ownership of the bookmarkmenu to another qobject, e.g. parentMenu.
68  * Currently this is a QObject without a parent, use setParent to benefit from automatic deletion.
69  *
70  * @deprecated since 5.69. Use overload without KActionCollection and add actions manually to your actioncollection if desired.
71  * @code
72  * KBookmarkMenu *menu = new KBookmarkMenu(manager, owner, parentMenu);
73  *
74  * QAction *addAction = menu->addBookmarkAction();
75  * actionCollection()->addAction(addAction->objectName(), addAction);
76  *
77  * QAction *bookmarkTabsAction = menu->bookmarkTabsAsFolderAction();
78  * actionCollection()->addAction(bookmarkTabsAction->objectName(), bookmarkTabsAction);
79  *
80  * QAction *editAction = menu->editBookmarksAction();
81  * actionCollection()->addAction(editAction->objectName(), editAction);
82  * @endcode
83  *
84  * Alternatively you can get a list of the actions from @p parentMenu, and add them to your
85  * actionCollection:
86  * @code
87  * KBookmarkMenu *menu = new KBookmarkMenu(manager, owner, parentMenu);
88  * actionCollection()->addActions(parentMenu->actions());
89  * @endcode
90  *
91  * Note that adding the actions to your KActionCollection will make them show up in the shortcuts editor
92  * dialog.
93  *
94  */
95  KBOOKMARKS_DEPRECATED_VERSION(5, 69, "Use overload without KActionCollection and add actions manually to your actionCollection if desired")
96  KBookmarkMenu(KBookmarkManager *mgr, KBookmarkOwner *owner, QMenu *parentMenu, KActionCollection *collec);
97 #endif
98 
99  /**
100  * Fills a bookmark menu
101  * (one instance of KBookmarkMenu is created for the toplevel menu,
102  * but also one per submenu).
103  *
104  * @param manager the bookmark manager to use (i.e. for reading and writing)
105  * @param owner implementation of the KBookmarkOwner callback interface.
106  * @note If you pass a null KBookmarkOwner to the constructor, the
107  * openBookmark signal is not emitted, instead QDesktopServices::openUrl is used to open the bookmark.
108  * @param parentMenu menu to be filled
109  * @since 5.69
110  */
111  KBookmarkMenu(KBookmarkManager *manager, KBookmarkOwner *owner, QMenu *parentMenu);
112 
113  /**
114  * Creates a bookmark submenu
115  *
116  * @todo KF6: give ownership of the bookmarkmenu to another qobject, e.g. parentMenu.
117  * Currently this is a QObject without a parent, use setParent to benefit from automatic deletion.
118  */
119  KBookmarkMenu(KBookmarkManager *mgr, KBookmarkOwner *owner, QMenu *parentMenu, const QString &parentAddress);
120 
121  ~KBookmarkMenu() override;
122 
123  /**
124  * Call ensureUpToDate() if you need KBookmarkMenu to adjust to its
125  * final size before it is executed.
126  **/
127  void ensureUpToDate();
128 
129  /**
130  * @brief Sets the number of currently open tabs
131  * @param numberOfOpenTabs The number of currently open tabs
132  * @see numberOfOpenTabs()
133  * @since 5.58
134  */
135  void setNumberOfOpenTabs(int numberOfOpenTabs);
136  /**
137  * This function returns how many (if any) tabs the application has open.
138  * This is used to determine if the Add a folder for all open
139  * tabs should be added to the menu, so if the application has more than
140  * one tab open, then the menu will be added.
141  * Default returns @c 2.
142  * @since 5.58
143  */
144  int numberOfOpenTabs() const;
145 
146  /**
147  * Returns the action for adding a bookmark. If you are using KXmlGui, you can add it to your
148  * action collection.
149  * @code
150  * KBookmarkMenu *menu = new KBookmarkMenu(manager, owner, parentMenu);
151  * QAction *addAction = menu->addBookmarkAction();
152  * actionCollection()->addAction(addAction->objectName(), addAction);
153  * @endcode
154  * @return the action for adding a bookmark.
155  * @since 5.69
156  */
157  QAction *addBookmarkAction() const;
158 
159  /**
160  * Returns the action for adding all current tabs as bookmarks. If you are using KXmlGui, you can
161  * add it to your action collection.
162  * @code
163  * KBookmarkMenu *menu = new KBookmarkMenu(manager, owner, parentMenu);
164  * QAction *bookmarkTabsAction = menu->bookmarkTabsAsFolderAction();
165  * actionCollection()->addAction(bookmarkTabsAction->objectName(), bookmarkTabsAction);
166  * @endcode
167  * @return the action for adding all current tabs as bookmarks.
168  * @since 5.69
169  */
170  QAction *bookmarkTabsAsFolderAction() const;
171 
172  /**
173  * Returns the action for adding a new bookmarks folder. If you are using KXmlGui, you can add it
174  * to your action collection.
175  * @code
176  * KBookmarkMenu *menu = new KBookmarkMenu(manager, owner, parentMenu);
177  * QAction *newBookmarkFolderAction = menu->bookmarkTabsAsFolderAction();
178  * actionCollection()->addAction(newBookmarkFolderAction->objectName(), newBookmarkFolderAction);
179  * @endcode
180  * @return the action for adding a new bookmarks folder
181  * @since 5.70
182  */
183  QAction *newBookmarkFolderAction() const;
184 
185  /**
186  * Returns the action for editing bookmarks. If you are using KXmlGui, you can add it to your
187  * action collection.
188  * @code
189  * KBookmarkMenu *menu = new KBookmarkMenu(manager, owner, parentMenu);
190  * QAction *editAction = menu->editBookmarksAction();
191  * actionCollection()->addAction(editAction->objectName(), editAction);
192  * @endcode
193  * @return the action for editing bookmarks.
194  * @since 5.69
195  */
196  QAction *editBookmarksAction() const;
197 
198 public Q_SLOTS:
199  // public for KonqBookmarkBar
200  void slotBookmarksChanged(const QString &);
201 
202 protected Q_SLOTS:
203  void slotAboutToShow();
204  void slotAddBookmarksList();
205  void slotAddBookmark();
206  void slotNewFolder();
207  void slotOpenFolderInTabs();
208 
209 protected:
210  virtual void clear();
211  virtual void refill();
212  virtual QAction *actionForBookmark(const KBookmark &bm);
213  virtual QMenu *contextMenu(QAction *action);
214 
215  void addActions();
216  void fillBookmarks();
217  void addAddBookmark();
218  void addAddBookmarksList();
219  void addEditBookmarks();
220  void addNewFolder();
221  void addOpenInTabs();
222 
223  bool isRoot() const;
224  bool isDirty() const;
225 
226  /**
227  * Parent bookmark for this menu.
228  */
229  QString parentAddress() const;
230 
231  KBookmarkManager *manager() const;
232  KBookmarkOwner *owner() const;
233  /**
234  * The menu in which we insert our actions
235  * Supplied in the constructor.
236  */
237  QMenu *parentMenu() const;
238 
239  /**
240  * List of our sub menus
241  */
243 
244  // This is used to "export" our actions into an actionlist
245  // we got in the constructor. So that the program can show our
246  // actions in their shortcut dialog
247  KActionCollection *m_actionCollection;
248  /**
249  * List of our actions.
250  */
252 
253 private Q_SLOTS:
254  KBOOKMARKS_NO_EXPORT void slotCustomContextMenu(const QPoint &);
255 
256 private:
257  KBOOKMARKS_NO_EXPORT void init();
258 
259 private:
260  std::unique_ptr<KBookmarkMenuPrivate> const d;
261 
262  // TODO KF6:: move into KBookmarkMenuPrivate
263  bool m_bIsRoot;
264  bool m_bDirty;
265  KBookmarkManager *m_pManager;
266  KBookmarkOwner *m_pOwner;
267  QMenu *m_parentMenu;
268  QString m_parentAddress;
269 };
270 
271 #endif
Q_SLOTSQ_SLOTS
QCA_EXPORT void init()
QList< KBookmarkMenu * > m_lstSubMenus
List of our sub menus.
QList< QAction * > m_actions
List of our actions.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Dec 5 2023 04:00:22 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.