KWidgetsAddons

krecentfilesmenu.h
1 // This file is part of the KDE libraries
2 // SPDX-FileCopyrightText: 2020 Nicolas Fella <[email protected]>
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  /**
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 
88 public 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 
99 Q_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 
118 private:
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
Q_SLOTSQ_SLOTS
Q_SIGNALSQ_SIGNALS
A menu that offers a set of recent files.
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Tue Oct 3 2023 04:01:07 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.