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& ) = delete;
38 virtual explicit operator bool() const;
40};
41
42enum class ErrorDialogType {
48};
49
52
53 ErrorDialogOptions() = default;
56
59
60 ErrorDialogOptions &&ModalHelp( bool modalHelp_ ) &&
61 { modalHelp = modalHelp_; return std::move(*this); }
62
63 ErrorDialogOptions &&Log( std::wstring log_ ) &&
64 { log = std::move(log_); return std::move(*this); }
65
67
71 bool modalHelp{ true };
73 std::wstring log;
74};
75
78
79enum class Icon {
80 None,
81 Warning,
82 Error,
85};
86
87enum class Button {
88 Default,
89 Ok,
90 YesNo
91};
92
96
98 { parent = parent_; return std::move(*this); }
99
101 { caption = std::move(caption_); return std::move(*this); }
102
104 { iconStyle = style; return std::move(*this); }
105
107 { buttonStyle = style; return std::move(*this); }
108
111 { yesOrOkDefaultButton = false; return std::move(*this); }
112
114 { cancelButton = true; return std::move(*this); }
115
118 { centered = true; return std::move(*this); }
119
121
127 bool cancelButton{ false };
128 bool centered{ false };
129};
130
131enum class MessageBoxResult : int {
132 None,
133 Yes,
134 No,
135 Ok,
136 Cancel,
137};
138
139enum ProgressDialogOptions : unsigned {
144};
145
146enum class ProgressResult : unsigned
147{
148 Cancelled = 0, //<! User says that whatever is happening is undesirable and shouldn't have happened at all
149 Success, //<! User says nothing, everything works fine, continue doing whatever we're doing
150 Failed, //<! Something has gone wrong, we should stop and cancel everything we did
151 Stopped //<! Nothing is wrong, but user says we should stop now and leave things as they are now
152};
153
155class BASIC_UI_API ProgressDialog
156{
157public:
159
162 unsigned long long numerator,
163 unsigned long long denominator,
164 const TranslatableString &message = {}) = 0;
165
167 virtual void SetMessage(const TranslatableString & message) = 0;
168
170 virtual void SetDialogTitle(const TranslatableString & title) = 0;
171
173 virtual void Reinit() = 0;
174};
175
177class BASIC_UI_API GenericProgressDialog
178{
179public:
182 virtual void Pulse() = 0;
183};
184
186
188
191class BASIC_UI_API Services {
192public:
193 virtual ~Services();
194 virtual void DoCallAfter(const Action &action) = 0;
195 virtual void DoYield() = 0;
196 virtual void DoShowErrorDialog(const WindowPlacement &placement,
197 const TranslatableString &dlogTitle,
198 const TranslatableString &message,
199 const ManualPageID &helpPage,
200 const ErrorDialogOptions &options) = 0;
202 const TranslatableString& message,
203 MessageBoxOptions options) = 0;
204 virtual std::unique_ptr<ProgressDialog>
206 const TranslatableString &message,
207 unsigned flag,
208 const TranslatableString &remainingLabelText) = 0;
209 virtual std::unique_ptr<GenericProgressDialog>
212 const TranslatableString &message) = 0;
213 virtual int DoMultiDialog(const TranslatableString &message,
215 const TranslatableStrings &buttons,
216 const ManualPageID &helpPage,
217 const TranslatableString &boxMsg, bool log) = 0;
218
219 virtual bool DoOpenInDefaultBrowser(const wxString &url) = 0;
220
221 virtual std::unique_ptr<WindowPlacement> DoFindFocus() = 0;
222 virtual void DoSetFocus(const WindowPlacement &focus) = 0;
223};
224
226BASIC_UI_API Services *Get();
227
229BASIC_UI_API Services *Install(Services *pInstance);
230
237
239
243BASIC_UI_API void CallAfter(Action action);
244
246
251BASIC_UI_API void Yield();
252
254
256BASIC_UI_API bool OpenInDefaultBrowser(const wxString &url);
257
259inline void ShowErrorDialog(
260 const WindowPlacement &placement,
261 const TranslatableString &dlogTitle,
262 const TranslatableString &message,
263 const ManualPageID &helpPage,
264 const ErrorDialogOptions &options = {})
265{
266 if (auto p = Get())
267 p->DoShowErrorDialog(placement, dlogTitle, message, helpPage, options);
268}
269
271
275 MessageBoxOptions options = {})
276{
277 if (auto p = Get())
278 return p->DoMessageBox(message, std::move(options));
279 else
281}
282
284
289inline std::unique_ptr<ProgressDialog> MakeProgress(
291 const TranslatableString & message,
292 unsigned flags = (ProgressShowStop | ProgressShowCancel),
293 const TranslatableString & remainingLabelText = {})
294{
295 if (auto p = Get())
296 return p->DoMakeProgress(title, message, flags, remainingLabelText);
297 else
298 return nullptr;
299}
300
302
307inline std::unique_ptr<GenericProgressDialog> MakeGenericProgress(
308 const WindowPlacement &placement,
309 const TranslatableString &title, const TranslatableString &message)
310{
311 if (auto p = Get())
312 return p->DoMakeGenericProgress(placement, title, message);
313 else
314 return nullptr;
315}
316
318
327inline int ShowMultiDialog(const TranslatableString &message,
329 const TranslatableStrings &buttons,
330 const ManualPageID &helpPage,
331 const TranslatableString &boxMsg, bool log)
332{
333 if (auto p = Get())
334 return p->DoMultiDialog(message, title, buttons, helpPage, boxMsg, log);
335 else
336 return -1;
337}
338
340
343inline std::unique_ptr<WindowPlacement> FindFocus()
344{
345 if (auto p = Get())
346 if (auto result = p->DoFindFocus())
347 return result;
348 return std::make_unique<WindowPlacement>();
349}
350
352inline void SetFocus(const WindowPlacement &focus)
353{
354 if (auto p = Get())
355 p->DoSetFocus(focus);
356}
357
359}
360
361#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:178
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:156
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:191
virtual std::unique_ptr< GenericProgressDialog > DoMakeGenericProgress(const WindowPlacement &placement, const TranslatableString &title, const TranslatableString &message)=0
virtual std::unique_ptr< WindowPlacement > DoFindFocus()=0
virtual void DoShowErrorDialog(const WindowPlacement &placement, const TranslatableString &dlogTitle, const TranslatableString &message, const ManualPageID &helpPage, const ErrorDialogOptions &options)=0
virtual ~Services()
virtual void DoSetFocus(const WindowPlacement &focus)=0
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 &)=delete
Don't slice.
WindowPlacement(const WindowPlacement &)=delete
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:307
TranslatableString DefaultCaption()
"Message", suitably translated
Definition: BasicUI.cpp:253
void SetFocus(const WindowPlacement &focus)
Set the window that accepts keyboard input.
Definition: BasicUI.h:352
ProgressResult
Definition: BasicUI.h:147
ProgressDialogOptions
Definition: BasicUI.h:139
@ ProgressHideTime
Definition: BasicUI.h:142
@ ProgressShowCancel
Definition: BasicUI.h:141
@ ProgressConfirmStopOrCancel
Definition: BasicUI.h:143
@ ProgressShowStop
Definition: BasicUI.h:140
bool OpenInDefaultBrowser(const wxString &url)
Open an URL in default browser.
Definition: BasicUI.cpp:240
Services * Install(Services *pInstance)
Install an implementation; return the previously installed instance.
Definition: BasicUI.cpp:198
void CallAfter(Action action)
Schedule an action to be done later, and in the main thread.
Definition: BasicUI.cpp:208
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:259
ErrorDialogType
Definition: BasicUI.h:42
Button
Definition: BasicUI.h:87
@ 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:196
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:327
std::function< void()> Action
Definition: BasicUI.h:24
MessageBoxResult
Definition: BasicUI.h:131
@ None
May be returned if no Services are installed.
void Yield()
Dispatch waiting events, including actions enqueued by CallAfter.
Definition: BasicUI.cpp:219
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:274
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:289
std::unique_ptr< WindowPlacement > FindFocus()
Find the window that is accepting keyboard input, if any.
Definition: BasicUI.h:343
Options for variations of error dialogs; the default is for modal dialogs.
Definition: BasicUI.h:51
ErrorDialogType type
Type of help dialog.
Definition: BasicUI.h:69
std::wstring log
Optional extra logging information to be shown.
Definition: BasicUI.h:73
ErrorDialogOptions && ModalHelp(bool modalHelp_) &&
Definition: BasicUI.h:60
ErrorDialogOptions && Log(std::wstring log_) &&
Definition: BasicUI.h:63
ErrorDialogOptions(ErrorDialogType type)
Non-explicit.
Definition: BasicUI.h:55
bool modalHelp
Whether the secondary help dialog with more information should be modal.
Definition: BasicUI.h:71
MessageBoxOptions && CancelButton() &&
Definition: BasicUI.h:113
MessageBoxOptions && Parent(WindowPlacement *parent_) &&
Definition: BasicUI.h:97
TranslatableString caption
Definition: BasicUI.h:123
MessageBoxOptions && Caption(TranslatableString caption_) &&
Definition: BasicUI.h:100
MessageBoxOptions && Centered() &&
Center the dialog on its parent window, if any.
Definition: BasicUI.h:117
WindowPlacement * parent
Definition: BasicUI.h:122
MessageBoxOptions && ButtonStyle(Button style) &&
Definition: BasicUI.h:106
MessageBoxOptions && DefaultIsNo() &&
Override the usual defaulting to Yes; affects only the YesNo case.
Definition: BasicUI.h:110
MessageBoxOptions && IconStyle(Icon style) &&
Definition: BasicUI.h:103