1/* This file is part of the KDE libraries
2 Copyright (C) 1999 Reginald Stadlbauer <reggie@kde.org>
3 (C) 1999 Simon Hausmann <hausmann@kde.org>
4 (C) 2000 Nicolas Hadacek <haadcek@kde.org>
5 (C) 2000 Kurt Granroth <granroth@kde.org>
6 (C) 2000 Michael Koch <koch@kde.org>
7 (C) 2001 Holger Freyther <freyther@kde.org>
8 (C) 2002 Ellis Whitehead <ellis@kde.org>
9 (C) 2003 Andras Mantia <amantia@kde.org>
10 (C) 2005-2006 Hamish Rodda <rodda@kde.org>
11
12 This library is free software; you can redistribute it and/or
13 modify it under the terms of the GNU Library General Public
14 License version 2 as published by the Free Software Foundation.
15
16 This library is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 Library General Public License for more details.
20
21 You should have received a copy of the GNU Library General Public License
22 along with this library; see the file COPYING.LIB. If not, write to
23 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
24 Boston, MA 02110-1301, USA.
25*/
26
27#ifndef KRECENTFILESACTION_H
28#define KRECENTFILESACTION_H
29
30#include <kselectaction.h>
31#include <kurl.h>
32
33class KConfigGroup;
34class KRecentFilesActionPrivate;
35
36/**
37 * @short Recent files action
38 *
39 * This class is an action to handle a recent files submenu.
40 * The best way to create the action is to use KStandardAction::openRecent.
41 * Then you simply need to call loadEntries on startup, saveEntries
42 * on shutdown, addURL when your application loads/saves a file.
43 *
44 * @author Michael Koch
45 */
46class KDEUI_EXPORT KRecentFilesAction : public KSelectAction
47{
48 Q_OBJECT
49 Q_PROPERTY( int maxItems READ maxItems WRITE setMaxItems )
50 Q_DECLARE_PRIVATE(KRecentFilesAction)
51
52public:
53 /**
54 * Constructs an action with the specified parent.
55 *
56 * @param parent The parent of this action.
57 */
58 explicit KRecentFilesAction(QObject *parent);
59
60 /**
61 * Constructs an action with text; a shortcut may be specified by
62 * the ampersand character (e.g. \"&amp;Option\" creates a shortcut with key \e O )
63 *
64 * This is the most common KAction used when you do not have a
65 * corresponding icon (note that it won't appear in the current version
66 * of the "Edit ToolBar" dialog, because an action needs an icon to be
67 * plugged in a toolbar...).
68 *
69 * @param text The text that will be displayed.
70 * @param parent The parent of this action.
71 */
72 KRecentFilesAction(const QString &text, QObject *parent);
73
74 /**
75 * Constructs an action with text and an icon; a shortcut may be specified by
76 * the ampersand character (e.g. \"&amp;Option\" creates a shortcut with key \e O )
77 *
78 * This is the other common KAction used. Use it when you
79 * \e do have a corresponding icon.
80 *
81 * @param icon The icon to display.
82 * @param text The text that will be displayed.
83 * @param parent The parent of this action.
84 */
85 KRecentFilesAction(const KIcon &icon, const QString &text, QObject *parent);
86
87 /**
88 * Destructor.
89 */
90 virtual ~KRecentFilesAction();
91
92 /**
93 * Adds \a action to the list of URLs, with \a url and title \a name.
94 *
95 * Do not use addAction(QAction*), as no url will be associated, and
96 * consequently urlSelected() will not be emitted when \a action is selected.
97 */
98 void addAction(QAction* action, const KUrl& url, const QString& name);
99
100 /**
101 * Reimplemented for internal reasons.
102 */
103 virtual QAction* removeAction(QAction* action);
104
105public Q_SLOTS:
106 /**
107 * Clears the recent files list.
108 * Note that there is also an action shown to the user for clearing the list.
109 */
110 virtual void clear();
111
112public:
113 /**
114 * Returns the maximum of items in the recent files list.
115 */
116 int maxItems() const;
117
118 /**
119 * Sets the maximum of items in the recent files list.
120 * The default for this value is 10 set in the constructor.
121 *
122 * If this value is lesser than the number of items currently
123 * in the recent files list the last items are deleted until
124 * the number of items are equal to the new maximum.
125 */
126 void setMaxItems( int maxItems );
127
128 /**
129 * Loads the recent files entries from a given KConfigGroup object.
130 * You can provide the name of the group used to load the entries.
131 * If the groupname is empty, entries are load from a group called 'RecentFiles'
132 *
133 */
134 void loadEntries( const KConfigGroup &config );
135
136 /**
137 * Saves the current recent files entries to a given KConfigGroup object.
138 * You can provide the name of the group used to load the entries.
139 * If the groupname is empty, entries are saved to a group called 'RecentFiles'
140 *
141 */
142 void saveEntries( const KConfigGroup &config );
143
144 /**
145 * Add URL to recent files list.
146 *
147 * @param url The URL of the file
148 * @param name The user visible pretty name that appears before the URL
149 */
150 void addUrl( const KUrl& url, const QString& name = QString() );
151
152 /**
153 * Remove an URL from the recent files list.
154 *
155 * @param url The URL of the file
156 */
157 void removeUrl( const KUrl& url );
158
159 /**
160 * Retrieve a list of all URLs in the recent files list.
161 */
162 KUrl::List urls() const;
163
164Q_SIGNALS:
165 /**
166 * This signal gets emitted when the user selects an URL.
167 *
168 * @param url The URL thats the user selected.
169 */
170 void urlSelected( const KUrl& url );
171
172 /**
173 * This signal gets emitted when the user clear list.
174 * So when user store url in specific config file it can saveEntry.
175 * @since 4.3
176 */
177 void recentListCleared();
178
179private:
180 //Internal
181 void clearEntries();
182 // Don't warn about the virtual overload. As the comment of the other
183 // addAction() says, addAction( QAction* ) should not be used.
184 using KSelectAction::addAction;
185
186 Q_PRIVATE_SLOT( d_func(), void _k_urlSelected(QAction*) )
187};
188
189#endif
190