Audacity 3.2.0
Static Public Member Functions | Static Public Attributes | List of all members
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
parentParent window for the dialog
localFileNameName 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).
remoteURLuse instead of file if nonempty, and user preferences specify remote, or localFileName is invalid
bModalWhether the resulting dialogue should be modal or not. Default is modeless dialogue
alwaysDefaultBrowserForce use of default web browser. Default allows built in browser for local files.

Definition at line 237 of file HelpSystem.cpp.

242{
243 wxASSERT(parent); // to justify safenew
244 wxString HelpMode = wxT("Local");
245
246// DA: Default for DA is manual from internet.
247#ifdef EXPERIMENTAL_DA
248 gPrefs->Read(wxT("/GUI/Help"), &HelpMode, wxT("FromInternet") );
249#else
250 gPrefs->Read(wxT("/GUI/Help"), &HelpMode, wxT("Local") );
251#endif
252
253 {
254 // these next lines are for legacy cfg files (pre 2.0) where we had different modes
255 if( (HelpMode == wxT("Standard")) || (HelpMode == wxT("InBrowser")) )
256 {
257 HelpMode = GUIManualLocation.Default().Internal();
258 GUIManualLocation.Write(HelpMode);
259 gPrefs->Flush();
260 }
261 }
262
263 // Anchors (URLs with a '#' in them) are not supported by many OSs for local file names
264 // See, for example, https://groups.google.com/forum/#!topic/wx-users/pC0uOZJalRQ
265 // Problems have been reported on Win, Mac and some versions of Linux.
266 // So we set HelpMode to use the internet if an anchor is found.
267 if (localFileName.Find('#', true) != wxNOT_FOUND)
268 HelpMode = wxT("FromInternet");
269 // Until a solution is found for this, the next few lines are irrelevant.
270
271 // Obtain the local file system file name, without the anchor if present.
272 wxString localfile;
273 if (localFileName.Find('#', true) != wxNOT_FOUND)
274 localfile = localFileName.BeforeLast('#');
275 else
276 localfile = localFileName;
277
278 if( (HelpMode == wxT("FromInternet")) && !remoteURL.empty() )
279 {
280 // Always go to remote URL. Use External browser.
281 OpenInDefaultBrowser( remoteURL );
282 }
283 else if( localfile.empty() || !wxFileExists( localfile ))
284 {
285 // If you give an empty remote URL, you should have already ensured
286 // that the file exists!
287 wxASSERT( !remoteURL.empty() );
288 // I can't find it'.
289 // Use Built-in browser to suggest you use the remote url.
290 wxString Text = HelpText( wxT("remotehelp") );
291 Text.Replace( wxT("*URL*"), remoteURL.GET() );
292 // Always make the 'help on the internet' dialog modal.
293 // Fixes Bug 1411.
294 ShowHtmlText( parent, XO("Help on the Internet"), Text, false, true );
295 }
296 else if( HelpMode == wxT("Local") || alwaysDefaultBrowser)
297 {
298 // Local file, External browser
299 OpenInDefaultBrowser( L"file:" + localFileName );
300 }
301 else
302 {
303 // Local file, Built-in browser
304 ShowHtmlText( parent, {}, localFileName, true, bModal );
305 }
306}
ChoiceSetting GUIManualLocation
Definition: GUIPrefs.cpp:130
void OpenInDefaultBrowser(const URLString &link)
Definition: HelpSystem.cpp:522
wxString HelpText(const wxString &Key)
Definition: HelpText.cpp:360
#define XO(s)
Definition: Internat.h:31
FileConfig * gPrefs
Definition: Prefs.cpp:71
bool Write(const wxString &value)
Definition: Prefs.cpp:390
const EnumValueSymbol & Default() const
Definition: Prefs.cpp:346
const wxString & Internal() const
virtual bool Flush(bool bCurrentOnly=false) wxOVERRIDE
Definition: FileConfig.cpp:143
static void ShowHtmlText(wxWindow *pParent, const TranslatableString &Title, const wxString &HtmlText, bool bIsFile=false, bool bModal=false)
Definition: HelpSystem.cpp:125
bool empty() const
Definition: Identifier.h:61
const wxString & GET() const
Explicit conversion to wxString, meant to be ugly-looking and demanding of a comment why it's correct...
Definition: Identifier.h:66

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

