1 | /* -*- c++ -*- |
2 | SPDX-FileCopyrightText: 2000 Daniel M. Duley <mosfet@kde.org> |
3 | SPDX-FileCopyrightText: 2022 Méven Car <meven.car@kdemail.net> |
4 | |
5 | SPDX-License-Identifier: BSD-2-Clause |
6 | */ |
7 | |
8 | #ifndef __KRECENTDOCUMENT_H |
9 | #define __KRECENTDOCUMENT_H |
10 | |
11 | #include "kiocore_export.h" |
12 | |
13 | #include <QDateTime> |
14 | #include <QString> |
15 | #include <QUrl> |
16 | |
17 | /*! |
18 | * \class KRecentDocument |
19 | * \inmodule KIOCore |
20 | * |
21 | * \brief Manage the "Recent Document Menu" entries displayed by |
22 | * applications such as Kicker and Konqueror. |
23 | * |
24 | * These entries are automatically generated .desktop files pointing |
25 | * to the current application and document. You should call the |
26 | * static add() method whenever the user opens or saves a new |
27 | * document if you want it to show up in the menu. |
28 | * |
29 | * It also stores history following xdg specification. |
30 | * Ref: https://www.freedesktop.org/wiki/Specifications/desktop-bookmark-spec |
31 | * This allows cross-framework file history sharing. |
32 | * I.e Gtk Apps can access files recently opened by KDE Apps. |
33 | * |
34 | * You don't have to worry about this if you are using |
35 | * QFileDialog to open and save documents, as the KDE implementation |
36 | * (KFileWidget) already calls this class. User defined limits on the maximum |
37 | * number of documents to save, etc... are all automatically handled. |
38 | */ |
39 | class KIOCORE_EXPORT KRecentDocument |
40 | { |
41 | public: |
42 | /*! |
43 | * Usage group for a file to bookmark in recently-used.xbel file |
44 | * |
45 | * From spec https://www.freedesktop.org/wiki/Specifications/desktop-bookmark-spec/#appendixb:registeredgroupnames |
46 | * |
47 | * \value Development A bookmark related to a development environment |
48 | * \value Office A bookmark related to an office type document or folder |
49 | * \value Database A bookmark related to a database application; Office; relates to Development |
50 | * \value Email A bookmark related to an email application relates to Office |
51 | * \value Presentation A bookmark related to a presentation application relates to Office |
52 | * \value Spreadsheet A bookmark related to a spreadsheet application relates to Office |
53 | * \value WordProcessor A bookmark related to a word processing application relates to Office |
54 | * \value Graphics A bookmark related to a graphical application |
55 | * \value TextEditor A bookmark related to a text editor |
56 | * \value Viewer A bookmark related to any kind of file viewer |
57 | * \value Archive A bookmark related to an archive file |
58 | * \value Multimedia A bookmark related to a multimedia file or application |
59 | * \value Audio A bookmark related to an audio file or application relates to Multimedia |
60 | * \value Video A bookmark related to a video file or application relates to Multimedia |
61 | * \value Photo A bookmark related to a digital photography file or application relates to Multimedia; Graphics; Viewer |
62 | * \value Application Special bookmark for application launchers |
63 | * \since 5.93 |
64 | */ |
65 | enum RecentDocumentGroup { |
66 | Development, |
67 | Office, |
68 | Database, |
69 | Email, |
70 | Presentation, |
71 | Spreadsheet, |
72 | WordProcessor, |
73 | Graphics, |
74 | TextEditor, |
75 | Viewer, |
76 | Archive, |
77 | Multimedia, |
78 | Audio, |
79 | Video, |
80 | Photo, |
81 | Application, |
82 | }; |
83 | |
84 | // TODO qdoc? |
85 | typedef QList<KRecentDocument::RecentDocumentGroup> RecentDocumentGroups; |
86 | |
87 | /*! |
88 | * Returns a list of recent URLs. This includes all the URLs from |
89 | * recentDocuments() as well as URLs from other applications conforming to |
90 | * the XDG desktop-bookmark-spec (e. g. the GTK file dialog). |
91 | * |
92 | * \since 5.93 |
93 | */ |
94 | static QList<QUrl> recentUrls(); |
95 | |
96 | /*! |
97 | * Add a new item to the Recent Document menu. |
98 | * |
99 | * \a url The url to add. |
100 | */ |
101 | static void add(const QUrl &url); |
102 | |
103 | /*! |
104 | * \since 5.93 |
105 | */ |
106 | static void add(const QUrl &url, KRecentDocument::RecentDocumentGroups groups); |
107 | |
108 | /*! |
109 | * Add a new item to the Recent Document menu, specifying the application to open it with. |
110 | * The above add() method uses QCoreApplication::applicationName() for the app name, |
111 | * which isn't always flexible enough. |
112 | * This method is used when an application launches another one to open a document. |
113 | * |
114 | * \a url The url to add. |
115 | * |
116 | * \a desktopEntryName The desktopEntryName of the service to use for opening this document. |
117 | */ |
118 | static void add(const QUrl &url, const QString &desktopEntryName); |
119 | |
120 | /*! |
121 | * \since 5.93 |
122 | */ |
123 | static void add(const QUrl &url, const QString &desktopEntryName, KRecentDocument::RecentDocumentGroups groups); |
124 | |
125 | /*! |
126 | * |
127 | */ |
128 | static bool clearEntriesOldestEntries(int maxEntries); |
129 | |
130 | /*! |
131 | * \since 6.6 |
132 | */ |
133 | static void removeFile(const QUrl &url); |
134 | |
135 | /*! |
136 | * \since 6.6 |
137 | */ |
138 | static void removeApplication(const QString &desktopEntryName); |
139 | |
140 | /*! |
141 | * Remove bookmarks whose modification date is after \a since parameter. |
142 | * |
143 | * \since 6.6 |
144 | */ |
145 | static void removeBookmarksModifiedSince(const QDateTime &since); |
146 | |
147 | /*! |
148 | * Clear the recent document menu of all entries. |
149 | */ |
150 | static void clear(); |
151 | |
152 | /*! |
153 | * Returns the maximum amount of recent document entries allowed. |
154 | */ |
155 | static int maximumItems(); |
156 | }; |
157 | |
158 | #endif |
159 | |