BasicUI.h

Go to the documentation of this file.

/*!********************************************************************
 
Audacity: A Digital Audio Editor
 
@file BasicUI.h
@brief Toolkit-neutral facade for basic user interface services
 
Paul Licameli
 
**********************************************************************/
#ifndef __AUDACITY_BASIC_UI__
#define __AUDACITY_BASIC_UI__
 
#include <functional>
#include <memory>
#include "Identifier.h"
#include "Internat.h"
 
namespace BasicUI {
 
 
using Action = std::function<void()>;
using ProgressReporter = std::function<void(double)>;
 
 
class BASIC_UI_API WindowPlacement {
public:
   WindowPlacement() = default;
 
   WindowPlacement( const WindowPlacement& ) = delete;
   WindowPlacement &operator=( const WindowPlacement& ) = delete;
   virtual explicit operator bool() const;
   virtual ~WindowPlacement();
};
 
enum class ErrorDialogType {
   ModelessError,
   ModalError,
   ModalErrorReport, 
};
 
struct ErrorDialogOptions {
 
   ErrorDialogOptions() = default;
   ErrorDialogOptions( ErrorDialogType type ) : type{ type } {}
 
 
   ErrorDialogOptions &&ModalHelp( bool modalHelp_ ) &&
   { modalHelp = modalHelp_; return std::move(*this); }
 
   ErrorDialogOptions &&Log( std::wstring log_ ) &&
   { log = std::move(log_); return std::move(*this); }
 
 
   ErrorDialogType type{ ErrorDialogType::ModalError };
   bool modalHelp{ true };
   std::wstring log;
};
 
BASIC_UI_API TranslatableString DefaultCaption();
 
enum class Icon {
   None,
   Warning,
   Error,
   Question,
   Information,
};
 
enum class Button {
   Default, 
   Ok,      
   YesNo    
};
 
struct MessageBoxOptions {
 
   MessageBoxOptions &&Parent(WindowPlacement *parent_) &&
   { parent = parent_; return std::move(*this); }
 
   MessageBoxOptions &&Caption(TranslatableString caption_) &&
   { caption = std::move(caption_); return std::move(*this); }
 
   MessageBoxOptions &&IconStyle(Icon style) &&
   { iconStyle = style; return std::move(*this); }
 
   MessageBoxOptions &&ButtonStyle(Button style) &&
   { buttonStyle = style; return std::move(*this); }
 
   MessageBoxOptions &&DefaultIsNo() &&
   { yesOrOkDefaultButton = false; return std::move(*this); }
 
   MessageBoxOptions &&CancelButton() &&
   { cancelButton = true; return std::move(*this); }
 
   MessageBoxOptions &&Centered() &&
   { centered = true; return std::move(*this); }
 
 
   WindowPlacement *parent{ nullptr };
   TranslatableString caption{ DefaultCaption() };
   Icon iconStyle{ Icon::None };
   Button buttonStyle{ Button::Default };
   bool yesOrOkDefaultButton{ true };
   bool cancelButton{ false };
   bool centered{ false };
};
 
enum class MessageBoxResult : int {
   None, 
   Yes,
   No,
   Ok,
   Cancel,
};
 
enum ProgressDialogOptions : unsigned {
   ProgressShowStop            = (1 << 0),
   ProgressShowCancel          = (1 << 1),
   ProgressHideTime            = (1 << 2),
   ProgressConfirmStopOrCancel = (1 << 3),
};
 
enum GenericProgressDialogStyle : int {
   ProgressCanAbort            = (1 << 0),
   ProgressAppModal            = (1 << 1),
   ProgressShowElapsedTime     = (1 << 2),
   ProgressSmooth              = (1 << 3),
};
 
enum class ProgressResult : unsigned
{
   Cancelled = 0, //<! User says that whatever is happening is undesirable and shouldn't have happened at all
   Success,       //<! User says nothing, everything works fine, continue doing whatever we're doing
   Failed,        //<! Something has gone wrong, we should stop and cancel everything we did
   Stopped        //<! Nothing is wrong, but user says we should stop now and leave things as they are now
};
 
class BASIC_UI_API ProgressDialog
{
public:
   virtual ~ProgressDialog();
 
   virtual ProgressResult Poll(
      unsigned long long numerator,
      unsigned long long denominator,
      const TranslatableString &message = {}) = 0;
 
   virtual void SetMessage(const TranslatableString & message) = 0;
 
   virtual void SetDialogTitle(const TranslatableString & title) = 0;
 
   virtual void Reinit() = 0;
};
 
class BASIC_UI_API GenericProgressDialog
{
public:
   virtual ~GenericProgressDialog();
   virtual ProgressResult Pulse() = 0;
};
 
 
 
class BASIC_UI_API Services {
public:
   virtual ~Services();
   virtual void DoCallAfter(const Action &action) = 0;
   virtual void DoYield() = 0;
   virtual void DoShowErrorDialog(const WindowPlacement &placement,
      const TranslatableString &dlogTitle,
      const TranslatableString &message,
      const ManualPageID &helpPage,
      const ErrorDialogOptions &options) = 0;
   virtual MessageBoxResult DoMessageBox(
      const TranslatableString& message,
      MessageBoxOptions options) = 0;
   virtual std::unique_ptr<ProgressDialog>
   DoMakeProgress(const TranslatableString &title,
      const TranslatableString &message,
      unsigned flag,
      const TranslatableString &remainingLabelText) = 0;
   virtual std::unique_ptr<GenericProgressDialog>
   DoMakeGenericProgress(const WindowPlacement &placement,
      const TranslatableString &title,
      const TranslatableString &message,
      int style) = 0;
   virtual int DoMultiDialog(const TranslatableString &message,
      const TranslatableString &title,
      const TranslatableStrings &buttons,
      const ManualPageID &helpPage,
      const TranslatableString &boxMsg, bool log) = 0;
 
   virtual bool DoOpenInDefaultBrowser(const wxString &url) = 0;
 
   virtual std::unique_ptr<WindowPlacement> DoFindFocus() = 0;
   virtual void DoSetFocus(const WindowPlacement &focus) = 0;
 
   virtual bool IsUsingRtlLayout() const = 0;
 
   virtual bool IsUiThread() const = 0;
};
 
BASIC_UI_API Services *Get();
 
BASIC_UI_API Services *Install(Services *pInstance);
 
 
 
BASIC_UI_API void CallAfter(Action action);
 
 
BASIC_UI_API void Yield();
 
 
BASIC_UI_API bool OpenInDefaultBrowser(const wxString &url);
 
inline void ShowErrorDialog(
   const WindowPlacement &placement,    
   const TranslatableString &dlogTitle, 
   const TranslatableString &message,   
   const ManualPageID &helpPage,          
   const ErrorDialogOptions &options = {})
{
   if (auto p = Get())
      p->DoShowErrorDialog(placement, dlogTitle, message, helpPage, options);
}
 
 
inline MessageBoxResult ShowMessageBox( const TranslatableString &message,
   MessageBoxOptions options = {})
{
   if (auto p = Get())
      return p->DoMessageBox(message, std::move(options));
   else
      return MessageBoxResult::None;
}
 
 
inline std::unique_ptr<ProgressDialog> MakeProgress(
   const TranslatableString & title,
   const TranslatableString & message,
   unsigned flags = (ProgressShowStop | ProgressShowCancel),
   const TranslatableString & remainingLabelText = {})
{
   if (auto p = Get())
      return p->DoMakeProgress(title, message, flags, remainingLabelText);
   else
      return nullptr;
}
 
 
inline std::unique_ptr<GenericProgressDialog> MakeGenericProgress(
   const WindowPlacement &placement,
   const TranslatableString &title, const TranslatableString &message, int style = (ProgressAppModal | ProgressShowElapsedTime | ProgressSmooth))
{
   if (auto p = Get())
      return p->DoMakeGenericProgress(placement, title, message, style);
   else
      return nullptr;
}
 
template <typename ItType, typename FnType>
void SplitProgress(
   ItType first, ItType last, FnType action, ProgressReporter parent)
{
   auto count = 0;
   const auto numIters = std::distance(first, last);
   if (numIters == 0)
      return;
   const ProgressReporter child =
      parent ? [&](double progress) { parent((count + progress) / numIters); } :
               ProgressReporter {};
 
   for (; first != last; ++first)
   {
      action(*first, child);
      ++count;
   }
}
 
 
inline int ShowMultiDialog(const TranslatableString &message,
   const TranslatableString &title,
   const TranslatableStrings &buttons,
   const ManualPageID &helpPage,
   const TranslatableString &boxMsg, bool log)
{
   if (auto p = Get())
      return p->DoMultiDialog(message, title, buttons, helpPage, boxMsg, log);
   else
      return -1;
}
 
 
inline std::unique_ptr<WindowPlacement> FindFocus()
{
   if (auto p = Get())
      if (auto result = p->DoFindFocus())
         return result;
   return std::make_unique<WindowPlacement>();
}
 
inline void SetFocus(const WindowPlacement &focus)
{
   if (auto p = Get())
      p->DoSetFocus(focus);
}
 
inline bool IsUsingRtlLayout()
{
   if (auto p = Get())
      return p->IsUsingRtlLayout();
   return false;
}
 
inline bool IsUiThread ()
{
   if (auto p = Get())
      return p->IsUiThread();
   return true;
}
 
#define ASSERT_MAIN_THREAD() \
   assert(                     \
      BasicUI::IsUiThread() && \
      "This function should only be called on the main thread")
 
}
 
#endif