Audacity  3.0.3
NumericTextCtrl.h
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  NumericTextCtrl.h
6 
7  Dominic Mazzoni
8 
9  See NumericTextCtrl.cpp for documentation on how to use the
10  format string to specify how a NumericTextCtrl's fields are
11  laid out.
12 
13 **********************************************************************/
14 
15 #ifndef __AUDACITY_TIME_TEXT_CTRL__
16 #define __AUDACITY_TIME_TEXT_CTRL__
17 
18 
19 
20 #include <memory>
21 #include "../../include/audacity/ComponentInterface.h"
22 #include <vector>
23 #include <wx/setup.h> // for wxUSE_* macros
24 #include <wx/defs.h>
25 #include <wx/control.h> // to inherit
26 
27 #include "Internat.h"
28 
29 // One event type for each type of control. Event is raised when a control
30 // changes its format. Owners of controls of the same type can listen and
31 // update their formats to agree.
32 DECLARE_EXPORTED_EVENT_TYPE(AUDACITY_DLL_API, EVT_TIMETEXTCTRL_UPDATED, -1);
33 DECLARE_EXPORTED_EVENT_TYPE(AUDACITY_DLL_API, EVT_FREQUENCYTEXTCTRL_UPDATED, -1);
34 DECLARE_EXPORTED_EVENT_TYPE(AUDACITY_DLL_API, EVT_BANDWIDTHTEXTCTRL_UPDATED,
35  -1);
36 
40 struct BuiltinFormatString;
41 
42 class NumericField;
43 
44 class DigitInfo;
45 
46 class AUDACITY_DLL_API NumericConverter /* not final */
47 {
48 public:
49 
50  enum Type {
52  ATIME, // for Audio time control.
55  };
56 
57  struct FormatStrings {
59  // How to name the fraction of the unit; not necessary for time formats
60  // or when the format string has no decimal point
62 
64  const TranslatableString &format = {},
65  const TranslatableString &fraction = {})
66  : formatStr{ format }, fraction{ fraction }
67  {}
68 
69  friend bool operator == ( const FormatStrings &x, const FormatStrings &y )
70  { return x.formatStr == y.formatStr && x.fraction == y.fraction; }
71  friend bool operator != ( const FormatStrings &x, const FormatStrings &y )
72  { return !(x == y); }
73  };
74 
75  static NumericFormatSymbol DefaultSelectionFormat();
76  static NumericFormatSymbol TimeAndSampleFormat();
77  static NumericFormatSymbol SecondsFormat();
78  static NumericFormatSymbol HoursMinsSecondsFormat();
79  static NumericFormatSymbol HundredthsFormat();
80  static NumericFormatSymbol HertzFormat();
81 
82  static NumericFormatSymbol LookupFormat( Type type, const wxString& id);
83 
84  NumericConverter(Type type,
85  const NumericFormatSymbol & formatName = {},
86  double value = 0.0f,
87  double sampleRate = 1.0f /* to prevent div by 0 */);
89 
90  virtual ~NumericConverter();
91 
92  // ValueToControls() formats a raw value (either provided as
93  // argument, or mValue, depending on the version of the function
94  // called). The result is stored to mValueString.
95  virtual void ValueToControls();
96  virtual void ValueToControls(double rawValue, bool nearest = true);
97 
98  // Converts the stored formatted string (mValueString) back to a
99  // raw value (mValue).
100  virtual void ControlsToValue();
101 
102 private:
103  void ParseFormatString(const TranslatableString & untranslatedFormat);
104 
105 public:
106  void PrintDebugInfo();
107 
108  // returns true iff the format name really changed:
109  bool SetFormatName(const NumericFormatSymbol & formatName);
110 
111  // returns true iff the format string really changed:
112  bool SetFormatString(const FormatStrings & formatString);
113 
114  void SetSampleRate(double sampleRate);
115  void SetValue(double newValue);
116  void SetMinValue(double minValue);
117  void ResetMinValue();
118  void SetMaxValue(double maxValue);
119  void ResetMaxValue();
120 
121  double GetValue();
122 
123  wxString GetString();
124 
125  int GetFormatIndex();
126 
127  int GetNumBuiltins();
128  NumericFormatSymbol GetBuiltinName(const int index);
129  FormatStrings GetBuiltinFormat(const int index);
130  FormatStrings GetBuiltinFormat(const NumericFormatSymbol & name);
131 
132  // Adjust the value by the number "steps" in the active format.
133  // Increment if "dir" is 1, decrement if "dir" is -1.
134  void Adjust(int steps, int dir);
135 
136  void Increment();
137  void Decrement();
138 
139 protected:
141 
142  double mValue;
143 
144  double mMinValue;
145  double mMaxValue;
147 
149 
150  std::vector<NumericField> mFields;
151  wxString mPrefix;
152  wxString mValueTemplate;
153  wxString mValueMask;
154  // Formatted mValue, by ValueToControls().
155  wxString mValueString;
156 
158  double mSampleRate;
159  bool mNtscDrop;
160 
162  std::vector<DigitInfo> mDigits;
163 
165  const size_t mNBuiltins;
167 };
168 
169 class AUDACITY_DLL_API NumericTextCtrl final
170  : public wxControl, public NumericConverter
171 {
172  friend class NumericTextCtrlAx;
173 
174  public:
175  DECLARE_DYNAMIC_CLASS(NumericTextCtrl)
176 
177  struct Options {
178  bool autoPos { true };
179  bool readOnly { false };
180  bool menuEnabled { true };
181  bool hasInvalidValue { false };
182  double invalidValue { -1.0 };
184  bool hasValue { false };
185  double value{ -1.0 };
186 
187  Options() {}
188 
189  Options &AutoPos (bool enable) { autoPos = enable; return *this; }
190  Options &ReadOnly (bool enable) { readOnly = enable; return *this; }
191  Options &MenuEnabled (bool enable) { menuEnabled = enable; return *this; }
192  Options &InvalidValue (bool has, double v = -1.0)
193  { hasInvalidValue = has, invalidValue = v; return *this; }
194  // use a custom format not in the tables:
196  { format = f; return *this; }
197  Options &Value (bool has, double v)
198  { hasValue = has, value = v; return *this; }
199  };
200 
201  NumericTextCtrl(wxWindow *parent, wxWindowID winid,
203  const NumericFormatSymbol &formatName = {},
204  double value = 0.0,
205  double sampleRate = 44100,
206  const Options &options = {},
207  const wxPoint &pos = wxDefaultPosition,
208  const wxSize &size = wxDefaultSize);
209 
210  virtual ~NumericTextCtrl();
211 
212  // Hide the inherited function that takes wxString
213  void SetName( const TranslatableString &name );
214 
215  wxSize ComputeSizing(bool update = true, wxCoord digitW = 0, wxCoord digitH = 0);
216  bool Layout() override;
217  void Fit() override;
218 
219  void SetSampleRate(double sampleRate);
220  void SetValue(double newValue);
221 
222  // returns true iff the format string really changed:
223  bool SetFormatString(const FormatStrings & formatString);
224 
225  // returns true iff the format name really changed:
226  bool SetFormatName(const NumericFormatSymbol & formatName);
227 
228  void SetFieldFocus(int /* digit */);
229 
230  wxSize GetDimensions() { return wxSize(mWidth + mButtonWidth, mHeight); }
231  wxSize GetDigitSize() { return wxSize(mDigitBoxW, mDigitBoxH); }
232  void SetDigitSize(int width, int height);
233  void SetReadOnly(bool readOnly = true);
234  void EnableMenu(bool enable = true);
235 
236  // The text control permits typing DELETE to make the value invalid only if this
237  // function has previously been called.
238  // Maybe you want something other than the default of -1 to indicate the invalid value
239  // this control returns to the program, so you can specify.
240  void SetInvalidValue(double invalidValue);
241 
242  int GetFocusedField() { return mLastField; }
243  int GetFocusedDigit() { return mFocusedDigit; }
244 
245 private:
246 
247  void OnCaptureKey(wxCommandEvent &event);
248  void OnKeyDown(wxKeyEvent &event);
249  void OnKeyUp(wxKeyEvent &event);
250  void OnMouse(wxMouseEvent &event);
251  void OnErase(wxEraseEvent &event);
252  void OnPaint(wxPaintEvent &event);
253  void OnFocus(wxFocusEvent &event);
254  void OnContext(wxContextMenuEvent &event);
255 
256  // Formats mValue into mValueString, using the method of the base class.
257  // Triggers a refresh of the wx window only when the value actually
258  // changed since last time a refresh was triggered.
259  void ValueToControls() override;
260  void ControlsToValue() override;
261 
262  // If autoPos was enabled, focus the first non-zero digit
263  void UpdateAutoFocus();
264 
265  void Updated(bool keyup = false);
266 
267 private:
268 
270  bool mReadOnly;
271 
272  std::unique_ptr<wxBitmap> mBackgroundBitmap;
273 
274  std::unique_ptr<wxFont> mDigitFont, mLabelFont;
277  int mDigitW;
278  int mDigitH;
283  int mWidth;
284  int mHeight;
286 
288 
289  // If true, the focus will be set to the first non-zero digit
290  bool mAutoPos;
291 
292  // Keeps track of extra fractional scrollwheel steps
294 
296 
298 
299  DECLARE_EVENT_TABLE()
300 };
301 
302 #endif // __AUDACITY_TIME_TEXT_CTRL__
TranslatableString
Holds a msgid for the translation catalog; may also bind format arguments.
Definition: TranslatableString.h:32
NumericConverter::SetFormatString
bool SetFormatString(const FormatStrings &formatString)
Definition: NumericTextCtrl.cpp:1115
DigitInfo
DigitInfo is a class used in NumericTextCtrl.
Definition: NumericTextCtrl.cpp:347
NumericTextCtrl::Options::AutoPos
Options & AutoPos(bool enable)
Definition: NumericTextCtrl.h:189
NumericConverter::SetFormatName
bool SetFormatName(const NumericFormatSymbol &formatName)
Definition: NumericTextCtrl.cpp:1109
NumericField
NumericField is a class used in NumericTextCtrl.
Definition: NumericTextCtrl.cpp:301
NumericTextCtrl::mLastField
int mLastField
Definition: NumericTextCtrl.h:287
NumericTextCtrl::mBorderTop
int mBorderTop
Definition: NumericTextCtrl.h:280
BuiltinFormatString
struct to hold a formatting control string and its user facing name Used in an array to hold the buil...
Definition: NumericTextCtrl.cpp:286
NumericConverter::FormatStrings::fraction
TranslatableString fraction
Definition: NumericTextCtrl.h:61
NumericTextCtrl::GetDigitSize
wxSize GetDigitSize()
Definition: NumericTextCtrl.h:231
NumericConverter::mFields
std::vector< NumericField > mFields
Definition: NumericTextCtrl.h:150
NumericTextCtrl::Options::Value
Options & Value(bool has, double v)
Definition: NumericTextCtrl.h:197
NumericConverter::mScalingFactor
double mScalingFactor
Definition: NumericTextCtrl.h:157
DECLARE_EXPORTED_EVENT_TYPE
DECLARE_EXPORTED_EVENT_TYPE(AUDACITY_DLL_API, EVT_TIMETEXTCTRL_UPDATED, -1)
NumericConverter::ATIME
@ ATIME
Definition: NumericTextCtrl.h:52
NumericConverter::mNBuiltins
const size_t mNBuiltins
Definition: NumericTextCtrl.h:165
NumericConverter::mValue
double mValue
Definition: NumericTextCtrl.h:142
NumericConverter::mValueMask
wxString mValueMask
Definition: NumericTextCtrl.h:153
NumericTextCtrl::mBorderBottom
int mBorderBottom
Definition: NumericTextCtrl.h:282
NumericTextCtrl::mBorderLeft
int mBorderLeft
Definition: NumericTextCtrl.h:279
NumericConverter::ValueToControls
virtual void ValueToControls()
Definition: NumericTextCtrl.cpp:947
NumericTextCtrl
Definition: NumericTextCtrl.h:171
NumericConverter::mDigits
std::vector< DigitInfo > mDigits
Definition: NumericTextCtrl.h:162
NumericConverter::mBuiltinFormatStrings
const BuiltinFormatString * mBuiltinFormatStrings
Definition: NumericTextCtrl.h:164
NumericTextCtrl::GetFocusedDigit
int GetFocusedDigit()
Definition: NumericTextCtrl.h:243
NumericConverter::mPrefix
wxString mPrefix
Definition: NumericTextCtrl.h:151
NumericTextCtrlAx
NumericTextCtrlAx gives the NumericTextCtrl Accessibility.
ComponentInterfaceSymbol
ComponentInterfaceSymbol pairs a persistent string identifier used internally with an optional,...
Definition: ComponentInterface.h:61
NumericTextCtrl::Options
Definition: NumericTextCtrl.h:177
NumericConverter::BANDWIDTH
@ BANDWIDTH
Definition: NumericTextCtrl.h:54
operator==
bool operator==(const Tags &lhs, const Tags &rhs)
Definition: Tags.cpp:360
NumericConverter::FormatStrings::formatStr
TranslatableString formatStr
Definition: NumericTextCtrl.h:58
NumericConverter::mNtscDrop
bool mNtscDrop
Definition: NumericTextCtrl.h:159
NumericTextCtrl::mReadOnly
bool mReadOnly
Definition: NumericTextCtrl.h:270
NumericConverter::NumericConverter
NumericConverter(const NumericConverter &)
NumericConverter::mInvalidValue
double mInvalidValue
Definition: NumericTextCtrl.h:146
NumericTextCtrl::mType
NumericConverter::Type mType
Definition: NumericTextCtrl.h:295
NumericTextCtrl::Options::Options
Options()
Definition: NumericTextCtrl.h:187
NumericTextCtrl::Options::InvalidValue
Options & InvalidValue(bool has, double v=-1.0)
Definition: NumericTextCtrl.h:192
NumericConverter::mSampleRate
double mSampleRate
Definition: NumericTextCtrl.h:158
NumericTextCtrl::mWidth
int mWidth
Definition: NumericTextCtrl.h:283
NumericConverter::ControlsToValue
virtual void ControlsToValue()
Definition: NumericTextCtrl.cpp:1058
NumericTextCtrl::mHeight
int mHeight
Definition: NumericTextCtrl.h:284
NumericTextCtrl::mDigitH
int mDigitH
Definition: NumericTextCtrl.h:278
NumericConverter::mType
Type mType
Definition: NumericTextCtrl.h:140
NumericTextCtrl::mDigitBoxW
int mDigitBoxW
Definition: NumericTextCtrl.h:275
NumericTextCtrl::mDigitBoxH
int mDigitBoxH
Definition: NumericTextCtrl.h:276
NumericConverter::mMinValue
double mMinValue
Definition: NumericTextCtrl.h:144
name
const TranslatableString name
Definition: Distortion.cpp:98
NumericConverter::TIME
@ TIME
Definition: NumericTextCtrl.h:51
format
int format
Definition: ExportPCM.cpp:54
NumericTextCtrl::Options::Format
Options & Format(const FormatStrings &f)
Definition: NumericTextCtrl.h:195
NumericTextCtrl::mMenuEnabled
bool mMenuEnabled
Definition: NumericTextCtrl.h:269
NumericTextCtrl::Options::MenuEnabled
Options & MenuEnabled(bool enable)
Definition: NumericTextCtrl.h:191
NumericConverter::mMaxValue
double mMaxValue
Definition: NumericTextCtrl.h:145
NumericConverter::FREQUENCY
@ FREQUENCY
Definition: NumericTextCtrl.h:53
Internat.h
NumericConverter::FormatStrings::FormatStrings
FormatStrings(const TranslatableString &format={}, const TranslatableString &fraction={})
Definition: NumericTextCtrl.h:63
NumericConverter::FormatStrings
Definition: NumericTextCtrl.h:57
NumericTextCtrl::GetDimensions
wxSize GetDimensions()
Definition: NumericTextCtrl.h:230
NumericTextCtrl::mScrollRemainder
double mScrollRemainder
Definition: NumericTextCtrl.h:293
NumericConverter::mDefaultNdx
int mDefaultNdx
Definition: NumericTextCtrl.h:166
NumericConverter
NumericConverter provides the advanced formatting control used in the selection bar of Audacity.
Definition: NumericTextCtrl.h:47
NumericConverter::mFormatString
FormatStrings mFormatString
Definition: NumericTextCtrl.h:148
NumericConverter::mValueTemplate
wxString mValueTemplate
Definition: NumericTextCtrl.h:152
NumericTextCtrl::mLabelFont
std::unique_ptr< wxFont > mLabelFont
Definition: NumericTextCtrl.h:274
NumericConverter::SetValue
void SetValue(double newValue)
Definition: NumericTextCtrl.cpp:1136
NumericTextCtrl::Options::ReadOnly
Options & ReadOnly(bool enable)
Definition: NumericTextCtrl.h:190
NumericTextCtrl::mBackgroundBitmap
std::unique_ptr< wxBitmap > mBackgroundBitmap
Definition: NumericTextCtrl.h:272
NumericTextCtrl::GetFocusedField
int GetFocusedField()
Definition: NumericTextCtrl.h:242
KeyboardCapture::OnFocus
void OnFocus(wxWindow &window, wxFocusEvent &event)
a function useful to implement a focus event handler The window releases the keyboard if the event is...
Definition: KeyboardCapture.cpp:94
NumericConverter::mFocusedDigit
int mFocusedDigit
Definition: NumericTextCtrl.h:161
operator!=
bool operator!=(const SelectedRegion &lhs, const SelectedRegion &rhs)
Definition: SelectedRegion.h:283
NumericConverter::SetSampleRate
void SetSampleRate(double sampleRate)
Definition: NumericTextCtrl.cpp:1128
NumericTextCtrl::mAllowInvalidValue
bool mAllowInvalidValue
Definition: NumericTextCtrl.h:297
NumericConverter::Type
Type
Definition: NumericTextCtrl.h:50
NumericTextCtrl::mAutoPos
bool mAutoPos
Definition: NumericTextCtrl.h:290
NumericTextCtrl::mDigitW
int mDigitW
Definition: NumericTextCtrl.h:277
anonymous_namespace{Menus.cpp}::Options
std::vector< CommandFlagOptions > & Options()
Definition: Menus.cpp:526
NumericTextCtrl::mButtonWidth
int mButtonWidth
Definition: NumericTextCtrl.h:285
NumericConverter::mValueString
wxString mValueString
Definition: NumericTextCtrl.h:155
NumericTextCtrl::mBorderRight
int mBorderRight
Definition: NumericTextCtrl.h:281