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 233 of file HelpSystem.cpp.

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

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(), ScreenshotBigDialog::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
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 312 of file HelpSystem.cpp.

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

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

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

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: