Audacity  2.2.2
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 wxString &dlogTitle, const wxString &shortMsg, const wxString &message, const int xSize, const int ySize)
 Displays cutable information in a text ctrl, with an OK button. More...
 
static void ShowHtmlText (wxWindow *pParent, const wxString &Title, const wxString &HtmlText, bool bIsFile=false, bool bModal=false)
 
static void ShowHelp (wxWindow *parent, const wxString &localFileName, const wxString &remoteURL, bool bModal=false, bool alwaysDefaultBrowser=false)
 
static void ShowHelp (wxWindow *parent, const wxString &PageName, bool bModal=false)
 

Static Public Attributes

static const wxString HelpHostname = wxT("alphamanual.audacityteam.org")
 
static const wxString HelpServerHomeDir = wxT("/man/")
 
static const wxString HelpServerManDir = wxT("/man/")
 
static const wxString LocalHelpManDir = wxT("/man/")
 
static const wxString ReleaseSuffix = wxT(".html")
 

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 28 of file HelpSystem.h.

Member Function Documentation

void HelpSystem::ShowHelp ( wxWindow *  parent,
const wxString &  localFileName,
const wxString &  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
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).
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 195 of file HelpSystem.cpp.

References _(), GetActiveProject(), gPrefs, HelpText(), AudacityProject::mHelpPref, OpenInDefaultBrowser(), and ShowHtmlText().

Referenced by FindDialog::OnDownload(), LibraryPrefs::OnFFmpegDownButton(), ContrastDialog::OnGetURL(), FreqWindow::OnGetURL(), ErrorDialog::OnHelp(), ApplyMacroDialog::OnHelp(), MacroCommandDialog::OnHelp(), LabelDialog::OnHelp(), PrefsDialog::OnHelp(), AudacityCommandDialog::OnHelp(), EffectNoiseReduction::Dialog::OnHelp(), EffectUIHost::OnHelp(), TimerRecordDialog::OnHelpButtonClick(), LinkingHtmlWindow::OnLinkClicked(), AudacityProject::OnManual(), LibraryPrefs::OnMP3DownButton(), AudacityProject::OnQuickHelp(), and ShowHelp().

200 {
201  wxASSERT(parent); // to justify safenew
202  AudacityProject * pProj = GetActiveProject();
203  wxString HelpMode = wxT("Local");
204 
205  if( pProj )
206  {
207  HelpMode = pProj->mHelpPref;
208  // these next lines are for legacy cfg files (pre 2.0) where we had different modes
209  if( (HelpMode == wxT("Standard")) || (HelpMode == wxT("InBrowser")) )
210  {
211  HelpMode = wxT("Local");
212  pProj->mHelpPref = HelpMode;
213  gPrefs->Write(wxT("/GUI/Help"), HelpMode);
214  gPrefs->Flush();
215  }
216  }
217 
218  // Anchors (URLs with a '#' in them) are not supported by many OSs for local file names
219  // See, for example, https://groups.google.com/forum/#!topic/wx-users/pC0uOZJalRQ
220  // Problems have been reported on Win, Mac and some versions of Linux.
221  // So we set HelpMode to use the internet if an anchor is found.
222  if (localFileName.Find('#', true) != wxNOT_FOUND)
223  HelpMode = wxT("FromInternet");
224  // Until a solution is found for this, the next few lines are irrelevant.
225 
226  // Obtain the local file system file name, without the anchor if present.
227  wxString localfile;
228  if (localFileName.Find('#', true) != wxNOT_FOUND)
229  localfile = localFileName.BeforeLast('#');
230  else
231  localfile = localFileName;
232 
233  if( (HelpMode == wxT("FromInternet")) && !remoteURL.IsEmpty() )
234  {
235  // Always go to remote URL. Use External browser.
236  OpenInDefaultBrowser( remoteURL );
237  }
238  else if( localfile.IsEmpty() || !wxFileExists( localfile ))
239  {
240  // If you give an empty remote URL, you should have already ensured
241  // that the file exists!
242  wxASSERT( !remoteURL.IsEmpty() );
243  // I can't find it'.
244  // Use Built-in browser to suggest you use the remote url.
245  wxString Text = HelpText( wxT("remotehelp") );
246  Text.Replace( wxT("*URL*"), remoteURL );
247  ShowHtmlText( parent, _("Help on the Internet"), Text, false, bModal );
248  }
249  else if( HelpMode == wxT("Local") || alwaysDefaultBrowser)
250  {
251  // Local file, External browser
252  OpenInDefaultBrowser( wxString(wxT("file:"))+localFileName );
253  }
254  else
255  {
256  // Local file, Built-in browser
257  ShowHtmlText( parent, wxT(""), localFileName, true, bModal );
258  }
259 }
AudacityPrefs * gPrefs
Definition: Prefs.cpp:73
static void ShowHtmlText(wxWindow *pParent, const wxString &Title, const wxString &HtmlText, bool bIsFile=false, bool bModal=false)
Definition: HelpSystem.cpp:89
AudacityProject provides the main window, with tools and tracks contained within it.
Definition: Project.h:176
wxString HelpText(const wxString &Key)
Definition: HelpText.cpp:298
_("Move Track &Down")+wxT("\t")+(GetActiveProject() -> GetCommandManager() ->GetKeyFromName(wxT("TrackMoveDown")).Raw()), OnMoveTrack) POPUP_MENU_ITEM(OnMoveTopID, _("Move Track to &Top")+wxT("\t")+(GetActiveProject() ->GetCommandManager() ->GetKeyFromName(wxT("TrackMoveTop")).Raw()), OnMoveTrack) POPUP_MENU_ITEM(OnMoveBottomID, _("Move Track to &Bottom")+wxT("\t")+(GetActiveProject() ->GetCommandManager() ->GetKeyFromName(wxT("TrackMoveBottom")).Raw()), OnMoveTrack)#define SET_TRACK_NAME_PLUGIN_SYMBOLclass SetTrackNameCommand:public AudacityCommand
AUDACITY_DLL_API AudacityProject * GetActiveProject()
Definition: Project.cpp:308
wxString mHelpPref
Definition: Project.h:706
void OpenInDefaultBrowser(const wxHtmlLinkInfo &link)
void HelpSystem::ShowHelp ( wxWindow *  parent,
const wxString &  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
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

Definition at line 261 of file HelpSystem.cpp.

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

264 {
265  wxString localHelpPage;
266  wxString webHelpPath;
267  wxString webHelpPage;
268  wxString releasePageName;
269  wxString anchor; // optional part of URL after (and including) the '#'
270  if (PageName.Find('#', true) != wxNOT_FOUND)
271  { // need to split anchor off into separate variable
272  releasePageName= PageName.BeforeLast('#');
273  anchor = wxT("#") + PageName.AfterLast('#');
274  }
275  else
276  {
277  releasePageName = PageName;
278  anchor = wxT("");
279  }
280  // The wiki pages are transformed to static HTML by
281  // scripts/mw2html_audacity/mw2html.py
282  // The name is first transformed to lower case, then all
283  // 'special characters' are replaced by underscores. Spaces are
284  // transformed to "+".
285  //
286  // The transformations are handled in mw2html by first applying
287  // 'urllib.parse.quote_plus' (escape chars that are not in "always safe" list)
288  // then replacing escape characters (%xx) with underscores,
289  // and finally removing duplicate / redundant underscores.
290  //
291  // The front page and 'quick_help' are treated as special cases and placed in
292  // the root of the help directory rather than the "/man/" sub-directory.
293  if (releasePageName == wxT("Main_Page"))
294  {
295  releasePageName = wxT("index") + HelpSystem::ReleaseSuffix + anchor;
296  localHelpPage = wxFileName(FileNames::HtmlHelpDir(), releasePageName).GetFullPath();
297  webHelpPath = wxT("https://")+HelpSystem::HelpHostname+HelpSystem::HelpServerHomeDir;
298  }
299  else if (releasePageName == wxT("Quick_Help"))
300  {
301 // DA: No bundled help, by default, and different quick-help URL.
302 #ifdef EXPERIMENTAL_DA
303  releasePageName = wxT("video") + HelpSystem::ReleaseSuffix + anchor;
304  localHelpPage = wxFileName(FileNames::HtmlHelpDir(), releasePageName).GetFullPath();
305  webHelpPath = wxT("http://www.darkaudacity.com/");
306 #else
307  releasePageName = wxT("quick_help") + HelpSystem::ReleaseSuffix + anchor;
308  localHelpPage = wxFileName(FileNames::HtmlHelpDir(), releasePageName).GetFullPath();
309  webHelpPath = wxT("https://")+HelpSystem::HelpHostname+HelpSystem::HelpServerHomeDir;
310 #endif
311  }
312  // not a page name, but rather a full path (e.g. to wiki)
313  // in which case do not do any substitutions.
314  else if (releasePageName.StartsWith( "http" ) )
315  {
316  localHelpPage = "";
317  webHelpPage = releasePageName + anchor;
318  }
319  else
320  {
321  // Handle all other pages.
322  // Change to lower case.
323  releasePageName = releasePageName.Lower();
324  wxRegEx re;
325  // replace 'special characters' with underscores.
326  // RFC 2396 defines the characters a-z, A-Z, 0-9 and ".-_" as "always safe"
327  // mw2html also replaces "-" with "_" so replace that too.
328 
329  // If PageName contains a %xx code, mw2html will transform it:
330  // '%xx' => '%25xx' => '_'
331  re.Compile(wxT("%.."));
332  re.ReplaceAll(&releasePageName, (wxT("_")));
333  // Now replace all other 'not-safe' characters.
334  re.Compile(wxT("[^[:alnum:] . [:space:]]"));
335  re.ReplaceAll(&releasePageName, (wxT("_")));
336  // Replace spaces with "+"
337  releasePageName.Replace(wxT(" "), wxT("+"), true);
338  // Reduce multiple underscores to single underscores
339  re.Compile(wxT("__+"));
340  re.ReplaceAll(&releasePageName, (wxT("_")));
341  // Replace "_." with "."
342  releasePageName.Replace(wxT("_."), wxT("."), true);
343  // Concatenate file name with file extension and anchor.
344  releasePageName = releasePageName + HelpSystem::ReleaseSuffix + anchor;
345  // Other than index and quick_help, all local pages are in subdirectory 'LocalHelpManDir'.
346  localHelpPage = wxFileName(FileNames::HtmlHelpDir() + LocalHelpManDir, releasePageName).GetFullPath();
347  // Other than index and quick_help, all on-line pages are in subdirectory 'HelpServerManDir'.
348  webHelpPath = wxT("https://")+HelpSystem::HelpHostname+HelpSystem::HelpServerManDir;
349  }
350 
351 #ifdef USE_ALPHA_MANUAL
352  webHelpPage = webHelpPath + PageName;
353 #else
354  webHelpPage = webHelpPath + releasePageName;
355 #endif
356 
357  wxLogMessage(wxT("Help button pressed: PageName %s, releasePageName %s"),
358  PageName, releasePageName);
359  wxLogMessage(wxT("webHelpPage %s, localHelpPage %s"),
360  webHelpPage, localHelpPage);
361 
362  wxASSERT(parent); // to justify safenew
363 
365  parent,
366  localHelpPage,
367  webHelpPage,
368  bModal
369  );
370 }
static const wxString LocalHelpManDir
Definition: HelpSystem.h:96
static const wxString HelpServerHomeDir
Definition: HelpSystem.h:86
static const wxString HelpHostname
Definition: HelpSystem.h:81
static wxString HtmlHelpDir()
Definition: FileNames.cpp:173
static void ShowHelp(wxWindow *parent, const wxString &localFileName, const wxString &remoteURL, bool bModal=false, bool alwaysDefaultBrowser=false)
Definition: HelpSystem.cpp:195
static const wxString ReleaseSuffix
Definition: HelpSystem.h:100
static const wxString HelpServerManDir
Definition: HelpSystem.h:91
void HelpSystem::ShowHtmlText ( wxWindow *  pParent,
const wxString &  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 89 of file HelpSystem.cpp.

References _(), ShuttleGuiBase::AddButton(), ShuttleGuiBase::AddWindow(), ThemeBase::Bitmap(), eIsCreating, ShuttleGuiBase::EndHorizontalLay(), ShuttleGuiBase::EndPanel(), ShuttleGui::Id(), BrowserDialog::mpHtml, ShuttleGui::Prop(), safenew, ShuttleGuiBase::SetStyle(), ShuttleGuiBase::StartHorizontalLay(), ShuttleGuiBase::StartPanel(), and theTheme.

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

94 {
95  LinkingHtmlWindow *html;
96 
97  wxASSERT(pParent); // to justify safenew
98  // JKC: ANSWER-ME: Why do we create a fake 'frame' and then put a BrowserDialog
99  // inside it, rather than have a variant of the BrowserDialog that is a
100  // frame??
101  // Bug 1412 seems to be related to the extra frame.
102  auto pFrame = safenew wxFrame {
103  pParent, wxID_ANY, Title, wxDefaultPosition, wxDefaultSize,
104 #if defined(__WXMAC__)
105  // On OSX, the html frame can go behind the help dialog and if the help
106  // html frame is modal, you can't get back to it. Pressing escape gets
107  // you out of this, but it's just easier to add the wxSTAY_ON_TOP flag
108  // to prevent it from falling behind the dialog. Not the perfect solution
109  // but acceptable in this case.
110  wxSTAY_ON_TOP |
111 #endif
112  wxDEFAULT_FRAME_STYLE
113  };
114 
115  BrowserDialog * pWnd;
116  if( bModal )
117  pWnd = safenew HtmlTextHelpDialog{ pFrame, Title };
118  else
119  pWnd = safenew BrowserDialog{ pFrame, Title };
120 
121  // Bug 1412 workaround for 'extra window'. Hide the 'fake' window.
122  pFrame->SetTransparent(0);
123  ShuttleGui S( pWnd, eIsCreating );
124 
125  S.SetStyle( wxNO_BORDER | wxTAB_TRAVERSAL );
126  wxPanel *pPan = S.Prop(true).StartPanel();
127  {
128  S.StartHorizontalLay( wxEXPAND, false );
129  {
130  wxButton * pWndBackwards = S.Id( wxID_BACKWARD ).AddButton( _("<") );
131  wxButton * pWndForwards = S.Id( wxID_FORWARD ).AddButton( _(">") );
132  pWndForwards->Enable( false );
133  pWndBackwards->Enable( false );
134  #if wxUSE_TOOLTIPS
135  pWndForwards->SetToolTip( _("Forwards" ));
136  pWndBackwards->SetToolTip( _("Backwards" ));
137  #endif
138  }
139  S.EndHorizontalLay();
140 
141  html = safenew LinkingHtmlWindow(pPan, wxID_ANY,
142  wxDefaultPosition,
143  bIsFile ? wxSize(500, 400) : wxSize(480, 240),
144  wxHW_SCROLLBAR_AUTO | wxSUNKEN_BORDER);
145 
146  html->SetRelatedFrame( pFrame, wxT("Help: %s") );
147  if( bIsFile )
148  html->LoadFile( HtmlText );
149  else
150  html->SetPage( HtmlText);
151 
152  S.Prop(1).AddWindow( html, wxEXPAND );
153 
154  S.Id( wxID_CANCEL ).AddButton( _("Close") )->SetDefault();
155  }
156  S.EndPanel();
157 
158  // -- START of ICON stuff -----
159  // If this section (providing an icon) causes compilation errors on linux, comment it out for now.
160  // it will just mean that the icon is missing. Works OK on Windows.
161  #ifdef __WXMSW__
162  wxIcon ic{ wxICON(AudacityLogo) };
163  #else
164  wxIcon ic{};
165  ic.CopyFromBitmap(theTheme.Bitmap(bmpAudacityLogo48x48));
166  #endif
167  pFrame->SetIcon( ic );
168  // -- END of ICON stuff -----
169 
170 
171  pWnd->mpHtml = html;
172  pWnd->SetBackgroundColour( wxSystemSettings::GetColour(wxSYS_COLOUR_BTNFACE));
173 
174  pFrame->CreateStatusBar();
175  pFrame->Centre();
176  pFrame->Layout();
177  pFrame->Fit();
178  pFrame->SetSizeHints(pWnd->GetSize());
179 
180  pFrame->SetName(Title);
181  if (bModal)
182  pWnd->ShowModal();
183  else {
184  pWnd->Show(true);
185  pFrame->Show(true);
186  }
187 
188  html->SetRelatedStatusBar( 0 );
189  html->SetFocus();
190 
191  return;
192 }
AUDACITY_DLL_API Theme theTheme
Definition: Theme.cpp:209
Derived from ShuttleGuiBase, an Audacity specific class for shuttling data to and from GUI...
Definition: ShuttleGui.h:409
#define safenew
Definition: Audacity.h:230
wxBitmap & Bitmap(int iIndex)
Definition: Theme.cpp:1244
_("Move Track &Down")+wxT("\t")+(GetActiveProject() -> GetCommandManager() ->GetKeyFromName(wxT("TrackMoveDown")).Raw()), OnMoveTrack) POPUP_MENU_ITEM(OnMoveTopID, _("Move Track to &Top")+wxT("\t")+(GetActiveProject() ->GetCommandManager() ->GetKeyFromName(wxT("TrackMoveTop")).Raw()), OnMoveTrack) POPUP_MENU_ITEM(OnMoveBottomID, _("Move Track to &Bottom")+wxT("\t")+(GetActiveProject() ->GetCommandManager() ->GetKeyFromName(wxT("TrackMoveBottom")).Raw()), OnMoveTrack)#define SET_TRACK_NAME_PLUGIN_SYMBOLclass SetTrackNameCommand:public AudacityCommand
HtmlWindow * mpHtml
void HelpSystem::ShowInfoDialog ( wxWindow *  parent,
const wxString &  dlogTitle,
const wxString &  shortMsg,
const wxString &  message,
const int  xSize,
const int  ySize 
)
static

