Automation: AudacityCommand

This is a squash of 50 commits.

This merges the capabilities of BatchCommands and Effects using a new
AudacityCommand class.  AudacityCommand provides one function to specify the
parameters, and then we leverage that one function in automation, whether by chains,
mod-script-pipe or (future) Nyquist.

- Now have AudacityCommand which is using the same mechanism as Effect
- Has configurable parameters
- Has data-entry GUI (built using shuttle GUI)
- Registers with PluginManager.
- Menu commands now provided in chains, and to python batch.
   - Tested with Zoom Toggle.

- ShuttleParams now can set, get, set defaults, validate and specify
the parameters.
- Bugfix: Don't overwrite values with defaults first time out.
- Add DefineParams function for all built-in effects.
- Extend CommandContext to carry output channels for results.

We abuse EffectsManager.  It handles both Effects and
AudacityCommands now.  In time an Effect should become a special case of
AudacityCommand and we'll split and rename the EffectManager class.

- Don't use 'default' as a parameter name.
- Massive renaming for CommandDefinitionInterface
- EffectIdentInterface becomes EffectDefinitionInterface
- EffectAutomationParameters becomes CommandAutomationParameters
- PluginType is now a bit field.

This way we can search for related types at the same time.

- Most old batch commands made into AudacityCommands.
The ones that weren't are for a reason.  They are used by mod-script-pipe
to carry commands and responses across from a non-GUI thread to the GUI
thread.

- Major tidy up of ScreenshotCommand
- Reworking of SelectCommand
- GetPreferenceCommand and SetPreferenceCommand
- GetTrackInfo and SetTrackInfo
- GetInfoCommand
- Help, Open, Save, Import and Export commands.
- Removed obsolete commands ExecMenu, GetProjectInfo and SetProjectInfo
  which are now better handled by other commands.

- JSONify "GetInfo: Commands" output, i.e. commas in the right places.

- General work on better Doxygen.
    - Lyrics -> LyricsPanel
    - Meter -> MeterPanel
- Updated Linux makefile.
- Scripting commands added into Extra menu.
- Distinct names for previously duplicated find-clipping parameters.
- Fixed longstanding error with erroneous status field number which
  previously caused an ASSERT in debug.
- Sensible formatting of numbers in Chains, 0.1 not 0.1000000000137

include/audacity/ConfigInterface.h

@@ -42,6 +42,15 @@
 #ifndef __AUDACITY_CONFIGINTERFACE_H__
 #define __AUDACITY_CONFIGINTERFACE_H__
 
+/*************************************************************************************//**
+
+\class ConfigClientInterface
+
+\brief ConfigClientInterface is an unholy get/set configuration class, which 
+differentiates between private and shared config.  It should probably be replaced 
+with a Shuttle.
+
+*******************************************************************************************/
 class AUDACITY_DLL_API ConfigClientInterface /* not final */
 {
 public:
@@ -84,11 +93,20 @@ public:
    virtual bool RemovePrivateConfig(const wxString & group, const wxString & key) = 0;
 };
 
+#if 0
+/*************************************************************************************//**
+
+\class ConfigHostInterface
+
+\brief ConfigHostInterface appears not to be used.
+
+*******************************************************************************************/
 class ConfigHostInterface
 {
 public:
    virtual ~ConfigHostInterface() {};
 
 };
+#endif
 
 #endif // __AUDACITY_CONFIGINTERFACE_H__

include/audacity/EffectAutomationParameters.h

@@ -3,6 +3,7 @@
    Audacity: A Digital Audio Editor
 
    EffectAutomationParameters.h
+   (defining CommandAutomationParameters)
 
    Leland Lucius
 
@@ -39,8 +40,8 @@
 
 **********************************************************************/
 
-#ifndef __AUDACITY_EFFECTAUTOMATIONPARAMETERS_H__
-#define __AUDACITY_EFFECTAUTOMATIONPARAMETERS_H__
+#ifndef __AUDACITY_COMMAND_AUTOMATION_PARAMETERS_H__
+#define __AUDACITY_COMMAND_AUTOMATION_PARAMETERS_H__
 
 #include <locale.h>
 
@@ -48,10 +49,22 @@
 #include <wx/fileconf.h>
 #include <wx/intl.h>
 
