Audacity 3.2.0
Classes | Functions | Variables
BasicUI Namespace Reference


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
struct  Point
 A pair of screen coordinates, x increasing rightward, y downward. More...
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...


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...
bool OpenInDefaultBrowser (const wxString &url)
 Open an URL in default browser. 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...
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. More...
std::unique_ptr< WindowPlacementFindFocus ()
 Find the window that is accepting keyboard input, if any. More...
void SetFocus (const WindowPlacement &focus)
 Set the window that accepts keyboard input. More...


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

Types used in the Services interface

enum class  ErrorDialogType { ModelessError , ModalError , ModalErrorReport }
enum class  Icon {
  None , Warning , Error , Question ,
enum class  Button { Default , Ok , YesNo }
enum class  MessageBoxResult : int {
  None , Yes , No , Ok ,
enum  ProgressDialogOptions : unsigned { ProgressShowStop = (1 << 0) , ProgressShowCancel = (1 << 1) , ProgressHideTime = (1 << 2) , ProgressConfirmStopOrCancel = (1 << 3) }
enum class  ProgressResult : unsigned { Cancelled = 0 , Success , Failed , 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 class BasicUI::Button

Like Ok, except maybe minor difference of dialog position.


One button.


Two buttons.

Definition at line 87 of file BasicUI.h.

87 {
88 Default,
89 Ok,
90 YesNo
@ Ok
One button.
@ YesNo
Two buttons.
NumericFormatSymbol Default(const NumericConverterType &type)
Returns the default format for the type or empty symbol, if no default symbol is registered.

◆ ErrorDialogType

enum class BasicUI::ErrorDialogType

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

Definition at line 42 of file BasicUI.h.

◆ Icon

enum class BasicUI::Icon

Definition at line 79 of file BasicUI.h.

◆ MessageBoxResult

enum class BasicUI::MessageBoxResult : int

May be returned if no Services are installed.


Definition at line 131 of file BasicUI.h.

◆ ProgressDialogOptions


Definition at line 139 of file BasicUI.h.

139 : unsigned {
140 ProgressShowStop = (1 << 0),
141 ProgressShowCancel = (1 << 1),
142 ProgressHideTime = (1 << 2),
@ ProgressHideTime
Definition: BasicUI.h:142
@ ProgressShowCancel
Definition: BasicUI.h:141
@ ProgressConfirmStopOrCancel
Definition: BasicUI.h:143
@ ProgressShowStop
Definition: BasicUI.h:140

◆ ProgressResult

enum class BasicUI::ProgressResult : unsigned

Definition at line 146 of file BasicUI.h.

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

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 208 of file BasicUI.cpp.

210 if (auto p = Get())
211 p->DoCallAfter(action);
212 else {
213 // No services yet -- but don't lose the action. Put it in a queue
214 auto guard = std::lock_guard{ sActionsMutex };
215 sActions.emplace_back(std::move(action));
216 }
static std::vector< Action > sActions
Definition: BasicUI.cpp:206
Services * Get()
Fetch the global instance, or nullptr if none is yet installed.
Definition: BasicUI.cpp:196
static std::recursive_mutex sActionsMutex
Definition: BasicUI.cpp:205

References Get(), sActions, and sActionsMutex.

Referenced by AdornedRulerPanel::AdornedRulerPanel(), Clipboard::Assign(), PrefsListener::Broadcast(), AudioIO::CallAfterRecording(), Clipboard::Clear(), cloud::audiocom::UserService::ClearUserData(), cloud::audiocom::OAuthService::DoAuthorise(), cloud::audiocom::UserService::DownloadAvatar(), AudacityException::EnqueueAction(), UndoManager::EnqueueMessage(), Journal::Events::FailedEventSerialization(), AsyncPluginValidator::Impl::HandleInternalError(), ProjectWindow::HandleResize(), AsyncPluginValidator::Impl::HandleResult(), AudacityApp::InitPart2(), NotifyingSelectedRegion::Notify(), AudioSetupToolBar::OnAudioDeviceRescan(), TrackPanel::OnAudioIO(), AudacityApp::OnExceptionInMainLoop(), App::OnInit(), AudacityApp::OnInit(), AudacityApp::OnInit0(), AdornedRulerPanel::OnLeave(), TrackPanel::OnMouseEvent(), IncompatiblePluginsDialog::OnPluginManagerClicked(), anonymous_namespace{SnappingToolBar.cpp}::SnapModePopup::OnPopup(), ErrorReportDialog::OnSend(), CLExportProcessor::Process(), TrackList::QueueEvent(), ProjectWindow::RedrawProject(), AdornedRulerPanel::Refresh(), TrackPanel::Refresh(), cloud::audiocom::OAuthService::SafePublish(), ProjectFileIO::SaveProject(), TrackPanelAx::SetFocus(), ProjectFileIO::SetProjectTitle(), AudioIO::StopStream(), and cloud::audiocom::UserService::UpdateUserData().

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 253 of file BasicUI.cpp.

255 return XO("Message");

References XO().

Referenced by MessageBoxException::DelayedHandlerAction().

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

◆ FindFocus()

std::unique_ptr< WindowPlacement > BasicUI::FindFocus ( )

Find the window that is accepting keyboard input, if any.

result: result != nullptr (but may point to an empty WindowPlacement)

Definition at line 343 of file BasicUI.h.

345 if (auto p = Get())
346 if (auto result = p->DoFindFocus())
347 return result;
348 return std::make_unique<WindowPlacement>();

References Get().

Referenced by TagsEditorDialog::DoCancel(), EffectUI::DoEffect(), wxWidgetsBasicUI::DoFindFocus(), anonymous_namespace{TrackPanel.cpp}::LabeledChannelGroup::Draw(), EffectPreview(), DeviceToolBar::EnableDisableButtons(), EventMonitor::FilterEvent(), CommandManager::FilterKeyEvent(), EventMonitor::HandleCapture(), ProgressDialog::Init(), ProjectWindow::MacShowUndockedToolbars(), TrackPanelAx::MessageForScreenReader(), anonymous_namespace{NavigationMenus.cpp}::NextOrPrevFrame(), NyqBench::OnAutoWrap(), DeviceToolBar::OnCaptureKey(), SelectionBar::OnCaptureKey(), TranscriptionToolBar::OnCaptureKey(), RealtimeEffectPanel::OnCharHook(), NyqBench::OnClear(), NyqBench::OnClearUpdate(), NyqBench::OnCopy(), NyqBench::OnCopyUpdate(), NyqBench::OnCut(), NyqBench::OnCutUpdate(), KeyView::OnDrawBackground(), KeyView::OnDrawItem(), RealtimeEffectListWindow::OnEffectListItemChange(), ToolBarResizer::OnEnter(), NyqBench::OnFind(), NyqBench::OnFont(), EffectUIHost::OnInitDialog(), NavigationActions::Handler::OnNextWindow(), NyqBench::OnOutputUpdate(), NumericTextCtrl::OnPaint(), NyqBench::OnPaste(), NyqBench::OnPasteUpdate(), NavigationActions::Handler::OnPrevWindow(), NyqBench::OnRedo(), NyqBench::OnRedoUpdate(), LabelDialog::OnRemove(), NyqBench::OnScriptUpdate(), NyqBench::OnSelectAll(), NyqBench::OnUndo(), NyqBench::OnUndoUpdate(), SelectionBar::OnUpdate(), MenuCreator::RebuildMenuBar(), FrequencyPlotDialog::Recalc(), RealtimeEffectListWindow::ReloadEffectsList(), TrackPanelAx::SetFocus(), LabelTrackView::ShowContextMenu(), TrackPanelHasFocus(), HistoryDialog::UpdateLevels(), and wxTabTraversalWrapperCharHook().

Here is the call graph for this function:

◆ Get()

BASIC_UI_API Services * BasicUI::Get ( )

Fetch the global instance, or nullptr if none is yet installed.

Definition at line 196 of file BasicUI.cpp.

196{ return theInstance; }
static Services * theInstance
Definition: BasicUI.cpp:194

References theInstance.

Referenced by audacity::sentry::AddExceptionContext(), audacity::sentry::anonymous_namespace{SentryReport.cpp}::AddOSContext(), CallAfter(), WaveTrack::ConvertToSampleFormat(), audacity::network_manager::CurlHandleManager::CurlHandleManager(), WaveChannelView::DoGetMultiView(), PlayableTrack::DoGetMute(), WaveChannelView::DoGetPlacements(), PlayableTrack::DoGetSolo(), WaveTrack::DoSetGain(), PlayableTrack::DoSetMute(), WaveTrack::DoSetPan(), WaveTrack::DoSetRate(), PlayableTrack::DoSetSolo(), FindFocus(), VST3EffectsModule::FindModulePaths(), FindProjectFrame(), UndoManager::Get(), anonymous_namespace{ProjectWindows.cpp}::ProjectWindows::Get(), anonymous_namespace{PlayableTrack.cpp}::MuteAndSolo::Get(), anonymous_namespace{WaveChannelView.cpp}::PlacementArray::Get(), GetAttachedWindows(), PlatformCompatibility::GetExecutablePath(), WaveTrack::GetGain(), Languages::GetLanguages(), WaveTrack::GetPan(), GetProjectFrame(), GetProjectPanel(), WaveTrack::GetRate(), WaveTrack::GetSampleFormat(), UpdateManager::GetUpdates(), anonymous_namespace{FileNames.cpp}::GetUserTargetDir(), WaveTrack::GetWaveColorIndex(), WaveTrack::HandleXMLTag(), UpdateDataParser::HandleXMLTag(), anonymous_namespace{AudacityApp.cpp}::InitCrashreports(), MakeGenericProgress(), EffectSettingsAccess::ModifySettings(), WaveTrack::MoveTo(), WaveTrack::NewestOrNewClip(), anonymous_namespace{WaveTrackAffordanceControls.cpp}::OnChangeClipSpeed(), anonymous_namespace{WaveTrackAffordanceControls.cpp}::OnEditClipName(), Grid::OnKeyDown(), anonymous_namespace{WaveTrackAffordanceControls.cpp}::OnRenderClipStretching(), OpenInDefaultBrowser(), NyquistEffect::Process(), RemoveDependencies(), WaveTrack::RightmostOrNewClip(), anonymous_namespace{WaveTrackAffordanceControls.cpp}::SelectedIntervalOfFocusedTrack(), audacity::sentry::anonymous_namespace{SentryReport.cpp}::SerializeException(), SetFocus(), SetProjectFrame(), SetProjectPanel(), WaveTrack::SetWaveColorIndex(), ShowMultiDialog(), WaveTrack::WaveTrack(), and Yield().

◆ Install()

BASIC_UI_API Services * BasicUI::Install ( Services pInstance)

Install an implementation; return the previously installed instance.

Definition at line 198 of file BasicUI.cpp.

200 auto result = theInstance;
201 theInstance = pInstance;
202 return result;

References theInstance.

Referenced by AudacityApp::OnInit0().

Here is the caller graph for this function:

◆ MakeGenericProgress()

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

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 307 of file BasicUI.h.

311 if (auto p = Get())
312 return p->DoMakeGenericProgress(placement, title, message);
313 else
314 return nullptr;
static const auto title

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 = {} 

Create and display a progress dialog.

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

Definition at line 289 of file BasicUI.h.

293 {})
295 if (auto p = Get())
296 return p->DoMakeProgress(title, message, flags, remainingLabelText);
297 else
298 return nullptr;

Referenced by ProjectFileIO::CopyTo(), EffectBase::DoEffect(), EffectOutputTracks::EffectOutputTracks(), EffectPreview(), UpdateManager::GetUpdates(), MixAndRender(), anonymous_namespace{EditMenus.cpp}::NotificationScope(), SqliteSampleBlockFactory::OnBeginPurge(), anonymous_namespace{ProjectFileManager.cpp}::ImportProgress::OnImportProgress(), WaveTrackAffordanceControls::OnRenderClipStretching(), anonymous_namespace{TrackMenus.cpp}::OnResample(), anonymous_namespace{EditMenus.cpp}::OnSilence(), EffectAutoDuck::Process(), and anonymous_namespace{ExportProgressUI.cpp}::DialogExportProgressDelegate::UpdateUI().

Here is the caller graph for this function:

◆ OpenInDefaultBrowser()

BASIC_UI_API bool BasicUI::OpenInDefaultBrowser ( const wxString &  url)

Open an URL in default browser.

This function may be called in other threads than the main.

Definition at line 240 of file BasicUI.cpp.

243 if (RunXDGOpen(url.ToStdString()))
244 return true;
247 if(auto p = Get())
248 return p->DoOpenInDefaultBrowser(url);
250 return false;

References Get().

Referenced by cloud::audiocom::ShareAudioDialog::HandleUploadSucceeded(), cloud::audiocom::ShareAudioDialog::InitialStatePanel::OnLinkButtonPressed(), OpenInDefaultBrowser(), RealtimeEffectListWindow::PickEffect(), RealtimeEffectListWindow::RealtimeEffectListWindow(), and AudacityFileConfig::Warn().

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

◆ SetFocus()

void BasicUI::SetFocus ( const WindowPlacement focus)

Set the window that accepts keyboard input.

Definition at line 352 of file BasicUI.h.

354 if (auto p = Get())
355 p->DoSetFocus(focus);

References Get().

Referenced by EffectPreview(), NumericTextCtrl::OnContext(), KeyView::OnLeftDown(), NumericTextCtrl::OnMouse(), wxSliderWrapper::SetFocus(), ListNavigationEnabled< WindowBase >::SetFocus(), AdornedRulerPanel::SetFocusFromKbd(), AButton::SetFocusFromKbd(), ASlider::SetFocusFromKbd(), MeterPanel::SetFocusFromKbd(), and UpdateNoticeDialog::UpdateNoticeDialog().

Here is the call graph for this function:
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 = {} 

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

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

Definition at line 259 of file BasicUI.h.

264 {})
266 if (auto p = Get())
267 p->DoShowErrorDialog(placement, dlogTitle, message, helpPage, options);

Referenced by MessageBoxException::DelayedHandlerAction(), ProjectAudioManager::DoRecord(), ProjectFileManager::DoSave(), EffectPreview(), TempDirectory::FATFilesystemDenied(), UpdateManager::GetUpdates(), cloud::audiocom::ShareAudioDialog::HandleExportFailure(), cloud::audiocom::ShareAudioDialog::HandleUploadFailed(), ProjectFileManager::Import(), ProjectAudioManager::PlayPlayRegion(), ProjectFileIO::ProjectFileIO(), ProjectFileManager::SaveCopy(), ChangeClipSpeedDialog::SetClipSpeedFromDialog(), ExportProgressUI::Show(), 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 = {} 

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

indicates which button was pressed

Definition at line 274 of file BasicUI.h.

275 {})
277 if (auto p = Get())
278 return p->DoMessageBox(message, std::move(options));
279 else
280 return MessageBoxResult::None;

Referenced by AudioIO::AllocateBuffers(), AudioIO::AudioIO(), anonymous_namespace{Registry.cpp}::BadPath(), ExportMP3::CheckFileName(), ConfirmSave(), CreateDirectory(), ThemeBase::CreateImageCache(), ThemeBase::CreateOneImageCache(), MessageBoxException::DelayedHandlerAction(), EffectUI::DoEffect(), DoMessageBox(), PluginManager::DropFile(), ExportProgressUI::ExceptionWrappedCall(), Journal::Events::FailedEventSerialization(), FrequencyPlotDialog::GetAudio(), gtk_filedialog_ok_callback(), VSTWrapper::HandleXMLTag(), ExportOptionsCLEditor::IsValidCommand(), VSTWrapper::LoadFXB(), VSTWrapper::LoadFXP(), MP3Exporter::LoadLibrary(), ThemeBase::LoadOneThemeComponents(), Effect::LoadSettingsFromString(), VSTWrapper::LoadXML(), anonymous_namespace{MIDIPlay.h}::MIDIPlay::MIDIPlay(), RealtimeEffectListWindow::OnAddEffectClicked(), WaveTrackMenuTable::OnMergeStereo(), SelectActions::Handler::OnZeroCrossing(), SFFileCloser::operator()(), ThemeBase::ReadImageCache(), ProjectFileManager::ReadProjectFile(), VSTWrapper::SaveFXB(), VSTWrapper::SaveFXP(), ImportUtils::ShowMessageBox(), AudioIO::StartStream(), and Sequence::WriteXML().

Here is the caller graph for this function:

◆ ShowMultiDialog()

int BasicUI::ShowMultiDialog ( const TranslatableString message,
const TranslatableString title,
const TranslatableStrings buttons,
const ManualPageID helpPage,
const TranslatableString boxMsg,
bool  log 

Display a dialog with radio buttons.

zero-based index of the chosen button, or -1 if Services not installed.
messagemain message in the dialog
titledialog title
buttonslabels for individual radio buttons
boxMsglabel for the group of buttons
helpPageidentifies a manual page
logwhether to add a "Show Log for Details" push button

Definition at line 327 of file BasicUI.h.

333 if (auto p = Get())
334 return p->DoMultiDialog(message, title, buttons, helpPage, boxMsg, log);
335 else
336 return -1;

References Get(), and title.

Referenced by wxWidgetsBasicUI::DoMultiDialog(), ProjectFSCK(), and ModuleManager::TryLoadModules().

Here is the call graph for this function:
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 219 of file BasicUI.cpp.

221 do {
222 // Dispatch anything in the queue, added while there were no Services
223 {
224 auto guard = std::lock_guard{ sActionsMutex };
225 std::vector<Action> actions;
226 actions.swap(sActions);
227 for (auto &action : actions)
228 action();
229 }
231 // Dispatch according to Services, if present
232 if (auto p = Get())
233 p->DoYield();
234 }
235 // Re-test for more actions that might have been enqueued by actions just
236 // dispatched
237 while ( !sActions.empty() );

References Get(), sActions, and sActionsMutex.

Referenced by CLExportProcessor::Process(), cloud::audiocom::ShareAudioDialog::ResetProgress(), and NyquistEffect::ShowHostInterface().

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

Variable Documentation

◆ sActions

std::vector<Action> BasicUI::sActions

Definition at line 206 of file BasicUI.cpp.

Referenced by CallAfter(), and Yield().

◆ sActionsMutex

std::recursive_mutex BasicUI::sActionsMutex

Definition at line 205 of file BasicUI.cpp.

Referenced by CallAfter(), and Yield().

◆ theInstance

Services* BasicUI::theInstance = nullptr

Definition at line 194 of file BasicUI.cpp.

Referenced by Get(), and Install().