juce/source/src/audio/plugin_host/juce_KnownPluginList.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_KNOWNPLUGINLIST_JUCEHEADER__
  27 #define __JUCE_KNOWNPLUGINLIST_JUCEHEADER__
  28
  29 #include "juce_PluginDescription.h"
  30 #include "juce_AudioPluginFormat.h"
  31 #include "../../events/juce_ChangeBroadcaster.h"
  32 #include "../../gui/components/menus/juce_PopupMenu.h"
  33
  34
  35 //==============================================================================
  36 /**
  37     Manages a list of plugin types.
  38
  39     This can be easily edited, saved and loaded, and used to create instances of
  40     the plugin types in it.
  41
  42     @see PluginListComponent
  43 */
  44 class JUCE_API  KnownPluginList   : public ChangeBroadcaster
  45 {
  46 public:
  47     //==============================================================================
  48     /** Creates an empty list.
  49     */
  50     KnownPluginList();
  51
  52     /** Destructor. */
  53     ~KnownPluginList();
  54
  55     //==============================================================================
  56     /** Clears the list. */
  57     void clear();
  58
  59     /** Returns the number of types currently in the list.
  60         @see getType
  61     */
  62     int getNumTypes() const noexcept                                { return types.size(); }
  63
  64     /** Returns one of the types.
  65         @see getNumTypes
  66     */
  67     PluginDescription* getType (int index) const noexcept           { return types [index]; }
  68
  69     /** Looks for a type in the list which comes from this file.
  70     */
  71     PluginDescription* getTypeForFile (const String& fileOrIdentifier) const;
  72
  73     /** Looks for a type in the list which matches a plugin type ID.
  74
  75         The identifierString parameter must have been created by
  76         PluginDescription::createIdentifierString().
  77     */
  78     PluginDescription* getTypeForIdentifierString (const String& identifierString) const;
  79
  80     /** Adds a type manually from its description. */
  81     bool addType (const PluginDescription& type);
  82
  83     /** Removes a type. */
  84     void removeType (int index);
  85
  86     /** Looks for all types that can be loaded from a given file, and adds them
  87         to the list.
  88
  89         If dontRescanIfAlreadyInList is true, then the file will only be loaded and
  90         re-tested if it's not already in the list, or if the file's modification
  91         time has changed since the list was created. If dontRescanIfAlreadyInList is
  92         false, the file will always be reloaded and tested.
  93
  94         Returns true if any new types were added, and all the types found in this
  95         file (even if it was already known and hasn't been re-scanned) get returned
  96         in the array.
  97     */
  98     bool scanAndAddFile (const String& possiblePluginFileOrIdentifier,
  99                          bool dontRescanIfAlreadyInList,
 100                          OwnedArray <PluginDescription>& typesFound,
 101                          AudioPluginFormat& formatToUse);
 102
 103     /** Returns true if the specified file is already known about and if it
 104         hasn't been modified since our entry was created.
 105     */
 106     bool isListingUpToDate (const String& possiblePluginFileOrIdentifier) const;
 107
 108     /** Scans and adds a bunch of files that might have been dragged-and-dropped.
 109
 110         If any types are found in the files, their descriptions are returned in the array.
 111     */
 112     void scanAndAddDragAndDroppedFiles (const StringArray& filenames,
 113                                         OwnedArray <PluginDescription>& typesFound);
 114
 115     //==============================================================================
 116     /** Sort methods used to change the order of the plugins in the list.
 117     */
 118     enum SortMethod
 119     {
 120         defaultOrder = 0,
 121         sortAlphabetically,
 122         sortByCategory,
 123         sortByManufacturer,
 124         sortByFileSystemLocation
 125     };
 126
 127     //==============================================================================
 128     /** Adds all the plugin types to a popup menu so that the user can select one.
 129
 130         Depending on the sort method, it may add sub-menus for categories,
 131         manufacturers, etc.
 132
 133         Use getIndexChosenByMenu() to find out the type that was chosen.
 134     */
 135     void addToMenu (PopupMenu& menu,
 136                     const SortMethod sortMethod) const;
 137
 138     /** Converts a menu item index that has been chosen into its index in this list.
 139
 140         Returns -1 if it's not an ID that was used.
 141
 142         @see addToMenu
 143     */
 144     int getIndexChosenByMenu (int menuResultCode) const;
 145
 146     //==============================================================================
 147     /** Sorts the list. */
 148     void sort (const SortMethod method);
 149
 150     //==============================================================================
 151     /** Creates some XML that can be used to store the state of this list.
 152     */
 153     XmlElement* createXml() const;
 154
 155     /** Recreates the state of this list from its stored XML format.
 156     */
 157     void recreateFromXml (const XmlElement& xml);
 158
 159
 160 private:
 161     //==============================================================================
 162     OwnedArray <PluginDescription> types;
 163
 164     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (KnownPluginList);
 165 };
 166
 167
 168 #endif   // __JUCE_KNOWNPLUGINLIST_JUCEHEADER__