Displays cutable 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 54 of file HelpSystem.cpp.

References ShuttleGui::AddStandardButtons(), ShuttleGuiBase::AddTextWindow(), ShuttleGuiBase::AddTitle(), eIsCreating, ShuttleGuiBase::EndHorizontalLay(), ShuttleGuiBase::EndVerticalLay(), eOkButton, ShuttleGuiBase::SetBorder(), ShuttleGuiBase::SetStyle(), ShuttleGuiBase::StartHorizontalLay(), and ShuttleGuiBase::StartVerticalLay().

Referenced by ExportMultiple::OnExport().

59 {
60  wxDialogWrapper dlog(parent, wxID_ANY,
61  dlogTitle,
62  wxDefaultPosition, wxDefaultSize,
63  wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER | wxMAXIMIZE_BOX /*| wxDEFAULT_FRAME_STYLE */);
64 
65  dlog.SetName(dlog.GetTitle());
66  ShuttleGui S(&dlog, eIsCreating);
67 
68  S.StartVerticalLay(1);
69  {
70  S.AddTitle( shortMsg);
71  S.SetStyle( wxTE_MULTILINE | wxTE_READONLY | wxTE_RICH | wxTE_RICH2 |
72  wxTE_AUTO_URL | wxTE_NOHIDESEL | wxHSCROLL );
73  S.AddTextWindow(message);
74 
75  S.SetBorder( 0 );
76  S.StartHorizontalLay(wxALIGN_CENTER_HORIZONTAL, 0);
77  S.AddStandardButtons(eOkButton);
78  S.EndHorizontalLay();
79  }
80  S.EndVerticalLay();
81 
82  // Smallest size is half default size. Seems reasonable.
83  dlog.SetMinSize( wxSize(xSize/2, ySize/2) );
84  dlog.SetSize( wxSize(xSize, ySize) );
85  dlog.Center();
86  dlog.ShowModal();
87 }
Derived from ShuttleGuiBase, an Audacity specific class for shuttling data to and from GUI...
Definition: ShuttleGui.h:409

Member Data Documentation

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

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

Definition at line 81 of file HelpSystem.h.

Referenced by ShowHelp().

const wxString HelpSystem::HelpServerHomeDir = wxT("/man/")
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 86 of file HelpSystem.h.

Referenced by ShowHelp().

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 91 of file HelpSystem.h.

Referenced by ShowHelp().

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 96 of file HelpSystem.h.

Referenced by ShowHelp().

const wxString HelpSystem::ReleaseSuffix = wxT(".html")
static

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 100 of file HelpSystem.h.

Referenced by ShowHelp().


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