Audacity  3.0.3
Classes | Functions | Variables
BasicUI Namespace Reference

Classes

struct  ErrorDialogOptions
 Options for variations of error dialogs; the default is for modal dialogs. More...
 
class  GenericProgressDialog
 Abstraction of a progress dialog with undefined time-to-completion estimate. More...
 
struct  MessageBoxOptions
 
class  ProgressDialog
 Abstraction of a progress dialog with well defined time-to-completion estimate. More...
 
class  Services
 Abstract class defines a few user interface services, not mentioning particular toolkits. More...
 
class  WindowPlacement
 Subclasses may hold information such as a parent window pointer for a dialog. More...
 

Functions

ServicesGet ()
 Fetch the global instance, or nullptr if none is yet installed. More...
 
ServicesInstall (Services *pInstance)
 Install an implementation; return the previously installed instance. More...
 
Functions that invoke global Services

These dispatch to the global Services, if supplied. If none was supplied, they are mostly no-ops, with exceptions as noted. All should be called on the main thread only, except as noted.

void CallAfter (Action action)
 Schedule an action to be done later, and in the main thread. More...
 
void Yield ()
 Dispatch waiting events, including actions enqueued by CallAfter. More...
 
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. More...
 
MessageBoxResult ShowMessageBox (const TranslatableString &message, MessageBoxOptions options={})
 Show a modal message box with either Ok or Yes and No, and optionally Cancel. More...
 
std::unique_ptr< ProgressDialogMakeProgress (const TranslatableString &title, const TranslatableString &message, unsigned flags=(ProgressShowStop|ProgressShowCancel), const TranslatableString &remainingLabelText={})
 Create and display a progress dialog. More...
 
std::unique_ptr< GenericProgressDialogMakeGenericProgress (const WindowPlacement &placement, const TranslatableString &title, const TranslatableString &message)
 Create and display a progress dialog (return nullptr if Services not installed) More...
 

Variables

static ServicestheInstance = nullptr
 
static std::recursive_mutex sActionsMutex
 
static std::vector< ActionsActions
 

Types used in the Services interface

enum  ErrorDialogType { ErrorDialogType::ModelessError, ErrorDialogType::ModalError, ErrorDialogType::ModalErrorReport }
 
enum  Icon {
  Icon::None, Icon::Warning, Icon::Error, Icon::Question,
  Icon::Information
}
 
enum  Button { Button::Default, Button::Ok, Button::YesNo }
 
enum  MessageBoxResult : int {
  MessageBoxResult::None, MessageBoxResult::Yes, MessageBoxResult::No, MessageBoxResult::Ok,
  MessageBoxResult::Cancel
}
 
enum  ProgressDialogOptions : unsigned { ProgressShowStop = (1 << 0), ProgressShowCancel = (1 << 1), ProgressHideTime = (1 << 2), ProgressConfirmStopOrCancel = (1 << 3) }
 
enum  ProgressResult : unsigned { ProgressResult::Cancelled = 0, ProgressResult::Success, ProgressResult::Failed, ProgressResult::Stopped }
 
using Action = std::function< void()>
 
TranslatableString DefaultCaption ()
 "Message", suitably translated More...
 

Typedef Documentation

◆ Action

using BasicUI::Action = typedef std::function<void()>

Definition at line 24 of file BasicUI.h.

Enumeration Type Documentation

◆ Button

enum BasicUI::Button
strong
Enumerator
Default 

Like Ok, except maybe minor difference of dialog position.

Ok 

One button.

YesNo 

Two buttons.

Definition at line 85 of file BasicUI.h.

85  {
86  Default,
87  Ok,
88  YesNo
89 };

◆ ErrorDialogType

Enumerator
ModelessError 
ModalError 
ModalErrorReport 

If error reporting is enabled, may give option to send; if not, then like ModalError

Definition at line 40 of file BasicUI.h.

40  {
42  ModalError,
46 };

◆ Icon

enum BasicUI::Icon
strong
Enumerator
None 
Warning 
Error 
Question 
Information 

Definition at line 77 of file BasicUI.h.

77  {
78  None,
79  Warning,
80  Error,
81  Question,
83 };

◆ MessageBoxResult

enum BasicUI::MessageBoxResult : int
strong
Enumerator
None 

May be returned if no Services are installed.

Yes 
No 
Ok 
Cancel 

Definition at line 129 of file BasicUI.h.

129  : int {
130  None,
131  Yes,
132  No,
133  Ok,
134  Cancel,
135 };

◆ ProgressDialogOptions

Enumerator
ProgressShowStop 
ProgressShowCancel 
ProgressHideTime 
ProgressConfirmStopOrCancel 

Definition at line 137 of file BasicUI.h.

