juce/source/src/utilities/juce_RecentlyOpenedFilesList.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_RECENTLYOPENEDFILESLIST_JUCEHEADER__
  27 #define __JUCE_RECENTLYOPENEDFILESLIST_JUCEHEADER__
  28
  29 #include "../io/files/juce_File.h"
  30 #include "../gui/components/menus/juce_PopupMenu.h"
  31
  32
  33 //==============================================================================
  34 /**
  35     Manages a set of files for use as a list of recently-opened documents.
  36
  37     This is a handy class for holding your list of recently-opened documents, with
  38     helpful methods for things like purging any non-existent files, automatically
  39     adding them to a menu, and making persistence easy.
  40
  41     @see File, FileBasedDocument
  42 */
  43 class JUCE_API  RecentlyOpenedFilesList
  44 {
  45 public:
  46     //==============================================================================
  47     /** Creates an empty list.
  48     */
  49     RecentlyOpenedFilesList();
  50
  51     /** Destructor. */
  52     ~RecentlyOpenedFilesList();
  53
  54     //==============================================================================
  55     /** Sets a limit for the number of files that will be stored in the list.
  56
  57         When addFile() is called, then if there is no more space in the list, the
  58         least-recently added file will be dropped.
  59
  60         @see getMaxNumberOfItems
  61     */
  62     void setMaxNumberOfItems (int newMaxNumber);
  63
  64     /** Returns the number of items that this list will store.
  65         @see setMaxNumberOfItems
  66     */
  67     int getMaxNumberOfItems() const noexcept                            { return maxNumberOfItems; }
  68
  69     /** Returns the number of files in the list.
  70
  71         The most recently added file is always at index 0.
  72     */
  73     int getNumFiles() const;
  74
  75     /** Returns one of the files in the list.
  76
  77         The most recently added file is always at index 0.
  78     */
  79     File getFile (int index) const;
  80
  81     /** Returns an array of all the absolute pathnames in the list.
  82     */
  83     const StringArray& getAllFilenames() const noexcept                 { return files; }
  84
  85     /** Clears all the files from the list. */
  86     void clear();
  87
  88     /** Adds a file to the list.
  89
  90         The file will be added at index 0. If this file is already in the list, it will
  91         be moved up to index 0, but a file can only appear once in the list.
  92
  93         If the list already contains the maximum number of items that is permitted, the
  94         least-recently added file will be dropped from the end.
  95     */
  96     void addFile (const File& file);
  97
  98     /** Removes a file from the list. */
  99     void removeFile (const File& file);
 100
 101     /** Checks each of the files in the list, removing any that don't exist.
 102
 103         You might want to call this after reloading a list of files, or before putting them
 104         on a menu.
 105     */
 106     void removeNonExistentFiles();
 107
 108     //==============================================================================
 109     /** Adds entries to a menu, representing each of the files in the list.
 110
 111         This is handy for creating an "open recent file..." menu in your app. The
 112         menu items are numbered consecutively starting with the baseItemId value,
 113         and can either be added as complete pathnames, or just the last part of the
 114         filename.
 115
 116         If dontAddNonExistentFiles is true, then each file will be checked and only those
 117         that exist will be added.
 118
 119         If filesToAvoid is non-zero, then it is considered to be a zero-terminated array of
 120         pointers to file objects. Any files that appear in this list will not be added to the
 121         menu - the reason for this is that you might have a number of files already open, so
 122         might not want these to be shown in the menu.
 123
 124         It returns the number of items that were added.
 125     */
 126     int createPopupMenuItems (PopupMenu& menuToAddItemsTo,
 127                               int baseItemId,
 128                               bool showFullPaths,
 129                               bool dontAddNonExistentFiles,
 130                               const File** filesToAvoid = nullptr);
 131
 132     //==============================================================================
 133     /** Returns a string that encapsulates all the files in the list.
 134
 135         The string that is returned can later be passed into restoreFromString() in
 136         order to recreate the list. This is handy for persisting your list, e.g. in
 137         a PropertiesFile object.
 138
 139         @see restoreFromString
 140     */
 141     String toString() const;
 142
 143     /** Restores the list from a previously stringified version of the list.
 144
 145         Pass in a stringified version created with toString() in order to persist/restore
 146         your list.
 147
 148         @see toString
 149     */
 150     void restoreFromString (const String& stringifiedVersion);
 151
 152
 153 private:
 154     //==============================================================================
 155     StringArray files;
 156     int maxNumberOfItems;
 157
 158     JUCE_LEAK_DETECTOR (RecentlyOpenedFilesList);
 159 };
 160
 161
 162 #endif   // __JUCE_RECENTLYOPENEDFILESLIST_JUCEHEADER__