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

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

Referenced by COMMON_CONTROL::ShowHelp().