Setting< T > Class Template Reference

#include <Prefs.h>

Inheritance diagram for Setting< T >:

Collaboration diagram for Setting< T >:

Public Types
using	ValueType = T
using	DefaultValueFunction = std::function< T() >

Public Member Functions
	Setting (const SettingBase &path, const T &defaultValue)
	Usual overload supplies a default value. More...
	Setting (const SettingBase &path, DefaultValueFunction function)
	This overload causes recomputation of the default each time it is needed. More...
const T &	GetDefault () const
bool	Read (T *pVar) const
	overload of Read returning a boolean that is true if the value was previously defined *‍/ More...
bool	ReadWithDefault (T *pVar, const T &defaultValue) const
	overload of ReadWithDefault returning a boolean that is true if the value was previously defined *‍/ More...
T	Read () const
	overload of Read, always returning a value More...
T	ReadWithDefault (const T &defaultValue) const
	new direct use is discouraged but it may be needed in legacy code More...
bool	Write (const T &value)
	Write value to config and return true if successful. More...
bool	Reset ()
	Reset to the default value. More...
void	Invalidate () override
Public Member Functions inherited from CachingSettingBase< T >
	CachingSettingBase (const SettingBase &path)
Public Member Functions inherited from TransactionalSettingBase
virtual void	Invalidate ()=0
	SettingBase (const char *path)
	SettingBase (const wxChar *path)
	SettingBase (const wxString &path)
	SettingBase (const SettingBase &)=default
Public Member Functions inherited from SettingBase
	SettingBase (const char *path)
	SettingBase (const wxChar *path)
	SettingBase (const wxString &path)
audacity::BasicSettings *	GetConfig () const
const SettingPath &	GetPath () const
bool	Delete ()
	Delete the key if present, and return true iff it was. More...

Protected Member Functions
bool	DoWrite ()
	Write cached value to config and return true if successful. More...
Protected Member Functions inherited from CachingSettingBase< T >
	CachingSettingBase (const CachingSettingBase &)=default
virtual void	EnterTransaction (size_t depth)=0
virtual bool	Commit ()=0
virtual void	Rollback () noexcept=0
Protected Member Functions inherited from SettingBase
	SettingBase (const SettingBase &)=default

Protected Attributes
const DefaultValueFunction	mFunction
T	mDefaultValue {}
std::vector< T >	mPreviousValues
Protected Attributes inherited from CachingSettingBase< T >
T	mCurrentValue {}
bool	mValid {false}
Protected Attributes inherited from SettingBase
const SettingPath	mPath

Private Member Functions
void	EnterTransaction (size_t depth) override
bool	Commit () override
void	Rollback () noexcept override

Detailed Description

template<typename T>
class Setting< T >

Class template adds default value, read, and write methods to CachingSetingBase and generates TransactionalSettingBase virtual functions

Definition at line 177 of file Prefs.h.

Member Typedef Documentation

DefaultValueFunction

template<typename T >

using Setting< T >::DefaultValueFunction = std::function< T() >

Definition at line 184 of file Prefs.h.

ValueType

template<typename T >

using Setting< T >::ValueType = T

Definition at line 180 of file Prefs.h.

Constructor & Destructor Documentation

Setting() [1/2]

template<typename T >

Setting< T >::Setting ( const SettingBase &  path, const T &  defaultValue  )

inline

Usual overload supplies a default value.

Definition at line 187 of file Prefs.h.

      : CachingSettingBase< T >{ path }
      , mDefaultValue{ defaultValue }
   {}

Setting() [2/2]

template<typename T >

Setting< T >::Setting ( const SettingBase &  path, DefaultValueFunction  function  )

inline

This overload causes recomputation of the default each time it is needed.

Definition at line 193 of file Prefs.h.

      : CachingSettingBase< T >{ path }
      , mFunction{ function }
   {}

Member Function Documentation

Commit()

template<typename T >

bool Setting< T >::Commit ( )

inlineoverrideprivatevirtual

Returns

true if successful

Implements TransactionalSettingBase.

Definition at line 303 of file Prefs.h.

   {
      // This can be only called from within the transaction
      assert(!this->mPreviousValues.empty());
 
      if (this->mPreviousValues.empty())
         return false;
      
      const auto result = this->mPreviousValues.size() > 1 || DoWrite();
      mPreviousValues.pop_back();
 
      return result;
   }

DoWrite()

template<typename T >

bool Setting< T >::DoWrite ( )

inlineprotected

Write cached value to config and return true if successful.

(But the config object is not flushed)

Definition at line 332 of file Prefs.h.

   {
      const auto config = this->GetConfig();
      return this->mValid =
         config ? config->Write( this->mPath, this->mCurrentValue ) : false;
   }

