HelpSystem Class Reference

Class which contains static methods and data needed for implementing help buttons. More...

#include <HelpSystem.h>

Static Public Member Functions
static void	ShowInfoDialog (wxWindow *parent, const TranslatableString &dlogTitle, const TranslatableString &shortMsg, const wxString &message, const int xSize, const int ySize)
	Displays cuttable information in a text ctrl, with an OK button. More...
static void	ShowHtmlText (wxWindow *pParent, const TranslatableString &Title, const wxString &HtmlText, bool bIsFile=false, bool bModal=false)
static void	ShowHelp (wxWindow *parent, const FilePath &localFileName, const URLString &remoteURL, bool bModal=false, bool alwaysDefaultBrowser=false)
static void	ShowHelp (wxWindow *parent, const ManualPageID &PageName, bool bModal=false)

Static Public Attributes
static const wxString	HelpHostname = wxT("manual.audacityteam.org")
static const wxString	HelpServerHomeDir = wxT("/")
static const wxString	HelpServerManDir = wxT("/man/")
static const wxString	LocalHelpManDir = wxT("/man/")

Detailed Description

Class which contains static methods and data needed for implementing help buttons.

This class should be the only place in the codebase where the location of the online copy of the Audacity manual is stored, so that it can be changed if required

Definition at line 39 of file HelpSystem.h.

Member Function Documentation

ShowHelp() [1/2]

void HelpSystem::ShowHelp ( wxWindow *  parent, const FilePath &  localFileName, const URLString &  remoteURL, bool  bModal = false, bool  alwaysDefaultBrowser = false  )

static

Displays a file in your browser, if it's available locally, OR else links to the internet. Generally using this outside this class is depreciated in favour of the "smarter" overload below, unless there is a good reason for using this form.

Parameters

parent	Parent window for the dialog
localFileName	Name and path of the file on the local machine file system to be opened. file.name::anchor syntax is allowed, and therefore file names containing a '#' are not (on any platform).
remoteURL	use instead of file if nonempty, and user preferences specify remote, or localFileName is invalid
bModal	Whether the resulting dialogue should be modal or not. Default is modeless dialogue
alwaysDefaultBrowser	Force use of default web browser. Default allows built in browser for local files.

Definition at line 231 of file HelpSystem.cpp.

{
   wxASSERT(parent); // to justify safenew
   wxString HelpMode = wxT("Local"); //this probably always gets overwritten to FromInternet 
                                     //TODO: remove code which handles local manual
 
   gPrefs->Read(wxT("/GUI/Help"), &HelpMode, {"FromInternet"} );
 
   {
      // these next lines are for legacy cfg files (pre 2.0) where we had different modes
      if( (HelpMode == wxT("Standard")) || (HelpMode == wxT("InBrowser")) )
      {
         HelpMode = GUIManualLocation.Default().Internal();
         GUIManualLocation.Write(HelpMode);
         gPrefs->Flush();
      }
   }
 
   // Anchors (URLs with a '#' in them) are not supported by many OSs for local file names
   // See, for example, https://groups.google.com/forum/#!topic/wx-users/pC0uOZJalRQ
   // Problems have been reported on Win, Mac and some versions of Linux.
   // So we set HelpMode to use the internet if an anchor is found.
   if (localFileName.Find('#', true) != wxNOT_FOUND)
      HelpMode = wxT("FromInternet");
   // Until a solution is found for this, the next few lines are irrelevant.
 
   // Obtain the local file system file name, without the anchor if present.
   wxString localfile;
   if (localFileName.Find('#', true) != wxNOT_FOUND)
      localfile = localFileName.BeforeLast('#');
   else
      localfile = localFileName;
 
   if( (HelpMode == wxT("FromInternet")) && !remoteURL.empty() )
   {
      // Always go to remote URL.  Use External browser.
      OpenInDefaultBrowser( remoteURL );
   }
   else if( localfile.empty() || !wxFileExists( localfile ))
   {
      if (remoteURL.empty())
      {
         // If you give an empty remote URL, you should have already ensured
         // that the file exists!
         wxASSERT(!remoteURL.empty());
         // I can't find it'.
         // Use Built-in browser to suggest you use the remote url.
         wxString Text = HelpText(wxT("remotehelp"));
         Text.Replace(wxT("*URL*"), remoteURL.GET());
         // Always make the 'help on the internet' dialog modal.
         // Fixes Bug 1411.
         ShowHtmlText(parent, XO("Help on the Internet"), Text, false, true);
      }
      else
      {
         // Use External browser to go to remote URL.
         OpenInDefaultBrowser(remoteURL);
      }
   }
   else if( HelpMode == wxT("Local") || alwaysDefaultBrowser)
   {
      // Local file, External browser
      OpenInDefaultBrowser( L"file:" + localFileName );
   }
   else
   {
      // Local file, Built-in browser
      ShowHtmlText( parent, {}, localFileName, true, bModal );
   }
}

