NumericConverter Class Reference

NumericConverter provides the advanced formatting control used in the selection bar of Audacity. More...

#include <NumericConverter.h>

Inheritance diagram for NumericConverter:

Collaboration diagram for NumericConverter:

Public Member Functions
	NumericConverter (const FormatterContext &context, NumericConverterType type, const NumericFormatID &formatName={}, double value=0.0f)
virtual	~NumericConverter ()
virtual void	ValueToControls ()
virtual void	ValueToControls (double rawValue, bool nearest=true)
virtual void	ControlsToValue ()
bool	SetTypeAndFormatName (const NumericConverterType &type, const NumericFormatID &formatName)
bool	SetFormatName (const NumericFormatID &formatName)
NumericFormatID	GetFormatName () const
bool	SetCustomFormat (const TranslatableString &customFormat)
void	SetValue (double newValue)
void	SetMinValue (double minValue)
void	ResetMinValue ()
void	SetMaxValue (double maxValue)
void	ResetMaxValue ()
double	GetValue ()
wxString	GetString ()
void	UpdateFormatToFit (double value)
void	Adjust (int steps, int dir, int focusedDigit)
void	Increment (int focusedDigit=-1)
void	Decrement (int focusedDigit=-1)
Public Member Functions inherited from Observer::Publisher< FormatChangedToFitValueMessage >
	Publisher (ExceptionPolicy *pPolicy=nullptr, Alloc a={})
	Constructor supporting type-erased custom allocation/deletion. More...
	Publisher (Publisher &&)=default
Publisher &	operator= (Publisher &&)=default
Subscription	Subscribe (Callback callback)
	Connect a callback to the Publisher; later-connected are called earlier. More...
Subscription	Subscribe (Object &obj, Return(Object::*callback)(Args...))
	Overload of Subscribe takes an object and pointer-to-member-function. More...

Protected Member Functions
bool	UpdateFormatter ()
virtual void	OnFormatUpdated (bool resetFocus)
Protected Member Functions inherited from Observer::Publisher< FormatChangedToFitValueMessage >
CallbackReturn	Publish (const FormatChangedToFitValueMessage &message)
	Send a message to connected callbacks. More...

Protected Attributes
FormatterContext	mContext
NumericConverterType	mType
double	mMinValue { 0.0 }
double	mMaxValue { std::numeric_limits<double>::max() }
double	mInvalidValue { -1 }
double	mValue { mInvalidValue }
std::unique_ptr< NumericConverterFormatter >	mFormatter
NumericFormatID	mFormatID
TranslatableString	mCustomFormat
wxString	mValueString
std::vector< wxString >	mFieldValueStrings
Observer::Subscription	mFormatUpdatedSubscription

Private Member Functions
bool	ParseFormatString (const TranslatableString &untranslatedFormat)
int	GetSafeFocusedDigit (int focusedDigit) const noexcept

Additional Inherited Members
Public Types inherited from Observer::Publisher< FormatChangedToFitValueMessage >
using	message_type = FormatChangedToFitValueMessage
using	CallbackReturn = std::conditional_t< true, void, bool >
using	Callback = std::function< CallbackReturn(const FormatChangedToFitValueMessage &) >
	Type of functions that can be connected to the Publisher. More...
Static Public Attributes inherited from Observer::Publisher< FormatChangedToFitValueMessage >
static constexpr bool	notifies_all

Detailed Description

NumericConverter provides the advanced formatting control used in the selection bar of Audacity.

NumericConverter has all the time conversion and snapping functionality that used to live in NumericTextCtrl. The idea is to have a GUI-less class which can do the conversions, so that we can use it in sanpping without having a window created each time.

NumericConverter

Any negative value given to the converter is considered invalid and all digit positions of the resulting string will be filled with hyphens. Otherwise:

The NumericConverter makes use of a format string to specify the exact way that a single value is split into several fields, such as the hh:mm:ss format. The advantage of this format string is that it is very small and compact, but human-readable and somewhat intuitive, so that it's easy to add NEW layouts in the future. It's also designed to make it easier to add i18n support, since the way that numbers are displayed in different languages could conceivably vary a lot.

The number to be formatted may be expressed in seconds, so the format string can specify the relationship of each field to the number of seconds.

The class is also reused to format some non-time values such as frequency and log of frequency.

Let's start by considering an example: here's the format string that prints an integer number of seconds in the hour minute second h:m:s format:

:60:60

The "*" is a wildcard, saying that the leftmost field can contain numbers of arbitrary magnitude. The next character, ':', since it is not a digit or a wildcard, is interpreted as a delimiter, and will be displayed between those fields. The next number, 60, indicates that the range of the next field (minutes) is 60. Then there's another ':' delimiter, and finally the last field (seconds) is 60. So, if you give it a number like 3758 it is formatted as:

3758 seconds, "*:60:60" -> "1:2:38"

Note that 3758 = 1*60*60 + 2*60 + 38.

When NumericConverter formats an integer, you can think of its process as working from right to left. Given the value "3758", it fills in the seconds by dividing by 60, sticking the remainder in the seconds field and then passing the quotient to the next field to the left.

In order to format a field with leading zeros, simply add a leading zero to that field, like this:

3758 seconds, "*:060:060" -> "1:02:38"

In order to format fractions, simply include a field delimiter ending with a decimal point. If the delimiter is simply '.' with nothing else, then the '.' is actually displayed. Otherwise the '.' is dropped, and the other characters in the delimiter are displayed instead.

Here's how we'd display hours, minutes, and seconds with three decimal places after the seconds:

3758.5 seconds, "*:060:060.01000" -> "1:02:38.500"

Similarly, here's how we'd display the fractional part of seconds as film frames (24 per second) instead of milliseconds:

3758.5 seconds, "*:060:060 and .24 frames" -> "1:02:38 and 12 frames"

Note that the decimal '.' is associated with the delimiter, not with the 24.

Additionally, the special character '#' can be used in place of a number to represent the current sample rate. Use '0#' to add leading zeros to that field. For example:

3758.5 seconds, "*:060:060+.#samples" -> "1:02:38+22050samples"

(Almost) Finally, there is a rule that allows you to change the units into something other than seconds. To do this, put a "|" character on the far right, followed by a number specifying the scaling factor. As an exception to previous rules, decimal points are allowed in the final scaling factor - the period is not interpreted as it would be before the "|" character. (This is fine, because all previous fields must be integers to make sense.) Anyway, if you include a scaling factor after a "|", the number will be multiplied by this factor before it is formatted. For example, to express the current time in NTSC frames (~29.97 fps), you could use the following formatting:

3758.5 seconds, "*.01000 frames|29.97002997" -> "112642.358 frames"

Finally there is a further special character that can be used after a "|" and that is "N". This applies special rule for NTSC drop-frame timecode.

Summary of format string rules:

• The characters '0-9', '*', and '#' are numeric. Any sequence of these characters is treated as defining a NEW field by specifying its range. All other characters become delimiters between fields. (The one exception is that '.' is treated as numeric after the optional '|'.)
• A field with a range of '*', which only makes sense as the leftmost field, means the field should display as large a number as necessary. (Note: this no longer makes sense here and applies to a previous version).
• The character '#' represents the current sample rate.
• If a field specifier beings with a leading zero, it will be formatted with leading zeros, too - enough to display the maximum value that field can display. So the number 7 in a field specified as '01000' would be formatted as '007'. Bond. James Bond.
• Any non-numeric characters before the first field are treated as a prefix, and will be displayed to the left of the first field.
• A delimiter ending in '.' is treated specially. All fields after this delimiter are fractional fields, after the decimal point.
• The '|' character is treated as a special delimiter. The number to the right of this character (which is allowed to contain a decimal point) is treated as a scaling factor. The number is multiplied by this factor before converting.
• The special character 'N' after '|' is only used for NTSC drop-frame.

Constructor & Destructor Documentation

NumericConverter()

NumericConverter::NumericConverter	(	const FormatterContext &	context,
		NumericConverterType	type,
		const NumericFormatID &	formatName = {},
		double	value = 0.0f
	)

Definition at line 47 of file NumericConverter.cpp.

    : mContext { context }
    , mType { std::move(type) }
{
   ResetMinValue();
   ResetMaxValue();
 
   SetFormatName(formatName);
   SetValue(value);
}

References ResetMaxValue(), ResetMinValue(), SetFormatName(), and SetValue().

Here is the call graph for this function:

~NumericConverter()