Referenced by FindDialog::OnDownload(), FindFFmpegDialog::OnDownload(), UnwritableLocationErrorDialog::OnError(), LibraryPrefs::OnFFmpegDownButton(), ContrastDialog::OnGetURL(), ExportFFmpegOptions::OnGetURL(), FrequencyPlotDialog::OnGetURL(), HistoryDialog::OnGetURL(), ScreenshotBigDialog::OnGetURL(), anonymous_namespace{ProjectFileManager.cpp}::CompactDialog::OnGetURL(), anonymous_namespace{HelpMenus.cpp}::QuickFixDialog::OnHelp(), PrefsDialog::OnHelp(), MacroCommandDialog::OnHelp(), ApplyMacroDialog::OnHelp(), EffectNoiseReduction::Dialog::OnHelp(), ExportMultipleDialog::OnHelp(), LabelDialog::OnHelp(), ErrorDialog::OnHelp(), ErrorReportDialog::OnHelp(), MultiDialog::OnHelp(), AudacityCommandDialog::OnHelp(), EffectUIHost::OnHelp(), Exporter::OnHelp(), TagsEditorDialog::OnHelp(), TimerRecordDialog::OnHelpButtonClick(), LinkingHtmlWindow::OnLinkClicked(), HelpActions::Handler::OnManual(), ExportMixerDialog::OnMixerPanelHelp(), LibraryPrefs::OnMP3DownButton(), HelpActions::Handler::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
parentParent window for the dialog
PageNameThe 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.
bModalWhether 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 308 of file HelpSystem.cpp.

311{
314 const wxString ReleaseSuffix = L".html";
315
316 FilePath localHelpPage;
317 wxString webHelpPath;
318 wxString webHelpPage;
319 wxString releasePageName;
320 wxString anchor; // optional part of URL after (and including) the '#'
321 const auto &PageNameStr = PageName.GET();
322 if (PageNameStr.Find('#', true) != wxNOT_FOUND)
323 { // need to split anchor off into separate variable
324 releasePageName = PageNameStr.BeforeLast('#');
325 anchor = wxT("#") + PageNameStr.AfterLast('#');
326 }
327 else
328 {
329 releasePageName = PageName.GET();
330 anchor = wxT("");
331 }
332 // The wiki pages are transformed to static HTML by
333 // scripts/mw2html_audacity/mw2html.py
334 // The name is first transformed to lower case, then all
335 // 'special characters' are replaced by underscores. Spaces are
336 // transformed to "+".
337 //
338 // The transformations are handled in mw2html by first applying
339 // 'urllib.parse.quote_plus' (escape chars that are not in "always safe" list)
340 // then replacing escape characters (%xx) with underscores,
341 // and finally removing duplicate / redundant underscores.
342 //
343 // The front page and 'quick_help' are treated as special cases and placed in
344 // the root of the help directory rather than the "/man/" sub-directory.
345 if (releasePageName == L"Main_Page")
346 {
347 releasePageName = L"index" + ReleaseSuffix + anchor;
348 localHelpPage = wxFileName(FileNames::HtmlHelpDir(), releasePageName).GetFullPath();
349 webHelpPath = L"https://" + HelpSystem::HelpHostname + HelpSystem::HelpServerHomeDir;
350 }
351 else if (releasePageName == L"Quick_Help")
352 {
353// DA: No bundled help, by default, and different quick-help URL.
354#ifdef EXPERIMENTAL_DA
355 releasePageName = L"video" + ReleaseSuffix + anchor;
356 localHelpPage = wxFileName(FileNames::HtmlHelpDir(), releasePageName).GetFullPath();
357 webHelpPath = L"http://www.darkaudacity.com/";
358#else
359 releasePageName = L"quick_help" + ReleaseSuffix + anchor;
360 localHelpPage = wxFileName(FileNames::HtmlHelpDir(), releasePageName).GetFullPath();
361 webHelpPath = L"https://" + HelpSystem::HelpHostname + HelpSystem::HelpServerHomeDir;
362#endif
363 }
364 // not a page name, but rather a full path (e.g. to wiki)
365 // in which case do not do any substitutions.
366 else if (releasePageName.StartsWith( "http" ) )
367 {
368 localHelpPage = "";
369 releasePageName += anchor;
370 // webHelpPath remains empty
371 }
372 else
373 {
374 // Handle all other pages.
375 // Change to lower case.
376 releasePageName = releasePageName.Lower();
377 wxRegEx re;
378 // replace 'special characters' with underscores.
379 // RFC 2396 defines the characters a-z, A-Z, 0-9 and ".-_" as "always safe"
380 // mw2html also replaces "-" with "_" so replace that too.
381
382 // If PageName contains a %xx code, mw2html will transform it:
383 // '%xx' => '%25xx' => '_'
384 re.Compile(wxT("%.."));
385 re.ReplaceAll(&releasePageName, (wxT("_")));
386 // Now replace all other 'not-safe' characters.
387 re.Compile(wxT("[^[:alnum:] . [:space:]]"));
388 re.ReplaceAll(&releasePageName, (wxT("_")));
389 // Replace spaces with "+"
390 releasePageName.Replace(wxT(" "), wxT("+"), true);
391 // Reduce multiple underscores to single underscores
392 re.Compile(wxT("__+"));
393 re.ReplaceAll(&releasePageName, (wxT("_")));
394 // Replace "_." with "."
395 releasePageName.Replace(wxT("_."), wxT("."), true);
396 // Concatenate file name with file extension and anchor.
397 releasePageName = releasePageName + ReleaseSuffix + anchor;
398 // Other than index and quick_help, all local pages are in subdirectory 'LocalHelpManDir'.
399 localHelpPage = wxFileName(FileNames::HtmlHelpDir() + LocalHelpManDir, releasePageName).GetFullPath();
400 // Other than index and quick_help, all on-line pages are in subdirectory 'HelpServerManDir'.
401 webHelpPath = L"https://" + HelpSystem::HelpHostname + HelpSystem::HelpServerManDir;
402 }
403
404#ifdef USE_ALPHA_MANUAL
405 webHelpPage = webHelpPath + PageName.GET();
406#else
407 webHelpPage = webHelpPath + releasePageName;
408#endif
409
410 wxLogMessage(wxT("Help button pressed: PageName %s, releasePageName %s"),
411 PageName.GET(), releasePageName);
412 wxLogMessage(wxT("webHelpPage %s, localHelpPage %s"),
413 webHelpPage, localHelpPage);
414
415 wxASSERT(parent); // to justify safenew
416
418 parent,
419 localHelpPage,
420 webHelpPage,
421 bModal
422 );
423}
wxString FilePath
Definition: Project.h:20
static void ShowHelp(wxWindow *parent, const FilePath &localFileName, const URLString &remoteURL, bool bModal=false, bool alwaysDefaultBrowser=false)
Definition: HelpSystem.cpp:237
static const wxString LocalHelpManDir
Definition: HelpSystem.h:111
static const wxString HelpHostname
Definition: HelpSystem.h:96
static const wxString HelpServerHomeDir
Definition: HelpSystem.h:101
static const wxString HelpServerManDir
Definition: HelpSystem.h:106
FILES_API FilePath HtmlHelpDir()

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

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
HtmlTextEither the literal HTML code to go into the window, or the name of the file to read said HTML code from (see below).
bIsFileIf true, treat HtmlText argument as a file name, if false (default), then it is the HTML code to display.
bModalWhether the resulting window should be modal or not. Default is modeless dialogue