References SettingBase::GetConfig(), and SettingBase::mPath.

Here is the call graph for this function:

EnterTransaction()

template<typename T >

void Setting< T >::EnterTransaction ( size_t  depth )

inlineoverrideprivatevirtual

Implements TransactionalSettingBase.

Definition at line 295 of file Prefs.h.

   {
      const T value = Read();
 
      for (size_t i = mPreviousValues.size(); i < depth; ++i)
         this->mPreviousValues.emplace_back( value );
   }

GetDefault()

template<typename T >

const T & Setting< T >::GetDefault ( ) const

inline

Definition at line 199 of file Prefs.h.

   {
      if ( mFunction )
         mDefaultValue = mFunction();
      return mDefaultValue;
   }

Referenced by TracksPrefs::Commit(), DeduceSnapTo(), AudioIOBase::GetDeviceInfo(), AudioIOBase::HandleDeviceChange(), ShuttleGuiBase::TieCheckBox(), anonymous_namespace{GetInfoCommand.cpp}::ShuttleGuiGetDefinition::TieCheckBox(), ShuttleGuiBase::TieCheckBoxOnRight(), anonymous_namespace{GetInfoCommand.cpp}::ShuttleGuiGetDefinition::TieCheckBoxOnRight(), ShuttleGuiBase::TieIntegerTextBox(), anonymous_namespace{GetInfoCommand.cpp}::ShuttleGuiGetDefinition::TieIntegerTextBox(), anonymous_namespace{GetInfoCommand.cpp}::ShuttleGuiGetDefinition::TieNumberAsChoice(), ShuttleGuiBase::TieNumberAsChoice(), anonymous_namespace{GetInfoCommand.cpp}::ShuttleGuiGetDefinition::TieNumericTextBox(), ShuttleGuiBase::TieNumericTextBox(), ShuttleGuiBase::TieSlider(), anonymous_namespace{GetInfoCommand.cpp}::ShuttleGuiGetDefinition::TieSlider(), ShuttleGuiBase::TieSpinCtrl(), anonymous_namespace{GetInfoCommand.cpp}::ShuttleGuiGetDefinition::TieSpinCtrl(), ShuttleGuiBase::TieTextBox(), anonymous_namespace{GetInfoCommand.cpp}::ShuttleGuiGetDefinition::TieTextBox(), and TrackArtist::TrackArtist().

Here is the caller graph for this function:

Invalidate()

template<typename T >

void Setting< T >::Invalidate ( )

inlineoverridevirtual

Implements TransactionalSettingBase.

Definition at line 289 of file Prefs.h.

   {
      this->mValid = false;
   }

Referenced by anonymous_namespace{AudioComPrefsPanel.cpp}::AudioComPrefsPanel::Commit(), DevicePrefs::Commit(), GUIPrefs::Commit(), MidiIOPrefs::Commit(), RecordingPrefs::Commit(), TracksBehaviorsPrefs::Commit(), TracksPrefs::Commit(), and audacity::cloud::audiocom::anonymous_namespace{OAuthService.cpp}::OAuthServiceSettingsResetHandler::OnSettingResetEnd().

Here is the caller graph for this function:

Read() [1/2]

template<typename T >

T Setting< T >::Read ( ) const

inline

overload of Read, always returning a value

The value is the default stored in this in case the key is known to be absent from the config; but it returns type T's default value if there was failure to read the config

Definition at line 233 of file Prefs.h.

   {
      return ReadWithDefault( GetDefault() );
   }

Read() [2/2]

template<typename T >

bool Setting< T >::Read ( T *  pVar ) const

inline

overload of Read returning a boolean that is true if the value was previously defined *‍/

Definition at line 207 of file Prefs.h.

   {
      return ReadWithDefault( pVar, GetDefault() );
   }

