File indexing completed on 2024-03-24 03:56:09
0001 /* 0002 This file is part of the KDE libraries 0003 SPDX-FileCopyrightText: 1999 Reginald Stadlbauer <reggie@kde.org> 0004 SPDX-FileCopyrightText: 1999 Simon Hausmann <hausmann@kde.org> 0005 SPDX-FileCopyrightText: 2000 Nicolas Hadacek <haadcek@kde.org> 0006 SPDX-FileCopyrightText: 2000 Kurt Granroth <granroth@kde.org> 0007 SPDX-FileCopyrightText: 2000 Michael Koch <koch@kde.org> 0008 SPDX-FileCopyrightText: 2001 Holger Freyther <freyther@kde.org> 0009 SPDX-FileCopyrightText: 2002 Ellis Whitehead <ellis@kde.org> 0010 SPDX-FileCopyrightText: 2003 Andras Mantia <amantia@kde.org> 0011 SPDX-FileCopyrightText: 2005-2006 Hamish Rodda <rodda@kde.org> 0012 0013 SPDX-License-Identifier: LGPL-2.0-only 0014 */ 0015 0016 #ifndef KRECENTFILESACTION_H 0017 #define KRECENTFILESACTION_H 0018 0019 #include <KSelectAction> 0020 #include <QUrl> 0021 #include <kconfigwidgets_export.h> 0022 0023 #include <QMimeType> 0024 0025 class KConfigGroup; 0026 class KRecentFilesActionPrivate; 0027 0028 /** 0029 * @class KRecentFilesAction krecentfilesaction.h KRecentFilesAction 0030 * 0031 * @short Recent files action 0032 * 0033 * This class is an action to handle a recent files submenu. 0034 * The best way to create the action is to use KStandardAction::openRecent. 0035 * Then you simply need to call loadEntries on startup, saveEntries 0036 * on shutdown, addURL when your application loads/saves a file. 0037 * 0038 * @author Michael Koch 0039 */ 0040 class KCONFIGWIDGETS_EXPORT KRecentFilesAction : public KSelectAction 0041 { 0042 Q_OBJECT 0043 Q_PROPERTY(int maxItems READ maxItems WRITE setMaxItems) 0044 Q_DECLARE_PRIVATE(KRecentFilesAction) 0045 0046 public: 0047 /** 0048 * Constructs an action with the specified parent. 0049 * 0050 * @param parent The parent of this action. 0051 */ 0052 explicit KRecentFilesAction(QObject *parent); 0053 0054 /** 0055 * Constructs an action with text; a shortcut may be specified by 0056 * the ampersand character (e.g. \"&Option\" creates a shortcut with key \e O ) 0057 * 0058 * This is the most common KAction used when you do not have a 0059 * corresponding icon (note that it won't appear in the current version 0060 * of the "Edit ToolBar" dialog, because an action needs an icon to be 0061 * plugged in a toolbar...). 0062 * 0063 * @param text The text that will be displayed. 0064 * @param parent The parent of this action. 0065 */ 0066 KRecentFilesAction(const QString &text, QObject *parent); 0067 0068 /** 0069 * Constructs an action with text and an icon; a shortcut may be specified by 0070 * the ampersand character (e.g. \"&Option\" creates a shortcut with key \e O ) 0071 * 0072 * This is the other common KAction used. Use it when you 0073 * \e do have a corresponding icon. 0074 * 0075 * @param icon The icon to display. 0076 * @param text The text that will be displayed. 0077 * @param parent The parent of this action. 0078 */ 0079 KRecentFilesAction(const QIcon &icon, const QString &text, QObject *parent); 0080 0081 /** 0082 * Destructor. 0083 */ 0084 ~KRecentFilesAction() override; 0085 0086 /** 0087 * Adds \a action to the list of URLs, with \a url and title \a name. 0088 * 0089 * Do not use addAction(QAction*), as no url will be associated, and 0090 * consequently urlSelected() will not be emitted when \a action is selected. 0091 */ 0092 void addAction(QAction *action, const QUrl &url, const QString &name, const QMimeType &mimeType = QMimeType()); 0093 0094 /** 0095 * Reimplemented for internal reasons. 0096 */ 0097 QAction *removeAction(QAction *action) override; 0098 0099 /** 0100 * Returns the maximum of items in the recent files list. 0101 */ 0102 int maxItems() const; 0103 0104 /** 0105 * Sets the maximum of items in the recent files list. 0106 * The default for this value is 10 set in the constructor. 0107 * 0108 * If this value is lesser than the number of items currently 0109 * in the recent files list the last items are deleted until 0110 * the number of items are equal to the new maximum. 0111 * 0112 * Negative values will be normalized to 0. 0113 */ 0114 void setMaxItems(int maxItems); 0115 0116 /** 0117 * Loads the recent files entries from a given KConfigGroup object. 0118 * You can provide the name of the group used to load the entries. 0119 * If the groupname is empty, entries are loaded from a group called 'RecentFiles'. 0120 * Local file entries that do not exist anymore are not restored. 0121 * 0122 */ 0123 void loadEntries(const KConfigGroup &config); 0124 0125 /** 0126 * Saves the current recent files entries to a given KConfigGroup object. 0127 * You can provide the name of the group used to load the entries. 0128 * If the groupname is empty, entries are saved to a group called 'RecentFiles'. 0129 * 0130 */ 0131 void saveEntries(const KConfigGroup &config); 0132 0133 /** 0134 * Add URL to the recent files list. This will enable this action. 0135 * 0136 * @param url The URL of the file 0137 * @param name The user visible pretty name that appears before the URL 0138 * 0139 * @note URLs corresponding to local files in the temporary directory 0140 * (see @ref QDir::tempPath()) are automatically ignored by this method. 0141 */ 0142 void addUrl(const QUrl &url, const QString &name = QString()); 0143 0144 /** 0145 * Remove an URL from the recent files list. 0146 * 0147 * @param url The URL of the file 0148 */ 0149 void removeUrl(const QUrl &url); 0150 0151 /** 0152 * Retrieve a list of all URLs in the recent files list. 0153 */ 0154 QList<QUrl> urls() const; 0155 0156 public Q_SLOTS: 0157 /** 0158 * Clears the recent files list. 0159 * Note that there is also an action shown to the user for clearing the list. 0160 */ 0161 virtual void clear(); 0162 0163 Q_SIGNALS: 0164 /** 0165 * This signal gets emitted when the user selects an URL. 0166 * 0167 * @param url The URL that the user selected. 0168 */ 0169 void urlSelected(const QUrl &url); 0170 0171 /** 0172 * This signal gets emitted when the user clear list. 0173 * So when user store url in specific config file it can saveEntry. 0174 * @since 4.3 0175 */ 0176 void recentListCleared(); 0177 0178 private: 0179 // Internal 0180 KCONFIGWIDGETS_NO_EXPORT void clearEntries(); 0181 // Don't warn about the virtual overload. As the comment of the other 0182 // addAction() says, addAction( QAction* ) should not be used. 0183 using KSelectAction::addAction; 0184 0185 private: 0186 std::unique_ptr<KRecentFilesActionPrivate> const d_ptr; 0187 }; 0188 0189 #endif