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
25class KConfigGroup;
26class 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 */
39class KCONFIGWIDGETS_EXPORT KRecentFilesAction : public KSelectAction
40{
41 Q_OBJECT
42 Q_PROPERTY(int maxItems READ maxItems WRITE setMaxItems)
43 Q_DECLARE_PRIVATE(KRecentFilesAction)
44
45public:
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
169public 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
176Q_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
191private:
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
198private:
199 std::unique_ptr<KRecentFilesActionPrivate> const d_ptr;
200};
201
202#endif
203

source code of kconfigwidgets/src/krecentfilesaction.h