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 201 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(), PrefsDialog::OnHelp(), EffectUIHost::OnHelp(), TimerRecordDialog::OnHelpButtonClick(), LinkingHtmlWindow::OnLinkClicked(), AudacityProject::OnManual(), LibraryPrefs::OnMP3DownButton(), AudacityProject::OnQuickHelp(), and ShowHelp().

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

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

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

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

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: