AccessibleLinksFormatter Class Reference

A class that allows translatable text to have accessible links in it in a way that is friendly to translators. More...

#include <AccessibleLinksFormatter.h>

Collaboration diagram for AccessibleLinksFormatter:

Classes
struct	FormatArgument
struct	ProcessedArgument

Public Types
using	LinkClickedHandler = std::function< void()>
	Handler to be called, when the Link is activated. More...

Public Member Functions
	AccessibleLinksFormatter (TranslatableString message)
	Create AccessibleLinksFormatter using a TranslatableString. More...
AccessibleLinksFormatter &	FormatLink (wxString placeholder, TranslatableString value, std::string targetURL)
	Replace placeholder with a link, that will open URL in default browser. More...
AccessibleLinksFormatter &	FormatLink (wxString placeholder, TranslatableString value, LinkClickedHandler handler)
	Replace placeholder with a link, that will call a callback provided. More...
void	Populate (ShuttleGui &S) const
	Generate the UI. More...

Private Member Functions
std::vector< ProcessedArgument >	ProcessArguments (wxString translatedMessage) const

Private Attributes
TranslatableString	mMessage
std::vector< FormatArgument >	mFormatArguments

Detailed Description

A class that allows translatable text to have accessible links in it in a way that is friendly to translators.

This class allows to replace arbitrary placeholders (like s, url, {} or anything of the choice) with links, that are accessible from the keyboard.

In case there are multiple placeholders with the same name - they will be replaced in order they appear in the message.

Definition at line 29 of file AccessibleLinksFormatter.h.

Member Typedef Documentation

LinkClickedHandler

using AccessibleLinksFormatter::LinkClickedHandler = std::function<void()>

Handler to be called, when the Link is activated.

Definition at line 33 of file AccessibleLinksFormatter.h.

Constructor & Destructor Documentation

AccessibleLinksFormatter()

AccessibleLinksFormatter::AccessibleLinksFormatter ( TranslatableString  message )

explicit

Create AccessibleLinksFormatter using a TranslatableString.

TranslatableString may have the formatting options attached. TranslatableString copy will be stored, so formatting options that are appended after AccessibleLinksFormatter is created won't have any effect on the AccessibleLinksFormatter instance.

Definition at line 38 of file AccessibleLinksFormatter.cpp.

    : mMessage(std::move(message))
{
}

Member Function Documentation

FormatLink() [1/2]

AccessibleLinksFormatter & AccessibleLinksFormatter::FormatLink	(	wxString	placeholder,
		TranslatableString	value,
		LinkClickedHandler	handler
	)

Replace placeholder with a link, that will call a callback provided.

Definition at line 56 of file AccessibleLinksFormatter.cpp.

{
   mFormatArguments.push_back({ 
       std::move(placeholder), 
       std::move(value), 
       std::move(handler), 
       {} 
   });
 
   return *this;
}

References audacity::cloud::audiocom::anonymous_namespace{AuthorizationHandler.cpp}::handler, and mFormatArguments.

FormatLink() [2/2]

AccessibleLinksFormatter & AccessibleLinksFormatter::FormatLink	(	wxString	placeholder,
		TranslatableString	value,
		std::string	targetURL
	)

Replace placeholder with a link, that will open URL in default browser.

Definition at line 43 of file AccessibleLinksFormatter.cpp.

{
   mFormatArguments.push_back({ 
       std::move(placeholder), 
       std::move(value), 
       {}, 
       std::move(targetURL)
   });
 
   return *this;
}

References mFormatArguments.

Referenced by ErrorReportDialog::ErrorReportDialog(), MissingPluginsErrorDialog::MissingPluginsErrorDialog(), NoUpdatesAvailableDialog::NoUpdatesAvailableDialog(), audacity::cloud::audiocom::ShareAudioDialog::InitialStatePanel::PopulateInitialStatePanel(), AboutDialog::PopulateLicensePage(), ApplicationPrefs::PopulateOrExchange(), UnwritableLocationErrorDialog::UnwritableLocationErrorDialog(), and UpdateNoticeDialog::UpdateNoticeDialog().

Here is the caller graph for this function:

Populate()

void AccessibleLinksFormatter::Populate

(

ShuttleGui &

S

)

const

Generate the UI.

Definition at line 70 of file AccessibleLinksFormatter.cpp.

