KiCad PCB EDA Suite
searchhelpfilefullpath.cpp File Reference
#include <common.h>
#include <pgm_base.h>
#include <paths.h>
#include <systemdirsappend.h>
#include <trace_helpers.h>
#include <wx/arrstr.h>
#include <wx/log.h>

Go to the source code of this file.

Functions

wxString SearchHelpFileFullPath (const wxString &aBaseName)
 Return the help file's full path. More...
 

Function Documentation

◆ SearchHelpFileFullPath()

wxString SearchHelpFileFullPath ( const wxString &  aBaseName)

Return the help file's full path.

Return the full path and name (including extension) of the given KiCad help file. It is expected to be found in a subfolder help/<LANG>/ in one of the system paths. Supported file types are *.html and *.pdf. If no such file is available for the current locale, an attempt to find the English version is made. The search order for <LANG> is: 1) canonical form (e.g., "fr_FR"), 2) short form (e.g., "fr"), and 3) "en".

Parameters
aBaseNameis the name of the help file to search for (without extension).
Returns
the full path and filename if aBaseName is found, else wxEmptyString.

Definition at line 32 of file searchhelpfilefullpath.cpp.

33 {
34  SEARCH_STACK basePaths;
35  wxString helpFile;
36 
37  // help files are most likely located in the documentation install path
38  basePaths.Add( PATHS::GetDocumentationPath() );
39 
40  // just in case, add all known system directories to the search stack
41  SystemDirsAppend( &basePaths );
42 
43 #if defined( DEBUG )
44  basePaths.Show( wxString( __func__ ) + ": basePaths" );
45 #endif
46 
47  // By default, the documentation from kicad-doc is installed to a folder called "help" with
48  // subdirectories for all supported languages. Although this can be changed at build-time by
49  // overwriting ${KICAD_DOC_PATH}, the best guess KiCad can make is that help files are always
50  // located in a folder named "help". If no translation matching the current locale settings is
51  // available, the English version will be returned instead.
52 
53  wxLocale* currentLocale = Pgm().GetLocale();
54  wxArrayString localeNameDirs;
55 
56  // canonical form of the current locale (e.g., "fr_FR")
57  localeNameDirs.Add( currentLocale->GetCanonicalName() );
58 
59  // short form of the current locale (e.g., "fr")
60  // wxLocale::GetName() does not always return the short form
61  localeNameDirs.Add( currentLocale->GetName().BeforeLast( '_' ) );
62 
63  // plain English (in case a localised version of the help file cannot be found)
64  localeNameDirs.Add( "en" );
65 
66  for( wxString& locale : localeNameDirs )
67  {
68  SEARCH_STACK docPaths;
69 
70  for( wxString& base : basePaths )
71  {
72  wxFileName path( base, wxEmptyString );
73 
74  // add <base>/help/<locale>/
75  path.AppendDir( "help" );
76  path.AppendDir( locale );
77  docPaths.AddPaths( path.GetPath() );
78 
79  // add <base>/doc/help/<locale>/
80  path.InsertDir( path.GetDirCount() - 2, "doc" );
81  docPaths.AddPaths( path.GetPath() );
82 
83  // add <base>/doc/kicad/help/<locale>/
84  path.InsertDir( path.GetDirCount() - 2, "kicad" );
85  docPaths.AddPaths( path.GetPath() );
86  }
87 
88 #if defined( DEBUG )
89  docPaths.Show( wxString( __func__ ) + ": docPaths (" + locale + ")" );
90 #endif
91 
92  // search HTML first, as it is the preferred format for help files
93  wxLogTrace( tracePathsAndFiles, "Checking SEARCH_STACK for file %s.html", aBaseName );
94  helpFile = docPaths.FindValidPath( aBaseName + ".html" );
95 
96  if( !helpFile.IsEmpty() )
97  {
98  // prepend URI protocol to open the file in a browser
99  helpFile = "file://" + helpFile;
100  break;
101  }
102 
103  // search PDF only when no corresponding HTML file was found
104  wxLogTrace( tracePathsAndFiles, "Checking SEARCH_STACK for file %s.pdf", aBaseName );
105  helpFile = docPaths.FindValidPath( aBaseName + ".pdf" );
106 
107  if( !helpFile.IsEmpty() )
108  break;
109  }
110 
111  return helpFile;
112 }
wxString FindValidPath(const wxString &aFileName) const
Definition: search_stack.h:70
const wxChar *const tracePathsAndFiles
Flag to enable path and file name debug output.
Look for files in a number of paths.
Definition: search_stack.h:41
KIWAY Kiway & Pgm(), KFCTL_STANDALONE
The global Program "get" accessor.
Definition: single_top.cpp:106
static wxString GetDocumentationPath()
Gets the documentation path, which is the base path for help files.
Definition: paths.cpp:275
void SystemDirsAppend(SEARCH_STACK *aSearchStack)
Append system places to aSearchStack in a platform specific way and pertinent to KiCad programs.
void AddPaths(const wxString &aPaths, int aIndex=-1)
Insert or append path(s).

References SEARCH_STACK::AddPaths(), SEARCH_STACK::FindValidPath(), PATHS::GetDocumentationPath(), path, Pgm(), SystemDirsAppend(), and tracePathsAndFiles.

Referenced by COMMON_CONTROL::ShowHelp().