Audacity  3.0.3
HelpText.cpp
Go to the documentation of this file.
1 /**********************************************************************
2 
3  Audacity: A Digital Audio Editor
4 
5  HelpText.cpp
6 
7  James Crook
8 
9 ********************************************************************//********************************************************************/
14 
15 
16 #include "HelpText.h"
17 
18 #include <wx/colour.h>
19 #include <wx/string.h>
20 #include <wx/intl.h>
21 #include <wx/sstream.h>
22 #include <wx/txtstrm.h>
23 
24 #include "FileNames.h"
25 #include "Internat.h"
26 #include "AllThemeResources.h"
27 #include "Theme.h"
28 
29 #ifdef HAS_WHATS_NEW
30 
31 namespace
32 {
33 const char* WhatsNewURL = "https://youtube.com";
34 }
35 
36 #endif
37 
38 wxString HtmlColourOfIndex( int i ){
39  wxColour c = theTheme.Colour(i);
40  return wxString::Format("\"#%02X%02X%02X\"",
41  c.Red(), c.Green(), c.Blue() );
42 }
43 
44 static wxString WrapText( const wxString & Text )
45 {
46  return wxString(wxT(""))+
47  wxT("<html><head></head>") +
48  wxT("<body bgcolor=") + HtmlColourOfIndex(clrTrackInfo) + wxT(">") +
49  wxT("<font color=") + HtmlColourOfIndex(clrTrackPanelText) + wxT(">") +
50  wxT("<p>") + Text +
51  wxT("</font>")+
52  wxT("</body></html>");
53 }
54 
55 static wxString InnerLink( const wxString &Key, const wxString& Text )
56 {
57  return wxString(wxT("")) +
58  wxT("<a href='innerlink:") +
59  Key +
60  wxT("'>") +
61  Text +
62  wxT("</a>");
63 }
64 
65 static wxString WikiLink( const wxString &Key, const wxString& Text )
66 {
67  return wxString(wxT("")) +
68  wxT("<a href='https://www.audacityteam.org/wiki/index.php?title=") +
69  Key +
70  wxT("'>") +
71  Text +
72  wxT("</a>");
73 }
74 
75 static wxString FileLink( const wxString &Key, const wxString& Text )
76 {
77  return wxString(wxT("")) +
78  wxT("<a href='") +
79  wxT("file:") +
81  Key +
82  wxT("'>") +
83  Text +
84  wxT("</a>");
85 }
86 
87 static wxString TypedLink( const wxString &Key, const wxString& Text )
88 {
89  return wxString(wxT("")) +
90  wxT("<a href='") +
91  Key +
92  wxT("'>") +
93  Text +
94  wxT("</a>");
95 }
96 
97 static wxString LinkExpand( const wxString & Text )
98 {
99  wxString Temp = Text;
100  int i,j,k;
101  while( (i=Temp.First( wxT("[[") ))!= wxNOT_FOUND )
102  {
103  wxString Key = Temp.Mid(i+2);
104  j = Key.First( wxT("|") );
105  if( j==wxNOT_FOUND )
106  return Temp;
107  wxString LinkText = Key.Mid( j+1);
108  k = LinkText.First( wxT("]]") );
109  if( k==wxNOT_FOUND )
110  return Temp;
111  Key = Key.Mid( 0, j );
112  LinkText = LinkText.Mid( 0, k );
113 
114  LinkText=wxString("<font color=") + HtmlColourOfIndex(clrSample) + wxT(">") +LinkText+"</font>";
115  wxString Replacement;
116  if( Key.StartsWith( wxT("wiki:") ))
117  {
118  Replacement = WikiLink( Key.Mid( 5 ), LinkText );
119  }
120  else if( Key.StartsWith( wxT("file:") ))
121  {
122  Replacement = FileLink( Key.Mid( 5 ), LinkText );
123  }
124  else if( Key.StartsWith( wxT("http:") ))
125  {
126  Replacement = TypedLink( Key, LinkText );
127  }
128  else if( Key.StartsWith( wxT("https:") ))
129  {
130  Replacement = TypedLink( Key, LinkText );
131  }
132  else if( Key.StartsWith( wxT("mailto:") ))
133  {
134  Replacement = TypedLink( Key, LinkText );
135  }
136  else if( Key.StartsWith( wxT("*URL*") ))
137  {
138  Replacement = TypedLink( Key, LinkText );
139  }
140  else
141  {
142  Replacement = InnerLink( Key, LinkText );
143  }
144 
145 
146  Temp = Temp.Mid( 0, i ) + Replacement + Temp.Mid( i + j + k + 5 );// 5 for the [[|]]
147  }
148  return Temp;
149 }
150 
151 TranslatableString TitleText( const wxString & Key )
152 {
153  if(Key==wxT("welcome"))
154  {
155  return XO("Welcome!");
156  }
157 
158  if(Key ==wxT("play") )
159  {
160  /* i18n-hint: Title for a topic.*/
161  return XO("Playing Audio");
162  }
163  if((Key ==wxT("record") ) || (Key ==wxT("norecord") ))
164  {
165  /* i18n-hint: Title for a topic.*/
166  return XO("Recording Audio");
167  }
168  if(Key ==wxT("inputdevice") )
169  {
170  /* i18n-hint: Title for a topic.*/
171  return XO("Recording - Choosing the Recording Device");
172  }
173  if(Key ==wxT("inputsource") )
174  {
175  /* i18n-hint: Title for a topic.*/
176  return XO("Recording - Choosing the Recording Source");
177  }
178  if(Key ==wxT("inputlevel") )
179  {
180  /* i18n-hint: Title for a topic.*/
181  return XO("Recording - Setting the Recording Level");
182  }
183  if((Key ==wxT("edit") ) || (Key==wxT("grey")))
184  {
185  /* i18n-hint: Title for a topic.*/
186  return XO("Editing and greyed out Menus");
187  }
188  if(Key ==wxT("export") )
189  {
190  /* i18n-hint: Title for a topic.*/
191  return XO("Exporting an Audio File");
192  }
193  if(Key ==wxT("save") )
194  {
195  /* i18n-hint: Title for a topic.*/
196  return XO("Saving an Audacity Project");
197  }
198  if(Key ==wxT("wma-proprietary") )
199  {
200  /* i18n-hint: Title for a topic.*/
201  return XO("Support for Other Formats");
202  }
203  if(Key ==wxT("burncd") )
204  {
205  /* i18n-hint: Title for a topic.*/
206  return XO("Burn to CD" );
207  }
208  if(Key == wxT("remotehelp") )
209  {
210  return XO("No Local Help");
211  }
212  // Uh oh, no translation...
213  return Verbatim( Key );
214 }
215 
216 static wxString HelpTextBuiltIn( const wxString & Key )
217 {
218  // PRL: Is it necessary to define these outside of conditional compilation so that both get into the .pot file?
219  const auto alphamsg = XO(
220 "<br><br>The version of Audacity you are using is an <b>Alpha test version</b>.");
221  const auto betamsg = XO(
222 "<br><br>The version of Audacity you are using is a <b>Beta test version</b>.");
223 
224  if (Key == wxT("welcome"))
225  {
226  wxStringOutputStream o;
227  wxTextOutputStream s(o);
228  s
229 #if defined(IS_ALPHA) || defined(IS_BETA)
230  << wxT("<hr><center><h3>")
231  << XO("Get the Official Released Version of Audacity")
232  << wxT("</h3></center>")
233  << VerCheckHtml()
234 #ifdef IS_ALPHA
235  << alphamsg
236 #else
237  << betamsg
238 #endif
239  << wxT(" ")
240  << XO(
241 "We strongly recommend that you use our latest stable released version, which has full documentation and support.<br><br>")
242  << XO(
243 "You can help us get Audacity ready for release by joining our [[https://www.audacityteam.org/community/|community]].<hr><br><br>")
244 #endif
245 
246 // DA: Support methods text.
247 #ifdef EXPERIMENTAL_DA
248  // Deliberately not translated.
249  << wxT("<center><h3>DarkAudacity ")
250  << AUDACITY_VERSION_STRING
251  << wxT("</h3></center>")
252  << wxT("<br><br>DarkAudacity is based on Audacity:")
253  << wxT("<ul><li>")
254  << wxT(" [[http://www.darkaudacity.com|www.darkaudacity.com]] - for differences between them.")
255  << wxT("</li><li>")
256  << wxT(
257 " email to [[mailto:[email protected]|[email protected]]] - for help using DarkAudacity.")
258  << wxT("</li><li>")
259  << wxT(
260 " [[http://www.darkaudacity.com/video.html|Tutorials]] - for getting started with DarkAudacity.")
261  << wxT("</li></ul>")
262  << wxT("<br><br>Audacity has these support methods:")
263  << wxT("<ul><li>")
264  << wxT(" [[https://manual.audacityteam.org/|Manual]] - for comprehensive Audacity documentation")
265  << wxT("</li><li>")
266  << wxT(" [[https://forum.audacityteam.org/|Forum]] - for large knowledge base on using Audacity.")
267  << wxT("</li></ul>")
268 #else
269  << wxT("<center><h3>")
270 #ifndef HAS_WHATS_NEW
271  << wxT("Audacity ") << AUDACITY_VERSION_STRING
272 #else
273  /* i18n-hint: %s is replaced with Audacity version */
274  << XO("What's new in Audacity %s").Format(AUDACITY_VERSION_STRING)
275  << wxT(R"(<p><a href=")") << WhatsNewURL << wxT(R"(">)")
276  << wxT(R"(<img src="memory:whats_new_btn.png" width="263" height="148" /></a></p>)")
277 #endif
278  << wxT("</h3><h3>")
279  << XO("How to get help")
280  << wxT("</h3></center>")
281  << XO("These are our support methods:")
282  << wxT("<p><ul><li>")
283  /* i18n-hint: Preserve '[[help:Quick_Help|' as it's the name of a link.*/
284  << XO("[[help:Quick_Help|Quick Help]] - if not installed locally, [[https://manual.audacityteam.org/quick_help.html|view online]]")
285  << wxT("</li><li>")
286  << XO(
287 /* i18n-hint: Preserve '[[help:Main_Page|' as it's the name of a link.*/
288 " [[help:Main_Page|Manual]] - if not installed locally, [[https://manual.audacityteam.org/|view online]]")
289  << wxT("</li><li>")
290  << XO(
291 " [[https://forum.audacityteam.org/|Forum]] - ask your question directly, online.")
292  << wxT("</li></ul></p><p>")
293  << wxT("<b>")
294  << XO("More:</b> Visit our [[https://wiki.audacityteam.org/index.php|Wiki]] for tips, tricks, extra tutorials and effects plug-ins.")
295  << wxT("</p>")
296 #endif
297  ;
298 
299  auto result = o.GetString();
300 #ifdef USE_ALPHA_MANUAL
301  result.Replace( "//manual.audacityteam.org/quick_help.html","//alphamanual.audacityteam.org/man/Quick_Help" );
302  result.Replace( "//manual.audacityteam.org/","//alphamanual.audacityteam.org/man/" );
303 #endif
304 
305  return WrapText( result );
306  }
307  if(Key==wxT("wma-proprietary"))
308  {
309  wxStringOutputStream o;
310  wxTextOutputStream s(o);
311  s
312  << wxT("<p>")
313  << XO(
314 "Audacity can import unprotected files in many other formats (such as M4A and WMA, \
315 compressed WAV files from portable recorders and audio from video files) if you download and install \
316 the optional [[https://manual.audacityteam.org/man/faq_opening_and_saving_files.html#foreign| \
317 FFmpeg library]] to your computer.")
318  << wxT("</p><p>")
319  << XO(
320 "You can also read our help on importing \
321 [[https://manual.audacityteam.org/man/playing_and_recording.html#midi|MIDI files]] \
322 and tracks from [[https://manual.audacityteam.org/man/faq_opening_and_saving_files.html#fromcd| \
323 audio CDs]].")
324  << wxT("</p>")
325  ;
326  return WrapText( o.GetString() );
327  }
328 
329  // Remote help allows us to link to a local copy of the help if it exists,
330  // or provide a message that takes you to the Internet if it does not.
331  // It's used by the menu item Help > Index
332  if(Key == wxT("remotehelp") )
333  {
334  wxStringOutputStream o;
335  wxTextOutputStream s(o);
336  s
337 // *URL* will be replaced by whatever URL we are looking for.
338 // DA: View the manual on line is expected.
339 #ifdef EXPERIMENTAL_DA
340  << XO(
341 "The Manual does not appear to be installed. \
342 Please [[*URL*|view the Manual online]].<br><br>\
343 To always view the Manual online, change \"Location of Manual\" in \
344 Interface Preferences to \"From Internet\".")
345 #else
346  << XO(
347 "The Manual does not appear to be installed. \
348 Please [[*URL*|view the Manual online]] or \
349 [[https://manual.audacityteam.org/man/unzipping_the_manual.html| \
350 download the Manual]].<br><br>\
351 To always view the Manual online, change \"Location of Manual\" in \
352 Interface Preferences to \"From Internet\".")
353 #endif
354  ;
355  return WrapText( o.GetString() );
356  }
357  return {};
358 }
359 
360 wxString HelpText( const wxString & Key )
361 {
362 
363  // Possible future enhancement...
364  // We could look for the text as a local file and use
365  // that if we find it...
366  // if( wxFileExists( Path+Key ) )
367  // ...
368 
369  wxString Text;
370  Text = HelpTextBuiltIn( Key );
371 
372  if( !Text.empty())
373  return LinkExpand( Text );
374 
375  // Perhaps useful for debugging - we'll return key that we didn't find.
376  return WrapText( Key );
377 }
378 
379 
380 wxString FormatHtmlText( const wxString & Text ){
381 
382  wxString localeStr = wxLocale::GetSystemEncodingName();
383 
384  return
385  wxT("<html><head><META http-equiv=\"Content-Type\" content=\"text/html; charset=") +
386  localeStr +
387  wxT("\"></head>") +
388  WrapText( LinkExpand( Text ))+
389  wxT("</html>");
390 }
391 
392 // Function to give the extra arguments to put on the version check string.
393 const wxString VerCheckArgs(){
394  wxString result = wxString("from_ver=") + AUDACITY_VERSION_STRING;
395 #ifdef REV_LONG
396  result += wxString("&CommitId=")+wxString(REV_LONG).Left(6);
397 #endif
398  result += wxString("&Time=") + wxString( __DATE__ ) + wxString( __TIME__ );
399  result.Replace(" ","");
400  return result;
401 }
402 
403 // Text of hyperlink to check versions.
404 const wxString VerCheckHtml()
405 {
406  wxStringOutputStream o;
407  wxTextOutputStream s(o);
408  s
409  << "<center>[["
410  << VerCheckUrl().GET()
411  << "|"
412  << XO("Check Online")
413  << "]]</center>\n";
414  return o.GetString();
415 }
416 
417 // Url with Version check args attached.
418 const URLString VerCheckUrl()
419 {
420  //The version we intend to use for live Audacity.
421 #define VER_CHECK_URL "https://www.audacityteam.org/download/?"
422 //For testing of our scriptlet.
423 //#define VER_CHECK_URL "http://www.audacityteam.org/slug/?"
424 //For testing locally
425 //#define VER_CHECK_URL "http://localhost:63342/WorkingDocs/demos/download.html?"
426 
427  return wxString( wxT(VER_CHECK_URL)) +VerCheckArgs();
428 }
TranslatableString
Holds a msgid for the translation catalog; may also bind format arguments.
Definition: TranslatableString.h:32
FormatHtmlText
AUDACITY_DLL_API wxString FormatHtmlText(const wxString &Text)
WrapText
static wxString WrapText(const wxString &Text)
Definition: HelpText.cpp:44
AllThemeResources.h
XO
#define XO(s)
Definition: Internat.h:31
HelpText.h
WikiLink
static wxString WikiLink(const wxString &Key, const wxString &Text)
Definition: HelpText.cpp:65
TypedLink
static wxString TypedLink(const wxString &Key, const wxString &Text)
Definition: HelpText.cpp:87
VerCheckArgs
AUDACITY_DLL_API const wxString VerCheckArgs()
LinkExpand
static wxString LinkExpand(const wxString &Text)
Definition: HelpText.cpp:97
Theme.h
VerCheckHtml
AUDACITY_DLL_API const wxString VerCheckHtml()
VerCheckUrl
AUDACITY_DLL_API const URLString VerCheckUrl()
theTheme
THEME_API Theme theTheme
Definition: Theme.cpp:79
Identifier::GET
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
VER_CHECK_URL
#define VER_CHECK_URL
Internat.h
TaggedIdentifier
Template generates different TaggedIdentifier classes that don't interconvert implicitly.
Definition: Identifier.h:113
FileNames.h
FileNames::HtmlHelpDir
FILES_API FilePath HtmlHelpDir()
HtmlColourOfIndex
wxString HtmlColourOfIndex(int i)
Definition: HelpText.cpp:38
Verbatim
TranslatableString Verbatim(wxString str)
Require calls to the one-argument constructor to go through this distinct global function name.
Definition: TranslatableString.h:321
ThemeBase::Colour
wxColour & Colour(int iIndex)
Definition: Theme.cpp:1057
InnerLink
static wxString InnerLink(const wxString &Key, const wxString &Text)
Definition: HelpText.cpp:55
HelpText
AUDACITY_DLL_API wxString HelpText(const wxString &Key)
TitleText
AUDACITY_DLL_API TranslatableString TitleText(const wxString &Key)
FileLink
static wxString FileLink(const wxString &Key, const wxString &Text)
Definition: HelpText.cpp:75