Definition at line 125 of file HelpSystem.cpp.

130{
131 LinkingHtmlWindow *html;
132
133 wxASSERT(pParent); // to justify safenew
134 // JKC: ANSWER-ME: Why do we create a fake 'frame' and then put a BrowserDialog
135 // inside it, rather than have a variant of the BrowserDialog that is a
136 // frame??
137 // Bug 1412 seems to be related to the extra frame.
138 auto pFrame = safenew wxFrame {
139 pParent, wxID_ANY, Title.Translation(), wxDefaultPosition, wxDefaultSize,
140#if defined(__WXMAC__)
141 // On OSX, the html frame can go behind the help dialog and if the help
142 // html frame is modal, you can't get back to it. Pressing escape gets
143 // you out of this, but it's just easier to add the wxSTAY_ON_TOP flag
144 // to prevent it from falling behind the dialog. Not the perfect solution
145 // but acceptable in this case.
146 wxSTAY_ON_TOP |
147#endif
148 wxDEFAULT_FRAME_STYLE
149 };
150
151 BrowserDialog * pWnd;
152 if( bModal )
153 pWnd = safenew HtmlTextHelpDialog{ pFrame, Title };
154 else
155 pWnd = safenew BrowserDialog{ pFrame, Title };
156
157 // Bug 1412 workaround for 'extra window'. Hide the 'fake' window.
158 pFrame->SetTransparent(0);
159 ShuttleGui S( pWnd, eIsCreating );
160
161 S.Style( wxNO_BORDER | wxTAB_TRAVERSAL )
162 .Prop(true)
163 .StartPanel();
164 {
165 S.StartHorizontalLay( wxEXPAND, false );
166 {
167 S.Id( wxID_BACKWARD )
168 .Disable()
169#if wxUSE_TOOLTIPS
170 .ToolTip( XO("Backwards" ) )
171#endif
172 /* i18n-hint arrowhead meaning backward movement */
173 .AddButton( XXO("<") );
174 S.Id( wxID_FORWARD )
175 .Disable()
176#if wxUSE_TOOLTIPS
177 .ToolTip( XO("Forwards" ) )
178#endif
179 /* i18n-hint arrowhead meaning forward movement */
180 .AddButton( XXO(">") );
181 }
182 S.EndHorizontalLay();
183
184 html = safenew LinkingHtmlWindow(S.GetParent(), wxID_ANY,
185 wxDefaultPosition,
186 bIsFile ? wxSize(500, 400) : wxSize(480, 240),
187 wxHW_SCROLLBAR_AUTO | wxSUNKEN_BORDER);
188
189 html->SetRelatedFrame( pFrame, wxT("Help: %s") );
190 if( bIsFile )
191 html->LoadFile( HtmlText );
192 else
193 html->SetPage( HtmlText);
194
195 S.Prop(1).Focus().Position( wxEXPAND )
196 .AddWindow( html );
197
198 S.Id( wxID_CANCEL ).AddButton( XXO("Close"), wxALIGN_CENTER, true );
199 }
200 S.EndPanel();
201
202 // -- START of ICON stuff -----
203 // If this section (providing an icon) causes compilation errors on linux, comment it out for now.
204 // it will just mean that the icon is missing. Works OK on Windows.
205 #ifdef __WXMSW__
206 wxIcon ic{ wxICON(AudacityLogo) };
207 #else
208 wxIcon ic{};
209 ic.CopyFromBitmap(theTheme.Bitmap(bmpAudacityLogo48x48));
210 #endif
211 pFrame->SetIcon( ic );
212 // -- END of ICON stuff -----
213
214
215 pWnd->mpHtml = html;
216 pWnd->SetBackgroundColour( wxSystemSettings::GetColour(wxSYS_COLOUR_BTNFACE));
217
218 pFrame->CreateStatusBar();
219 pFrame->Centre();
220 pFrame->Layout();
221 pFrame->SetSizeHints(pWnd->GetSize());
222
223 pFrame->SetName(Title.Translation());
224 if (bModal)
225 pWnd->ShowModal();
226 else {
227 pWnd->Show(true);
228 pFrame->Show(true);
229 }
230
231 html->SetRelatedStatusBar( 0 );
232
233 return;
234}
#define XXO(s)
Definition: Internat.h:44
#define safenew
Definition: MemoryX.h:10
@ eIsCreating
Definition: ShuttleGui.h:39
THEME_API Theme theTheme
Definition: Theme.cpp:82
#define S(N)
Definition: ToChars.cpp:64
Adds some event handling to an HtmlWindow.
Definition: HelpSystem.h:140
HtmlWindow * mpHtml
Definition: HelpSystem.h:154
An HtmlWindow that handles linked clicked - usually the link will go to our own local copy of the man...
Definition: HelpSystem.h:126
Derived from ShuttleGuiBase, an Audacity specific class for shuttling data to and from GUI.
Definition: ShuttleGui.h:628
wxBitmap & Bitmap(int iIndex)
wxString Translation() const
void SetName(const TranslatableString &title)

References ThemeBase::Bitmap(), eIsCreating, BrowserDialog::mpHtml, S, safenew, wxDialogWrapper::SetName(), theTheme, TranslatableString::Translation(), 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 90 of file HelpSystem.cpp.

95{
96 wxDialogWrapper dlog(parent, wxID_ANY,
97 dlogTitle,
98 wxDefaultPosition, wxDefaultSize,
99 wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxMAXIMIZE_BOX /*| wxDEFAULT_FRAME_STYLE */);
100
101 dlog.SetName();
102 ShuttleGui S(&dlog, eIsCreating);
103
104 S.StartVerticalLay(1);
105 {
106 S.AddTitle( shortMsg );
107 S.Style( wxTE_MULTILINE | wxTE_READONLY | wxTE_RICH | wxTE_RICH2 |
108 wxTE_AUTO_URL | wxTE_NOHIDESEL | wxHSCROLL )
109 .AddTextWindow(message);
110
111 S.SetBorder( 0 );
112 S.StartHorizontalLay(wxALIGN_CENTER_HORIZONTAL, 0);
113 S.AddStandardButtons(eOkButton);
114 S.EndHorizontalLay();
115 }
116 S.EndVerticalLay();
117
118 // Smallest size is half default size. Seems reasonable.
119 dlog.SetMinSize( wxSize(xSize/2, ySize/2) );
120 dlog.SetSize( wxSize(xSize, ySize) );
121 dlog.Center();
122 dlog.ShowModal();
123}
@ eOkButton
Definition: ShuttleGui.h:597

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

Referenced by ExportMultipleDialog::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: