KConfigWidgets

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

KDE's Doxygen guidelines are available online.