{
   // Just add the text, if there are no links to format
   if (mFormatArguments.empty())
   {
      S.AddFixedText(mMessage);
      return;
   }
 
#ifdef __WXGTK__
   // Non empty label is required, as wxHyperlinkCtrl would assert otherwise
   std::unique_ptr<wxHyperlinkCtrl> tempHyperlink
       = std::make_unique<wxHyperlinkCtrl>(S.GetParent(), wxID_ANY, wxT("temp"), wxString());
 
   const wxColour hyperlinkColour = tempHyperlink->GetNormalColour();
 
   tempHyperlink.reset();
#endif
 
   wxString translated = mMessage.Translation();
 
   std::vector<ProcessedArgument> processedArguments =
      ProcessArguments(translated);
 
   if (processedArguments.empty())
   {
      S.AddFixedText(mMessage);
      return;
   }
 
   const int borderSize = S.GetBorder();
 
   S.StartHorizontalLay(wxEXPAND);
   {
      S.SetBorder(0);
      S.AddSpace(borderSize);
 
      S.StartWrapLay(wxEXPAND, 1);
      {
         size_t currentPosition = 0;
 
         for (const ProcessedArgument& processedArgument : processedArguments)
         {
            const FormatArgument* argument = processedArgument.Argument;
 
            // Add everything between currentPosition and PlaceholderPosition
 
            if (currentPosition != processedArgument.PlaceholderPosition)
            {
               const size_t substrLength =
                  processedArgument.PlaceholderPosition - currentPosition;
 
               S.Prop(0).AddFixedText(
                  Verbatim(translated.substr(currentPosition, substrLength)));
            }
 
            // Add hyperlink
#ifndef __WXGTK__
            const auto value = argument->Value.Translation();
            // On macOS wx refuses to create wxHyperlinkCtrl with an empty value
            if (!value.empty())
            {
               wxHyperlinkCtrl* hyperlink = safenew wxHyperlinkCtrl(
                  S.GetParent(), wxID_ANY, argument->Value.Translation(),
                  argument->TargetURL);
 
               hyperlink->Bind(
                  wxEVT_HYPERLINK,
                  [handler = argument->Handler,
                   url = argument->TargetURL](wxHyperlinkEvent& evt)
                  {
                     if (handler)
                        handler();
                     else if (!url.empty())
                        BasicUI::OpenInDefaultBrowser(url);
                     
                  });
               
 
               S.AddWindow(hyperlink, wxALIGN_TOP | wxALIGN_LEFT);
            }
#else
            wxStaticText* hyperlink = S.AddVariableText(argument->Value);
 
            hyperlink->SetFont(hyperlink->GetFont().Underlined());
            hyperlink->SetForegroundColour(hyperlinkColour);
            hyperlink->SetCursor(wxCURSOR_HAND);
 
            hyperlink->Bind(wxEVT_LEFT_UP, [handler = argument->Handler, url = argument->TargetURL](wxEvent&) {
                if (handler)
                    handler();
                else if (!url.empty())
                     BasicUI::OpenInDefaultBrowser(url);
            });
#endif
            // Update the currentPostion to the first symbol after the
            // Placeholder
 
            currentPosition = OffsetPosition(
               processedArgument.PlaceholderPosition,
               argument->Placeholder.Length());
 
            if (currentPosition >= translated.Length())
               break;
         }
 
         if (currentPosition < translated.Length())
            S.AddFixedText(Verbatim(translated.substr(currentPosition)));
      }
      S.EndWrapLay();
   }
   S.EndHorizontalLay();
 
   S.SetBorder(borderSize);
}

References currentPosition, AccessibleLinksFormatter::FormatArgument::Handler, audacity::cloud::audiocom::anonymous_namespace{AuthorizationHandler.cpp}::handler, mFormatArguments, mMessage, anonymous_namespace{AccessibleLinksFormatter.cpp}::OffsetPosition(), AccessibleLinksFormatter::FormatArgument::Placeholder, ProcessArguments(), S, safenew, AccessibleLinksFormatter::FormatArgument::TargetURL, TranslatableString::Translation(), AccessibleLinksFormatter::FormatArgument::Value, Verbatim(), and wxT().

Referenced by ErrorReportDialog::ErrorReportDialog(), MissingPluginsErrorDialog::MissingPluginsErrorDialog(), NoUpdatesAvailableDialog::NoUpdatesAvailableDialog(), audacity::cloud::audiocom::ShareAudioDialog::InitialStatePanel::PopulateInitialStatePanel(), AboutDialog::PopulateLicensePage(), ApplicationPrefs::PopulateOrExchange(), UnwritableLocationErrorDialog::UnwritableLocationErrorDialog(), and UpdateNoticeDialog::UpdateNoticeDialog().

Here is the call graph for this function:

Here is the caller graph for this function:

ProcessArguments()

std::vector< AccessibleLinksFormatter::ProcessedArgument > AccessibleLinksFormatter::ProcessArguments ( wxString  translatedMessage ) const

private

Definition at line 187 of file AccessibleLinksFormatter.cpp.

{
   std::vector<ProcessedArgument> result;
   result.reserve(mFormatArguments.size());
   // Arguments with the same placeholder are processed left-to-right.
   // Lets track the last known position of the placeholder
   std::unordered_map<wxString, size_t> knownPlaceholderPosition;
 
   for (const FormatArgument& argument : mFormatArguments)
   {
      auto it = knownPlaceholderPosition.find(argument.Placeholder);
 
      const size_t startingPosition =
         it != knownPlaceholderPosition.end() ?
            OffsetPosition(it->second, argument.Placeholder.length()) :
            0;
 
      const size_t placeholderPosition =
         startingPosition == wxString::npos ?
            wxString::npos :
            translatedMessage.find(argument.Placeholder, startingPosition);
 
      knownPlaceholderPosition[argument.Placeholder] = placeholderPosition;
 
      if (placeholderPosition != wxString::npos)
      {
         result.emplace_back(
            ProcessedArgument { &argument, placeholderPosition });
      }
   }
 
   std::sort(
      result.begin(), result.end(),
      [](const ProcessedArgument& lhs, const ProcessedArgument& rhs) {
         return lhs.PlaceholderPosition < rhs.PlaceholderPosition;
      });
 
   return result;
}

References mFormatArguments, Tuple::detail::npos(), and anonymous_namespace{AccessibleLinksFormatter.cpp}::OffsetPosition().

Referenced by Populate().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

mFormatArguments

std::vector<FormatArgument> AccessibleLinksFormatter::mFormatArguments

private

Definition at line 78 of file AccessibleLinksFormatter.h.

Referenced by FormatLink(), Populate(), and ProcessArguments().

mMessage

TranslatableString AccessibleLinksFormatter::mMessage

private

Definition at line 77 of file AccessibleLinksFormatter.h.

Referenced by Populate().

---

The documentation for this class was generated from the following files:

• AccessibleLinksFormatter.h
• AccessibleLinksFormatter.cpp