Okular

bookmarkmanager.h
1 /*
2  SPDX-FileCopyrightText: 2006 Pino Toscano <[email protected]>
3 
4  SPDX-License-Identifier: GPL-2.0-or-later
5 */
6 
7 #ifndef _OKULAR_BOOKMARK_MANAGER_H_
8 #define _OKULAR_BOOKMARK_MANAGER_H_
9 
10 #include <KBookmark>
11 
12 #include "okularcore_export.h"
13 #include <QObject>
14 #include <QUrl>
15 
16 class QAction;
17 
18 namespace Okular
19 {
20 class Document;
21 class DocumentPrivate;
22 class DocumentViewport;
23 
24 /**
25  * @brief Bookmarks manager utility.
26  *
27  * This class is responsible for loading and saving the bookmarks using the
28  * proper format, and for working with them (eg querying, adding, removing).
29  */
30 class OKULARCORE_EXPORT BookmarkManager : public QObject
31 {
32  Q_OBJECT
33 
34 public:
35  ~BookmarkManager() override;
36 
37  /**
38  * Returns the list of documents with bookmarks.
39  */
40  QList<QUrl> files() const;
41 
42  /**
43  * Returns the list of bookmarks for the specified @p documentUrl.
44  */
45  KBookmark::List bookmarks(const QUrl &documentUrl) const;
46 
47  /**
48  * Returns the list of bookmarks for document
49  * @since 0.14 (KDE 4.8)
50  */
51  KBookmark::List bookmarks() const;
52 
53  /**
54  * Returns the list of bookmarks for the given page of the document
55  * @since 0.15 (KDE 4.9)
56  */
57  KBookmark::List bookmarks(int page) const;
58 
59  /**
60  * Returns the bookmark for the given page of the document
61  * @since 0.14 (KDE 4.8)
62  */
63  KBookmark bookmark(int page) const;
64 
65  /**
66  * Returns the bookmark for the given @p viewport of the document
67  * @since 0.15 (KDE 4.9)
68  */
69  KBookmark bookmark(const DocumentViewport &viewport) const;
70 
71  /**
72  * Forces to save the list of bookmarks.
73  */
74  void save() const;
75 
76  /**
77  * Adds a bookmark for the given @p page.
78  */
79  void addBookmark(int page);
80 
81  /**
82  * Adds a bookmark for the given viewport @p vp
83  * @since 0.15 (KDE 4.9)
84  */
85  void addBookmark(const DocumentViewport &vp);
86 
87  /**
88  * Adds a new bookmark for the @p documentUrl at the specified viewport @p vp,
89  * with an optional @p title.
90  *
91  * If no @p title is specified, then \em \#n will be used.
92  */
93  bool addBookmark(const QUrl &documentUrl, const Okular::DocumentViewport &vp, const QString &title = QString());
94 
95  /**
96  * Remove a bookmark for the given @p page.
97  */
98  void removeBookmark(int page);
99 
100  /**
101  * Remove a bookmark for the given viewport @p vp
102  * @since 0.15 (KDE 4.9)
103  */
104  void removeBookmark(const DocumentViewport &vp);
105 
106  /**
107  * Removes the bookmark @p bm for the @p documentUrl specified.
108  */
109  int removeBookmark(const QUrl &documentUrl, const KBookmark &bm);
110 
111  /**
112  * Removes the bookmarks in @p list for the @p documentUrl specified.
113  *
114  * @note it will remove only the bookmarks which belong to @p documentUrl
115  *
116  * @since 0.11 (KDE 4.5)
117  */
118  void removeBookmarks(const QUrl &documentUrl, const KBookmark::List &list);
119 
120  /**
121  * Returns the bookmark given bookmark of the document
122  * @since 0.14 (KDE 4.8)
123  */
124  void renameBookmark(KBookmark *bm, const QString &newName);
125 
126  /**
127  * Renames the top-level bookmark for the @p documentUrl specified with
128  * the @p newName specified.
129  * @since 0.15 (KDE 4.9)
130  */
131  void renameBookmark(const QUrl &documentUrl, const QString &newName);
132 
133  /**
134  * Returns title for the @p documentUrl
135  * @since 0.15 (KDE 4.9)
136  */
137  QString titleForUrl(const QUrl &documentUrl) const;
138 
139  /**
140  * Returns whether the given @p page is bookmarked.
141  */
142  bool isBookmarked(int page) const;
143 
144  /**
145  * Return whether the given @p viewport is bookmarked.
146  * @since 0.15 (KDE 4.9)
147  */
148  bool isBookmarked(const DocumentViewport &viewport) const;
149 
150  /**
151  * Given a @p viewport, returns the next bookmark
152  * @since 0.15 (KDE 4.9)
153  */
154  KBookmark nextBookmark(const DocumentViewport &viewport) const;
155 
156  /**
157  * Given a @p viewport, returns the previous bookmark
158  * @since 0.15 (KDE 4.9)
159  */
160  KBookmark previousBookmark(const DocumentViewport &viewport) const;
161 
162  /**
163  * Returns a list of actions for the bookmarks of the specified @p url.
164  *
165  * @note the actions will have no parents, so you have to delete them
166  * yourself
167  */
168  QList<QAction *> actionsForUrl(const QUrl &documentUrl) const;
169 
170 Q_SIGNALS:
171  /**
172  * The bookmark manager is requesting to open the specified @p url.
173  */
174  void openUrl(const QUrl &url);
175 
176  /**
177  * This signal is emitted whenever bookmarks have been saved.
178  */
179  void saved();
180 
181  /**
182  * The bookmarks for specified @p url were changed.
183  *
184  * @since 0.7 (KDE 4.1)
185  */
186  void bookmarksChanged(const QUrl &url);
187 
188 private:
189  class Private;
190  Private *const d;
191  friend class Private;
192 
193  // private interface used by the Document
194  friend class Document;
195  friend class DocumentPrivate;
196 
197  explicit BookmarkManager(DocumentPrivate *document);
198 
199  void setUrl(const QUrl &url);
200  bool setPageBookmark(int page);
201  bool removePageBookmark(int page);
202 
203  Q_DISABLE_COPY(BookmarkManager)
204 };
205 
206 }
207 
208 #endif
The Document.
Definition: document.h:191
The documentation to the global Okular namespace.
Definition: action.h:16
Bookmarks manager utility.
A view on the document.
Definition: document.h:1349
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Sun Oct 1 2023 03:54:17 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.