137  : unsigned {
138  ProgressShowStop = (1 << 0),
139  ProgressShowCancel = (1 << 1),
140  ProgressHideTime = (1 << 2),
141  ProgressConfirmStopOrCancel = (1 << 3),
142 };

◆ ProgressResult

enum BasicUI::ProgressResult : unsigned
strong
Enumerator
Cancelled 
Success 
Failed 
Stopped 

Definition at line 144 of file BasicUI.h.

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 };

Function Documentation

◆ CallAfter()

BASIC_UI_API void BasicUI::CallAfter ( Action  action)

Schedule an action to be done later, and in the main thread.

This function may be called in other threads than the main. If no Services are yet installed, the action is not lost, but may be dispatched by Yield(). The action may itself invoke CallAfter to enqueue other actions.

Definition at line 38 of file BasicUI.cpp.

39 {
40  if (auto p = Get())
41  p->DoCallAfter(action);
42  else {
43  // No services yet -- but don't lose the action. Put it in a queue
44  auto guard = std::lock_guard{ sActionsMutex };
45  sActions.emplace_back(std::move(action));
46  }
47 }

References Get(), sActions, and sActionsMutex.

Referenced by AdornedRulerPanel::AdornedRulerPanel(), PrefsListener::Broadcast(), AudacityException::EnqueueAction(), ProjectWindow::HandleResize(), AudacityApp::InitPart2(), TrackPanel::OnAudioIO(), AudacityApp::OnExceptionInMainLoop(), AudacityApp::OnInit(), TrackPanel::OnMouseEvent(), ErrorReportDialog::OnSend(), ProjectWindow::RedrawProject(), AdornedRulerPanel::Refresh(), and TrackPanel::Refresh().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ DefaultCaption()

BASIC_UI_API TranslatableString BasicUI::DefaultCaption ( )

"Message", suitably translated

Definition at line 70 of file BasicUI.cpp.

71 {
72  return XO("Message");
73 }

References XO.

Referenced by MessageBoxException::DelayedHandlerAction().

Here is the caller graph for this function:

◆ Get()

BASIC_UI_API Services * BasicUI::Get ( )

◆ Install()

BASIC_UI_API Services * BasicUI::Install ( Services pInstance)

Install an implementation; return the previously installed instance.

Definition at line 28 of file BasicUI.cpp.

29 {
30  auto result = theInstance;
31  theInstance = pInstance;
32  return result;
33 }

References theInstance.

Referenced by AudacityApp::OnInit().

Here is the caller graph for this function:

◆ MakeGenericProgress()

std::unique_ptr<GenericProgressDialog> BasicUI::MakeGenericProgress ( const WindowPlacement placement,
const TranslatableString title,
const TranslatableString message 
)
inline

Create and display a progress dialog (return nullptr if Services not installed)

This function makes a "generic" progress dialog, for the case when time to completion cannot be estimated, but some indication of progress is still given

Definition at line 281 of file BasicUI.h.

284 {
285  if (auto p = Get())
286  return p->DoMakeGenericProgress(placement, title, message);
287  else
288  return nullptr;
289 }

References Get(), and title.

Referenced by DBConnection::Close(), ProjectFileIO::RenameOrWarn(), and ProjectFileIO::SaveProject().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ MakeProgress()

std::unique_ptr<ProgressDialog> BasicUI::MakeProgress ( const TranslatableString title,
const TranslatableString message,
unsigned  flags = (ProgressShowStop | ProgressShowCancel),
const TranslatableString remainingLabelText = {} 
)
inline

Create and display a progress dialog.

Parameters
flagsbitwise OR of values in ProgressDialogOptions
remainingLabelTextif not empty substitutes for "Remaining Time:"
Returns
nullptr if Services not installed

Definition at line 263 of file BasicUI.h.

267  {})
268 {
269  if (auto p = Get())
270  return p->DoMakeProgress(title, message, flags, remainingLabelText);
271  else
272  return nullptr;
273 }

Referenced by UpdateManager::GetUpdates().

Here is the caller graph for this function:

◆ ShowErrorDialog()

void BasicUI::ShowErrorDialog ( const WindowPlacement placement,
const TranslatableString dlogTitle,
const TranslatableString message,
const ManualPageID helpPage,
const ErrorDialogOptions options = {} 
)
inline

Show an error dialog with a link to the manual for further help.

Parameters
placementhow to parent the dialog
dlogTitleText for title bar
messageThe main message text
helpPageIdentifies manual page (and maybe an anchor)

Definition at line 233 of file BasicUI.h.

238  {})
239 {
240  if (auto p = Get())
241  p->DoShowErrorDialog(placement, dlogTitle, message, helpPage, options);
242 }

