KBookmarks

kbookmarkowner.h
1 /*
2  This file is part of the KDE libraries
3  SPDX-FileCopyrightText: 2000, 2006 David Faure <[email protected]>
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 
15 class QWidget;
16 
17 class KBookmarkGroup;
18 class KBookmarkDialog;
19 
20 /**
21  * @class KBookmarkOwner kbookmarkowner.h KBookmarkOwner
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 @em 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, actionCollection);
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  */
43 class KBOOKMARKS_EXPORT KBookmarkOwner
44 {
45 public:
46  // TODO KF6: add non-inline constructor, de-inline destructor. Otherwise the d pointer cannot be used.
47  virtual ~KBookmarkOwner()
48  {
49  }
50 
51  /**
52  * This function is called whenever the user wants to add the
53  * current page to the bookmarks list. The title will become the
54  * "name" of the bookmark. You must overload this function if you
55  * wish to give your users the ability to add bookmarks.
56  * The default returns an empty string.
57  *
58  * @return the title of the current page.
59  */
60  virtual QString currentTitle() const
61  {
62  return QString();
63  }
64 
65  /**
66  * This function is called whenever the user wants to add the
67  * current page to the bookmarks list. The URL will become the URL
68  * of the bookmark. You must overload this function if you wish to
69  * give your users the ability to add bookmarks.
70  * The default returns an empty string.
71  *
72  * @return the URL of the current page.
73  * Since 5.0 this method returns a QUrl. While porting it, remember to implement currentIcon too.
74  */
75  virtual QUrl currentUrl() const
76  {
77  return QUrl();
78  }
79 
80  /**
81  * This function is called whenever the user wants to add the
82  * current page to the bookmarks list. The icon will become the icon
83  * of the bookmark. You must overload this function if you wish to
84  * give your users the ability to add bookmarks.
85  * The default returns an empty string.
86  *
87  * A very common implementation for this method is
88  * return KIO::iconNameForUrl(currentUrl());
89  *
90  * @return the icon name of the current page.
91  * @since 5.0
92  */
93  virtual QString currentIcon() const
94  {
95  return QString();
96  }
97 
98  /**
99  * This function returns whether the owner supports tabs.
100  * The default returns @c false.
101  */
102  virtual bool supportsTabs() const
103  {
104  return false;
105  }
106 
107  class FutureBookmarkPrivate;
108  /**
109  * Represents the data for a bookmark that will be added.
110  * @since 5.0
111  */
112  class KBOOKMARKS_EXPORT FutureBookmark
113  {
114  public:
115  FutureBookmark(const QString &title, const QUrl &url, const QString &icon);
116  ~FutureBookmark();
117  FutureBookmark(const FutureBookmark &other);
118  FutureBookmark &operator=(const FutureBookmark &other);
119 
120  QString title() const;
121  QUrl url() const;
122  QString icon() const;
123 
124  private:
126  };
127 
128  /**
129  * Returns a list of bookmark data for the open tabs.
130  * The default returns an empty list.
131  */
133  {
134  return QList<FutureBookmark>();
135  }
136 
137  enum BookmarkOption { ShowAddBookmark, ShowEditBookmark };
138 
139  /** Returns true if \p action should be shown in the menu
140  * The default is to show both a add and editBookmark Entry
141  * //TODO ContextMenuAction? to disable the contextMenu?
142  * Delete and Properties to disable those in the
143  * context menu?
144  */
145  virtual bool enableOption(BookmarkOption option) const;
146 
147  /**
148  * Called if a bookmark is selected. You need to override this.
149  */
150  virtual void openBookmark(const KBookmark &bm, Qt::MouseButtons mb, Qt::KeyboardModifiers km) = 0;
151 
152  /**
153  * Called if the user wants to open every bookmark in this folder in a new tab.
154  * The default implementation does nothing.
155  * This is only called if supportsTabs() returns true
156  */
157  virtual void openFolderinTabs(const KBookmarkGroup &bm);
158 
159  virtual KBookmarkDialog *bookmarkDialog(KBookmarkManager *mgr, QWidget *parent);
160 
161  /**
162  * Called when a bookmark should be opened in a new tab.
163  * The default implementation calls openBookmark.
164  * @since 5.0
165  */
166  virtual void openInNewTab(const KBookmark &bm);
167 
168  /**
169  * Called when a bookmark should be opened in a new window.
170  * The default implementation calls openBookmark.
171  * @since 5.0
172  */
173  virtual void openInNewWindow(const KBookmark &bm);
174 
175 private:
176  class KBookmarkOwnerPrivate;
177  KBookmarkOwnerPrivate *d;
178 };
179 
180 #endif
virtual QUrl currentUrl() 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.
typedef MouseButtons
Represents the data for a bookmark that will be added.
virtual QList< FutureBookmark > currentBookmarkList() const
Returns a list of bookmark data for the open tabs.
virtual QString currentTitle() const
This function is called whenever the user wants to add the current page to the bookmarks list.
virtual QString currentIcon() const
This function is called whenever the user wants to add the current page to the bookmarks list.
typedef KeyboardModifiers
A group of bookmarks.
Definition: kbookmark.h:322
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Sep 26 2023 03:58:02 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.