References ChoiceSetting::Default(), Identifier::empty(), audacity::BasicSettings::Flush(), Identifier::GET(), gPrefs, GUIManualLocation, HelpText(), ComponentInterfaceSymbol::Internal(), OpenInDefaultBrowser(), audacity::BasicSettings::Read(), ShowHtmlText(), ChoiceSetting::Write(), wxT(), and XO().

Referenced by anonymous_namespace{FFmpegPrefs.cpp}::AddControls(), FindFFmpegDialog::OnDownload(), FindDialog::OnDownload(), UnwritableLocationErrorDialog::OnError(), ExportFFmpegOptions::OnGetURL(), ContrastDialog::OnGetURL(), FrequencyPlotDialog::OnGetURL(), HistoryDialog::OnGetURL(), anonymous_namespace{ProjectFileManager.cpp}::CompactDialog::OnGetURL(), anonymous_namespace{HelpMenus.cpp}::QuickFixDialog::OnHelp(), PrefsDialog::OnHelp(), ErrorDialog::OnHelp(), ErrorReportDialog::OnHelp(), MultiDialog::OnHelp(), MacroCommandDialog::OnHelp(), ApplyMacroDialog::OnHelp(), EffectNoiseReduction::Dialog::OnHelp(), ExportAudioDialog::OnHelp(), LabelDialog::OnHelp(), AudacityCommandDialog::OnHelp(), TagsEditorDialog::OnHelp(), TimerRecordDialog::OnHelpButtonClick(), LinkingHtmlWindow::OnLinkClicked(), anonymous_namespace{HelpMenus.cpp}::OnManual(), ExportMixerDialog::OnMixerPanelHelp(), anonymous_namespace{HelpMenus.cpp}::OnQuickHelp(), and ShowHelp().

Here is the call graph for this function:

Here is the caller graph for this function:

ShowHelp() [2/2]

void HelpSystem::ShowHelp ( wxWindow *  parent, const ManualPageID &  PageName, bool  bModal = false  )

static

Displays a page from the Audacity manual in your browser, if it's available locally, OR else links to the internet.

Parameters

parent	Parent window for the dialog
PageName	The name of the manual page to display as it is in development version of the manual (i.e. in MediaWiki), not the converted file name used for offline and released manuals.
bModal	Whether the resulting dialogue should be modal or not. Default is modeless dialogue

The string which is appended to the development manual page name in order obtain the file name in the local and release web copies of the manual

Definition at line 306 of file HelpSystem.cpp.

