![]() |
Audacity 3.2.0
|
Utility to register hooks into a host class that attach client data. More...
#include <ClientData.h>
Classes | |
class | RegisteredFactory |
Client code makes static instance from a factory of attachments; passes it to Get or Find as a retrieval key. More... | |
Public Types | |
using | DataType = ClientData |
using | DataPointer = Pointer< ClientData > |
using | DataFactory = std::function< DataPointer(Host &) > |
Type of function from which RegisteredFactory is constructed; it builds attachments. More... | |
Public Member Functions | |
~Site () | |
Site () | |
Site (const Site &other) | |
Site & | operator= (const Site &other) |
Site (Site &&other) | |
Site & | operator= (Site &&other) |
size_t | size () const |
How many attachment pointers are in the Site. More... | |
Retrieval and reassignment of attachments | |
template<typename Subclass = ClientData> | |
Subclass & | Get (const RegisteredFactory &key) |
Get reference to an attachment, creating on demand if not present, down-cast it to Subclass. More... | |
template<typename Subclass = const ClientData> | |
auto | Get (const RegisteredFactory &key) const -> std::enable_if_t< std::is_const< Subclass >::value, Subclass & > |
Get reference to an attachment, creating on demand if not present, down-cast it to Subclass. More... | |
template<typename Subclass = ClientData> | |
Subclass * | Find (const RegisteredFactory &key) |
Get a (bare) pointer to an attachment, or null, down-cast it to Subclass *; will not create on demand. More... | |
template<typename Subclass = const ClientData> | |
auto | Find (const RegisteredFactory &key) const -> std::enable_if_t< std::is_const< Subclass >::value, Subclass * > |
Get a (bare) pointer to an attachment, or null, down-cast it to Subclass *; will not create on demand. More... | |
template<typename ReplacementPointer > | |
void | Assign (const RegisteredFactory &key, ReplacementPointer &&replacement) |
Reassign Site's pointer to ClientData. More... | |
Static Public Member Functions | |
static size_t | numFactories () |
How many static factories have been registered with this specialization of Site. More... | |
Protected Member Functions | |
member functions for use by @b Host | |
template<typename Function > | |
void | ForEach (const Function &function) |
Invoke function on each ClientData object that has been created in this . More... | |
template<typename Function > | |
void | ForEach (const Function &function) const |
Invoke function on each ClientData object that has been created in this . More... | |
template<typename Function > | |
ClientData * | FindIf (const Function &function) |
Return pointer to first attachment in this that is not null and satisfies a predicate, or nullptr. More... | |
template<typename Function > | |
const ClientData * | FindIf (const Function &function) const |
Return pointer to first attachment in this that is not null and satisfies a predicate, or nullptr. More... | |
void | BuildAll () |
For each RegisteredFactory, if the corresponding attachment is absent in this , build and store it. More... | |
Private Types | |
using | DataFactories = Lockable< std::vector< DataFactory >, RegistryLockingPolicy > |
using | DataContainer = Lockable< Copyable< std::vector< DataPointer >, ObjectCopyingPolicy >, ObjectLockingPolicy > |
Private Member Functions | |
template<typename Subclass > | |
Subclass & | DoGet (Locked< DataContainer > &data, const RegisteredFactory &key) |
template<typename Subclass > | |
Subclass * | DoFind (Locked< DataContainer > &data, const RegisteredFactory &key) |
Locked< DataContainer > | GetData () |
Locked< const DataContainer > | GetData () const |
DataPointer & | Build (Locked< DataContainer > &, typename DataContainer::iterator iter, size_t index) |
Static Private Member Functions | |
static Locked< DataFactories > | GetFactories () |
static void | EnsureIndex (Locked< DataContainer > &data, size_t index) |
static DataContainer::iterator | GetIterator (Locked< DataContainer > &data, size_t index) |
Private Attributes | |
decltype(Dereferenceable(std::declval< DataPointer & >())) | Slot (Locked< DataContainer > &data, const RegisteredFactory &key, bool create) |
DataContainer | mData |
Container of pointers returned by factories, per instance of Host class. More... | |
Utility to register hooks into a host class that attach client data.
This allows the host object to be the root of an ownership tree of sub-objects at run-time, but inverting the compile-time dependency among implementation files: The host's implementation is in low-level files, and cyclic file dependencies are avoided. The set of client objects attached to each host object is not fixed in the definition of the host class, but instead a system of registration of factories of client objects lets it be open-ended.
Besides mere storage and retrieval, this can also implement the observer pattern, in which the host pushes notifications to some virtual function defined in each attached item.
If the client only needs retrieval, it might need construction of data only on demand. But if the host is meant to push notifications to the clients, then the host class is responsible for forcing early building of all ClientData when host is constructed, as in the example above.
If registration of a factory happens after some host objects are already in existence, their associated client data fail to be created if you rely only on BuildAll in the @B Host constructor. Early deregistration of factories is permitted, in which case any later constructed host objects will carry null pointers in the associated slot, and a small "leak" in the space of per-host slots will persist until the program exits. All such usage is not recommended.
Host | Type that derives from this base class; it supports hooks to invoke attached object factories. This is an example of the curiously recurring template pattern |
ClientData | Common base class of attachments; must have a virtual destructor |
CopyingPolicy | CopyingPolicy value Chooses deep, shallow, or (default) no-op copying of attachments |
Pointer | The kind of pointer Host will hold to ClientData; default is std::unique_ptr. You might want to use std::shared_ptr, std::weak_ptr, or wxWeakRef instead |
ObjectLockingPolicy | LockingPolicy value chooses thread safety policy for array of attachments in each Host, default is unsafe |
RegistryLockingPolicy | LockingPolicy value chooses thread safety policy for the static table of attachment factory functions, default is unsafe |
Definition at line 227 of file ClientData.h.
|
private |
Definition at line 474 of file ClientData.h.
|
private |
Definition at line 472 of file ClientData.h.
using ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::DataFactory = std::function< DataPointer( Host& ) > |
Type of function from which RegisteredFactory is constructed; it builds attachments.
Definition at line 239 of file ClientData.h.
using ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::DataPointer = Pointer< ClientData > |
Definition at line 237 of file ClientData.h.
using ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::DataType = ClientData |
Definition at line 236 of file ClientData.h.
|
inline |
Definition at line 230 of file ClientData.h.
|
inline |
Definition at line 241 of file ClientData.h.
References ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetFactories(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::mData, and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::size().
|
inline |
Definition at line 247 of file ClientData.h.
|
inline |
Definition at line 252 of file ClientData.h.
|
inline |
Reassign Site's pointer to ClientData.
If ObjectLockingPolicy isn't default, then reassignments are serialized.
ReplacementPointer | Pointer<Subclass> where Subclass derives ClientData |
key | Reference to static object created in client code |
replacement | A temporary or std::move'd pointer |
Definition at line 363 of file ClientData.h.
References ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::EnsureIndex(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetData(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetIterator(), key, and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::RegisteredFactory::mIndex.
Referenced by AdornedRulerPanel::Destroy(), and TrackPanel::Destroy().
|
inlineprivate |
Definition at line 551 of file ClientData.h.
References ClientData::Dereferenceable(), cloud::factory, ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetFactories(), and audacity::network_manager::common_headers::Host.
Referenced by ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::BuildAll().
|
inlineprotected |
For each RegisteredFactory, if the corresponding attachment is absent in this
, build and store it.
Definition at line 449 of file ClientData.h.
References ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::Build(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::EnsureIndex(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetData(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetFactories(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetIterator(), and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::size().
Referenced by WaveChannelView::BuildSubViews().
|
inlineprivate |
Definition at line 502 of file ClientData.h.
References key, and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::Slot.
|
inlineprivate |
Definition at line 491 of file ClientData.h.
References key, ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::Slot, and THROW_INCONSISTENCY_EXCEPTION.
|
inlinestaticprivate |
Definition at line 532 of file ClientData.h.
References ClientData::Locked< Lockable >::mObject.
Referenced by ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::Assign(), and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::BuildAll().
|
inline |
Get a (bare) pointer to an attachment, or null, down-cast it to Subclass *; will not create on demand.
(Lifetime of the object may depend on the host's lifetime and also on the client's use of Assign(). Site is not responsible for guarantees.)
Subclass | Expected actual type of attachment, assumed to be correct |
key | Reference to static object created in client code |
Definition at line 341 of file ClientData.h.
References ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetData(), and key.
Referenced by AdornedRulerPanel::Destroy(), TrackPanel::Destroy(), TimeShiftHandle::Drag(), ProjectWindow::Find(), anonymous_namespace{SyncLock.cpp}::FindSyncLockGroup(), and WaveTrack::ReallyDoGetChannelGroup().
|
inline |
Get a (bare) pointer to an attachment, or null, down-cast it to Subclass *; will not create on demand.
(Lifetime of the object may depend on the host's lifetime and also on the client's use of Assign(). Site is not responsible for guarantees.)
Subclass | Expected actual type of attachment, assumed to be correct |
key | Reference to static object created in client code |
const overload returns pointers to const only.
Definition at line 350 of file ClientData.h.
References ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetData(), and key.
|
inlineprotected |
Return pointer to first attachment in this
that is not null and satisfies a predicate, or nullptr.
Beware that the sequence of visitation is not specified.
Function | takes reference to ClientData, returns value convertible to bool |
function | of type Function |
Definition at line 420 of file ClientData.h.
References ClientData::Dereferenceable(), and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetData().
Referenced by NoteTrack::HandleXMLTag(), and WaveChannelView::ToggleSubView().
|
inlineprotected |
Return pointer to first attachment in this
that is not null and satisfies a predicate, or nullptr.
Beware that the sequence of visitation is not specified.
Function | takes reference to ClientData, returns value convertible to bool |
function | of type Function |
const overload only compiles with a function callable with a const reference to ClientData.
Definition at line 434 of file ClientData.h.
References ClientData::Dereferenceable(), and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetData().
|
inlineprotected |
Invoke function on each ClientData object that has been created in this
.
Function | takes reference to ClientData, return value is ignored |
function | of type Function |
Definition at line 388 of file ClientData.h.
References ClientData::Dereferenceable(), and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetData().
Referenced by WaveChannelView::DoSetDisplay(), WaveChannelView::DoSetMinimized(), WaveChannelView::GetAllSubViews(), WaveChannelView::GetDisplays(), WaveChannelView::GetSubViews(), Track::HandleCommonXMLAttribute(), WaveChannelView::Reparent(), and Track::WriteCommonXMLAttributes().
|
inlineprotected |
Invoke function on each ClientData object that has been created in this
.
Function | takes reference to ClientData, return value is ignored |
function | of type Function |
const overload only compiles with a function that takes reference to const ClientData.
Definition at line 401 of file ClientData.h.
References ClientData::Dereferenceable(), and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetData().
|
inline |
Get reference to an attachment, creating on demand if not present, down-cast it to Subclass.
Uses static_cast. Throws on failure to create it. (Lifetime of the object may depend on the host's lifetime and also on the client's use of Assign(). Site is not responsible for guarantees.)
Subclass | Expected actual type of attachment, assumed to be correct |
key | Reference to static object created in client code |
Definition at line 317 of file ClientData.h.
References ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetData(), and key.
Referenced by SetTrackStatusCommand::ApplyInner(), AdornedRulerPanel::Get(), ProjectWindow::Get(), RealtimeEffectPanel::Get(), TrackPanel::Get(), WaveTrackFactory::Get(), anonymous_namespace{WaveTrack.cpp}::WaveTrackData::Get(), RealtimeEffectStateUI::Get(), TrackPanel::GetFocusedCell(), LabelTrackView::IsValidIndex(), anonymous_namespace{Contrast.cpp}::anonymous_namespace{Contrast.cpp}::OnContrast(), anonymous_namespace{HistoryWindow.cpp}::OnHistory(), NavigationActions::Handler::OnLastTrack(), anonymous_namespace{MixerBoard.cpp}::OnMixerBoard(), anonymous_namespace{FreqWindow.cpp}::OnPlotSpectrum(), WaveTrackMenuTable::OnSwapChannels(), NavigationActions::Handler::OnToggle(), anonymous_namespace{TrackMenus.cpp}::OnTrackClose(), anonymous_namespace{TrackMenus.cpp}::OnTrackGain(), anonymous_namespace{TrackMenus.cpp}::OnTrackGainDec(), anonymous_namespace{TrackMenus.cpp}::OnTrackGainInc(), anonymous_namespace{TrackMenus.cpp}::OnTrackMoveBottom(), anonymous_namespace{TrackMenus.cpp}::OnTrackMoveDown(), anonymous_namespace{TrackMenus.cpp}::OnTrackMoveTop(), anonymous_namespace{TrackMenus.cpp}::OnTrackMoveUp(), anonymous_namespace{TrackMenus.cpp}::OnTrackMute(), anonymous_namespace{TrackMenus.cpp}::OnTrackPan(), anonymous_namespace{TrackMenus.cpp}::OnTrackPanLeft(), anonymous_namespace{TrackMenus.cpp}::OnTrackPanRight(), anonymous_namespace{TrackMenus.cpp}::OnTrackSolo(), EffectNoiseRemoval::ProcessOne(), GetInfoCommand::SendTracks(), MuteButtonHandle::Tip(), SoloButtonHandle::Tip(), EffectsButtonHandle::Tip(), MenuButtonHandle::Tip(), and CloseButtonHandle::Tip().
|
inline |
Get reference to an attachment, creating on demand if not present, down-cast it to Subclass.
Uses static_cast. Throws on failure to create it. (Lifetime of the object may depend on the host's lifetime and also on the client's use of Assign(). Site is not responsible for guarantees.)
Subclass | Expected actual type of attachment, assumed to be correct |
key | Reference to static object created in client code |
const overload returns const references only.
Definition at line 326 of file ClientData.h.
References ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetData(), and key.
|
inlineprivate |
Definition at line 522 of file ClientData.h.
Referenced by ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::Assign(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::BuildAll(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::Find(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::FindIf(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::ForEach(), and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::Get().
|
inlineprivate |
Definition at line 527 of file ClientData.h.
|
inlinestaticprivate |
Definition at line 511 of file ClientData.h.
Referenced by ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::Build(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::BuildAll(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::numFactories(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::RegisteredFactory::RegisteredFactory(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::Site(), and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::RegisteredFactory::~RegisteredFactory().
|
inlinestaticprivate |
Definition at line 539 of file ClientData.h.
References ClientData::Locked< Lockable >::mObject.
Referenced by ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::Assign(), and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::BuildAll().
|
inlinestatic |
How many static factories have been registered with this specialization of Site.
Usually agrees with the size() of each site unless some registrations happened later than some Site's construction.
Definition at line 266 of file ClientData.h.
Referenced by Append().
|
inline |
Definition at line 250 of file ClientData.h.
|
inline |
Definition at line 255 of file ClientData.h.
|
inline |
How many attachment pointers are in the Site.
Definition at line 259 of file ClientData.h.
Referenced by ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::BuildAll(), WaveChannelView::BuildSubViews(), anonymous_namespace{TransportMenus.cpp}::DoMoveToLabel(), anonymous_namespace{TrackMenus.cpp}::DoPanTracks(), TrackUtilities::DoTrackMute(), ContrastDialog::GetDB(), anonymous_namespace{FileMenus.cpp}::OnExportLabels(), anonymous_namespace{ExportMIDI.cpp}::OnExportMIDI(), cloud::ShareAudioToolbar::RegenerateTooltips(), AudioSetupToolBar::RegenerateTooltips(), ControlToolBar::RegenerateTooltips(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::Site(), and WaveChannelView::ToggleSubView().
|
private |
Container of pointers returned by factories, per instance of Host class.
This is the only non-static data member that Site injects into the derived class.
Definition at line 571 of file ClientData.h.
Referenced by ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::GetData(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::operator=(), ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::Site(), and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::size().
|
inlineprivate |
Definition at line 481 of file ClientData.h.
Referenced by ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::DoFind(), and ClientData::Site< Host, ClientData, ObjectCopyingPolicy, Pointer, ObjectLockingPolicy, RegistryLockingPolicy >::DoGet().