NumericConverter::~NumericConverter ( )

virtual

Definition at line 69 of file NumericConverter.cpp.

{
}

Member Function Documentation

Adjust()

void NumericConverter::Adjust	(	int	steps,
		int	dir,
		int	focusedDigit
	)

Definition at line 271 of file NumericConverter.cpp.

{
   if (!mFormatter || mFormatter->GetDigitInfos().empty())
      return;
   // It is possible and "valid" for steps to be zero if a
   // high precision device is being used and wxWidgets supports
   // reporting a higher precision...Mac wx3 does.
   if (steps == 0)
      return;
 
   focusedDigit = GetSafeFocusedDigit(focusedDigit);
 
   wxASSERT(dir == -1 || dir == 1);
   wxASSERT(steps > 0);
   if (steps < 0)
      steps = -steps;
 
   while (steps != 0)
   {
      mValue = mFormatter->SingleStep(mValue, focusedDigit, dir > 0);
      steps--;
   }
 
   mValue = std::clamp(mValue, mMinValue, mMaxValue);
 
   ValueToControls();
}

References GetSafeFocusedDigit(), mFormatter, mMaxValue, mMinValue, mValue, and ValueToControls().

Referenced by Decrement(), Increment(), NumericTextCtrl::OnKeyDown(), and NumericTextCtrl::OnMouse().

Here is the call graph for this function:

Here is the caller graph for this function:

ControlsToValue()

void NumericConverter::ControlsToValue ( )

virtual

Reimplemented in NumericTextCtrl.

Definition at line 90 of file NumericConverter.cpp.

{
   if (!mFormatter)
   {
      mValue = mInvalidValue;
      return;
   }
 
   auto result = mFormatter->StringToValue(mValueString);
 
   mValue = result.has_value() ?
               std::clamp(*result, mMinValue, mMaxValue) :
               mInvalidValue;
}

References mFormatter, mInvalidValue, mMaxValue, mMinValue, mValue, and mValueString.

Referenced by NumericTextCtrl::ControlsToValue(), GetValue(), OnFormatUpdated(), and SetValue().

Here is the caller graph for this function:

Decrement()

void NumericConverter::Decrement

(

int

focusedDigit = -1

)

Definition at line 225 of file NumericConverter.cpp.

{
   Adjust(1, -1, focusedDigit);
}

References Adjust().

Here is the call graph for this function:

GetFormatName()

NumericFormatID NumericConverter::GetFormatName

(

)

const

Definition at line 137 of file NumericConverter.cpp.

{
   return mFormatID;
}

References mFormatID.

Referenced by TimeToolBar::Populate(), SpectralSelectionBar::SetBandwidthSelectionFormatName(), SpectralSelectionBar::SetFrequencySelectionFormatName(), SpectralSelectionBar::UpdatePrefs(), and TimeToolBar::UpdatePrefs().

Here is the caller graph for this function:

GetSafeFocusedDigit()

int NumericConverter::GetSafeFocusedDigit ( int  focusedDigit ) const

privatenoexcept

Definition at line 211 of file NumericConverter.cpp.

{
   if (focusedDigit < 0)
      return int(mFormatter->GetDigitInfos().size() - 1);
   else
      return std::clamp<int>(
         focusedDigit, 0, mFormatter->GetDigitInfos().size() - 1);
}

Referenced by Adjust().

Here is the caller graph for this function:

GetString()

wxString NumericConverter::GetString

(

)

Definition at line 200 of file NumericConverter.cpp.

{
   ValueToControls();
   return mValueString;
}

References mValueString, and ValueToControls().

Referenced by EffectRepeat::DisplayNewTime(), and NumericRenderer::Draw().

Here is the call graph for this function:

Here is the caller graph for this function:

GetValue()

double NumericConverter::GetValue

(

)

Definition at line 194 of file NumericConverter.cpp.

{
   ControlsToValue();
   return mValue;
}

References ControlsToValue(), and mValue.