{
   const wxString ReleaseSuffix = L".html";
 
   FilePath localHelpPage;
   wxString webHelpPath;
   wxString webHelpPage;
   wxString releasePageName;
   wxString anchor;  // optional part of URL after (and including) the '#'
   const auto &PageNameStr = PageName.GET();
   if (PageNameStr.Find('#', true) != wxNOT_FOUND)
   {  // need to split anchor off into separate variable
      releasePageName = PageNameStr.BeforeLast('#');
      anchor = wxT("#") + PageNameStr.AfterLast('#');
   }
   else
   {
      releasePageName = PageName.GET();
      anchor = wxT("");
   }
   // The wiki pages are transformed to static HTML by
   // scripts/mw2html_audacity/mw2html.py
   // The name is first transformed to lower case, then all
   // 'special characters' are replaced by underscores. Spaces are
   // transformed to "+".
   //
   // The transformations are handled in mw2html by first applying
   // 'urllib.parse.quote_plus' (escape chars that are not in "always safe" list)
   // then replacing escape characters (%xx) with underscores,
   // and finally removing duplicate / redundant underscores.
   //
   // The front page and 'quick_help' are treated as special cases and placed in
   // the root of the help directory rather than the "/man/" sub-directory.
   if (releasePageName == L"Main_Page")
   {
      releasePageName = L"index" + ReleaseSuffix + anchor;
      localHelpPage = wxFileName(FileNames::HtmlHelpDir(), releasePageName).GetFullPath();
      webHelpPath = L"https://" + HelpSystem::HelpHostname + HelpSystem::HelpServerHomeDir;
   }
   else if (releasePageName == L"Quick_Help")
   {
      releasePageName = L"quick_help" + ReleaseSuffix + anchor;
      localHelpPage = wxFileName(FileNames::HtmlHelpDir(), releasePageName).GetFullPath();
      webHelpPath = L"https://" + HelpSystem::HelpHostname + HelpSystem::HelpServerHomeDir;
   }
   // not a page name, but rather a full path (e.g. to wiki)
   // in which case do not do any substitutions.
   else if (releasePageName.StartsWith( "http" ) )
   {
      localHelpPage = "";
      releasePageName += anchor;
      // webHelpPath remains empty
   }
   else
   {
      // Handle all other pages.
      // Change to lower case.
      releasePageName = releasePageName.Lower();
      wxRegEx re;
      // replace 'special characters' with underscores.
      // RFC 2396 defines the characters a-z, A-Z, 0-9 and ".-_" as "always safe"
      // mw2html also replaces "-" with "_" so replace that too.
 
      // If PageName contains a %xx code, mw2html will transform it:
      // '%xx' => '%25xx' => '_'
      re.Compile(wxT("%.."));
      re.ReplaceAll(&releasePageName, (wxT("_")));
      // Now replace all other 'not-safe' characters.
      re.Compile(wxT("[^[:alnum:] . [:space:]]"));
      re.ReplaceAll(&releasePageName, (wxT("_")));
      // Replace spaces with "+"
      releasePageName.Replace(wxT(" "), wxT("+"), true);
      // Reduce multiple underscores to single underscores
      re.Compile(wxT("__+"));
      re.ReplaceAll(&releasePageName, (wxT("_")));
      // Replace "_." with "."
      releasePageName.Replace(wxT("_."), wxT("."), true);
      // Concatenate file name with file extension and anchor.
      releasePageName = releasePageName + ReleaseSuffix + anchor;
      // Other than index and quick_help, all local pages are in subdirectory 'LocalHelpManDir'.
      localHelpPage = wxFileName(FileNames::HtmlHelpDir() + LocalHelpManDir, releasePageName).GetFullPath();
      // Other than index and quick_help, all on-line pages are in subdirectory 'HelpServerManDir'.
      webHelpPath = L"https://" + HelpSystem::HelpHostname + HelpSystem::HelpServerManDir;
   }
 
   webHelpPage = webHelpPath + releasePageName;
 
 
   wxLogMessage(wxT("Help button pressed: PageName %s, releasePageName %s"),
              PageName.GET(), releasePageName);
   wxLogMessage(wxT("webHelpPage %s, localHelpPage %s"),
              webHelpPage, localHelpPage);
 
   wxASSERT(parent); // to justify safenew
 
   HelpSystem::ShowHelp(
      parent,
      localHelpPage,
      webHelpPage,
      bModal
      );
}

References Identifier::GET(), HelpHostname, HelpServerHomeDir, HelpServerManDir, FileNames::HtmlHelpDir(), LocalHelpManDir, ShowHelp(), and wxT().

Here is the call graph for this function:

ShowHtmlText()

