Audacity  3.0.3
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 };
164 
166 class BASIC_UI_API GenericProgressDialog
167 {
168 public:
171  virtual void Pulse() = 0;
172 };
173 
175 
177 
180 class BASIC_UI_API Services {
181 public:
182  virtual ~Services();
183  virtual void DoCallAfter(const Action &action) = 0;
184  virtual void DoYield() = 0;
185  virtual void DoShowErrorDialog(const WindowPlacement &placement,
186  const TranslatableString &dlogTitle,
187  const TranslatableString &message,
188  const ManualPageID &helpPage,
189  const ErrorDialogOptions &options) = 0;
191  const TranslatableString& message,
192  MessageBoxOptions options) = 0;
193  virtual std::unique_ptr<ProgressDialog>
195  const TranslatableString &message,
196  unsigned flag,
197  const TranslatableString &remainingLabelText) = 0;
198  virtual std::unique_ptr<GenericProgressDialog>
200  const TranslatableString &title,
201  const TranslatableString &message) = 0;
202 };
203 
205 BASIC_UI_API Services *Get();
206 
208 BASIC_UI_API Services *Install(Services *pInstance);
209 
215 
218 
222 BASIC_UI_API void CallAfter(Action action);
223 
225 
230 BASIC_UI_API void Yield();
231 
233 inline void ShowErrorDialog(
234  const WindowPlacement &placement,
235  const TranslatableString &dlogTitle,
236  const TranslatableString &message,
237  const ManualPageID &helpPage,
238  const ErrorDialogOptions &options = {})
239 {
240  if (auto p = Get())
241  p->DoShowErrorDialog(placement, dlogTitle, message, helpPage, options);
242 }
243 
245 
249  MessageBoxOptions options = {})
250 {
251  if (auto p = Get())
252  return p->DoMessageBox(message, std::move(options));
253  else
254  return MessageBoxResult::None;
255 }
256 
258 
263 inline std::unique_ptr<ProgressDialog> MakeProgress(
264  const TranslatableString & title,
265  const TranslatableString & message,
266  unsigned flags = (ProgressShowStop | ProgressShowCancel),
267  const TranslatableString & remainingLabelText = {})
268 {
269  if (auto p = Get())
270  return p->DoMakeProgress(title, message, flags, remainingLabelText);
271  else
272  return nullptr;
273 }
274 
276 
281 inline std::unique_ptr<GenericProgressDialog> MakeGenericProgress(
282  const WindowPlacement &placement,
283  const TranslatableString &title, const TranslatableString &message)
284 {
285  if (auto p = Get())
286  return p->DoMakeGenericProgress(placement, title, message);
287  else
288  return nullptr;
289 }
290 
292 }
293 
294 #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:263
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:1124
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:233
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:248
BasicUI::MessageBoxResult::None
@ None
May be returned if no Services are installed.
BasicUI::ProgressResult
ProgressResult
Definition: BasicUI.h:145
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::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
title
static const auto title
Definition: UpdateNoticeDialog.cpp:23
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: Export.h:39
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:281
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:180
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:167
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::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.