-class EffectAutomationParameters : public wxFileConfig
+
+/**
+\brief CommandAutomationParameters, derived from wxFileConfig, is essentially doing 
+the same things as the Shuttle classes.  It does text <-> binary conversions of
+parameters.  It does not seem to be using actual file read/writing.  
+
+Should it be converted to using Shuttle?  Probably yes.  Shuttle leads to shorter code.  
+And Shuttle is more multi-functional since Shuttle can report on signature, do the work of 
+wxWidget validators, and can create default dialogs.  However until that conversion is 
+done, we need this class, and we use a pointer to one from within a Shuttle when interfacing
+with the code that still uses it.
+*/
+class CommandAutomationParameters final : public wxFileConfig
 {
 public:
-   EffectAutomationParameters(const wxString & parms = wxEmptyString)
+   CommandAutomationParameters(const wxString & parms = wxEmptyString)
    :  wxFileConfig(wxEmptyString,
                    wxEmptyString,
                    wxEmptyString,
@@ -61,7 +74,7 @@ public:
       SetParameters(parms);
    }
 
-   virtual ~EffectAutomationParameters()
+   virtual ~CommandAutomationParameters()
    {
    }
 
@@ -114,7 +127,7 @@ public:
 
    virtual bool DoWriteDouble(const wxString & key, double value) override
    {
-      return DoWriteString(key, wxString::Format(wxT("%.12f"), value));
+      return DoWriteString(key, wxString::Format(wxT("%g"), value));
    }
 
    bool ReadFloat(const wxString & key, float *pf) const

include/audacity/EffectInterface.h

@@ -45,7 +45,7 @@
 #include "audacity/Types.h"
 #include "audacity/IdentInterface.h"
 #include "audacity/ConfigInterface.h"
-#include "audacity/EffectAutomationParameters.h"
+#include "audacity/EffectAutomationParameters.h" // for command automation
 
 #include <wx/dialog.h>
 
@@ -58,10 +58,35 @@ typedef enum EffectType
    EffectTypeAnalyze
 } EffectType;
 