Referenced by NumericEditor::EndEdit(), SpectralSelectionBar::ModifySpectralSelection(), VST3Editor::OnClose(), TimerRecordDialog::OnDatePicker_End(), TimerRecordDialog::OnDatePicker_Start(), ContrastDialog::OnExport(), NyquistEffect::OnTime(), EffectChangeSpeed::OnTimeCtrl_ToLength(), TimerRecordDialog::OnTimeText_Duration(), TimerRecordDialog::OnTimeText_End(), TimerRecordDialog::OnTimeText_Start(), NyquistEffect::TransferDataFromEffectWindow(), TimeDialog::TransferDataFromWindow(), TimerRecordDialog::TransferDataFromWindow(), EffectNoise::TransferDataFromWindow(), EffectSilence::TransferDataFromWindow(), EffectToneGen::TransferDataFromWindow(), LadspaEditor::ValidateUI(), LV2Editor::ValidateUI(), VSTEditor::ValidateUI(), and VST3Editor::ValidateUI().

Here is the call graph for this function:

Here is the caller graph for this function:

Increment()

void NumericConverter::Increment

(

int

focusedDigit = -1

)

Definition at line 220 of file NumericConverter.cpp.

{
   Adjust(1, 1, focusedDigit);
}

References Adjust().

Here is the call graph for this function:

OnFormatUpdated()

void NumericConverter::OnFormatUpdated ( bool  resetFocus )

protectedvirtual

Reimplemented in NumericTextCtrl.

Definition at line 262 of file NumericConverter.cpp.

{
   if (!mFormatter)
      return;
   
   ValueToControls();
   ControlsToValue();
}

References ControlsToValue(), mFormatter, and ValueToControls().

Referenced by NumericTextCtrl::OnFormatUpdated(), and UpdateFormatter().

Here is the call graph for this function:

Here is the caller graph for this function:

ParseFormatString()

bool NumericConverter::ParseFormatString ( const TranslatableString &  untranslatedFormat )

private

Definition at line 60 of file NumericConverter.cpp.

{
   mFormatter = CreateParsedNumericConverterFormatter(
      mContext, mType, untranslatedFormat);
 
   return mFormatter != nullptr;
}

References CreateParsedNumericConverterFormatter(), mContext, mFormatter, and mType.

Referenced by SetCustomFormat(), and UpdateFormatter().

Here is the call graph for this function:

Here is the caller graph for this function:

ResetMaxValue()

void NumericConverter::ResetMaxValue

(

)

Definition at line 189 of file NumericConverter.cpp.

{
   mMaxValue = std::numeric_limits<double>::max();
}

References mMaxValue.

Referenced by NumericConverter(), and SpectralSelectionBar::SetBounds().

Here is the caller graph for this function:

ResetMinValue()

void NumericConverter::ResetMinValue

(

)

Definition at line 174 of file NumericConverter.cpp.

{
   mMinValue = 0.0;
}

References mMinValue.

Referenced by NumericConverter(), and SpectralSelectionBar::SetBounds().

Here is the caller graph for this function:

SetCustomFormat()

bool NumericConverter::SetCustomFormat

(

const TranslatableString &

customFormat

)

Definition at line 142 of file NumericConverter.cpp.

{
   if (mCustomFormat == customFormat)
      return false;
 
   if (!ParseFormatString(customFormat))
      return false;
 
   mFormatID = {};
   mCustomFormat = customFormat;
 
   UpdateFormatter();
 
   return true;
}

References mCustomFormat, mFormatID, ParseFormatString(), and UpdateFormatter().

Referenced by NumericTextCtrl::SetCustomFormat().

Here is the call graph for this function:

Here is the caller graph for this function:

SetFormatName()

bool NumericConverter::SetFormatName

(

const NumericFormatID &

formatName

)

Definition at line 118 of file NumericConverter.cpp.

{
   if (mFormatID == formatName && !formatName.empty())
      return false;
 
   const auto newFormat =
      NumericConverterFormats::Lookup(mContext, mType, formatName).Internal();
 
   if (mFormatID == newFormat)
      return false;
 
   mFormatID = newFormat;
   mCustomFormat = {};
 
   UpdateFormatter();
 
   return true;
}

References Identifier::empty(), ComponentInterfaceSymbol::Internal(), NumericConverterFormats::Lookup(), mContext, mCustomFormat, mFormatID, mType, and UpdateFormatter().

Referenced by NumericConverter(), NumericTextCtrl::SetFormatName(), and SetTypeAndFormatName().

Here is the call graph for this function:

Here is the caller graph for this function:

SetMaxValue()

void NumericConverter::SetMaxValue

