source/modules/juce_audio_processors/scanning/juce_KnownPluginList.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    By using JUCE, you agree to the terms of both the JUCE 7 End-User License
  11    Agreement and JUCE Privacy Policy.
  12
  13    End User License Agreement: www.juce.com/juce-7-licence
  14    Privacy Policy: www.juce.com/juce-privacy-policy
  15
  16    Or: You may also use this code under the terms of the GPL v3 (see
  17    www.gnu.org/licenses).
  18
  19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  21    DISCLAIMED.
  22
  23   ==============================================================================
  24 */
  25
  26 namespace juce
  27 {
  28
  29 //==============================================================================
  30 /**
  31     Manages a list of plugin types.
  32
  33     This can be easily edited, saved and loaded, and used to create instances of
  34     the plugin types in it.
  35
  36     @see PluginListComponent
  37
  38     @tags{Audio}
  39 */
  40 class JUCE_API  KnownPluginList   : public ChangeBroadcaster
  41 {
  42 public:
  43     //==============================================================================
  44     /** Creates an empty list. */
  45     KnownPluginList();
  46
  47     /** Destructor. */
  48     ~KnownPluginList() override;
  49
  50     //==============================================================================
  51     /** Clears the list. */
  52     void clear();
  53
  54     /** Adds a type manually from its description. */
  55     bool addType (const PluginDescription& type);
  56
  57     /** Removes a type. */
  58     void removeType (const PluginDescription& type);
  59
  60     /** Returns the number of types currently in the list. */
  61     int getNumTypes() const noexcept;
  62
  63     /** Returns a copy of the current list. */
  64     Array<PluginDescription> getTypes() const;
  65
  66     /** Returns the subset of plugin types for a given format. */
  67     Array<PluginDescription> getTypesForFormat (AudioPluginFormat&) const;
  68
  69     /** Looks for a type in the list which comes from this file. */
  70     std::unique_ptr<PluginDescription> getTypeForFile (const String& fileOrIdentifier) const;
  71
  72     /** Looks for a type in the list which matches a plugin type ID.
  73
  74         The identifierString parameter must have been created by
  75         PluginDescription::createIdentifierString().
  76     */
  77     std::unique_ptr<PluginDescription> getTypeForIdentifierString (const String& identifierString) const;
  78
  79     /** Looks for all types that can be loaded from a given file, and adds them
  80         to the list.
  81
  82         If dontRescanIfAlreadyInList is true, then the file will only be loaded and
  83         re-tested if it's not already in the list, or if the file's modification
  84         time has changed since the list was created. If dontRescanIfAlreadyInList is
  85         false, the file will always be reloaded and tested.
  86
  87         Returns true if any new types were added, and all the types found in this
  88         file (even if it was already known and hasn't been re-scanned) get returned
  89         in the array.
  90     */
  91     bool scanAndAddFile (const String& possiblePluginFileOrIdentifier,
  92                          bool dontRescanIfAlreadyInList,
  93                          OwnedArray<PluginDescription>& typesFound,
  94                          AudioPluginFormat& formatToUse);
  95
  96     /** Tells a custom scanner that a scan has finished, and it can release any resources. */
  97     void scanFinished();
  98
  99     /** Returns true if the specified file is already known about and if it
 100         hasn't been modified since our entry was created.
 101     */
 102     bool isListingUpToDate (const String& possiblePluginFileOrIdentifier,
 103                             AudioPluginFormat& formatToUse) const;
 104
 105     /** Scans and adds a bunch of files that might have been dragged-and-dropped.
 106         If any types are found in the files, their descriptions are returned in the array.
 107     */
 108     void scanAndAddDragAndDroppedFiles (AudioPluginFormatManager& formatManager,
 109                                         const StringArray& filenames,
 110                                         OwnedArray<PluginDescription>& typesFound);
 111
 112     //==============================================================================
 113     /** Returns the list of blacklisted files. */
 114     const StringArray& getBlacklistedFiles() const;
 115
 116     /** Adds a plugin ID to the black-list. */
 117     void addToBlacklist (const String& pluginID);
 118
 119     /** Removes a plugin ID from the black-list. */
 120     void removeFromBlacklist (const String& pluginID);
 121
 122     /** Clears all the blacklisted files. */
 123     void clearBlacklistedFiles();
 124
 125     //==============================================================================
 126     /** Sort methods used to change the order of the plugins in the list.
 127     */
 128     enum SortMethod
 129     {
 130         defaultOrder = 0,
 131         sortAlphabetically,
 132         sortByCategory,
 133         sortByManufacturer,
 134         sortByFormat,
 135         sortByFileSystemLocation,
 136         sortByInfoUpdateTime
 137     };
 138
 139     //==============================================================================
 140     /** Adds the plug-in types to a popup menu so that the user can select one.
 141
 142         Depending on the sort method, it may add sub-menus for categories,
 143         manufacturers, etc.
 144
 145         Use getIndexChosenByMenu() to find out the type that was chosen.
 146     */
 147     static void addToMenu (PopupMenu& menu, const Array<PluginDescription>& types,
 148                            SortMethod sortMethod, const String& currentlyTickedPluginID = {});
 149
 150     /** Converts a menu item index that has been chosen into its index in the list.
 151         Returns -1 if it's not an ID that was used.
 152         @see addToMenu
 153     */
 154     static int getIndexChosenByMenu (const Array<PluginDescription>& types, int menuResultCode);
 155
 156     //==============================================================================
 157     /** Sorts the list. */
 158     void sort (SortMethod method, bool forwards);
 159
 160     //==============================================================================
 161     /** Creates some XML that can be used to store the state of this list. */
 162     std::unique_ptr<XmlElement> createXml() const;
 163
 164     /** Recreates the state of this list from its stored XML format. */
 165     void recreateFromXml (const XmlElement& xml);
 166
 167     //==============================================================================
 168     /** A structure that recursively holds a tree of plugins.
 169         @see KnownPluginList::createTree()
 170     */
 171     struct PluginTree
 172     {
 173         String folder; /**< The name of this folder in the tree */
 174         OwnedArray<PluginTree> subFolders;
 175         Array<PluginDescription> plugins;
 176     };
 177
 178     /** Creates a PluginTree object representing the list of plug-ins. */
 179     static std::unique_ptr<PluginTree> createTree (const Array<PluginDescription>& types, SortMethod sortMethod);
 180
 181     //==============================================================================
 182     /** Class to define a custom plugin scanner */
 183     class CustomScanner
 184     {
 185     public:
 186         CustomScanner();
 187         virtual ~CustomScanner();
 188
 189         /** Attempts to load the given file and find a list of plugins in it.
 190             @returns true if the plugin loaded, false if it crashed
 191         */
 192         virtual bool findPluginTypesFor (AudioPluginFormat& format,
 193                                          OwnedArray<PluginDescription>& result,
 194                                          const String& fileOrIdentifier) = 0;
 195
 196         /** Called when a scan has finished, to allow clean-up of resources. */
 197         virtual void scanFinished();
 198
 199         /** Returns true if the current scan should be abandoned.
 200             Any blocking methods should check this value repeatedly and return if
 201             if becomes true.
 202         */
 203         bool shouldExit() const noexcept;
 204     };
 205
 206     /** Supplies a custom scanner to be used in future scans.
 207         The KnownPluginList will take ownership of the object passed in.
 208     */
 209     void setCustomScanner (std::unique_ptr<CustomScanner> newScanner);
 210
 211     //==============================================================================
 212    #ifndef DOXYGEN
 213     // These methods have been deprecated! When getting the list of plugin types you should instead use
 214     // the getTypes() method which returns a copy of the internal PluginDescription array and can be accessed
 215     // in a thread-safe way.
 216     [[deprecated]] PluginDescription* getType (int index)  noexcept            { return &types.getReference (index); }
 217     [[deprecated]] const PluginDescription* getType (int index) const noexcept { return &types.getReference (index); }
 218     [[deprecated]] PluginDescription** begin() noexcept                        { jassertfalse; return nullptr; }
 219     [[deprecated]] PluginDescription* const* begin() const noexcept            { jassertfalse; return nullptr; }
 220     [[deprecated]] PluginDescription** end() noexcept                          { jassertfalse; return nullptr; }
 221     [[deprecated]] PluginDescription* const* end() const noexcept              { jassertfalse; return nullptr; }
 222
 223     // These methods have been deprecated in favour of their static counterparts. You should call getTypes()
 224     // to store the plug-in list at a point in time and use it when calling these methods.
 225     [[deprecated]] void addToMenu (PopupMenu& menu, SortMethod sortMethod, const String& currentlyTickedPluginID = {}) const;
 226     [[deprecated]] int getIndexChosenByMenu (int menuResultCode) const;
 227     [[deprecated]] std::unique_ptr<PluginTree> createTree (const SortMethod sortMethod) const;
 228    #endif
 229
 230 private:
 231     //==============================================================================
 232     Array<PluginDescription> types;
 233     StringArray blacklist;
 234     std::unique_ptr<CustomScanner> scanner;
 235     CriticalSection scanLock, typesArrayLock;
 236
 237     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (KnownPluginList)
 238 };
 239
 240 } // namespace juce