-class AUDACITY_DLL_API EffectIdentInterface  /* not final */ : public IdentInterface
+class ShuttleParams;
+
+/*************************************************************************************//**
+
+\class CommandDefinitionInterface 
+\brief CommandDefinitionInterface is an IdentInterface (to name the command) along with a
+DefineParameters virtual function, that defines the parameters of the command.
+
+*******************************************************************************************/
+class AUDACITY_DLL_API CommandDefinitionInterface  /* not final */ : public IdentInterface
 {
 public:
-   virtual ~EffectIdentInterface() {};
+   virtual ~CommandDefinitionInterface() {};
+   // returns true if implemented.
+   virtual bool DefineParams( ShuttleParams & WXUNUSED(S) ){ return false;};
+};
+
+/*************************************************************************************//**
+
+\class EffectDefinitionInterface 
+
+\brief EffectDefinitionInterface is a CommandDefinitionInterface that additionally tracks
+flag-functions for interactivity, play-preview and whether the effect can run without a GUI.
+
+*******************************************************************************************/
+class AUDACITY_DLL_API EffectDefinitionInterface  /* not final */ : public CommandDefinitionInterface
+{
+public:
+   virtual ~EffectDefinitionInterface() {};
 
    virtual EffectType GetType() = 0;
 
@@ -94,6 +119,15 @@ public:
 class EffectUIHostInterface;
 class EffectUIClientInterface;
 
+/*************************************************************************************//**
+
+\class EffectHostInterface 
+
+\brief EffectHostInterface is a decorator of a EffectUIClientInterface.  It adds 
+virtual (abstract) functions to get presets and actually apply the effect.  It uses
+ConfigClientInterface to add Getters/setters for private and shared configs. 
+
+*******************************************************************************************/
 class AUDACITY_DLL_API EffectHostInterface  /* not final */ : public ConfigClientInterface
 {
 public:
@@ -116,7 +150,16 @@ public:
    virtual wxString GetFactoryDefaultsGroup() = 0;
 };
 
-class AUDACITY_DLL_API EffectClientInterface  /* not final */ : public EffectIdentInterface
+/*************************************************************************************//**
+
+\class EffectClientInterface 
+
+\brief EffectClientInterface provides the ident interface to Effect, and is what makes
+Effect into a plug-in command.  It has functions for realtime that are not part of 
+AudacityCommand.
+
+*******************************************************************************************/
+class AUDACITY_DLL_API EffectClientInterface  /* not final */ : public EffectDefinitionInterface
 {
 public:
    virtual ~EffectClientInterface() {};
@@ -151,9 +194,15 @@ public:
    virtual bool RealtimeProcessEnd() = 0;
 
    virtual bool ShowInterface(wxWindow *parent, bool forceModal = false) = 0;
-
-   virtual bool GetAutomationParameters(EffectAutomationParameters & parms) = 0;
-   virtual bool SetAutomationParameters(EffectAutomationParameters & parms) = 0;
+   // Some effects will use define params to define what parameters they take.
+   // If they do, they won't need to implement Get or SetAutomation parameters.
+   // since the Effect class can do it.  Or at least that is how things happen
+   // in AudacityCommand.  IF we do the same in class Effect, then Effect maybe 
+   // should derive by some route from AudacityCommand to pick up that 
+   // functionality.
+   //virtual bool DefineParams( ShuttleParams & S){ return false;};
+   virtual bool GetAutomationParameters(CommandAutomationParameters & parms) = 0;
+   virtual bool SetAutomationParameters(CommandAutomationParameters & parms) = 0;
 
    virtual bool LoadUserPreset(const wxString & name) = 0;
    virtual bool SaveUserPreset(const wxString & name) = 0;
@@ -163,12 +212,29 @@ public:
    virtual bool LoadFactoryDefaults() = 0;
 };
 
+/*************************************************************************************//**
+
+\class EffectUIHostInterface
+
+\brief EffectUIHostInterface has nothing in it.  It is provided so that an Effect
+can call SetHostUI passing in a pointer to an EffectUIHostInterface.  It contains no 
+functionality and is provided, apparently, for type checking.  Since only EffectUIHost
+uses it, EffectUIHost could be used instead.
+*******************************************************************************************/
 class AUDACITY_DLL_API EffectUIHostInterface
 {
 public:
    virtual ~EffectUIHostInterface() {};
 };
 
+/*************************************************************************************//**
+
+\class EffectUIClientInterface
+
+\brief EffectUIClientInterface is an abstract base class to populate a UI and validate UI
+values.  It can import and export presets.
+
+*******************************************************************************************/
 class AUDACITY_DLL_API EffectUIClientInterface /* not final */
 {
 public:
@@ -189,6 +255,15 @@ public:
    virtual void ShowOptions() = 0;
 };
 
+
+/*************************************************************************************//**
+
+\class EffectManagerInterface
+
+\brief UNUSED.  EffectManagerInterface provides a single function to find files matching 
+a pattern in a list.
+
+*******************************************************************************************/
 class AUDACITY_DLL_API EffectManagerInterface
 {
 public:

include/audacity/IdentInterface.h

@@ -44,6 +44,11 @@
 
 #include "audacity/Types.h"
 
+/**************************************************************************//**
+
+\brief IdentInterface provides name / vendor / version functions to identify
+plugins.  It is what makes a class a plug-in.
+********************************************************************************/
 class AUDACITY_DLL_API IdentInterface /* not final */
 {
 public:

include/audacity/ModuleInterface.h

@@ -120,11 +120,10 @@ public:
    // Return value is the number of plugins found.
    using RegistrationCallback =
       std::function<
-         const PluginID &(ModuleInterface *, EffectIdentInterface *) >;
+         const PluginID &(ModuleInterface *, CommandDefinitionInterface *) >;
    virtual unsigned DiscoverPluginsAtPath(
       const wxString & path, wxString &errMsg,
-      const RegistrationCallback &callback =
-         PluginManagerInterface::DefaultRegistrationCallback)
+      const RegistrationCallback &callback )
          = 0;
 
    // For modules providing an interface to other dynamically loaded plugins,

include/audacity/PluginInterface.h

@@ -48,19 +48,23 @@
 #include "audacity/ImporterInterface.h"
 #include "audacity/ModuleInterface.h"
 
+
 class ModuleInterface;
 
+
 class PluginManagerInterface /* not final */
 {
 public:
 
    static const PluginID &DefaultRegistrationCallback(
-      ModuleInterface *provider, EffectIdentInterface *ident );
+      ModuleInterface *provider, CommandDefinitionInterface *ident );
+   static const PluginID &GenericRegistrationCallback(
+      ModuleInterface *provider, CommandDefinitionInterface *ident );
 
    virtual bool IsPluginRegistered(const wxString & path) = 0;
 
    virtual const PluginID & RegisterPlugin(ModuleInterface *module) = 0;
-   virtual const PluginID & RegisterPlugin(ModuleInterface *provider, EffectIdentInterface *effect) = 0;
+   virtual const PluginID & RegisterPlugin(ModuleInterface *provider, EffectDefinitionInterface *effect, int type) = 0;
    virtual const PluginID & RegisterPlugin(ModuleInterface *provider, ImporterInterface *importer) = 0;
 
    virtual void FindFilesInPathList(const wxString & pattern,