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 
15 class KRecentFilesMenuPrivate;
16 
17 /**
18  * A menu that offers a set of recent files.
19  *
20  * @since 5.74
21  */
22 class KWIDGETSADDONS_EXPORT KRecentFilesMenu : public QMenu
23 {
24     Q_OBJECT
25 public:
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 Q_SIGNALS:
79     /**
80      * emitted when the user clicks on a file action.
81      * Usually this should result in the specified URL being opened.
82      *
83      * @param url The url associated with the triggered action.
84      */
85     void urlTriggered(const QUrl &url);
86 
87 private:
88     void readFromFile();
89     void writeToFile();
90     void rebuildMenu();
91 
92     std::unique_ptr<KRecentFilesMenuPrivate> const d;
93 };
94 
95 #endif
96