Audacity  3.2.0
PluginManager.h
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  PluginManager.h
6 
7  Leland Lucius
8 
9 **********************************************************************/
10 
11 #ifndef __AUDACITY_PLUGINMANAGER_H__
12 #define __AUDACITY_PLUGINMANAGER_H__
13 
14 #include <wx/defs.h>
15 
16 #include "wxArrayStringEx.h"
17 #include <functional>
18 #include <map>
19 #include <memory>
20 
21 #include "EffectInterface.h"
22 #include "PluginInterface.h"
23 
24 class wxArrayString;
25 class FileConfig;
26 
28 //
29 // PluginDescriptor
30 //
32 
33 typedef enum : unsigned {
34  PluginTypeNone = 0, // 2.1.0 placeholder entries...not used by 2.1.1 or greater
35  PluginTypeStub =1, // Used for plugins that have not yet been registered
41 } PluginType;
42 
43 // TODO: Convert this to multiple derived classes
44 class MODULE_MANAGER_API PluginDescriptor
45 {
46 public:
49  virtual ~PluginDescriptor();
50 
51  bool IsInstantiated() const;
52 
53  PluginType GetPluginType() const;
54 
55  // All plugins
56 
57  // These return untranslated strings
58  const wxString & GetID() const;
59  const wxString & GetProviderID() const;
60  const PluginPath & GetPath() const;
61  const ComponentInterfaceSymbol & GetSymbol() const;
62 
63  wxString GetUntranslatedVersion() const;
64  // There is no translated version
65 
66  wxString GetVendor() const;
67 
68  bool IsEnabled() const;
69  bool IsValid() const;
70 
71  void SetEnabled(bool enable);
72  void SetValid(bool valid);
73 
74  // Effect plugins only
75 
76  // Internal string only, no translated counterpart!
77  // (Use Effect::GetFamilyName instead)
78  // This string persists in configuration files
79  // So config compatibility will break if it is changed across Audacity versions
80  wxString GetEffectFamily() const;
81 
82  EffectType GetEffectType() const;
83  bool IsEffectDefault() const;
84  bool IsEffectInteractive() const;
85  bool IsEffectLegacy() const;
86  bool IsEffectRealtime() const;
87  bool IsEffectAutomatable() const;
88 
89  // Importer plugins only
90 
91  const wxString & GetImporterIdentifier() const;
93  const FileExtensions & GetImporterExtensions() const;
94 
95 private:
96  friend class PluginManager;
97 
99  void SetInstance(std::unique_ptr<ComponentInterface> instance);
100 
101  void SetPluginType(PluginType type);
102 
103  // These should be passed an untranslated value
104  void SetID(const PluginID & ID);
105  void SetProviderID(const PluginID & providerID);
106  void SetPath(const PluginPath & path);
107  void SetSymbol(const ComponentInterfaceSymbol & symbol);
108 
109  // These should be passed an untranslated value wrapped in XO() so
110  // the value will still be extracted for translation
111  void SetVersion(const wxString & version);
112  void SetVendor(const wxString & vendor);
113 
114  // "family" should be an untranslated string wrapped in wxT()
115  void SetEffectFamily(const wxString & family);
116  void SetEffectType(EffectType type);
117  void SetEffectDefault(bool dflt);
118  void SetEffectInteractive(bool interactive);
119  void SetEffectLegacy(bool legacy);
120  void SetEffectRealtime(bool realtime);
121  void SetEffectAutomatable(bool automatable);
122 
123  void SetImporterIdentifier(const wxString & identifier);
125  void SetImporterExtensions(FileExtensions extensions);
126 
127  // Common
128 
129  // Among other purposes, PluginDescriptor acts as the resource handle,
130  // or smart pointer, to a resource created in a plugin library, and is responsible
131  // for a cleanup of this pointer.
132  std::unique_ptr<ComponentInterface> muInstance; // may be null for a module
134 
136 
137  wxString mID;
140  wxString mVersion;
141  wxString mVendor;
142  wxString mProviderID;
143  bool mEnabled;
144  bool mValid;
145 
146  // Effects
147 
148  wxString mEffectFamily;
155 
156  // Importers
157 
160 };
161 
163 //
164 // PluginManager
165 //
167 
168 typedef std::map<PluginID, PluginDescriptor> PluginMap;
169 
170 typedef wxArrayString PluginIDs;
171 
173 
174 class MODULE_MANAGER_API PluginManager final : public PluginManagerInterface
175 {
176 public:
177 
178  RegistryPath GetPluginEnabledSetting( const PluginID &ID ) const;
179  RegistryPath GetPluginEnabledSetting( const PluginDescriptor &desc ) const;
180 
181  // PluginManagerInterface implementation
182 
183  bool IsPluginRegistered(
184  const PluginPath &path, const TranslatableString *pSymbol) override;
185 
186  const PluginID & RegisterPlugin(ModuleInterface *module) override;
187  const PluginID & RegisterPlugin(ModuleInterface *provider, ComponentInterface *command);
188  const PluginID & RegisterPlugin(ModuleInterface *provider, EffectDefinitionInterface *effect, int type) override;
189 
190  void FindFilesInPathList(const wxString & pattern,
191  const FilePaths & pathList,
192  FilePaths & files,
193  bool directories = false) override;
194 
195  bool HasConfigGroup(ConfigurationType type, const PluginID & ID,
196  const RegistryPath & group) /* not override */;
197  bool GetConfigSubgroups(ConfigurationType type, const PluginID & ID,
198  const RegistryPath & group,
199  RegistryPaths & subgroups) override;
200 
201  bool GetConfigValue(ConfigurationType type, const PluginID & ID,
202  const RegistryPath & group, const RegistryPath & key,
203  ConfigReference var, ConfigConstReference defval) override;
204 
205  bool SetConfigValue(ConfigurationType type, const PluginID & ID,
206  const RegistryPath & group, const RegistryPath & key,
207  ConfigConstReference value) override;
208 
210  const PluginID & ID, const RegistryPath & group) override;
211  bool RemoveConfig(ConfigurationType type, const PluginID & ID,
212  const RegistryPath & group, const RegistryPath & key) override;
213 
214  // PluginManager implementation
215 
216  // Initialization must inject a factory to make a concrete subtype of
217  // FileConfig
218  using FileConfigFactory = std::function<
219  std::unique_ptr<FileConfig>(const FilePath &localFilename ) >;
222  void Terminate();
223 
224  bool DropFile(const wxString &fileName);
225 
226  static PluginManager & Get();
227 
228  static PluginID GetID(ModuleInterface *module);
229  static PluginID GetID(ComponentInterface *command);
230  static PluginID GetID(EffectDefinitionInterface *effect);
231 
232  // This string persists in configuration files
233  // So config compatibility will break if it is changed across Audacity versions
234  static wxString GetPluginTypeString(PluginType type);
235 
236  int GetPluginCount(PluginType type);
237  const PluginDescriptor *GetPlugin(const PluginID & ID) const;
238 
241  class MODULE_MANAGER_API Iterator {
242  public:
244  explicit Iterator(PluginManager &manager);
247  int pluginType
248  );
251  bool operator != (int) const {
252  return mIterator != mPm.mPlugins.end();
253  }
254  Iterator &operator ++ ();
255  auto &operator *() const { return mIterator->second; }
256  private:
257  void Advance(bool incrementing);
259  PluginMap::iterator mIterator;
260  EffectType mEffectType{ EffectTypeNone };
261  int mPluginType{ PluginTypeNone };
262  };
263  struct Range {
265  Iterator begin() const { return first; }
266  int end() const { return 0; }
267  };
268 
269  Range AllPlugins() { return { Iterator{ *this } }; }
270  Range PluginsOfType(int type) { return { Iterator{ *this, type } }; }
271  Range EffectsOfType(EffectType type) { return { Iterator{ *this, type } }; }
273 
274  bool IsPluginEnabled(const PluginID & ID);
275  void EnablePlugin(const PluginID & ID, bool enable);
276 
277  const ComponentInterfaceSymbol & GetSymbol(const PluginID & ID);
278  ComponentInterface *GetInstance(const PluginID & ID);
279 
280  void CheckForUpdates(bool bFast = false);
281 
283  const PluginID & RegisterPlugin(
284  std::unique_ptr<EffectDefinitionInterface> effect, PluginType type );
285  void UnregisterPlugin(const PluginID & ID);
286 
288  void Load();
290  void Save();
291 
292 private:
293  // private! Use Get()
294  PluginManager();
295  ~PluginManager();
296 
297  void LoadGroup(FileConfig *pRegistry, PluginType type);
298  void SaveGroup(FileConfig *pRegistry, PluginType type);
299 
300  PluginDescriptor & CreatePlugin(const PluginID & id, ComponentInterface *ident, PluginType type);
301 
302  FileConfig *GetSettings();
303 
304  bool HasGroup(const RegistryPath & group);
305  bool GetSubgroups(const RegistryPath & group, RegistryPaths & subgroups);
306 
308  ConfigConstReference defval);
310 
311  /* Return values are keys for lookup in a config file */
312  RegistryPath SettingsPath(ConfigurationType type, const PluginID & ID);
313  RegistryPath Group(ConfigurationType type, const PluginID & ID,
314  const RegistryPath & group);
315  RegistryPath Key(ConfigurationType type, const PluginID & ID,
316  const RegistryPath & group, const RegistryPath & key);
317 
318  // The PluginID must be kept unique. Since the wxFileConfig class does not preserve
319  // case, we use base64 encoding.
320  wxString ConvertID(const PluginID & ID);
321  wxString b64encode(const void *in, int len);
322  int b64decode(const wxString &in, void *out);
323 
324 private:
325  friend std::default_delete<PluginManager>;
326  static std::unique_ptr<PluginManager> mInstance;
327 
328  bool IsDirty();
329  void SetDirty(bool dirty = true);
330  std::unique_ptr<FileConfig> mSettings;
331 
332  bool mDirty;
334 
336 };
337 
338 // Defining these special names in the low-level PluginManager.h
339 // is unfortunate
340 // Internal name should be stable across versions
341 #define NYQUIST_PROMPT_ID wxT("Nyquist Prompt")
342 // User-visible name might change in later versions
343 #define NYQUIST_PROMPT_NAME XO("Nyquist Prompt")
344 
345 #endif /* __AUDACITY_PLUGINMANAGER_H__ */
PluginDescriptor::mEffectLegacy
bool mEffectLegacy
Definition: PluginManager.h:152
TranslatableString
Holds a msgid for the translation catalog; may also bind format arguments.
Definition: TranslatableString.h:32
PluginManagerInterface::SetConfigValue
virtual bool SetConfigValue(ConfigurationType type, const PluginID &ID, const RegistryPath &group, const RegistryPath &key, ConfigConstReference value)=0
PluginManager::GetInstance
ComponentInterface * GetInstance(const PluginID &ID)
Definition: PluginManager.cpp:1422
PluginDescriptor::mVendor
wxString mVendor
Definition: PluginManager.h:141
PluginSettings::SetConfigValue
bool SetConfigValue(EffectDefinitionInterface &ident, PluginSettings::ConfigurationType type, const RegistryPath &group, const RegistryPath &key, ConfigConstReference value)
Definition: ConfigInterface.cpp:43
PluginTypeEffect
@ PluginTypeEffect
Definition: PluginManager.h:36
PluginDescriptor::mInstance
ComponentInterface * mInstance
Definition: PluginManager.h:133
operator*
Vector operator*(const Vector &left, const Vector &right)
Definition: Matrix.cpp:153
PluginManager::mPlugins
PluginMap mPlugins
Definition: PluginManager.h:335
PluginManager::Range::begin
Iterator begin() const
Definition: PluginManager.h:265
EffectInterface.h
ident
static CommandHandlerObject & ident(AudacityProject &project)
Definition: ModNullCallback.cpp:65
RegistryPaths
std::vector< RegistryPath > RegistryPaths
Definition: Identifier.h:219
PluginSettings::GetConfigValue
bool GetConfigValue(EffectDefinitionInterface &ident, PluginSettings::ConfigurationType type, const RegistryPath &group, const RegistryPath &key, ConfigReference var, ConfigConstReference defval)
Definition: ConfigInterface.cpp:33
PluginPath
wxString PluginPath
type alias for identifying a Plugin supplied by a module, each module defining its own interpretation...
Definition: Identifier.h:214
operator!=
bool operator!=(const Tags &lhs, const Tags &rhs)
Definition: Tags.h:128
PluginManager::mCurrentIndex
int mCurrentIndex
Definition: PluginManager.h:333
PluginDescriptor::mVersion
wxString mVersion
Definition: PluginManager.h:140
PluginManager::SetDirty
void SetDirty(bool dirty=true)
EffectTypeNone
@ EffectTypeNone
Definition: EffectInterface.h:53
PluginDescriptor::mProviderID
wxString mProviderID
Definition: PluginManager.h:142
PluginManager::FileConfigFactory
std::function< std::unique_ptr< FileConfig >(const FilePath &localFilename) > FileConfigFactory
Definition: PluginManager.h:219
PluginRegistrationDialog
Definition: PluginRegistrationDialog.h:25
PluginManagerInterface::RegisterPlugin
virtual const PluginID & RegisterPlugin(ModuleInterface *module)=0
PluginDescriptor::muInstance
std::unique_ptr< ComponentInterface > muInstance
Definition: PluginManager.h:132
PluginDescriptor::mEffectDefault
bool mEffectDefault
Definition: PluginManager.h:151
PluginDescriptor::mPluginType
PluginType mPluginType
Definition: PluginManager.h:135
wxArrayStringEx
Extend wxArrayString with move operations and construction and insertion fromstd::initializer_list.
Definition: wxArrayStringEx.h:18
desc
const TranslatableString desc
Definition: ExportPCM.cpp:58
ComponentInterfaceSymbol
ComponentInterfaceSymbol pairs a persistent string identifier used internally with an optional,...
Definition: ComponentInterfaceSymbol.h:27
PluginManagerInterface::RemoveConfigSubgroup
virtual bool RemoveConfigSubgroup(ConfigurationType type, const PluginID &ID, const RegistryPath &group)=0
PluginType
PluginType
Definition: PluginManager.h:33
ModuleInterface
Definition: ModuleInterface.h:75
PluginManager::Range
Definition: PluginManager.h:263
PluginIDs
wxArrayString PluginIDs
Definition: PluginManager.h:170
PluginDescriptor::SetImporterFilterDescription
void SetImporterFilterDescription(const TranslatableString &filterDesc)
PluginManagerInterface::IsPluginRegistered
virtual bool IsPluginRegistered(const PluginPath &path, const TranslatableString *pName=nullptr)=0
Was the plugin registry already populated for a path (maybe from loading the config file)?
PluginManager::Iterator::mPm
const PluginManager & mPm
Definition: PluginManager.h:258
PluginMap
std::map< PluginID, PluginDescriptor > PluginMap
Definition: PluginManager.h:168
PluginManager::Iterator
Definition: PluginManager.h:241
PluginDescriptor::mPath
PluginPath mPath
Definition: PluginManager.h:138
PluginManager::IsDirty
bool IsDirty()
FilePath
wxString FilePath
Definition: Project.h:20
PluginManagerInterface
Definition: PluginInterface.h:84
factory
static RegisteredToolbarFactory factory
Definition: ControlToolBar.cpp:820
PluginDescriptor::mEffectInteractive
bool mEffectInteractive
Definition: PluginManager.h:150
BasicUI::Get
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:26
PluginManagerInterface::ConfigConstReference
PluginSettings::ConfigConstReference ConfigConstReference
Definition: PluginInterface.h:88
PluginID
wxString PluginID
Definition: EffectManager.h:31
PluginDescriptor::GetImporterFilterDescription
const TranslatableString & GetImporterFilterDescription() const
PluginManager::mSettings
std::unique_ptr< FileConfig > mSettings
Definition: PluginManager.h:330
PluginManagerInterface::GetConfigSubgroups
virtual bool GetConfigSubgroups(ConfigurationType type, const PluginID &ID, const RegistryPath &group, RegistryPaths &subgroups)=0
PluginTypeModule
@ PluginTypeModule
Definition: PluginManager.h:40
PluginManager::EffectsOfType
Range EffectsOfType(EffectType type)
Definition: PluginManager.h:271
PluginManager::Range::first
Iterator first
Definition: PluginManager.h:264
PluginManager::Iterator::mIterator
PluginMap::iterator mIterator
Definition: PluginManager.h:259
PluginManager::mDirty
bool mDirty
Definition: PluginManager.h:332
Journal::Events::anonymous_namespace{JournalEvents.cpp}::Initialize
void Initialize()
Definition: JournalEvents.cpp:438
PluginTypeAudacityCommand
@ PluginTypeAudacityCommand
Definition: PluginManager.h:37
PluginDescriptor
Definition: PluginManager.h:45
PluginManagerInterface::FindFilesInPathList
virtual void FindFilesInPathList(const wxString &pattern, const FilePaths &pathList, FilePaths &files, bool directories=false)=0
PluginDescriptor::mValid
bool mValid
Definition: PluginManager.h:144
PluginDescriptor::mID
wxString mID
Definition: PluginManager.h:137
PluginDescriptor::mSymbol
ComponentInterfaceSymbol mSymbol
Definition: PluginManager.h:139
PluginTypeNone
@ PluginTypeNone
Definition: PluginManager.h:34
RegistryPath
wxString RegistryPath
Definition: Identifier.h:218
FileConfig
Definition: FileConfig.h:21
PluginManager::mInstance
static std::unique_ptr< PluginManager > mInstance
Definition: PluginManager.h:326
PluginDescriptor::mImporterIdentifier
wxString mImporterIdentifier
Definition: PluginManager.h:158
wxArrayStringEx.h
PluginManagerInterface::ConfigReference
PluginSettings::ConfigReference ConfigReference
Definition: PluginInterface.h:87
PluginSettings::ConfigConstReference
ConfigReferenceGenerator< true, ConfigValueTypes >::type ConfigConstReference
Definition: PluginInterface.h:79
EffectDefinitionInterface
EffectDefinitionInterface is a ComponentInterface that adds some basic read-only information about ef...
Definition: EffectInterface.h:74
PluginTypeExporter
@ PluginTypeExporter
Definition: PluginManager.h:38
key
static const AudacityProject::AttachedObjects::RegisteredFactory key
Definition: CommandManager.cpp:201
PluginManager
PluginManager maintains a list of all plug ins. That covers modules, effects, generators,...
Definition: PluginManager.h:175
PluginManager::AllPlugins
Range AllPlugins()
Definition: PluginManager.h:269
PluginDescriptor::mEnabled
bool mEnabled
Definition: PluginManager.h:143
PluginDescriptor::mEffectRealtime
bool mEffectRealtime
Definition: PluginManager.h:153
PluginManagerInterface::GetConfigValue
virtual bool GetConfigValue(ConfigurationType type, const PluginID &ID, const RegistryPath &group, const RegistryPath &key, ConfigReference var, ConfigConstReference defval)=0
PluginManagerInterface::RemoveConfig
virtual bool RemoveConfig(ConfigurationType type, const PluginID &ID, const RegistryPath &group, const RegistryPath &key)=0
manager
static const AttachedProjectObjects::RegisteredFactory manager
Definition: RealtimeEffectManager.cpp:23
PluginManager::PluginsOfType
Range PluginsOfType(int type)
Definition: PluginManager.h:270
GetID
static PluginID GetID(Effect &effect)
Definition: EffectUI.cpp:27
ComponentInterface
ComponentInterface provides name / vendor / version functions to identify plugins....
Definition: ComponentInterface.h:62
PluginSettings::HasConfigGroup
bool HasConfigGroup(EffectDefinitionInterface &ident, PluginSettings::ConfigurationType type, const RegistryPath &group)
Definition: ConfigInterface.cpp:14
ThemeResources::Load
THEME_RESOURCES_API void Load()
Definition: LoadThemeResources.cpp:13
PluginInterface.h
PluginDescriptor::mEffectAutomatable
bool mEffectAutomatable
Definition: PluginManager.h:154
PluginTypeStub
@ PluginTypeStub
Definition: PluginManager.h:35
PluginSettings::ConfigurationType
ConfigurationType
Definition: PluginInterface.h:55
EffectType
EffectType
Definition: EffectInterface.h:52
PluginManager::Range::end
int end() const
Definition: PluginManager.h:266
PluginDescriptor::mImporterExtensions
FileExtensions mImporterExtensions
Definition: PluginManager.h:159
PluginDescriptor::mEffectType
EffectType mEffectType
Definition: PluginManager.h:149
PluginTypeImporter
@ PluginTypeImporter
Definition: PluginManager.h:39
PluginSettings::ConfigReference
ConfigReferenceGenerator< false, ConfigValueTypes >::type ConfigReference
Definition: PluginInterface.h:77
PluginDescriptor::mEffectFamily
wxString mEffectFamily
Definition: PluginManager.h:148