(

double

maxValue

)

Definition at line 179 of file NumericConverter.cpp.

{
   mMaxValue = maxValue;
   if (mMinValue > maxValue) {
      mMinValue = maxValue;
   }
   if (mValue > maxValue)
      SetValue(maxValue);
}

References mMaxValue, mMinValue, mValue, and SetValue().

Referenced by SpectralSelectionBar::SetBounds().

Here is the call graph for this function:

Here is the caller graph for this function:

SetMinValue()

void NumericConverter::SetMinValue

(

double

minValue

)

Definition at line 165 of file NumericConverter.cpp.

{
   mMinValue = minValue;
   if (mMaxValue < minValue)
      mMaxValue = minValue;
   if (mValue < minValue)
      SetValue(minValue);
}

References mMaxValue, mMinValue, mValue, and SetValue().

Referenced by SpectralSelectionBar::SetBounds().

Here is the call graph for this function:

Here is the caller graph for this function:

SetTypeAndFormatName()

bool NumericConverter::SetTypeAndFormatName	(	const NumericConverterType &	type,
		const NumericFormatID &	formatName
	)

Definition at line 105 of file NumericConverter.cpp.

{
   if (mType != type)
   {
      // Ensure that the format change will happen,
      // duration formats lists matches the time list
      mFormatID = {};
      mType = type;
   }
 
   return SetFormatName(formatName);
}

References mFormatID, mType, and SetFormatName().

Referenced by NumericTextCtrl::SetTypeAndFormatName().

Here is the call graph for this function:

Here is the caller graph for this function:

SetValue()

void NumericConverter::SetValue

(

double

newValue

)

Definition at line 158 of file NumericConverter.cpp.

{
   mValue = newValue;
   ValueToControls();
   ControlsToValue();
}

References ControlsToValue(), mValue, and ValueToControls().

Referenced by EffectRepeat::DisplayNewTime(), NumericConverter(), SetMaxValue(), SetMinValue(), and NumericTextCtrl::SetValue().

Here is the call graph for this function:

Here is the caller graph for this function:

UpdateFormatter()

bool NumericConverter::UpdateFormatter ( )

protected

Definition at line 230 of file NumericConverter.cpp.

{
   if (!mFormatID.empty())
   {
      auto formatterItem = NumericConverterRegistry::Find(mContext, mType, mFormatID);
 
      if (formatterItem == nullptr)
      {
         assert(formatterItem != nullptr);
         return false;
      }
 
      mFormatter = formatterItem->factory->Create(mContext);
   }
   else if (!mCustomFormat.empty ())
   {
      ParseFormatString(mCustomFormat);
   }
 
   if (mFormatter)
   {
      mFormatUpdatedSubscription =
         mFormatter->Subscribe([this](const auto& msg) {
            OnFormatUpdated(false);
            Publish({ msg.value });
      });
   }
 
   OnFormatUpdated(true);
   return mFormatter != nullptr;
}

References Identifier::empty(), TranslatableString::empty(), NumericConverterRegistry::Find(), mContext, mCustomFormat, mFormatID, mFormatter, mFormatUpdatedSubscription, mType, OnFormatUpdated(), ParseFormatString(), and Observer::Publisher< FormatChangedToFitValueMessage >::Publish().

Referenced by SetCustomFormat(), and SetFormatName().

Here is the call graph for this function:

Here is the caller graph for this function:

UpdateFormatToFit()

void NumericConverter::UpdateFormatToFit

(

double

value

)

Definition at line 206 of file NumericConverter.cpp.

{
   mFormatter->UpdateFormatForValue(value, false);
}

References mFormatter.

Referenced by ValueToControls().

Here is the caller graph for this function:

ValueToControls() [1/2]

void NumericConverter::ValueToControls ( )

virtual

Reimplemented in NumericTextCtrl.

Definition at line 73 of file NumericConverter.cpp.

{
   ValueToControls(mValue);
}

References mValue, and ValueToControls().

Referenced by Adjust(), GetString(), OnFormatUpdated(), SetValue(), ValueToControls(), and NumericTextCtrl::ValueToControls().

Here is the call graph for this function:

Here is the caller graph for this function:

ValueToControls() [2/2]

void NumericConverter::ValueToControls ( double  rawValue, bool  nearest = true  )

