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

aBaseName

is 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.

{
 SEARCH_STACK basePaths;
 wxString helpFile;
 
 // help files are most likely located in the documentation install path
 basePaths.Add( PATHS::GetDocumentationPath() );
 
#ifndef __WIN32__
 // just in case, add all known system directories to the search stack
 SystemDirsAppend( &basePaths );
#endif
 
#if defined( DEBUG )
 basePaths.Show( wxString( __func__ ) + wxS( ": basePaths" ) );
#endif
 
 // By default, the documentation from kicad-doc is installed to a folder called "help" with
 // subdirectories for all supported languages. Although this can be changed at build-time by
 // overwriting ${KICAD_DOC_PATH}, the best guess KiCad can make is that help files are always
 // located in a folder named "help". If no translation matching the current locale settings is
 // available, the English version will be returned instead.
 
 wxLocale* currentLocale = Pgm().GetLocale();
 wxArrayString localeNameDirs;
 
 // canonical form of the current locale (e.g., "fr_FR")
 localeNameDirs.Add( currentLocale->GetCanonicalName() );
 
 // short form of the current locale (e.g., "fr")
 // wxLocale::GetName() does not always return the short form
 localeNameDirs.Add( currentLocale->GetName().BeforeLast( wxS( '_' ) ) );
 
 // plain English (in case a localised version of the help file cannot be found)
 localeNameDirs.Add( wxS( "en" ) );
 
 for( wxString& locale : localeNameDirs )
 {
 SEARCH_STACK docPaths;
 
 for( wxString& base : basePaths )
 {
 wxFileName path( base, wxEmptyString );
 
 // add <base>/help/<locale>/
 path.AppendDir( wxS( "help" ) );
 path.AppendDir( locale );
 docPaths.AddPaths( path.GetPath() );
 
 // add <base>/doc/help/<locale>/
 path.InsertDir( path.GetDirCount() - 2, wxS( "doc" ) );
 docPaths.AddPaths( path.GetPath() );
 
 // add <base>/doc/kicad/help/<locale>/
 path.InsertDir( path.GetDirCount() - 2, wxS( "kicad" ) );
 docPaths.AddPaths( path.GetPath() );
 }
 
#if defined( DEBUG )
 docPaths.Show( wxString( __func__ ) + wxS( ": docPaths (" ) + locale + wxS( ")" ) );
#endif
 
 // search HTML first, as it is the preferred format for help files
 wxLogTrace( tracePathsAndFiles, wxS( "Checking SEARCH_STACK for file %s.html" ),
 aBaseName );
 helpFile = docPaths.FindValidPath( aBaseName + wxS( ".html" ) );
 
 if( !helpFile.IsEmpty() )
 {
 // prepend URI protocol to open the file in a browser
 helpFile = wxS( "file://" ) + helpFile;
 break;
 }
 
 // search PDF only when no corresponding HTML file was found
 wxLogTrace( tracePathsAndFiles, wxS( "Checking SEARCH_STACK for file %s.pdf" ), aBaseName );
 helpFile = docPaths.FindValidPath( aBaseName + wxS( ".pdf" ) );
 
 if( !helpFile.IsEmpty() )
 break;
 }
 
 return helpFile;
}

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

Referenced by COMMON_CONTROL::ShowHelp().