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

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

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

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

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