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 * A menu that offers a set of recent files.
19 *
20 * @since 5.74
21 */
22class KWIDGETSADDONS_EXPORT KRecentFilesMenu : public QMenu
23{
24 Q_OBJECT
25public:
26 explicit KRecentFilesMenu(const QString &title, QWidget *parent = nullptr);
27 explicit KRecentFilesMenu(QWidget *parent = nullptr);
28 ~KRecentFilesMenu() override;
29
30 /**
31 * The group the URLs are saved to/read from.
32 * Unless a group is specified by setGroup "RecentFiles" is used.
33 */
34 QString group() const;
35
36 /**
37 * Specify a group for storing the URLs. This allows e.g. storing multiple
38 * types of recent files.
39 *
40 * By default the group "RecentFiles" is used.
41 *
42 * @param group the name of the group.
43 */
44 void setGroup(const QString &group);
45
46 /**
47 * Add URL to recent files list. This will enable this action.
48 *
49 * @param url The URL of the file
50 * @param name The user visible pretty name that appears before the URL
51 */
52 void addUrl(const QUrl &url, const QString &name = QString());
53
54 /**
55 * Remove a URL from the recent files list.
56 *
57 * @param url The URL of the file
58 */
59 void removeUrl(const QUrl &url);
60
61 /**
62 * The maximum number of files this menu can hold.
63 *
64 * When the maximum url count is reached and a new URL is added the
65 * oldest will be replaced.
66 *
67 * By default maximum 10 URLs are shown.
68 */
69 int maximumItems() const;
70
71 /**
72 * Set the maximum URL count.
73 *
74 * See \ref maximumItems
75 */
76 void setMaximumItems(size_t maximumItems);
77
78 /**
79 * List of URLs of recent files.
80 *
81 * See \ref clearRecentFiles
82 * See \ref recentFilesChanged
83 *
84 * @since 5.101
85 */
86 QList<QUrl> recentFiles() const;
87
88public Q_SLOTS:
89 /**
90 * Clear recent files list.
91 *
92 * See \ref recentFiles
93 * See \ref recentFilesChanged
94 *
95 * @since 5.101
96 */
97 void clearRecentFiles();
98
99Q_SIGNALS:
100 /**
101 * emitted when the user clicks on a file action.
102 * Usually this should result in the specified URL being opened.
103 *
104 * @param url The url associated with the triggered action.
105 */
106 void urlTriggered(const QUrl &url);
107
108 /**
109 * Emitted when the recent files list has been changed.
110 *
111 * See \ref recentFiles
112 * See \ref clearRecentFiles
113 *
114 * @since 5.101
115 */
116 void recentFilesChanged();
117
118private:
119 KWIDGETSADDONS_NO_EXPORT void readFromFile();
120 KWIDGETSADDONS_NO_EXPORT void writeToFile();
121 KWIDGETSADDONS_NO_EXPORT void rebuildMenu();
122
123 friend class KRecentFilesMenuPrivate;
124
125 std::unique_ptr<KRecentFilesMenuPrivate> const d;
126};
127
128#endif
129

source code of kwidgetsaddons/src/krecentfilesmenu.h