Referenced by AudioIO::AudioIO(), audacity::cloud::audiocom::OAuthService::AuthoriseRefreshToken(), anonymous_namespace{AudioComPrefsPanel.cpp}::AudioComPrefsPanel::Browse(), DeviceToolBar::ChangeDevice(), AudioSetupToolBar::ChangeDeviceLabel(), DeviceToolBar::ChangeHost(), AudioSetupToolBar::ChangeHost(), ProjectAudioManager::ChooseExistingRecordingTracks(), RecordingPrefs::Commit(), ProjectAudioManager::DoRecord(), audacity::cloud::audiocom::UserService::DownloadAvatar(), SpectrumVZoomHandle::DoZoom(), anonymous_namespace{WaveformView.cpp}::DrawIndividualSamples(), EditToolBar::EditToolBar(), ExportAudioDialog::ExportAudioDialog(), FFmpegStartup(), AudioSetupToolBar::FillHostDevices(), DeviceToolBar::FillHostDevices(), AudioSetupToolBar::FillInputChannels(), DeviceToolBar::FillInputChannels(), AudioIOBase::GetDeviceInfo(), audacity::cloud::audiocom::UserService::GetDisplayName(), GetEditClipsCanMove(), ProjectManager::GetEstimatedRecordingMinsLeftOnDisk(), GetMIDIDeviceInfo(), GetNextWindowPlacement(), AudioIOBase::getPlayDevIndex(), AudioIOBase::getRecordDevIndex(), FFmpegFunctions::GetSearchPaths(), anonymous_namespace{EnvelopeHandle.cpp}::GetTimeTrackData(), audacity::cloud::audiocom::UserService::GetUserId(), audacity::cloud::audiocom::UserService::GetUserSlug(), AudioIOBase::HandleDeviceChange(), anonymous_namespace{TracksPrefs.cpp}::Handler::Handler(), audacity::cloud::audiocom::OAuthService::HasRefreshToken(), AudacityApp::InitPart2(), AudioIOBase::IsCaptureRateSupported(), SpectrogramSettings::Globals::LoadPrefs(), SpectrogramSettings::LoadPrefs(), WaveformSettings::LoadPrefs(), SpectrogramSettings::ColorSchemeEnumSetting::Migrate(), ToolManager::ModifyToolbarMenus(), anonymous_namespace{TransportMenus.cpp}::OnPunchAndRoll(), FrequencyPlotDialog::OnReplot(), anonymous_namespace{PluginMenus.cpp}::OnResetConfig(), anonymous_namespace{CloudProjectFileIOExtensions.cpp}::IOExtension::OnSave(), FFmpegImportPlugin::Open(), audacity::cloud::audiocom::sync::anonymous_namespace{CloudSyncHousekeeper.cpp}::Housekeeper::PerformHousekeeping(), FrequencyPlotDialog::Populate(), DevicePrefs::Populate(), MidiIOPrefs::Populate(), FFmpegNotFoundDialog::PopulateOrExchange(), SoundActivatedRecordDialog::PopulateOrExchange(), RecordingPrefs::PopulateOrExchange(), ProjectRate::ProjectRate(), anonymous_namespace{SelectionBar.cpp}::ReadSelectionMode(), ReadSnapTo(), Journal::RecordEnabled(), audacity::cloud::audiocom::ServiceConfig::ServiceConfig(), FrequencyPlotDialog::Show(), UpdateManager::Start(), AudioIO::StartMonitoring(), AudioIO::StartPortAudioStream(), anonymous_namespace{MIDIPlay.h}::MIDIPlay::StartPortMidiStream(), AudioIO::StartStream(), AudioIO::StopStream(), audacity::cloud::audiocom::CloudSyncService::SyncCloudSnapshot(), WaveTrack::SyncLockAdjust(), audacity::network_manager::anonymous_namespace{CurlHandleManager.cpp}::CurlConfig::UpdatePrefs(), SpectrogramSettings::UpdatePrefs(), WaveformSettings::UpdatePrefs(), AudioSetupToolBar::UpdatePrefs(), DeviceToolBar::UpdatePrefs(), TrackArtist::UpdatePrefs(), and MeterPanel::UpdatePrefs().

ReadWithDefault() [1/2]

template<typename T >

T Setting< T >::ReadWithDefault ( const T &  defaultValue ) const

inline

new direct use is discouraged but it may be needed in legacy code

Use the given default in case the preference is not defined, which may not be the default-default stored in this object.

Definition at line 241 of file Prefs.h.

   {
      if (this->mValid)
         return this->mCurrentValue;
      const auto config = this->GetConfig();
      if (config) {
         this->mCurrentValue =
            config->ReadObject(this->mPath, defaultValue);
         // If config file contains a value that agrees with the default, we
         // can't detect that, so assume invalidity still
         this->mValid = (this->mCurrentValue != defaultValue);
         return this->mCurrentValue;
      }
      else
         return T{};
   }

References SettingBase::GetConfig(), and SettingBase::mPath.

Here is the call graph for this function:

ReadWithDefault() [2/2]

template<typename T >

bool Setting< T >::ReadWithDefault ( T *  pVar, const T &  defaultValue  ) const

inline

overload of ReadWithDefault returning a boolean that is true if the value was previously defined *‍/

Definition at line 213 of file Prefs.h.

   {
      if ( pVar )
         *pVar = defaultValue;
      if ( pVar && this->mValid ) {
         *pVar = this->mCurrentValue;
         return true;
      }
      const auto config = this->GetConfig();
      if ( pVar && config ) {
         if ((this->mValid = config->Read( this->mPath, &this->mCurrentValue )))
            *pVar = this->mCurrentValue;
         return this->mValid;
      }
      return (this->mValid = false);
   }