void HelpSystem::ShowHtmlText ( wxWindow *  pParent, const TranslatableString &  Title, const wxString &  HtmlText, bool  bIsFile = false, bool  bModal = false  )

static

Displays a NEW window with wxHTML help.

Parameters

HtmlText	Either the literal HTML code to go into the window, or the name of the file to read said HTML code from (see below).
bIsFile	If true, treat HtmlText argument as a file name, if false (default), then it is the HTML code to display.
bModal	Whether the resulting window should be modal or not. Default is modeless dialogue

Definition at line 119 of file HelpSystem.cpp.

{
   LinkingHtmlWindow *html;
 
   wxASSERT(pParent); // to justify safenew
   // JKC: ANSWER-ME: Why do we create a fake 'frame' and then put a BrowserDialog
   // inside it, rather than have a variant of the BrowserDialog that is a
   // frame??
   // Bug 1412 seems to be related to the extra frame.
   auto pFrame = safenew wxFrame {
      pParent, wxID_ANY, Title.Translation(), wxDefaultPosition, wxDefaultSize,
#if defined(__WXMAC__)
      // On OSX, the html frame can go behind the help dialog and if the help
      // html frame is modal, you can't get back to it.  Pressing escape gets
      // you out of this, but it's just easier to add the wxSTAY_ON_TOP flag
      // to prevent it from falling behind the dialog.  Not the perfect solution
      // but acceptable in this case.
      wxSTAY_ON_TOP |
#endif
      wxDEFAULT_FRAME_STYLE
   };
 
   BrowserDialog * pWnd;
   if( bModal )
      pWnd = safenew HtmlTextHelpDialog{ pFrame, Title };
   else
      pWnd = safenew BrowserDialog{ pFrame, Title };
 
   // Bug 1412 workaround for 'extra window'.  Hide the 'fake' window.
   pFrame->SetTransparent(0);
   ShuttleGui S( pWnd, eIsCreating );
 
   S.Style( wxNO_BORDER | wxTAB_TRAVERSAL )
      .Prop(true)
      .StartPanel();
   {
      S.StartHorizontalLay( wxEXPAND, false );
      {
         S.Id( wxID_BACKWARD )
            .Disable()
#if wxUSE_TOOLTIPS
            .ToolTip( XO("Backwards" ) )
#endif
            /* i18n-hint arrowhead meaning backward movement */
            .AddButton( XXO("<") );
         S.Id( wxID_FORWARD  )
            .Disable()
#if wxUSE_TOOLTIPS
            .ToolTip( XO("Forwards" ) )
#endif
            /* i18n-hint arrowhead meaning forward movement */
            .AddButton( XXO(">") );
      }
      S.EndHorizontalLay();
 
      html = safenew LinkingHtmlWindow(S.GetParent(), wxID_ANY,
                                   wxDefaultPosition,
                                   bIsFile ? wxSize(500, 400) : wxSize(480, 240),
                                   wxHW_SCROLLBAR_AUTO);
 
      html->SetRelatedFrame( pFrame, wxT("Help: %s") );
      if( bIsFile )
         html->LoadFile( HtmlText );
      else
         html->SetPage( HtmlText);
 
      S.Prop(1).Focus().Position( wxEXPAND )
         .AddWindow( html );
 
      S.Id( wxID_CANCEL ).AddButton( XXO("Close"), wxALIGN_CENTER, true );
   }
   S.EndPanel();
 
   // -- START of ICON stuff -----
   // If this section (providing an icon) causes compilation errors on linux, comment it out for now.
   // it will just mean that the icon is missing.  Works OK on Windows.
   #ifdef __WXMSW__
   wxIcon ic{ wxICON(AudacityLogo) };
   #else
   wxIcon ic{};
      ic.CopyFromBitmap(theTheme.Bitmap(bmpAudacityLogo48x48));
   #endif
   pFrame->SetIcon( ic );
   // -- END of ICON stuff -----
 
 
   pWnd->mpHtml = html;
   pWnd->SetBackgroundColour( wxSystemSettings::GetColour(wxSYS_COLOUR_BTNFACE));
 
   pFrame->CreateStatusBar();
   pFrame->Centre();
   pFrame->Layout();
   pFrame->SetSizeHints(pWnd->GetSize());
 
   pFrame->SetName(Title.Translation());
   if (bModal)
      pWnd->ShowModal();
   else {
      pWnd->Show(true);
      pFrame->Show(true);
   }
 
   html->SetRelatedStatusBar( 0 );
 
   return;
}

