1// This file is part of the KDE libraries
2// SPDX-FileCopyrightText: 2020 Nicolas Fella <nicolas.fella@gmx.de>
3// SPDX-License-Identifier: LGPL-2.1-or-later
4
5#ifndef KRECENTFILESMENU_H
6#define KRECENTFILESMENU_H
7
8#include <kwidgetsaddons_export.h>
9
10#include <QMenu>
11#include <QUrl>
12
13#include <memory> // for std::unique_ptr
14
15class KRecentFilesMenuPrivate;
16
17/*!
18 * \class KRecentFilesMenu
19 * \inmodule KWidgetsAddons
20 *
21 * \brief A menu that offers a set of recent files.
22 *
23 * \since 5.74
24 */
25class KWIDGETSADDONS_EXPORT KRecentFilesMenu : public QMenu
26{
27 Q_OBJECT
28public:
29 /*!
30 *
31 */
32 explicit KRecentFilesMenu(const QString &title, QWidget *parent = nullptr);
33
34 /*!
35 *
36 */
37 explicit KRecentFilesMenu(QWidget *parent = nullptr);
38 ~KRecentFilesMenu() override;
39
40 /*!
41 * The group the URLs are saved to/read from.
42 * Unless a group is specified by setGroup "RecentFiles" is used.
43 */
44 QString group() const;
45
46 /*!
47 * Specify a group for storing the URLs. This allows e.g. storing multiple
48 * types of recent files.
49 *
50 * By default the group "RecentFiles" is used.
51 *
52 * \a group the name of the group.
53 */
54 void setGroup(const QString &group);
55
56 /*!
57 * Add URL to recent files list. This will enable this action.
58 *
59 * \a url The URL of the file
60 *
61 * \a name The user visible pretty name that appears before the URL
62 */
63 void addUrl(const QUrl &url, const QString &name = QString());
64
65 /*!
66 * Remove a URL from the recent files list.
67 *
68 * \a url The URL of the file
69 */
70 void removeUrl(const QUrl &url);
71
72 /*!
73 * The maximum number of files this menu can hold.
74 *
75 * When the maximum url count is reached and a new URL is added the
76 * oldest will be replaced.
77 *
78 * By default maximum 10 URLs are shown.
79 */
80 int maximumItems() const;
81
82 /*!
83 * Set the maximum URL count.
84 *
85 * \sa maximumItems()
86 */
87 void setMaximumItems(size_t maximumItems);
88
89 /*!
90 * List of URLs of recent files.
91 *
92 * \sa clearRecentFiles()
93 * \sa recentFilesChanged()
94 *
95 * \since 5.101
96 */
97 QList<QUrl> recentFiles() const;
98
99public Q_SLOTS:
100 /*!
101 * Clear recent files list.
102 *
103 * \sa recentFiles()
104 * \sa recentFilesChanged()
105 *
106 * \since 5.101
107 */
108 void clearRecentFiles();
109
110Q_SIGNALS:
111 /*!
112 * Emitted when the user clicks on a file action.
113 *
114 * Usually this should result in the specified URL being opened.
115 *
116 * \a url The url associated with the triggered action.
117 */
118 void urlTriggered(const QUrl &url);
119
120 /*!
121 * Emitted when the recent files list has been changed.
122 *
123 * \sa recentFiles()
124 * \sa clearRecentFiles()
125 *
126 * \since 5.101
127 */
128 void recentFilesChanged();
129
130private:
131 KWIDGETSADDONS_NO_EXPORT void readFromFile();
132 KWIDGETSADDONS_NO_EXPORT void writeToFile();
133 KWIDGETSADDONS_NO_EXPORT void rebuildMenu();
134
135 friend class KRecentFilesMenuPrivate;
136
137 std::unique_ptr<KRecentFilesMenuPrivate> const d;
138};
139
140#endif
141

source code of kwidgetsaddons/src/krecentfilesmenu.h