Chris@149: /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
Chris@149: 
Chris@149: /*
Chris@149:     Sonic Visualiser
Chris@149:     An audio file viewer and annotation editor.
Chris@149:     Centre for Digital Music, Queen Mary, University of London.
Chris@149:     This file copyright 2006 Chris Cannam.
Chris@149:     
Chris@149:     This program is free software; you can redistribute it and/or
Chris@149:     modify it under the terms of the GNU General Public License as
Chris@149:     published by the Free Software Foundation; either version 2 of the
Chris@149:     License, or (at your option) any later version.  See the file
Chris@149:     COPYING included with this distribution for more information.
Chris@149: */
Chris@149: 
Chris@1581: #ifndef SV_RECENT_FILES_H
Chris@1581: #define SV_RECENT_FILES_H
Chris@149: 
Chris@149: #include <QObject>
Chris@149: #include <QString>
Chris@1704: #include <QMutex>
Chris@149: #include <vector>
Chris@149: #include <deque>
Chris@149: 
Chris@166: /**
Chris@1704:  * RecentFiles manages a list of recently-used identifier strings,
Chris@1704:  * saving and restoring that list via QSettings.  The identifiers do
Chris@1704:  * not actually have to refer to files.
Chris@1704:  *
Chris@1704:  * Each entry must have a non-empty identifier, which is typically a
Chris@1704:  * filename, path, URI, or internal id, and may optionally also have a
Chris@1704:  * label, which is typically a user-visible convenience.
Chris@1704:  *
Chris@1704:  * RecentFiles is thread-safe - all access is serialised.
Chris@166:  */
Chris@149: class RecentFiles : public QObject
Chris@149: {
Chris@149:     Q_OBJECT
Chris@149: 
Chris@149: public:
Chris@166:     /**
Chris@166:      * Construct a RecentFiles object that saves and restores in the
Chris@166:      * given QSettings group and truncates when the given count of
Chris@1704:      * identifiers is reached.
Chris@166:      */
Chris@1704:     RecentFiles(QString settingsGroup = "RecentFiles",
Chris@1704:                 int maxCount = 10);
Chris@149: 
Chris@149:     virtual ~RecentFiles();
Chris@149: 
Chris@1704:     /**
Chris@1704:      * Return the settingsGroup as passed to the constructor.
Chris@1704:      */
Chris@1704:     QString getSettingsGroup() const {
Chris@1704:         return m_settingsGroup;
Chris@1704:     }
Chris@166: 
Chris@166:     /**
Chris@1704:      * Return the maxCount as passed to the constructor.
Chris@166:      */
Chris@1704:     int getMaxCount() const {
Chris@1704:         return m_maxCount;
Chris@1704:     }
Chris@1704: 
Chris@1704:     /**
Chris@1704:      * Return the list of recent identifiers, without labels.
Chris@1704:      */
Chris@1704:     std::vector<QString> getRecentIdentifiers() const;
Chris@1704: 
Chris@1704:     /**
Chris@1704:      * Return the list of recent identifiers, without labels. This is
Chris@1704:      * an alias for getRecentIdentifiers included for backward
Chris@1704:      * compatibility.
Chris@1704:      */
Chris@1704:     std::vector<QString> getRecent() const {
Chris@1704:         return getRecentIdentifiers();
Chris@1704:     }
Chris@1704: 
Chris@1704:     /**
Chris@1704:      * Return the list of recent identifiers, with labels. Each
Chris@1704:      * returned entry is a pair of identifier and label in that order.
Chris@1704:      */
Chris@1704:     std::vector<std::pair<QString, QString>> getRecentEntries() const;
Chris@149:     
Chris@166:     /**
Chris@1704:      * Add a literal identifier, optionally with a label.
Chris@1704:      *
Chris@1704:      * If the identifier already exists in the recent entries list, it
Chris@1704:      * is moved to the front of the list and its label is replaced
Chris@1704:      * with the given one.
Chris@166:      */
Chris@1704:     void add(QString identifier, QString label = "");
Chris@1704:     
Chris@1704:     /**
Chris@1704:      * Add a name that is known to be either a file path or a URL,
Chris@1704:      * optionally with a label.  If it looks like a URL, add it
Chris@1704:      * literally; otherwise treat it as a file path and canonicalise
Chris@1704:      * it appropriately.  Also take into account the user preference
Chris@1704:      * for whether to include temporary files in the recent files
Chris@1704:      * menu: the file will not be added if the preference is set and
Chris@1704:      * the file appears to be a temporary one.
Chris@1704:      *
Chris@1704:      * If the identifier derived from the file path already exists in
Chris@1704:      * the recent entries list, it is moved to the front of the list
Chris@1704:      * and its label is replaced with the given one.
Chris@1704:      */
Chris@1704:     void addFile(QString filepath, QString label = "");
Chris@149: 
Chris@149: signals:
Chris@166:     void recentChanged();
Chris@149: 
Chris@1704: private:
Chris@1704:     mutable QMutex m_mutex;
Chris@149: 
Chris@1704:     const QString m_settingsGroup;
Chris@1704:     const int m_maxCount;
Chris@1704: 
Chris@1704:     std::deque<std::pair<QString, QString>> m_entries; // identifier, label
Chris@149: 
Chris@166:     void read();
Chris@166:     void write();
Chris@149:     void truncateAndWrite();
Chris@149: };
Chris@149: 
Chris@149: #endif