References SettingBase::GetConfig().

Referenced by EffectBase::EffectBase(), WaveTrack::GetDefaultAudioTrackNamePreference(), GetNextWindowPlacement(), AudioIOBase::IsCaptureRateSupported(), AudioSetupToolBar::UpdatePrefs(), and DeviceToolBar::UpdatePrefs().

Here is the call graph for this function:

Here is the caller graph for this function:

Reset()

template<typename T >

bool Setting< T >::Reset ( )

inline

Reset to the default value.

Definition at line 284 of file Prefs.h.

   {
      return Write( GetDefault() );
   }

Referenced by DevicePrefs::Commit(), RecordingPrefs::Commit(), anonymous_namespace{PluginMenus.cpp}::OnResetConfig(), AudioSetupToolBar::SetDevices(), and DeviceToolBar::SetDevices().

Here is the caller graph for this function:

Rollback()

template<typename T >

void Setting< T >::Rollback ( )

inlineoverrideprivatevirtualnoexcept

Implements TransactionalSettingBase.

Definition at line 317 of file Prefs.h.

   {
      // This can be only called from within the transaction
      assert(!this->mPreviousValues.empty());
      
      if (!this->mPreviousValues.empty())
      {
         this->mCurrentValue = std::move(this->mPreviousValues.back());
         this->mPreviousValues.pop_back();
      }
   }

Write()

template<typename T >

bool Setting< T >::Write ( const T &  value )

inline

Write value to config and return true if successful.

Definition at line 259 of file Prefs.h.

   {
      const auto config = this->GetConfig();
      
      if (config == nullptr)
         return false;
      
      switch ( SettingScope::Add( *this ) ) {
         // Eager writes, but not flushed, when there is no transaction
         default:
         case SettingTransaction::NotAdded: {
            this->mCurrentValue = value;
            return DoWrite();
         }
 
         // Deferred writes, with flush, if there is a commit later
         case SettingTransaction::Added:
         case SettingTransaction::PreviouslyAdded:
            this->mCurrentValue = value;
            this->mValid = true;
            return true;
      }
   }

References SettingScope::Add(), SettingScope::Added, SettingBase::GetConfig(), SettingScope::NotAdded, and SettingScope::PreviouslyAdded.

Referenced by DeviceToolBar::ChangeHost(), AudioSetupToolBar::ChangeHost(), audacity::cloud::audiocom::UserService::ClearUserData(), DevicePrefs::Commit(), MidiIOPrefs::Commit(), anonymous_namespace{FileMenus.cpp}::DoImport(), audacity::cloud::audiocom::UserService::DownloadAvatar(), TimerRecordDialog::ExecutePostRecordActions(), AudioSetupToolBar::FillHostDevices(), DeviceToolBar::FillHostDevices(), AudioSetupToolBar::FillInputChannels(), DeviceToolBar::FillInputChannels(), FindFFmpegLibs(), AudioIO::Init(), LoadFFmpeg(), AudioSetupToolBar::OnChannels(), DeviceToolBar::OnChoice(), ExportAudioDialog::OnExport(), FFmpegNotFoundDialog::OnOk(), BenchmarkDialog::OnRun(), FFmpegImportPlugin::Open(), audacity::cloud::audiocom::OAuthService::ParseTokenResponse(), ProjectRate::ProjectRate(), ReadSnapTo(), SpectrogramSettings::Globals::SavePrefs(), SpectrogramSettings::SavePrefs(), anonymous_namespace{ProjectManager.cpp}::SaveWindowPreferences(), AudioSetupToolBar::SetDevices(), DeviceToolBar::SetDevices(), ProjectTimeSignature::SetLowerTimeSignature(), AudioIO::SetMixer(), Journal::SetRecordEnabled(), ProjectSnap::SetSnapTo(), ProjectTimeSignature::SetTempo(), ProjectTimeSignature::SetUpperTimeSignature(), UpdateManager::Start(), audacity::cloud::audiocom::OAuthService::UnlinkAccount(), anonymous_namespace{SelectionBar.cpp}::UpdateSelectionMode(), and audacity::cloud::audiocom::UserService::UpdateUserData().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

mDefaultValue

template<typename T >

T Setting< T >::mDefaultValue {}

mutableprotected

Definition at line 340 of file Prefs.h.

mFunction

template<typename T >

const DefaultValueFunction Setting< T >::mFunction

protected

Definition at line 339 of file Prefs.h.

mPreviousValues

template<typename T >

std::vector<T> Setting< T >::mPreviousValues

protected

Definition at line 341 of file Prefs.h.

---

The documentation for this class was generated from the following file:

• Prefs.h