Audacity  3.2.0
BasicUI.h
Go to the documentation of this file.
1 /*!********************************************************************
2 
3 Audacity: A Digital Audio Editor
4 
5 @file BasicUI.h
6 @brief Toolkit-neutral facade for basic user interface services
7 
8 Paul Licameli
9 
10 **********************************************************************/
11 #ifndef __AUDACITY_BASIC_UI__
12 #define __AUDACITY_BASIC_UI__
13 
14 #include <functional>
15 #include <memory>
16 #include "Identifier.h"
17 #include "Internat.h"
18 
19 namespace BasicUI {
20 
23 
24 using Action = std::function<void()>;
25 
27 
29 class BASIC_UI_API WindowPlacement {
30 public:
31  WindowPlacement() = default;
32 
34  WindowPlacement( const WindowPlacement& ) PROHIBITED;
36  WindowPlacement &operator=( const WindowPlacement& ) PROHIBITED;
37  virtual ~WindowPlacement();
38 };
39 
40 enum class ErrorDialogType {
42  ModalError,
46 };
47 
50 
51  ErrorDialogOptions() = default;
54 
57 
58  ErrorDialogOptions &&ModalHelp( bool modalHelp_ ) &&
59  { modalHelp = modalHelp_; return std::move(*this); }
60 
61  ErrorDialogOptions &&Log( std::wstring log_ ) &&
62  { log = std::move(log_); return std::move(*this); }
63 
65 
69  bool modalHelp{ true };
71  std::wstring log;
72 };
73 
75 BASIC_UI_API TranslatableString DefaultCaption();
76 
77 enum class Icon {
78  None,
79  Warning,
80  Error,
81  Question,
83 };
84 
85 enum class Button {
86  Default,
87  Ok,
88  YesNo
89 };
90 
94 
96  { parent = parent_; return std::move(*this); }
97 
99  { caption = std::move(caption_); return std::move(*this); }
100 
102  { iconStyle = style; return std::move(*this); }
103 
105  { buttonStyle = style; return std::move(*this); }
106 
109  { yesOrOkDefaultButton = false; return std::move(*this); }
110 
112  { cancelButton = true; return std::move(*this); }
113 
116  { centered = true; return std::move(*this); }
117 
119 
120  WindowPlacement *parent{ nullptr };
124  bool yesOrOkDefaultButton{ true };
125  bool cancelButton{ false };
126  bool centered{ false };
127 };
128 
129 enum class MessageBoxResult : int {
130  None,
131  Yes,
132  No,
133  Ok,
134  Cancel,
135 };
136 
137 enum ProgressDialogOptions : unsigned {
138  ProgressShowStop = (1 << 0),
139  ProgressShowCancel = (1 << 1),
140  ProgressHideTime = (1 << 2),
142 };
143 
144 enum class ProgressResult : unsigned
145 {
146  Cancelled = 0, //<! User says that whatever is happening is undesirable and shouldn't have happened at all
147  Success, //<! User says nothing, everything works fine, continue doing whatever we're doing
148  Failed, //<! Something has gone wrong, we should stop and cancel everything we did
149  Stopped //<! Nothing is wrong, but user says we should stop now and leave things as they are now
150 };
151 
153 class BASIC_UI_API ProgressDialog
154 {
155 public:
156  virtual ~ProgressDialog();
157 
160  unsigned long long numerator,
161  unsigned long long denominator,
162  const TranslatableString &message = {}) = 0;
163 
165  virtual void SetMessage(const TranslatableString & message) = 0;
166 };
167 
169 class BASIC_UI_API GenericProgressDialog
170 {
171 public:
174  virtual void Pulse() = 0;
175 };
176 
178 
180 
183 class BASIC_UI_API Services {
184 public:
185  virtual ~Services();
186  virtual void DoCallAfter(const Action &action) = 0;
187  virtual void DoYield() = 0;
188  virtual void DoShowErrorDialog(const WindowPlacement &placement,
189  const TranslatableString &dlogTitle,
190  const TranslatableString &message,
191  const ManualPageID &helpPage,
192  const ErrorDialogOptions &options) = 0;
194  const TranslatableString& message,
195  MessageBoxOptions options) = 0;
196  virtual std::unique_ptr<ProgressDialog>
198  const TranslatableString &message,
199  unsigned flag,
200  const TranslatableString &remainingLabelText) = 0;
201  virtual std::unique_ptr<GenericProgressDialog>
203  const TranslatableString &title,
204  const TranslatableString &message) = 0;
205  virtual int DoMultiDialog(const TranslatableString &message,
206  const TranslatableString &title,
207  const TranslatableStrings &buttons,
208  const ManualPageID &helpPage,
209  const TranslatableString &boxMsg, bool log) = 0;
210 };
211 
213 BASIC_UI_API Services *Get();
214 
216 BASIC_UI_API Services *Install(Services *pInstance);
217 
223 
226 
230 BASIC_UI_API void CallAfter(Action action);
231 
233 
238 BASIC_UI_API void Yield();
239 
241 inline void ShowErrorDialog(
242  const WindowPlacement &placement,
243  const TranslatableString &dlogTitle,
244  const TranslatableString &message,
245  const ManualPageID &helpPage,
246  const ErrorDialogOptions &options = {})
247 {
248  if (auto p = Get())
249  p->DoShowErrorDialog(placement, dlogTitle, message, helpPage, options);
250 }
251 
253 
257  MessageBoxOptions options = {})
258 {
259  if (auto p = Get())
260  return p->DoMessageBox(message, std::move(options));
261  else
262  return MessageBoxResult::None;
263 }
264 
266 
271 inline std::unique_ptr<ProgressDialog> MakeProgress(
272  const TranslatableString & title,
273  const TranslatableString & message,
274  unsigned flags = (ProgressShowStop | ProgressShowCancel),
275  const TranslatableString & remainingLabelText = {})
276 {
277  if (auto p = Get())
278  return p->DoMakeProgress(title, message, flags, remainingLabelText);
279  else
280  return nullptr;
281 }
282 
284 
289 inline std::unique_ptr<GenericProgressDialog> MakeGenericProgress(
290  const WindowPlacement &placement,
291  const TranslatableString &title, const TranslatableString &message)
292 {
293  if (auto p = Get())
294  return p->DoMakeGenericProgress(placement, title, message);
295  else
296  return nullptr;
297 }
298 
300 
309 inline int ShowMultiDialog(const TranslatableString &message,
310  const TranslatableString &title,
311  const TranslatableStrings &buttons,
312  const ManualPageID &helpPage,
313  const TranslatableString &boxMsg, bool log)
314 {
315  if (auto p = Get())
316  return p->DoMultiDialog(message, title, buttons, helpPage, boxMsg, log);
317  else
318  return -1;
319 }
320 
322 }
323 
324 #endif
BasicUI::ProgressDialog::~ProgressDialog
virtual ~ProgressDialog()
TranslatableString
Holds a msgid for the translation catalog; may also bind format arguments.
Definition: TranslatableString.h:32
BasicUI::MessageBoxOptions::cancelButton
bool cancelButton
Definition: BasicUI.h:125
BasicUI::GenericProgressDialog::Pulse
virtual void Pulse()=0
Give some visual indication of progress. Call only on the main thread.
BasicUI::MakeProgress
std::unique_ptr< ProgressDialog > MakeProgress(const TranslatableString &title, const TranslatableString &message, unsigned flags=(ProgressShowStop|ProgressShowCancel), const TranslatableString &remainingLabelText={})
Create and display a progress dialog.
Definition: BasicUI.h:271
BasicUI::ErrorDialogOptions::Log
ErrorDialogOptions && Log(std::wstring log_) &&
Definition: BasicUI.h:61
BasicUI::MessageBoxOptions
Definition: BasicUI.h:91
BasicUI::Services::DoMakeProgress
virtual std::unique_ptr< ProgressDialog > DoMakeProgress(const TranslatableString &title, const TranslatableString &message, unsigned flag, const TranslatableString &remainingLabelText)=0
BasicUI::Services::DoMakeGenericProgress
virtual std::unique_ptr< GenericProgressDialog > DoMakeGenericProgress(const WindowPlacement &placement, const TranslatableString &title, const TranslatableString &message)=0
BasicUI::ErrorDialogType
ErrorDialogType
Definition: BasicUI.h:40
BasicUI::ProgressResult::Success
@ Success
BasicUI::ProgressDialog::Poll
virtual ProgressResult Poll(unsigned long long numerator, unsigned long long denominator, const TranslatableString &message={})=0
Update the bar and poll for clicks. Call only on the main thread.
BasicUI::ProgressShowStop
@ ProgressShowStop
Definition: BasicUI.h:138
flag
static std::once_flag flag
Definition: WaveformView.cpp:1133
TranslatableStrings
std::vector< TranslatableString > TranslatableStrings
Definition: TranslatableString.h:295
BasicUI::ShowErrorDialog
void ShowErrorDialog(const WindowPlacement &placement, const TranslatableString &dlogTitle, const TranslatableString &message, const ManualPageID &helpPage, const ErrorDialogOptions &options={})
Show an error dialog with a link to the manual for further help.
Definition: BasicUI.h:241
BasicUI::Button::YesNo
@ YesNo
Two buttons.
BasicUI::ShowMessageBox
MessageBoxResult ShowMessageBox(const TranslatableString &message, MessageBoxOptions options={})
Show a modal message box with either Ok or Yes and No, and optionally Cancel.
Definition: BasicUI.h:256
BasicUI::MessageBoxResult::None
@ None
May be returned if no Services are installed.
BasicUI::ProgressResult
ProgressResult
Definition: BasicUI.h:145
BasicUI::ShowMultiDialog
int ShowMultiDialog(const TranslatableString &message, const TranslatableString &title, const TranslatableStrings &buttons, const ManualPageID &helpPage, const TranslatableString &boxMsg, bool log)
Display a dialog with radio buttons.
Definition: BasicUI.h:309
BasicUI::MessageBoxOptions::ButtonStyle
MessageBoxOptions && ButtonStyle(Button style) &&
Definition: BasicUI.h:104
BasicUI::ErrorDialogOptions::log
std::wstring log
Optional extra logging information to be shown.
Definition: BasicUI.h:71
BasicUI::MessageBoxOptions::CancelButton
MessageBoxOptions && CancelButton() &&
Definition: BasicUI.h:111
BasicUI::CallAfter
void CallAfter(Action action)
Schedule an action to be done later, and in the main thread.
Definition: BasicUI.cpp:38
BasicUI::Services::DoYield
virtual void DoYield()=0
BasicUI::ProgressDialog::SetMessage
virtual void SetMessage(const TranslatableString &message)=0
Change an existing dialog's message.
BasicUI::Action
std::function< void()> Action
Definition: BasicUI.h:24
BasicUI::MessageBoxResult
MessageBoxResult
Definition: BasicUI.h:129
BasicUI::ErrorDialogType::ModalErrorReport
@ ModalErrorReport
BasicUI::ProgressShowCancel
@ ProgressShowCancel
Definition: BasicUI.h:139
BasicUI::ProgressResult::Failed
@ Failed
BasicUI::Icon::Warning
@ Warning
BasicUI::ErrorDialogOptions::type
ErrorDialogType type
Type of help dialog.
Definition: BasicUI.h:67
BasicUI::MessageBoxOptions::buttonStyle
Button buttonStyle
Definition: BasicUI.h:123
BasicUI::GenericProgressDialog::~GenericProgressDialog
virtual ~GenericProgressDialog()
BasicUI::Icon::Information
@ Information
BasicUI::WindowPlacement::WindowPlacement
WindowPlacement()=default
BasicUI::MessageBoxOptions::Centered
MessageBoxOptions && Centered() &&
Center the dialog on its parent window, if any.
Definition: BasicUI.h:115
BasicUI::MessageBoxResult::Cancel
@ Cancel
BasicUI::Get
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:26
BasicUI::WindowPlacement
Subclasses may hold information such as a parent window pointer for a dialog.
Definition: BasicUI.h:29
BasicUI::MessageBoxOptions::iconStyle
Icon iconStyle
Definition: BasicUI.h:122
BasicUI::ErrorDialogOptions::ErrorDialogOptions
ErrorDialogOptions(ErrorDialogType type)
Non-explicit.
Definition: BasicUI.h:53
BasicUI::ErrorDialogType::ModalError
@ ModalError
BasicUI::Icon::None
@ None
Identifier.h
BasicUI::MessageBoxOptions::yesOrOkDefaultButton
bool yesOrOkDefaultButton
Definition: BasicUI.h:124
BasicUI::ErrorDialogOptions::ErrorDialogOptions
ErrorDialogOptions()=default
BasicUI::ProgressResult::Stopped
@ Stopped
BasicUI::Icon::Question
@ Question
BasicUI::ErrorDialogOptions::ModalHelp
ErrorDialogOptions && ModalHelp(bool modalHelp_) &&
Definition: BasicUI.h:58
BasicUI::Icon
Icon
Definition: BasicUI.h:77
BasicUI::MessageBoxOptions::Parent
MessageBoxOptions && Parent(WindowPlacement *parent_) &&
Definition: BasicUI.h:95
BasicUI::ErrorDialogOptions::modalHelp
bool modalHelp
Whether the secondary help dialog with more information should be modal.
Definition: BasicUI.h:69
BasicUI::ProgressResult::Cancelled
@ Cancelled
BasicUI::ErrorDialogOptions
Options for variations of error dialogs; the default is for modal dialogs.
Definition: BasicUI.h:49
Internat.h
BasicUI::ErrorDialogType::ModelessError
@ ModelessError
BasicUI::ProgressDialogOptions
ProgressDialogOptions
Definition: BasicUI.h:137
BasicUI
Definition: Effect.h:47
title
static const auto title
Definition: NoUpdatesAvailableDialog.cpp:22
BasicUI::MessageBoxOptions::Caption
MessageBoxOptions && Caption(TranslatableString caption_) &&
Definition: BasicUI.h:98
BasicUI::MakeGenericProgress
std::unique_ptr< GenericProgressDialog > MakeGenericProgress(const WindowPlacement &placement, const TranslatableString &title, const TranslatableString &message)
Create and display a progress dialog (return nullptr if Services not installed)
Definition: BasicUI.h:289
TaggedIdentifier< ManualPageIDTag >
BasicUI::ProgressHideTime
@ ProgressHideTime
Definition: BasicUI.h:140
BasicUI::ProgressDialog
Abstraction of a progress dialog with well defined time-to-completion estimate.
Definition: BasicUI.h:154
BasicUI::MessageBoxOptions::centered
bool centered
Definition: BasicUI.h:126
BasicUI::WindowPlacement::~WindowPlacement
virtual ~WindowPlacement()
BasicUI::MessageBoxResult::No
@ No
BasicUI::Services::DoCallAfter
virtual void DoCallAfter(const Action &action)=0
BasicUI::DefaultCaption
TranslatableString DefaultCaption()
"Message", suitably translated
Definition: BasicUI.cpp:70
BasicUI::MessageBoxOptions::DefaultIsNo
MessageBoxOptions && DefaultIsNo() &&
Override the usual defaulting to Yes; affects only the YesNo case.
Definition: BasicUI.h:108
BasicUI::Services
Abstract class defines a few user interface services, not mentioning particular toolkits.
Definition: BasicUI.h:183
BasicUI::Button
Button
Definition: BasicUI.h:85
BasicUI::Yield
void Yield()
Dispatch waiting events, including actions enqueued by CallAfter.
Definition: BasicUI.cpp:49
BasicUI::GenericProgressDialog
Abstraction of a progress dialog with undefined time-to-completion estimate.
Definition: BasicUI.h:170
BasicUI::Icon::Error
@ Error
BasicUI::MessageBoxResult::Yes
@ Yes
BasicUI::Install
Services * Install(Services *pInstance)
Install an implementation; return the previously installed instance.
Definition: BasicUI.cpp:28
BasicUI::ProgressConfirmStopOrCancel
@ ProgressConfirmStopOrCancel
Definition: BasicUI.h:141
BasicUI::Services::~Services
virtual ~Services()
BasicUI::Services::DoShowErrorDialog
virtual void DoShowErrorDialog(const WindowPlacement &placement, const TranslatableString &dlogTitle, const TranslatableString &message, const ManualPageID &helpPage, const ErrorDialogOptions &options)=0
BasicUI::MessageBoxResult::Ok
@ Ok
BasicUI::MessageBoxOptions::parent
WindowPlacement * parent
Definition: BasicUI.h:120
BasicUI::Services::DoMultiDialog
virtual int DoMultiDialog(const TranslatableString &message, const TranslatableString &title, const TranslatableStrings &buttons, const ManualPageID &helpPage, const TranslatableString &boxMsg, bool log)=0
BasicUI::MessageBoxOptions::caption
TranslatableString caption
Definition: BasicUI.h:121
BasicUI::WindowPlacement::operator=
WindowPlacement & operator=(const WindowPlacement &) PROHIBITED
Don't slice.
BasicUI::MessageBoxOptions::IconStyle
MessageBoxOptions && IconStyle(Icon style) &&
Definition: BasicUI.h:101
BasicUI::Button::Default
@ Default
Like Ok, except maybe minor difference of dialog position.
BasicUI::Services::DoMessageBox
virtual MessageBoxResult DoMessageBox(const TranslatableString &message, MessageBoxOptions options)=0
BasicUI::Button::Ok
@ Ok
One button.
BasicUI::WindowPlacement::WindowPlacement
WindowPlacement(const WindowPlacement &) PROHIBITED
Don't slice.