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 krecentfilesaction.h KRecentFilesAction
30 *
31 * @short Recent files action
32 *
33 * This class is an action to handle a recent files submenu.
34 * The best way to create the action is to use KStandardAction::openRecent.
35 * Then you simply need to call loadEntries on startup, saveEntries
36 * on shutdown, addURL when your application loads/saves a file.
37 *
38 * @author Michael Koch
39 */
40class KCONFIGWIDGETS_EXPORT KRecentFilesAction : public KSelectAction
41{
42 Q_OBJECT
43 Q_PROPERTY(int maxItems READ maxItems WRITE setMaxItems)
44 Q_DECLARE_PRIVATE(KRecentFilesAction)
45
46public:
47 /**
48 * Constructs an action with the specified parent.
49 *
50 * @param parent The parent of this action.
51 */
52 explicit KRecentFilesAction(QObject *parent);
53
54 /**
55 * Constructs an action with text; a shortcut may be specified by
56 * the ampersand character (e.g. \"&amp;Option\" creates a shortcut with key \e O )
57 *
58 * This is the most common KAction used when you do not have a
59 * corresponding icon (note that it won't appear in the current version
60 * of the "Edit ToolBar" dialog, because an action needs an icon to be
61 * plugged in a toolbar...).
62 *
63 * @param text The text that will be displayed.
64 * @param 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. \"&amp;Option\" creates a shortcut with key \e O )
71 *
72 * This is the other common KAction used. Use it when you
73 * \e do have a corresponding icon.
74 *
75 * @param icon The icon to display.
76 * @param text The text that will be displayed.
77 * @param parent The parent of this action.
78 */
79 KRecentFilesAction(const QIcon &icon, const QString &text, QObject *parent);
80
81 /**
82 * Destructor.
83 */
84 ~KRecentFilesAction() override;
85
86 /**
87 * Adds \a action to the list of URLs, with \a url and title \a name.
88 *
89 * Do not use addAction(QAction*), as no url will be associated, and
90 * consequently urlSelected() will not be emitted when \a action is selected.
91 */
92 void addAction(QAction *action, const QUrl &url, const QString &name, const QMimeType &mimeType = QMimeType());
93
94 /**
95 * Reimplemented for internal reasons.
96 */
97 QAction *removeAction(QAction *action) override;
98
99 /**
100 * Returns the maximum of items in the recent files list.
101 */
102 int maxItems() const;
103
104 /**
105 * Sets the maximum of items in the recent files list.
106 * The default for this value is 10 set in the constructor.
107 *
108 * If this value is lesser than the number of items currently
109 * in the recent files list the last items are deleted until
110 * the number of items are equal to the new maximum.
111 *
112 * Negative values will be normalized to 0.
113 */
114 void setMaxItems(int maxItems);
115
116 /**
117 * Loads the recent files entries from a given KConfigGroup object.
118 * You can provide the name of the group used to load the entries.
119 * If the groupname is empty, entries are loaded from a group called 'RecentFiles'.
120 * Local file entries that do not exist anymore are not restored.
121 *
122 */
123 void loadEntries(const KConfigGroup &config);
124
125 /**
126 * Saves the current recent files entries to a given KConfigGroup object.
127 * You can provide the name of the group used to load the entries.
128 * If the groupname is empty, entries are saved to a group called 'RecentFiles'.
129 *
130 */
131 void saveEntries(const KConfigGroup &config);
132
133 /**
134 * Add URL to the recent files list. This will enable this action.
135 *
136 * @param url The URL of the file
137 * @param name The user visible pretty name that appears before the URL
138 *
139 * @note URLs corresponding to local files in the temporary directory
140 * (see @ref QDir::tempPath()) are automatically ignored by this method.
141 */
142 void addUrl(const QUrl &url, const QString &name = QString());
143
144 /**
145 * Remove an URL from the recent files list.
146 *
147 * @param url The URL of the file
148 */
149 void removeUrl(const QUrl &url);
150
151 /**
152 * Retrieve a list of all URLs in the recent files list.
153 */
154 QList<QUrl> urls() const;
155
156public Q_SLOTS:
157 /**
158 * Clears the recent files list.
159 * Note that there is also an action shown to the user for clearing the list.
160 */
161 virtual void clear();
162
163Q_SIGNALS:
164 /**
165 * This signal gets emitted when the user selects an URL.
166 *
167 * @param url The URL that the user selected.
168 */
169 void urlSelected(const QUrl &url);
170
171 /**
172 * This signal gets emitted when the user clear list.
173 * So when user store url in specific config file it can saveEntry.
174 * @since 4.3
175 */
176 void recentListCleared();
177
178private:
179 // Internal
180 KCONFIGWIDGETS_NO_EXPORT void clearEntries();
181 // Don't warn about the virtual overload. As the comment of the other
182 // addAction() says, addAction( QAction* ) should not be used.
183 using KSelectAction::addAction;
184
185private:
186 std::unique_ptr<KRecentFilesActionPrivate> const d_ptr;
187};
188
189#endif
190

source code of kconfigwidgets/src/krecentfilesaction.h