1 | /* |
2 | This file is part of the KDE libraries |
3 | SPDX-FileCopyrightText: 1999 Reginald Stadlbauer <reggie@kde.org> |
4 | SPDX-FileCopyrightText: 1999 Simon Hausmann <hausmann@kde.org> |
5 | SPDX-FileCopyrightText: 2000 Nicolas Hadacek <haadcek@kde.org> |
6 | SPDX-FileCopyrightText: 2000 Kurt Granroth <granroth@kde.org> |
7 | SPDX-FileCopyrightText: 2000 Michael Koch <koch@kde.org> |
8 | SPDX-FileCopyrightText: 2001 Holger Freyther <freyther@kde.org> |
9 | SPDX-FileCopyrightText: 2002 Ellis Whitehead <ellis@kde.org> |
10 | SPDX-FileCopyrightText: 2003 Andras Mantia <amantia@kde.org> |
11 | SPDX-FileCopyrightText: 2005-2006 Hamish Rodda <rodda@kde.org> |
12 | |
13 | SPDX-License-Identifier: LGPL-2.0-only |
14 | */ |
15 | |
16 | #ifndef KRECENTFILESACTION_H |
17 | #define KRECENTFILESACTION_H |
18 | |
19 | #include <KSelectAction> |
20 | #include <QUrl> |
21 | #include <kconfigwidgets_export.h> |
22 | |
23 | #include <QMimeType> |
24 | |
25 | class KConfigGroup; |
26 | class KRecentFilesActionPrivate; |
27 | |
28 | /*! |
29 | * \class KRecentFilesAction |
30 | * \inmodule KConfigWidgets |
31 | * |
32 | * \brief Recent files action. |
33 | * |
34 | * This class is an action to handle a recent files submenu. |
35 | * The best way to create the action is to use KStandardAction::openRecent. |
36 | * Then you simply need to call loadEntries on startup, saveEntries |
37 | * on shutdown, addURL when your application loads/saves a file. |
38 | */ |
39 | class KCONFIGWIDGETS_EXPORT KRecentFilesAction : public KSelectAction |
40 | { |
41 | Q_OBJECT |
42 | Q_PROPERTY(int maxItems READ maxItems WRITE setMaxItems) |
43 | Q_DECLARE_PRIVATE(KRecentFilesAction) |
44 | |
45 | public: |
46 | /*! |
47 | * Constructs an action with the specified parent. |
48 | * |
49 | * \a parent The parent of this action. |
50 | */ |
51 | explicit KRecentFilesAction(QObject *parent); |
52 | |
53 | /*! |
54 | * Constructs an action with text; a shortcut may be specified by |
55 | * the ampersand character (e.g. \"&Option\" creates a shortcut with key \c O ) |
56 | * |
57 | * This is the most common KAction used when you do not have a |
58 | * corresponding icon (note that it won't appear in the current version |
59 | * of the "Edit ToolBar" dialog, because an action needs an icon to be |
60 | * plugged in a toolbar...). |
61 | * |
62 | * \a text The text that will be displayed. |
63 | * |
64 | * \a parent The parent of this action. |
65 | */ |
66 | KRecentFilesAction(const QString &text, QObject *parent); |
67 | |
68 | /*! |
69 | * Constructs an action with text and an icon; a shortcut may be specified by |
70 | * the ampersand character (e.g. \"&Option\" creates a shortcut with key \c O ) |
71 | * |
72 | * This is the other common KAction used. Use it when you |
73 | * \c do have a corresponding icon. |
74 | * |
75 | * \a icon The icon to display. |
76 | * |
77 | * \a text The text that will be displayed. |
78 | * |
79 | * \a parent The parent of this action. |
80 | */ |
81 | KRecentFilesAction(const QIcon &icon, const QString &text, QObject *parent); |
82 | |
83 | ~KRecentFilesAction() override; |
84 | |
85 | /*! |
86 | * Adds \a action to the list of URLs, with \a url and title \a name. |
87 | * |
88 | * Do not use addAction(QAction*), as no url will be associated, and |
89 | * consequently urlSelected() will not be emitted when \a action is selected. |
90 | */ |
91 | void addAction(QAction *action, const QUrl &url, const QString &name, const QMimeType &mimeType = QMimeType()); |
92 | |
93 | QAction *removeAction(QAction *action) override; |
94 | |
95 | /*! |
96 | * Returns the maximum of items in the recent files list. |
97 | */ |
98 | int maxItems() const; |
99 | |
100 | /*! |
101 | * Sets the maximum of items in the recent files list. |
102 | * The default for this value is 10 set in the constructor. |
103 | * |
104 | * If this value is lesser than the number of items currently |
105 | * in the recent files list the last items are deleted until |
106 | * the number of items are equal to the new maximum. |
107 | * |
108 | * Negative values will be normalized to 0. |
109 | */ |
110 | void setMaxItems(int maxItems); |
111 | |
112 | /*! |
113 | * Loads the recent files entries from a given KConfigGroup object. |
114 | * You can provide the name of the group used to load the entries. |
115 | * If the groupname is empty, entries are loaded from a group called 'RecentFiles'. |
116 | * Local file entries that do not exist anymore are not restored. |
117 | * |
118 | */ |
119 | void loadEntries(const KConfigGroup &config); |
120 | |
121 | /*! |
122 | * Saves the current recent files entries to a given KConfigGroup object. |
123 | * You can provide the name of the group used to load the entries. |
124 | * If the groupname is empty, entries are saved to a group called 'RecentFiles'. |
125 | * |
126 | */ |
127 | void saveEntries(const KConfigGroup &config); |
128 | |
129 | /*! |
130 | * Add URL to the recent files list. This will enable this action. |
131 | * |
132 | * \a url The URL of the file |
133 | * |
134 | * \a name The user visible pretty name that appears before the URL |
135 | * |
136 | * \note URLs corresponding to local files in the temporary directory |
137 | * (see QDir::tempPath()) are automatically ignored by this method. |
138 | */ |
139 | void addUrl(const QUrl &url, const QString &name = QString()); |
140 | |
141 | /*! |
142 | * Add URL to the recent files list. This will enable this action. |
143 | * |
144 | * \a url The URL of the file |
145 | * |
146 | * \a name The user visible pretty name that appears before the URL |
147 | * |
148 | * \a mimeType Specify the mimeType of the file |
149 | * |
150 | * \note URLs corresponding to local files in the temporary directory |
151 | * (see QDir::tempPath()) are automatically ignored by this method. |
152 | * |
153 | * \since 6.9 |
154 | */ |
155 | void addUrl(const QUrl &url, const QString &name, const QString &mimeType); |
156 | |
157 | /*! |
158 | * Remove an URL from the recent files list. |
159 | * |
160 | * \a url The URL of the file |
161 | */ |
162 | void removeUrl(const QUrl &url); |
163 | |
164 | /*! |
165 | * Retrieve a list of all URLs in the recent files list. |
166 | */ |
167 | QList<QUrl> urls() const; |
168 | |
169 | public Q_SLOTS: |
170 | /*! |
171 | * Clears the recent files list. |
172 | * Note that there is also an action shown to the user for clearing the list. |
173 | */ |
174 | virtual void clear(); |
175 | |
176 | Q_SIGNALS: |
177 | /*! |
178 | * This signal gets emitted when the user selects an URL. |
179 | * |
180 | * \a url The URL that the user selected. |
181 | */ |
182 | void urlSelected(const QUrl &url); |
183 | |
184 | /*! |
185 | * This signal gets emitted when the user clear list. |
186 | * So when user store url in specific config file it can saveEntry. |
187 | * \since 4.3 |
188 | */ |
189 | void recentListCleared(); |
190 | |
191 | private: |
192 | // Internal |
193 | KCONFIGWIDGETS_NO_EXPORT void clearEntries(); |
194 | // Don't warn about the virtual overload. As the comment of the other |
195 | // addAction() says, addAction( QAction* ) should not be used. |
196 | using KSelectAction::addAction; |
197 | |
198 | private: |
199 | std::unique_ptr<KRecentFilesActionPrivate> const d_ptr; |
200 | }; |
201 | |
202 | #endif |
203 | |