File indexing completed on 2024-07-21 03:39:37

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. \"&amp;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. \"&amp;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