References ThemeBase::Bitmap(), eIsCreating, BrowserDialog::mpHtml, S, safenew, wxDialogWrapper::SetName(), theTheme, wxT(), XO(), and XXO().

Referenced by ErrorDialog::OnHelp(), ErrorReportDialog::OnHelp(), and ShowHelp().

Here is the call graph for this function:

Here is the caller graph for this function:

ShowInfoDialog()

void HelpSystem::ShowInfoDialog ( wxWindow *  parent, const TranslatableString &  dlogTitle, const TranslatableString &  shortMsg, const wxString &  message, const int  xSize, const int  ySize  )

static

Displays cuttable information in a text ctrl, with an OK button.

Mostly we use this so that we have the code for resizability in one place. Other considerations like screen readers are also handled by having the code in one place.

Definition at line 81 of file HelpSystem.cpp.

{
   wxDialogWrapper dlog(parent, wxID_ANY,
                dlogTitle,
                wxDefaultPosition, wxDefaultSize,
                wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxMAXIMIZE_BOX /*| wxDEFAULT_FRAME_STYLE */);
 
   dlog.SetName();
   ShuttleGui S(&dlog, eIsCreating);
 
   S.StartVerticalLay(1);
   {
      S.AddTitle( shortMsg );
      S.Style( wxTE_MULTILINE | wxTE_READONLY | wxTE_RICH | wxTE_RICH2 |
              wxTE_AUTO_URL | wxTE_NOHIDESEL | wxHSCROLL | wxTE_PROCESS_ENTER)
         .AddTextWindow(message)
         ->Bind(wxEVT_TEXT_ENTER, [&dlog](auto&) {
         dlog.EndModal(wxID_OK);
         });
 
      S.SetBorder( 0 );
      S.StartHorizontalLay(wxALIGN_CENTER_HORIZONTAL, 0);
         S.AddStandardButtons(eOkButton);
      S.EndHorizontalLay();
   }
   S.EndVerticalLay();
 
   // Smallest size is half default size.  Seems reasonable.
   dlog.SetMinSize( wxSize(xSize/2, ySize/2) );
   dlog.SetSize( wxSize(xSize, ySize) );
   dlog.Center();
   dlog.ShowModal();
}

References eIsCreating, eOkButton, S, and wxDialogWrapper::SetName().

Referenced by ExportAudioDialog::OnExport().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

HelpHostname

const wxString HelpSystem::HelpHostname = wxT("manual.audacityteam.org")

static

Hostname (domain name including subdomain) of the server on which the online help is available

Definition at line 96 of file HelpSystem.h.

Referenced by ShowHelp(), and AudacityFileConfig::Warn().

HelpServerHomeDir

const wxString HelpSystem::HelpServerHomeDir = wxT("/")

static

URL path on the help server to the root directory of the manual. index and quick_help are here in the on-line release manual. Must both start and end with '/' characters.

Definition at line 101 of file HelpSystem.h.

Referenced by ShowHelp(), and AudacityFileConfig::Warn().

HelpServerManDir

const wxString HelpSystem::HelpServerManDir = wxT("/man/")

static

Path to sub-directory where the manual pages are located. index and quick_help are here only in the alpha manual. Must both start and end with '/' characters.

Definition at line 106 of file HelpSystem.h.

Referenced by ShowHelp().

LocalHelpManDir

const wxString HelpSystem::LocalHelpManDir = wxT("/man/")

static

Sub-directory for local help pages (but not index.html or quick_help.html) Must both start and end with '/' characters.

Definition at line 111 of file HelpSystem.h.

Referenced by ShowHelp().

---

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

• HelpSystem.h
• HelpSystem.cpp