Audacity 3.2.0
BasicUI.h
Go to the documentation of this file.
1/*!********************************************************************
2
3Audacity: A Digital Audio Editor
4
5@file BasicUI.h
6@brief Toolkit-neutral facade for basic user interface services
7
8Paul 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
19namespace BasicUI {
20
23
24using Action = std::function<void()>;
25
27
29class BASIC_UI_API WindowPlacement {
30public:
31 WindowPlacement() = default;
32
34 WindowPlacement( const WindowPlacement& ) PROHIBITED;
38};
39
40enum class ErrorDialogType {
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
76
77enum class Icon {
78 None,
79 Warning,
80 Error,
83};
84
85enum 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
125 bool cancelButton{ false };
126 bool centered{ false };
127};
128
129enum class MessageBoxResult : int {
130 None,
131 Yes,
132 No,
133 Ok,
134 Cancel,
135};
136
137enum ProgressDialogOptions : unsigned {
142};
143
144enum 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
153class BASIC_UI_API ProgressDialog
154{
155public:
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
168 virtual void SetDialogTitle(const TranslatableString & title) = 0;
169
171 virtual void Reinit() = 0;
172};
173
175class BASIC_UI_API GenericProgressDialog
176{
177public:
180 virtual void Pulse() = 0;
181};
182
184
186
189class BASIC_UI_API Services {
190public:
191 virtual ~Services();
192 virtual void DoCallAfter(const Action &action) = 0;
193 virtual void DoYield() = 0;
194 virtual void DoShowErrorDialog(const WindowPlacement &placement,
195 const TranslatableString &dlogTitle,
196 const TranslatableString &message,
197 const ManualPageID &helpPage,
198 const ErrorDialogOptions &options) = 0;
200 const TranslatableString& message,
201 MessageBoxOptions options) = 0;
202 virtual std::unique_ptr<ProgressDialog>
204 const TranslatableString &message,
205 unsigned flag,
206 const TranslatableString &remainingLabelText) = 0;
207 virtual std::unique_ptr<GenericProgressDialog>
210 const TranslatableString &message) = 0;
211 virtual int DoMultiDialog(const TranslatableString &message,
213 const TranslatableStrings &buttons,
214 const ManualPageID &helpPage,
215 const TranslatableString &boxMsg, bool log) = 0;
216
217 virtual bool DoOpenInDefaultBrowser(const wxString &url) = 0;
218};
219
221BASIC_UI_API Services *Get();
222
224BASIC_UI_API Services *Install(Services *pInstance);
225
232
234
238BASIC_UI_API void CallAfter(Action action);
239
241
246BASIC_UI_API void Yield();
247
249
251BASIC_UI_API bool OpenInDefaultBrowser(const wxString &url);
252
254inline void ShowErrorDialog(
255 const WindowPlacement &placement,
256 const TranslatableString &dlogTitle,
257 const TranslatableString &message,
258 const ManualPageID &helpPage,
259 const ErrorDialogOptions &options = {})
260{
261 if (auto p = Get())
262 p->DoShowErrorDialog(placement, dlogTitle, message, helpPage, options);
263}
264
266
270 MessageBoxOptions options = {})
271{
272 if (auto p = Get())
273 return p->DoMessageBox(message, std::move(options));
274 else
276}
277
279
284inline std::unique_ptr<ProgressDialog> MakeProgress(
286 const TranslatableString & message,
287 unsigned flags = (ProgressShowStop | ProgressShowCancel),
288 const TranslatableString & remainingLabelText = {})
289{
290 if (auto p = Get())
291 return p->DoMakeProgress(title, message, flags, remainingLabelText);
292 else
293 return nullptr;
294}
295
297
302inline std::unique_ptr<GenericProgressDialog> MakeGenericProgress(
303 const WindowPlacement &placement,
304 const TranslatableString &title, const TranslatableString &message)
305{
306 if (auto p = Get())
307 return p->DoMakeGenericProgress(placement, title, message);
308 else
309 return nullptr;
310}
311
313
322inline int ShowMultiDialog(const TranslatableString &message,
324 const TranslatableStrings &buttons,
325 const ManualPageID &helpPage,
326 const TranslatableString &boxMsg, bool log)
327{
328 if (auto p = Get())
329 return p->DoMultiDialog(message, title, buttons, helpPage, boxMsg, log);
330 else
331 return -1;
332}
333
335}
336
337#endif
static const auto title
std::vector< TranslatableString > TranslatableStrings
static std::once_flag flag
Abstraction of a progress dialog with undefined time-to-completion estimate.
Definition: BasicUI.h:176
virtual void Pulse()=0
Give some visual indication of progress. Call only on the main thread.
Abstraction of a progress dialog with well defined time-to-completion estimate.
Definition: BasicUI.h:154
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.
virtual void SetMessage(const TranslatableString &message)=0
Change an existing dialog's message.
virtual void SetDialogTitle(const TranslatableString &title)=0
Change the dialog's title.
virtual void Reinit()=0
Reset the dialog state.
Abstract class defines a few user interface services, not mentioning particular toolkits.
Definition: BasicUI.h:189
virtual std::unique_ptr< GenericProgressDialog > DoMakeGenericProgress(const WindowPlacement &placement, const TranslatableString &title, const TranslatableString &message)=0
virtual void DoShowErrorDialog(const WindowPlacement &placement, const TranslatableString &dlogTitle, const TranslatableString &message, const ManualPageID &helpPage, const ErrorDialogOptions &options)=0
virtual ~Services()
virtual std::unique_ptr< ProgressDialog > DoMakeProgress(const TranslatableString &title, const TranslatableString &message, unsigned flag, const TranslatableString &remainingLabelText)=0
virtual MessageBoxResult DoMessageBox(const TranslatableString &message, MessageBoxOptions options)=0
virtual int DoMultiDialog(const TranslatableString &message, const TranslatableString &title, const TranslatableStrings &buttons, const ManualPageID &helpPage, const TranslatableString &boxMsg, bool log)=0
virtual void DoCallAfter(const Action &action)=0
virtual bool DoOpenInDefaultBrowser(const wxString &url)=0
virtual void DoYield()=0
Subclasses may hold information such as a parent window pointer for a dialog.
Definition: BasicUI.h:29
WindowPlacement & operator=(const WindowPlacement &) PROHIBITED
Don't slice.
WindowPlacement(const WindowPlacement &) PROHIBITED
Don't slice.
Holds a msgid for the translation catalog; may also bind format arguments.
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:302
TranslatableString DefaultCaption()
"Message", suitably translated
Definition: BasicUI.cpp:251
ProgressResult
Definition: BasicUI.h:145
ProgressDialogOptions
Definition: BasicUI.h:137
@ ProgressHideTime
Definition: BasicUI.h:140
@ ProgressShowCancel
Definition: BasicUI.h:139
@ ProgressConfirmStopOrCancel
Definition: BasicUI.h:141
@ ProgressShowStop
Definition: BasicUI.h:138
bool OpenInDefaultBrowser(const wxString &url)
Open an URL in default browser.
Definition: BasicUI.cpp:238
Services * Install(Services *pInstance)
Install an implementation; return the previously installed instance.
Definition: BasicUI.cpp:196
void CallAfter(Action action)
Schedule an action to be done later, and in the main thread.
Definition: BasicUI.cpp:206
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:254
ErrorDialogType
Definition: BasicUI.h:40
Button
Definition: BasicUI.h:85
@ Default
Like Ok, except maybe minor difference of dialog position.
@ Ok
One button.
@ YesNo
Two buttons.
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:194
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:322
std::function< void()> Action
Definition: BasicUI.h:24
MessageBoxResult
Definition: BasicUI.h:129
@ None
May be returned if no Services are installed.
void Yield()
Dispatch waiting events, including actions enqueued by CallAfter.
Definition: BasicUI.cpp:217
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:269
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:284
Options for variations of error dialogs; the default is for modal dialogs.
Definition: BasicUI.h:49
ErrorDialogType type
Type of help dialog.
Definition: BasicUI.h:67
std::wstring log
Optional extra logging information to be shown.
Definition: BasicUI.h:71
ErrorDialogOptions && ModalHelp(bool modalHelp_) &&
Definition: BasicUI.h:58
ErrorDialogOptions && Log(std::wstring log_) &&
Definition: BasicUI.h:61
ErrorDialogOptions(ErrorDialogType type)
Non-explicit.
Definition: BasicUI.h:53
bool modalHelp
Whether the secondary help dialog with more information should be modal.
Definition: BasicUI.h:69
MessageBoxOptions && CancelButton() &&
Definition: BasicUI.h:111
MessageBoxOptions && Parent(WindowPlacement *parent_) &&
Definition: BasicUI.h:95
TranslatableString caption
Definition: BasicUI.h:121
MessageBoxOptions && Caption(TranslatableString caption_) &&
Definition: BasicUI.h:98
MessageBoxOptions && Centered() &&
Center the dialog on its parent window, if any.
Definition: BasicUI.h:115
WindowPlacement * parent
Definition: BasicUI.h:120
MessageBoxOptions && ButtonStyle(Button style) &&
Definition: BasicUI.h:104
MessageBoxOptions && DefaultIsNo() &&
Override the usual defaulting to Yes; affects only the YesNo case.
Definition: BasicUI.h:108
MessageBoxOptions && IconStyle(Icon style) &&
Definition: BasicUI.h:101