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

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

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

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

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.

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

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: