New library for registries

libraries/CMakeLists.txt

@@ -13,6 +13,7 @@ set( LIBRARIES
    lib-preferences
    lib-math
    lib-files
+   lib-registries
 )
 
 if ( ${_OPT}has_networking )

libraries/lib-registries/CMakeLists.txt

@@ -0,0 +1,47 @@
+#[[
+Some utilities for allowing open-endedness and decoupling of designs, by
+maintaining global tables that can be populated at static initialization by
+code in scattered places, on which the registry has no build dependency.
+
+AttachedVirtualFunction implements "open methods" -- functions that type-switch
+on the first argument, and dispatch to the correct implementation, but without
+intrusiveness into the base of the class hierarchy.  This allows the set of
+methods and the set of subclasses both to be open-ended.
+
+(That is unlike in the "Gang of Four" Visitor pattern, in which the set of
+methods becomes open-ended while the set of subclasses is closed-ended: the
+Visitor can't handle a new subclass without intrusion into the abstract
+Visitor definition.)
+
+ClientData allows a "Site" class to act as a container of attached objects
+produced by registered factory functions, and retrieved by the various attaching
+modules.  The Site's constructor is effectively hookable.  This in particular
+allows the Project object to be low-level in the graph of file dependencies,
+while it is also the top-level object of an ownership tree of various important
+sub-structures.  This is another "Dependency Inversion" of sorts (the D
+principle of SOLID).
+
+Registry implements trees of objects identified by textual paths, and allows
+scattered code to insert items or subtrees at specified paths.  Registry
+computes the merging of trees, and supports visitation.  It is used notably
+by the tree of menus, allowing insertion of menu items in decoupled code.
+]]#
+
+set( SOURCES
+   AttachedVirtualFunction.h
+   ClientData.cpp
+   ClientData.h
+   ClientDataHelpers.h
+   Registrar.h
+   Registry.cpp
+   Registry.h
+)
+set( LIBRARIES
+   lib-preferences-interface
+   lib-exceptions
+   PRIVATE
+   wxBase
+)
+audacity_library( lib-registries "${SOURCES}" "${LIBRARIES}"
+   "" ""
+)

libraries/lib-registries/ClientData.cpp

@@ -0,0 +1,15 @@
+/*!********************************************************************
+
+Audacity: A Digital Audio Editor
+
+@file ClientData.cpp
+
+Paul Licameli
+
+**********************************************************************/
+
+#include "ClientData.h"
+
+// These are needed out-of-line for the Windows link
+ClientData::Base::~Base() = default;
+template<> ClientData::Cloneable<>::~Cloneable() = default;

libraries/lib-registries/ClientData.h

@@ -24,9 +24,9 @@ Paul Licameli
 namespace ClientData {
 
 //! A convenient default parameter for class template @b Site
-struct AUDACITY_DLL_API Base
+struct REGISTRIES_API Base
 {
-   virtual ~Base() {}
+   virtual ~Base();
 };
 
 //! A one-argument alias template for the default template-template parameter of ClientData::Site
@@ -44,12 +44,12 @@ template< typename Object > using BarePtr = Object*;
  */
 template<
    template<typename> class Owner = UniquePtr
-> struct AUDACITY_DLL_API Cloneable
+> struct REGISTRIES_API Cloneable
 {
    using Base = Cloneable;
    using PointerType = Owner< Base >;
 
-   virtual ~Cloneable() {}
+   virtual ~Cloneable();
    virtual PointerType Clone() const = 0;
 };
 

libraries/lib-registries/Registrar.h

@@ -29,7 +29,7 @@ class LoadableModule;
 class ComponentInterface;
 class Effect;
 
-class AUDACITY_DLL_API Registrar 
+class REGISTRIES_API Registrar 
 {
 public:
    Registrar(){

libraries/lib-registries/Registry.cpp

@@ -14,7 +14,7 @@ Paul Licameli split from Menus.cpp
 
 #include <wx/log.h>
 
-#include "widgets/AudacityMessageBox.h"
+#include "BasicUI.h"
 
 namespace {
 
@@ -174,7 +174,7 @@ using Path = std::vector< Identifier >;
         wxLogDebug( msg.Translation() );
 #ifdef IS_ALPHA
         // user-visible message
-        AudacityMessageBox( msg );
+        BasicUI::ShowMessageBox( msg );
 #endif
      }
    }

libraries/lib-registries/Registry.h

@@ -56,7 +56,7 @@ namespace Registry {
    // Most items in the table will be the large ones describing commands, so the
    // waste of space in unions for separators and sub-menus should not be
    // large.
-   struct AUDACITY_DLL_API BaseItem {
+   struct REGISTRIES_API BaseItem {
       // declare at least one virtual function so dynamic_cast will work
       explicit
       BaseItem( const Identifier &internalName )
@@ -79,7 +79,7 @@ namespace Registry {
    // static tables of items to be computed once and reused
    // The name of the delegate is significant for path calculations, but the
    // SharedItem's ordering hint is used if the delegate has none
-   struct AUDACITY_DLL_API SharedItem final : BaseItem {
+   struct REGISTRIES_API SharedItem final : BaseItem {
       explicit SharedItem( const BaseItemSharedPtr &ptr_ )
          : BaseItem{ wxEmptyString }
          , ptr{ ptr_ }
@@ -97,7 +97,7 @@ namespace Registry {
    // the ComputedItem is visited
    // The name of the substitute is significant for path calculations, but the
    // ComputedItem's ordering hint is used if the substitute has none
-   struct AUDACITY_DLL_API ComputedItem final : BaseItem {
+   struct REGISTRIES_API ComputedItem final : BaseItem {
       // The type of functions that generate descriptions of items.
       // Return type is a shared_ptr to let the function decide whether to
       // recycle the object or rebuild it on demand each time.
@@ -117,13 +117,13 @@ namespace Registry {
    };
 
    // Common abstract base class for items that are not groups
-   struct AUDACITY_DLL_API SingleItem : BaseItem {
+   struct REGISTRIES_API SingleItem : BaseItem {
       using BaseItem::BaseItem;
       ~SingleItem() override = 0;
    };
 
    // Common abstract base class for items that group other items
-   struct AUDACITY_DLL_API GroupItem : BaseItem {
+   struct REGISTRIES_API GroupItem : BaseItem {
       using BaseItem::BaseItem;
 
       // Construction from an internal name and a previously built-up
@@ -231,14 +231,14 @@ namespace Registry {
    // The sequence of calls to RegisterItem has no significance for
    // determining the visitation ordering.  When sequence is important, register
    // a GroupItem.
-   AUDACITY_DLL_API
+   REGISTRIES_API
    void RegisterItem( GroupItem &registry, const Placement &placement,
       BaseItemPtr pItem );
    
    // Define actions to be done in Visit.
    // Default implementations do nothing
    // The supplied path does not include the name of the item
-   class AUDACITY_DLL_API Visitor
+   class REGISTRIES_API Visitor
    {
    public:
       virtual ~Visitor();
@@ -257,7 +257,7 @@ namespace Registry {
    // seen in the registry for the first time is placed somehere, and that
    // ordering should be kept the same thereafter in later runs (which may add
    // yet other previously unknown items).
-   void Visit(
+   REGISTRIES_API void Visit(
       Visitor &visitor,
       BaseItem *pTopItem,
       const GroupItem *pRegistry = nullptr );
@@ -269,7 +269,7 @@ namespace Registry {
    // registry of plug-ins, and something must be done to preserve old
    // behavior.  It can be done in the central place using string literal
    // identifiers only, not requiring static compilation or linkage dependency.
-   struct AUDACITY_DLL_API
+   struct REGISTRIES_API
    OrderingPreferenceInitializer : PreferenceInitializer {
       using Literal = const wxChar *;
       using Pair = std::pair< Literal, Literal >;

src/CMakeLists.txt

@@ -84,7 +84,6 @@ list( APPEND SOURCES
       AdornedRulerPanel.h
       AllThemeResources.cpp
       AllThemeResources.h
-      AttachedVirtualFunction.h
       AudacityApp.cpp
       AudacityApp.h
       $<$<BOOL:${wxIS_MAC}>:AudacityApp.mm>
@@ -110,8 +109,6 @@ list( APPEND SOURCES
       CellularPanel.cpp
       CellularPanel.h
       ClassicThemeAsCeeCode.h
-      ClientData.h
-      ClientDataHelpers.h
       Clipboard.cpp
       Clipboard.h
       CommonCommandFlags.cpp
@@ -217,9 +214,6 @@ list( APPEND SOURCES
       ProjectWindowBase.cpp
       ProjectWindowBase.h
       RefreshCode.h
-      Registrar.h
-      Registry.cpp
-      Registry.h
       RingBuffer.cpp
       RingBuffer.h
       SampleBlock.cpp

src/commands/AudacityCommand.h

@@ -23,7 +23,7 @@
 #include "ComponentInterface.h"
 #include "EffectAutomationParameters.h" // for command automation
 
-#include "../Registrar.h"
+#include "Registrar.h"
 
 class ShuttleGui;
 

src/commands/CommandManager.h

@@ -14,14 +14,14 @@
 
 #include "Identifier.h"
 
-#include "../ClientData.h"
+#include "ClientData.h"
 #include "CommandFunctors.h"
 #include "CommandFlag.h"
 
 #include "Keyboard.h"
 
 #include "Prefs.h"
-#include "../Registry.h"
+#include "Registry.h"
 
 #include <vector>
 

src/export/Export.h

@@ -19,7 +19,7 @@
 #include "../widgets/wxPanelWrapper.h" // to inherit
 #include "FileNames.h" // for FileTypes
 
-#include "../Registry.h"
+#include "Registry.h"
 
 class wxArrayString;
 class FileDialogWrapper;

src/import/Import.h

@@ -19,7 +19,7 @@
 #include "../widgets/wxPanelWrapper.h" // to inherit
 #include "FileNames.h" // for FileType
 
-#include "../Registry.h"
+#include "Registry.h"
 
 class wxArrayString;
 class wxListBox;

src/prefs/PrefsPanel.h

@@ -30,7 +30,7 @@ MousePrefs, QualityPrefs, SpectrumPrefs and ThemePrefs.
 #include <functional>
 #include "../widgets/wxPanelWrapper.h" // to inherit
 #include "ComponentInterface.h"
-#include "../Registry.h"
+#include "Registry.h"
 
 /* A few constants for an attempt at semi-uniformity */
 #define PREFS_FONT_SIZE     8

src/toolbars/ToolManager.h

@@ -20,7 +20,7 @@
 #include <wx/frame.h> // to inherit
 #include <wx/timer.h> // member variable
 
-#include "../ClientData.h"
+#include "ClientData.h"
 #include "ToolDock.h"
 
 #include "../commands/CommandFunctors.h"

src/tracks/playabletrack/wavetrack/ui/WaveTrackView.h

@@ -12,7 +12,7 @@ Paul Licameli split from class WaveTrack
 #define __AUDACITY_WAVE_TRACK_VIEW__
 
 #include "../../../ui/CommonTrackView.h"
-#include "../../../../ClientData.h"
+#include "ClientData.h"
 #include "SampleCount.h"
 namespace WaveTrackViewConstants{ enum Display : int; }
 struct WaveTrackSubViewType;

src/tracks/ui/BackgroundCell.h

@@ -11,7 +11,7 @@ Paul Licameli split from TrackPanel.cpp
 #ifndef __AUDACITY_BACKGROUND_CELL__
 #define __AUDACITY_BACKGROUND_CELL__
 
-#include "../../ClientData.h"
+#include "ClientData.h"
 #include "CommonTrackPanelCell.h"
 
 class AudacityProject;

src/tracks/ui/EditCursorOverlay.h

@@ -12,7 +12,7 @@ Paul Licameli split from TrackPanel.cpp
 #define __AUDACITY_EDIT_CURSOR_OVERLAY__
 
 #include <memory>
-#include "../../ClientData.h" // to inherit
+#include "ClientData.h" // to inherit
 #include "../../widgets/Overlay.h" // to inherit
 
 class AudacityProject;

src/tracks/ui/PlayIndicatorOverlay.h

@@ -13,7 +13,7 @@ Paul Licameli split from TrackPanel.cpp
 
 #include <wx/event.h> // to inherit
 #include <memory>
-#include "../../ClientData.h"
+#include "ClientData.h"
 #include "../../widgets/Overlay.h" // to inherit
 
 class AudacityProject;

src/tracks/ui/ScrubUI.cpp

@@ -12,7 +12,7 @@
 
 #include "Scrubbing.h"
 #include "../../widgets/Overlay.h"
-#include "../../ClientData.h"
+#include "ClientData.h"
 #include "../../AdornedRulerPanel.h"
 #include "../../Project.h"
 #include "../../ProjectWindow.h"

src/tracks/ui/Scrubbing.h

@@ -17,7 +17,7 @@ Paul Licameli split from TrackPanel.cpp
 #include <wx/longlong.h>
 
 #include "../../AudioIOBase.h" // for ScrubbingOptions
-#include "../../ClientData.h" // to inherit
+#include "ClientData.h" // to inherit
 #include "Prefs.h" // to inherit
 #include "../../widgets/Overlay.h" // to inherit
 #include "../../commands/CommandContext.h"

src/tracks/ui/TimeShiftHandle.h

@@ -15,7 +15,7 @@ Paul Licameli
 #include <unordered_map>
 #include <vector>
 
-#include "../../AttachedVirtualFunction.h"
+#include "AttachedVirtualFunction.h"
 #include "../../UIHandle.h"
 
 class SnapManager;

src/tracks/ui/TrackControls.h

@@ -28,7 +28,7 @@ public:
    virtual ~TrackControls() = 0;
 };
 
-#include "../../AttachedVirtualFunction.h"
+#include "AttachedVirtualFunction.h"
 
 struct DoGetControlsTag;
 

src/tracks/ui/TrackView.cpp

@@ -11,7 +11,7 @@ Paul Licameli split from TrackPanel.cpp
 #include "TrackView.h"
 #include "../../Track.h"
 
-#include "../../ClientData.h"
+#include "ClientData.h"
 #include "../../Project.h"
 #include "../../xml/XMLTagHandler.h"
 #include "../../xml/XMLWriter.h"

src/tracks/ui/TrackView.h

@@ -103,7 +103,7 @@ private:
    int            mHeight{ DefaultHeight };
 };
 
-#include "../../AttachedVirtualFunction.h"
+#include "AttachedVirtualFunction.h"
 
 struct DoGetViewTag;