virtual

Definition at line 78 of file NumericConverter.cpp.

{
   if (!mFormatter)
      return;
 
   UpdateFormatToFit(rawValue);
   auto result = mFormatter->ValueToString(rawValue, nearest);
 
   mValueString = std::move(result.valueString);
   mFieldValueStrings = std::move(result.fieldValueStrings);
}

References mFieldValueStrings, mFormatter, mValueString, and UpdateFormatToFit().

Here is the call graph for this function:

Member Data Documentation

mContext

FormatterContext NumericConverter::mContext

protected

Definition at line 86 of file NumericConverter.h.

Referenced by NumericTextCtrl::OnContext(), ParseFormatString(), SetFormatName(), and UpdateFormatter().

mCustomFormat

TranslatableString NumericConverter::mCustomFormat

protected

Definition at line 100 of file NumericConverter.h.

Referenced by SetCustomFormat(), SetFormatName(), and UpdateFormatter().

mFieldValueStrings

std::vector<wxString> NumericConverter::mFieldValueStrings

protected

Definition at line 104 of file NumericConverter.h.

Referenced by ValueToControls().

mFormatID

NumericFormatID NumericConverter::mFormatID

protected

Definition at line 99 of file NumericConverter.h.

Referenced by GetFormatName(), NumericTextCtrl::OnContext(), SetCustomFormat(), SetFormatName(), SetTypeAndFormatName(), and UpdateFormatter().

mFormatter

std::unique_ptr<NumericConverterFormatter> NumericConverter::mFormatter

protected

Definition at line 97 of file NumericConverter.h.

Referenced by Adjust(), NumericTextCtrl::ComputeSizing(), ControlsToValue(), NumericTextCtrl::Layout(), OnFormatUpdated(), NumericTextCtrl::OnKeyDown(), NumericTextCtrl::OnPaint(), ParseFormatString(), NumericTextCtrl::SetFieldFocus(), NumericTextCtrl::UpdateAutoFocus(), NumericTextCtrl::Updated(), UpdateFormatter(), UpdateFormatToFit(), and ValueToControls().

mFormatUpdatedSubscription

Observer::Subscription NumericConverter::mFormatUpdatedSubscription

protected

Definition at line 106 of file NumericConverter.h.

Referenced by UpdateFormatter().

mInvalidValue

double NumericConverter::mInvalidValue { -1 }

protected

Definition at line 92 of file NumericConverter.h.

Referenced by ControlsToValue(), NumericTextCtrl::OnKeyDown(), and NumericTextCtrl::SetInvalidValue().

mMaxValue

double NumericConverter::mMaxValue { std::numeric_limits<double>::max() }

protected

Definition at line 91 of file NumericConverter.h.

Referenced by Adjust(), ControlsToValue(), NumericTextCtrl::OnKeyDown(), ResetMaxValue(), SetMaxValue(), and SetMinValue().

mMinValue

double NumericConverter::mMinValue { 0.0 }

protected

Definition at line 90 of file NumericConverter.h.

Referenced by Adjust(), ControlsToValue(), NumericTextCtrl::OnKeyDown(), ResetMinValue(), SetMaxValue(), and SetMinValue().

mType

NumericConverterType NumericConverter::mType

protected

Definition at line 88 of file NumericConverter.h.

Referenced by ParseFormatString(), SetFormatName(), SetTypeAndFormatName(), and UpdateFormatter().

mValue

double NumericConverter::mValue { mInvalidValue }

protected

Definition at line 94 of file NumericConverter.h.

Referenced by Adjust(), ControlsToValue(), GetValue(), NumericTextCtrl::OnKeyDown(), NumericTextCtrl::SetInvalidValue(), SetMaxValue(), SetMinValue(), SetValue(), ValueToControls(), and NumericTextCtrl::ValueToControls().

mValueString

wxString NumericConverter::mValueString

protected

Definition at line 103 of file NumericConverter.h.

Referenced by ControlsToValue(), GetString(), NumericTextCtrl::OnKeyDown(), NumericTextCtrl::OnPaint(), NumericTextCtrl::UpdateAutoFocus(), NumericTextCtrl::ValueToControls(), and ValueToControls().

---

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

• NumericConverter.h
• ParsedNumericConverterFormatter.cpp
• NumericConverter.cpp