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()>;
25using ProgressReporter = std::function<void(double)>;
26
28
30class BASIC_UI_API WindowPlacement {
31public:
32 WindowPlacement() = default;
33
35 WindowPlacement( const WindowPlacement& ) = delete;
39 virtual explicit operator bool() const;
41};
42
43enum class ErrorDialogType {
49};
50
53
54 ErrorDialogOptions() = default;
57
60
61 ErrorDialogOptions &&ModalHelp( bool modalHelp_ ) &&
62 { modalHelp = modalHelp_; return std::move(*this); }
63
64 ErrorDialogOptions &&Log( std::wstring log_ ) &&
65 { log = std::move(log_); return std::move(*this); }
66
68
72 bool modalHelp{ true };
74 std::wstring log;
75};
76
79
80enum class Icon {
81 None,
82 Warning,
83 Error,
86};
87
88enum class Button {
89 Default,
90 Ok,
91 YesNo
92};
93
97
99 { parent = parent_; return std::move(*this); }
100
102 { caption = std::move(caption_); return std::move(*this); }
103
105 { iconStyle = style; return std::move(*this); }
106
108 { buttonStyle = style; return std::move(*this); }
109
112 { yesOrOkDefaultButton = false; return std::move(*this); }
113
115 { cancelButton = true; return std::move(*this); }
116
119 { centered = true; return std::move(*this); }
120
122
128 bool cancelButton{ false };
129 bool centered{ false };
130};
131
132enum class MessageBoxResult : int {
133 None,
134 Yes,
135 No,
136 Ok,
137 Cancel,
138};
139
140enum ProgressDialogOptions : unsigned {
145};
146
147enum class ProgressResult : unsigned
148{
149 Cancelled = 0, //<! User says that whatever is happening is undesirable and shouldn't have happened at all
150 Success, //<! User says nothing, everything works fine, continue doing whatever we're doing
151 Failed, //<! Something has gone wrong, we should stop and cancel everything we did
152 Stopped //<! Nothing is wrong, but user says we should stop now and leave things as they are now
153};
154
156class BASIC_UI_API ProgressDialog
157{
158public:
160
163 unsigned long long numerator,
164 unsigned long long denominator,
165 const TranslatableString &message = {}) = 0;
166
168 virtual void SetMessage(const TranslatableString & message) = 0;
169
171 virtual void SetDialogTitle(const TranslatableString & title) = 0;
172
174 virtual void Reinit() = 0;
175};
176
178class BASIC_UI_API GenericProgressDialog
179{
180public:
183 virtual void Pulse() = 0;
184};
185
187
189
192class BASIC_UI_API Services {
193public:
194 virtual ~Services();
195 virtual void DoCallAfter(const Action &action) = 0;
196 virtual void DoYield() = 0;
197 virtual void DoShowErrorDialog(const WindowPlacement &placement,
198 const TranslatableString &dlogTitle,
199 const TranslatableString &message,
200 const ManualPageID &helpPage,
201 const ErrorDialogOptions &options) = 0;
203 const TranslatableString& message,
204 MessageBoxOptions options) = 0;
205 virtual std::unique_ptr<ProgressDialog>
207 const TranslatableString &message,
208 unsigned flag,
209 const TranslatableString &remainingLabelText) = 0;
210 virtual std::unique_ptr<GenericProgressDialog>
213 const TranslatableString &message) = 0;
214 virtual int DoMultiDialog(const TranslatableString &message,
216 const TranslatableStrings &buttons,
217 const ManualPageID &helpPage,
218 const TranslatableString &boxMsg, bool log) = 0;
219
220 virtual bool DoOpenInDefaultBrowser(const wxString &url) = 0;
221
222 virtual std::unique_ptr<WindowPlacement> DoFindFocus() = 0;
223 virtual void DoSetFocus(const WindowPlacement &focus) = 0;
224
225 virtual bool IsUsingRtlLayout() const = 0;
226};
227
229BASIC_UI_API Services *Get();
230
232BASIC_UI_API Services *Install(Services *pInstance);
233
240
242
246BASIC_UI_API void CallAfter(Action action);
247
249
254BASIC_UI_API void Yield();
255
257
259BASIC_UI_API bool OpenInDefaultBrowser(const wxString &url);
260
262inline void ShowErrorDialog(
263 const WindowPlacement &placement,
264 const TranslatableString &dlogTitle,
265 const TranslatableString &message,
266 const ManualPageID &helpPage,
267 const ErrorDialogOptions &options = {})
268{
269 if (auto p = Get())
270 p->DoShowErrorDialog(placement, dlogTitle, message, helpPage, options);
271}
272
274
278 MessageBoxOptions options = {})
279{
280 if (auto p = Get())
281 return p->DoMessageBox(message, std::move(options));
282 else
284}
285
287
292inline std::unique_ptr<ProgressDialog> MakeProgress(
294 const TranslatableString & message,
295 unsigned flags = (ProgressShowStop | ProgressShowCancel),
296 const TranslatableString & remainingLabelText = {})
297{
298 if (auto p = Get())
299 return p->DoMakeProgress(title, message, flags, remainingLabelText);
300 else
301 return nullptr;
302}
303
305
310inline std::unique_ptr<GenericProgressDialog> MakeGenericProgress(
311 const WindowPlacement &placement,
312 const TranslatableString &title, const TranslatableString &message)
313{
314 if (auto p = Get())
315 return p->DoMakeGenericProgress(placement, title, message);
316 else
317 return nullptr;
318}
319
328template <typename ItType, typename FnType>
330 ItType first, ItType last, FnType action, ProgressReporter parent)
331{
332 auto count = 0;
333 const auto numIters = std::distance(first, last);
334 if (numIters == 0)
335 return;
336 const ProgressReporter child =
337 parent ? [&](double progress) { parent((count + progress) / numIters); } :
339
340 for (; first != last; ++first)
341 {
342 action(*first, child);
343 ++count;
344 }
345}
346
348
357inline int ShowMultiDialog(const TranslatableString &message,
359 const TranslatableStrings &buttons,
360 const ManualPageID &helpPage,
361 const TranslatableString &boxMsg, bool log)
362{
363 if (auto p = Get())
364 return p->DoMultiDialog(message, title, buttons, helpPage, boxMsg, log);
365 else
366 return -1;
367}
368
370
373inline std::unique_ptr<WindowPlacement> FindFocus()
374{
375 if (auto p = Get())
376 if (auto result = p->DoFindFocus())
377 return result;
378 return std::make_unique<WindowPlacement>();
379}
380
382inline void SetFocus(const WindowPlacement &focus)
383{
384 if (auto p = Get())
385 p->DoSetFocus(focus);
386}
387
389inline bool IsUsingRtlLayout()
390{
391 if (auto p = Get())
392 return p->IsUsingRtlLayout();
393 return false;
394}
395
397}
398
399#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:179
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:157
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:192
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 bool IsUsingRtlLayout() const =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:30
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:310
std::function< void(double)> ProgressReporter
Definition: BasicUI.h:25
TranslatableString DefaultCaption()
"Message", suitably translated
Definition: BasicUI.cpp:253
void SetFocus(const WindowPlacement &focus)
Set the window that accepts keyboard input.
Definition: BasicUI.h:382
ProgressResult
Definition: BasicUI.h:148
ProgressDialogOptions
Definition: BasicUI.h:140
@ ProgressHideTime
Definition: BasicUI.h:143
@ ProgressShowCancel
Definition: BasicUI.h:142
@ ProgressConfirmStopOrCancel
Definition: BasicUI.h:144
@ ProgressShowStop
Definition: BasicUI.h:141
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 SplitProgress(ItType first, ItType last, FnType action, ProgressReporter parent)
Helper for the update of a task's progress bar when this task is made of a range's subtasks.
Definition: BasicUI.h:329
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:262
ErrorDialogType
Definition: BasicUI.h:43
Button
Definition: BasicUI.h:88
@ 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:357
std::function< void()> Action
Definition: BasicUI.h:24
bool IsUsingRtlLayout()
Whether using a right-to-left language layout.
Definition: BasicUI.h:389
MessageBoxResult
Definition: BasicUI.h:132
@ 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:277
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:292
std::unique_ptr< WindowPlacement > FindFocus()
Find the window that is accepting keyboard input, if any.
Definition: BasicUI.h:373
Options for variations of error dialogs; the default is for modal dialogs.
Definition: BasicUI.h:52
ErrorDialogType type
Type of help dialog.
Definition: BasicUI.h:70
std::wstring log
Optional extra logging information to be shown.
Definition: BasicUI.h:74
ErrorDialogOptions && ModalHelp(bool modalHelp_) &&
Definition: BasicUI.h:61
ErrorDialogOptions && Log(std::wstring log_) &&
Definition: BasicUI.h:64
ErrorDialogOptions(ErrorDialogType type)
Non-explicit.
Definition: BasicUI.h:56
bool modalHelp
Whether the secondary help dialog with more information should be modal.
Definition: BasicUI.h:72
MessageBoxOptions && CancelButton() &&
Definition: BasicUI.h:114
MessageBoxOptions && Parent(WindowPlacement *parent_) &&
Definition: BasicUI.h:98
TranslatableString caption
Definition: BasicUI.h:124
MessageBoxOptions && Caption(TranslatableString caption_) &&
Definition: BasicUI.h:101
MessageBoxOptions && Centered() &&
Center the dialog on its parent window, if any.
Definition: BasicUI.h:118
WindowPlacement * parent
Definition: BasicUI.h:123
MessageBoxOptions && ButtonStyle(Button style) &&
Definition: BasicUI.h:107
MessageBoxOptions && DefaultIsNo() &&
Override the usual defaulting to Yes; affects only the YesNo case.
Definition: BasicUI.h:111
MessageBoxOptions && IconStyle(Icon style) &&
Definition: BasicUI.h:104