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 | |
33 | class KConfigGroup; |
34 | class 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 | */ |
46 | class KDEUI_EXPORT KRecentFilesAction : public KSelectAction |
47 | { |
48 | Q_OBJECT |
49 | Q_PROPERTY( int maxItems READ maxItems WRITE setMaxItems ) |
50 | Q_DECLARE_PRIVATE(KRecentFilesAction) |
51 | |
52 | public: |
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. \"&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. \"&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 | |
105 | public 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 | |
112 | public: |
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 | |
164 | Q_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 | |
179 | private: |
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 | |