Referenced by MessageBoxException::DelayedHandlerAction(), ProjectAudioManager::DoRecord(), ProjectFileManager::DoSave(), TempDirectory::FATFilesystemDenied(), UpdateManager::GetUpdates(), ProjectFileManager::Import(), ProjectAudioManager::PlayPlayRegion(), Effect::Preview(), ExportPCM::ReportTooBigError(), ProjectFileManager::SaveCopy(), ShowDiskFullExportErrorDialog(), ProjectFileIO::ShowError(), ShowExportErrorDialog(), AudioIO::StartMonitoring(), MenuManager::TellUserWhyDisallowed(), and TempDirectory::TempDir().

Here is the caller graph for this function:

◆ ShowMessageBox()

MessageBoxResult BasicUI::ShowMessageBox ( const TranslatableString message,
MessageBoxOptions  options = {} 
)
inline

Show a modal message box with either Ok or Yes and No, and optionally Cancel.

Returns
indicates which button was pressed

Definition at line 248 of file BasicUI.h.

249  {})
250 {
251  if (auto p = Get())
252  return p->DoMessageBox(message, std::move(options));
253  else
254  return MessageBoxResult::None;
255 }

Referenced by anonymous_namespace{Registry.cpp}::BadPath(), CreateDirectory(), MessageBoxException::DelayedHandlerAction(), and ThemeBase::SaveComponents().

Here is the caller graph for this function:

◆ Yield()

BASIC_UI_API void BasicUI::Yield ( )

Dispatch waiting events, including actions enqueued by CallAfter.

This function must be called by the main thread. Actions enqueued by CallAfter before Services were installed will be dispatched in the sequence they were enqueued, unless an exception thrown by one of them stops the dispatching.

Definition at line 49 of file BasicUI.cpp.

50 {
51  do {
52  // Dispatch anything in the queue, added while there were no Services
53  {
54  auto guard = std::lock_guard{ sActionsMutex };
55  std::vector<Action> actions;
56  actions.swap(sActions);
57  for (auto &action : actions)
58  action();
59  }
60 
61  // Dispatch according to Services, if present
62  if (auto p = Get())
63  p->DoYield();
64  }
65  // Re-test for more actions that might have been enqueued by actions just
66  // dispatched
67  while ( !sActions.empty() );
68 }

References Get(), sActions, and sActionsMutex.

Here is the call graph for this function:

Variable Documentation

◆ sActions

std::vector<Action> BasicUI::sActions
static

Definition at line 36 of file BasicUI.cpp.

Referenced by CallAfter(), and Yield().

◆ sActionsMutex

std::recursive_mutex BasicUI::sActionsMutex
static

Definition at line 35 of file BasicUI.cpp.

Referenced by CallAfter(), and Yield().

◆ theInstance

Services* BasicUI::theInstance = nullptr
static

Definition at line 24 of file BasicUI.cpp.

Referenced by Get(), and Install().

BasicUI::ProgressResult::Success
@ Success
BasicUI::ProgressShowStop
@ ProgressShowStop
Definition: BasicUI.h:138
TrackKind::None
@ None
no class
BasicUI::Button::YesNo
@ YesNo
Two buttons.
BasicUI::theInstance
static Services * theInstance
Definition: BasicUI.cpp:24
RefreshCode::Cancelled
@ Cancelled
Definition: RefreshCode.h:23
XO
#define XO(s)
Definition: Internat.h:31
BasicUI::ErrorDialogType::ModalErrorReport
@ ModalErrorReport
BasicUI::ProgressShowCancel
@ ProgressShowCancel
Definition: BasicUI.h:139
BasicUI::ProgressResult::Failed
@ Failed
BasicUI::Icon::Warning
@ Warning
BasicUI::Icon::Information
@ Information
BasicUI::MessageBoxResult::Cancel
@ Cancel
BasicUI::Get
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:26
BasicUI::sActions
static std::vector< Action > sActions
Definition: BasicUI.cpp:36
BasicUI::ErrorDialogType::ModalError
@ ModalError
BasicUI::ProgressResult::Stopped
@ Stopped
BasicUI::Icon::Question
@ Question
title
static const auto title
Definition: UpdateNoticeDialog.cpp:23
BasicUI::ErrorDialogType::ModelessError
@ ModelessError
BasicUI::ProgressHideTime
@ ProgressHideTime
Definition: BasicUI.h:140
BasicUI::MessageBoxResult::No
@ No
BasicUI::Icon::Error
@ Error
BasicUI::MessageBoxResult::Yes
@ Yes
BasicUI::ProgressConfirmStopOrCancel
@ ProgressConfirmStopOrCancel
Definition: BasicUI.h:141
BasicUI::sActionsMutex
static std::recursive_mutex sActionsMutex
Definition: BasicUI.cpp:35
BasicUI::Button::Default
@ Default
Like Ok, except maybe minor difference of dialog position.
BasicUI::Button::Ok
@ Ok
One button.