KiCad PCB EDA Suite
common.h File Reference

The common library. More...

#include <vector>
#include <wx/wx.h>
#include <wx/confbase.h>
#include <wx/fileconf.h>
#include <wx/dir.h>
#include <richio.h>
#include <gal/color4d.h>
#include <atomic>
#include <limits>
#include <memory>
#include <type_traits>
#include <typeinfo>

Go to the source code of this file.

Classes

class  LOCALE_IO
 Instantiate the current locale within a scope in which you are expecting exceptions to be thrown. More...
 
struct  std::hash< wxString >
 
struct  std::hash< wxPoint >
 
struct  std::less< wxPoint >
 
class  WX_FILENAME
 A wrapper around a wxFileName which is much more performant with a subset of the API. More...
 

Namespaces

 std
 

Template specialization to enable wxStrings for certain containers (e.g. unordered_map)


 

Macros

#define INCLUDE__COMMON_H_
 
#define NAMELESS_PROJECT   wxT( "noname" )
 
#define TEXT_ANGLE_HORIZ   0
 
#define TEXT_ANGLE_VERT   900
 
#define USE_KICAD_WXSTRING_HASH
 
#define USE_KICAD_WXPOINT_LESS_AND_HASH
 
#define NAMELESS_PROJECT   wxT( "noname" )
 default name for nameless projects More...
 
#define TEXT_ANGLE_HORIZ   0
 Frequent text rotations, used with {Set,Get}TextAngle(), in 0.1 degrees for now, hoping to migrate to degrees eventually. More...
 
#define TEXT_ANGLE_VERT   900
 
#define USE_KICAD_WXSTRING_HASH
 
#define USE_KICAD_WXPOINT_LESS_AND_HASH
 Required to use wxPoint as key type in maps. More...
 

Typedefs

typedef uint32_t timestamp_t
 timestamp_t is our type to represent unique IDs for all kinds of elements; historically simply the timestamp when they were created. More...
 

Enumerations

enum  EDA_UNITS {
  EDA_UNITS::INCHES = 0, EDA_UNITS::MILLIMETRES = 1, EDA_UNITS::UNSCALED = 2, EDA_UNITS::DEGREES = 3,
  EDA_UNITS::PERCENT = 4
}
 

Functions

wxSize GetTextSize (const wxString &aSingleLine, wxWindow *aWindow)
 Return the size of aSingleLine of text when it is rendered in aWindow using whatever font is currently set in that window. More...
 
bool EnsureTextCtrlWidth (wxTextCtrl *aCtrl, const wxString *aString=NULL)
 Set the minimum pixel width on a text control in order to make a text string be fully visible within it. More...
 
void SelectReferenceNumber (wxTextEntry *aTextEntry)
 Select the number (or "?") in a reference for ease of editing. More...
 
int ProcessExecute (const wxString &aCommandLine, int aFlags=wxEXEC_ASYNC, wxProcess *callback=NULL)
 Run a command in a child process. More...
 
timestamp_t GetNewTimeStamp ()
 
int GetCommandOptions (const int argc, const char **argv, const char *stringtst, const char **optarg, int *optind)
 
void wxStringSplit (const wxString &aText, wxArrayString &aStrings, wxChar aSplitter)
 Split aString to a string list separated at aSplitter. More...
 
wxString SearchHelpFileFullPath (const SEARCH_STACK &aSearchStack, const wxString &aBaseName)
 Return the help file's full path. More...
 
bool EnsureFileDirectoryExists (wxFileName *aTargetFullFileName, const wxString &aBaseFilename, REPORTER *aReporter=NULL)
 Make aTargetFullFileName absolute and create the path of this file if it doesn't yet exist. More...
 
const wxString PrePendPath (const wxString &aEnvVar, const wxString &aPriorityPath)
 Put aPriorityPath in front of all paths in the value of aEnvVar. More...
 
std::unique_ptr< wxConfigBase > GetNewConfig (const wxString &aProgName)
 Create a new wxConfig so we can put configuration files in a more proper place for each platform. More...
 
wxString GetKicadConfigPath ()
 Return the user configuration path used to store KiCad's configuration files. More...
 
const wxString ExpandEnvVarSubstitutions (const wxString &aString)
 Replace any environment variable references with their values. More...
 
const wxString ResolveUriByEnvVars (const wxString &aUri)
 Replace any environment variables in file-path uris (leaving network-path URIs alone). More...
 
std::ostream & operator<< (std::ostream &out, const wxSize &size)
 Helper function to print the given wxSize to a stream. More...
 
std::ostream & operator<< (std::ostream &out, const wxPoint &pt)
 Helper function to print the given wxPoint to a stream. More...
 
long long TimestampDir (const wxString &aDirPath, const wxString &aFilespec)
 A copy of ConvertFileTimeToWx() because wxWidgets left it as a static function private to src/common/filename.cpp. More...
 

Detailed Description

The common library.

Definition in file common.h.

Macro Definition Documentation

◆ INCLUDE__COMMON_H_

#define INCLUDE__COMMON_H_

Definition at line 34 of file numeric_evaluator.cpp.

◆ NAMELESS_PROJECT [1/2]

#define NAMELESS_PROJECT   wxT( "noname" )

◆ NAMELESS_PROJECT [2/2]

#define NAMELESS_PROJECT   wxT( "noname" )

default name for nameless projects

Definition at line 65 of file common.h.

◆ TEXT_ANGLE_HORIZ [1/2]

#define TEXT_ANGLE_HORIZ   0

Frequent text rotations, used with {Set,Get}TextAngle(), in 0.1 degrees for now, hoping to migrate to degrees eventually.

Definition at line 69 of file common.h.

◆ TEXT_ANGLE_HORIZ [2/2]

#define TEXT_ANGLE_HORIZ   0

◆ TEXT_ANGLE_VERT [1/2]

#define TEXT_ANGLE_VERT   900

Definition at line 70 of file common.h.

◆ TEXT_ANGLE_VERT [2/2]

#define TEXT_ANGLE_VERT   900

◆ USE_KICAD_WXPOINT_LESS_AND_HASH [1/2]

#define USE_KICAD_WXPOINT_LESS_AND_HASH

Required to use wxPoint as key type in maps.

Definition at line 279 of file common.h.

◆ USE_KICAD_WXPOINT_LESS_AND_HASH [2/2]

#define USE_KICAD_WXPOINT_LESS_AND_HASH

◆ USE_KICAD_WXSTRING_HASH [1/2]

#define USE_KICAD_WXSTRING_HASH

Definition at line 267 of file common.h.

◆ USE_KICAD_WXSTRING_HASH [2/2]

#define USE_KICAD_WXSTRING_HASH

Typedef Documentation

◆ timestamp_t

typedef uint32_t timestamp_t

timestamp_t is our type to represent unique IDs for all kinds of elements; historically simply the timestamp when they were created.

Long term, this type might be renamed to something like unique_id_t (and then rename all the methods from {Get,Set}TimeStamp() to {Get,Set}Id()) ?

Definition at line 52 of file common.h.

Enumeration Type Documentation

◆ EDA_UNITS

enum EDA_UNITS
strong
Enumerator
INCHES 
MILLIMETRES 
UNSCALED 
DEGREES 
PERCENT 

Definition at line 72 of file common.h.

Function Documentation

◆ EnsureFileDirectoryExists()

bool EnsureFileDirectoryExists ( wxFileName *  aTargetFullFileName,
const wxString &  aBaseFilename,
REPORTER aReporter = NULL 
)

Make aTargetFullFileName absolute and create the path of this file if it doesn't yet exist.

Parameters
aTargetFullFileNamethe wxFileName containing the full path and file name to modify. The path may be absolute or relative to aBaseFilename .
aBaseFilenamea full filename. Only its path is used to set the aTargetFullFileName path.
aReportera point to a REPORTER object use to show messages (can be NULL)
Returns
true if aOutputDir already exists or was successfully created.

Definition at line 456 of file common.cpp.

459 {
460  wxString msg;
461  wxString baseFilePath = wxFileName( aBaseFilename ).GetPath();
462 
463  // make aTargetFullFileName path, which is relative to aBaseFilename path (if it is not
464  // already an absolute path) absolute:
465  if( !aTargetFullFileName->MakeAbsolute( baseFilePath ) )
466  {
467  if( aReporter )
468  {
469  msg.Printf( _( "Cannot make path \"%s\" absolute with respect to \"%s\"." ),
470  GetChars( aTargetFullFileName->GetPath() ),
471  GetChars( baseFilePath ) );
472  aReporter->Report( msg, REPORTER::RPT_ERROR );
473  }
474 
475  return false;
476  }
477 
478  // Ensure the path of aTargetFullFileName exists, and create it if needed:
479  wxString outputPath( aTargetFullFileName->GetPath() );
480 
481  if( !wxFileName::DirExists( outputPath ) )
482  {
483  if( wxMkdir( outputPath ) )
484  {
485  if( aReporter )
486  {
487  msg.Printf( _( "Output directory \"%s\" created.\n" ), GetChars( outputPath ) );
488  aReporter->Report( msg, REPORTER::RPT_INFO );
489  return true;
490  }
491  }
492  else
493  {
494  if( aReporter )
495  {
496  msg.Printf( _( "Cannot create output directory \"%s\".\n" ),
497  GetChars( outputPath ) );
498  aReporter->Report( msg, REPORTER::RPT_ERROR );
499  }
500 
501  return false;
502  }
503  }
504 
505  return true;
506 }
static const wxChar * GetChars(const wxString &s)
Function GetChars returns a wxChar* to the actual wxChar* data within a wxString, and is helpful for ...
Definition: macros.h:101
#define _(s)
Definition: 3d_actions.cpp:31
virtual REPORTER & Report(const wxString &aText, SEVERITY aSeverity=RPT_UNDEFINED)=0
Function Report is a pure virtual function to override in the derived object.

References _, GetChars(), REPORTER::Report(), REPORTER::RPT_ERROR, and REPORTER::RPT_INFO.

Referenced by DIALOG_GEN_FOOTPRINT_POSITION::CreateAsciiFiles(), DIALOG_GEN_FOOTPRINT_POSITION::CreateGerberFiles(), DIALOG_PLOT_SCHEMATIC::createPlotFileName(), DIALOG_EXPORT_SVG::ExportSVGFile(), DIALOG_GENDRILL::GenDrillAndMapFiles(), PLOT_CONTROLLER::OpenPlotfile(), and DIALOG_PLOT::Plot().

◆ EnsureTextCtrlWidth()

bool EnsureTextCtrlWidth ( wxTextCtrl *  aCtrl,
const wxString *  aString = NULL 
)

Set the minimum pixel width on a text control in order to make a text string be fully visible within it.

The current font within the text control is considered. The text can come either from the control or be given as an argument. If the text control is larger than needed, then nothing is done.

Parameters
aCtrlthe text control to potentially make wider.
aStringthe text that is used in sizing the control's pixel width. If NULL, then the text already within the control is used.
Returns
bool - true if the aCtrl had its size changed, else false.

Definition at line 128 of file common.cpp.

129 {
130  wxWindow* window = aCtrl->GetParent();
131 
132  if( !window )
133  window = aCtrl;
134 
135  wxString ctrlText;
136 
137  if( !aString )
138  {
139  ctrlText = aCtrl->GetValue();
140  aString = &ctrlText;
141  }
142 
143  wxSize textz = GetTextSize( *aString, window );
144  wxSize ctrlz = aCtrl->GetSize();
145 
146  if( ctrlz.GetWidth() < textz.GetWidth() + 10 )
147  {
148  ctrlz.SetWidth( textz.GetWidth() + 10 );
149  aCtrl->SetSizeHints( ctrlz );
150  return true;
151  }
152 
153  return false;
154 }
wxSize GetTextSize(const wxString &aSingleLine, wxWindow *aWindow)
Return the size of aSingleLine of text when it is rendered in aWindow using whatever font is currentl...
Definition: common.cpp:113

References GetTextSize().

Referenced by GERBVIEW_FRAME::UpdateTitleAndInfo().

◆ ExpandEnvVarSubstitutions()

const wxString ExpandEnvVarSubstitutions ( const wxString &  aString)

Replace any environment variable references with their values.

Parameters
aString= a string containing (perhaps) references to env var
Returns
a string where env var are replaced by their value

Definition at line 429 of file common.cpp.

430 {
431  // wxGetenv( wchar_t* ) is not re-entrant on linux.
432  // Put a lock on multithreaded use of wxGetenv( wchar_t* ), called from wxEpandEnvVars(),
433  static std::mutex getenv_mutex;
434 
435  std::lock_guard<std::mutex> lock( getenv_mutex );
436 
437  // We reserve the right to do this another way, by providing our own member function.
438  return KIwxExpandEnvVars( aString );
439 }
wxString KIwxExpandEnvVars(const wxString &str)
Definition: common.cpp:300

References KIwxExpandEnvVars().

Referenced by FILENAME_RESOLVER::addPath(), FILENAME_RESOLVER::checkEnvVarPath(), S3D_PLUGIN_MANAGER::checkPluginName(), S3D_PLUGIN_MANAGER::checkPluginPath(), FILENAME_RESOLVER::createPathList(), LIB_TABLE::ExpandSubstitutions(), S3D_CACHE::Get3DConfigDir(), WS_DATA_MODEL::MakeFullFileName(), TEXT_BUTTON_FILE_BROWSER::OnButtonClick(), FILENAME_RESOLVER::ResolvePath(), ResolveUriByEnvVars(), FILENAME_RESOLVER::Set3DConfigDir(), S3D_CACHE::Set3DConfigDir(), FILENAME_RESOLVER::SetProjectDir(), and FILENAME_RESOLVER::ShortenPath().

◆ GetCommandOptions()

int GetCommandOptions ( const int  argc,
const char **  argv,
const char *  stringtst,
const char **  optarg,
int *  optind 
)

◆ GetKicadConfigPath()

wxString GetKicadConfigPath ( )

Return the user configuration path used to store KiCad's configuration files.

The configuration path order of precedence is determined by the following criteria:

  • The value of the KICAD_CONFIG_HOME environment variable
  • The value of the XDG_CONFIG_HOME environment variable.
  • The result of the call to wxStandardPaths::GetUserConfigDir() with ".config" appended as required on Linux builds.
Returns
A wxString containing the config path for Kicad

Definition at line 242 of file common.cpp.

243 {
244  wxFileName cfgpath;
245 
246  // http://docs.wxwidgets.org/3.0/classwx_standard_paths.html#a7c7cf595d94d29147360d031647476b0
247  cfgpath.AssignDir( wxStandardPaths::Get().GetUserConfigDir() );
248 
249  // GetUserConfigDir() does not default to ~/.config which is the current standard
250  // configuration file location on Linux. This has been fixed in later versions of wxWidgets.
251 #if !defined( __WXMSW__ ) && !defined( __WXMAC__ )
252  wxArrayString dirs = cfgpath.GetDirs();
253 
254  if( dirs.Last() != ".config" )
255  cfgpath.AppendDir( ".config" );
256 #endif
257 
258  wxString envstr;
259 
260  // This shouldn't cause any issues on Windows or MacOS.
261  if( wxGetEnv( wxT( "XDG_CONFIG_HOME" ), &envstr ) && !envstr.IsEmpty() )
262  {
263  // Override the assignment above with XDG_CONFIG_HOME
264  cfgpath.AssignDir( envstr );
265  }
266 
267  cfgpath.AppendDir( TO_STR( KICAD_CONFIG_DIR ) );
268 
269  // Use KICAD_CONFIG_HOME to allow the user to force a specific configuration path.
270  if( wxGetEnv( wxT( "KICAD_CONFIG_HOME" ), &envstr ) && !envstr.IsEmpty() )
271  {
272  // Override the assignment above with KICAD_CONFIG_HOME
273  cfgpath.AssignDir( envstr );
274  }
275 
276  if( !cfgpath.DirExists() )
277  {
278  cfgpath.Mkdir( wxS_DIR_DEFAULT, wxPATH_MKDIR_FULL );
279  }
280 
281  return cfgpath.GetPath();
282 }
#define TO_STR(x)
Definition: macros.h:56

References TO_STR.

Referenced by getAdvancedCfgFilename(), SYMBOL_LIB_TABLE::GetGlobalTableFileName(), FP_LIB_TABLE::GetGlobalTableFileName(), GetNewConfig(), ReadHotKeyConfig(), ReadLegacyHotkeyConfigFile(), and WriteHotKeyConfig().

◆ GetNewConfig()

std::unique_ptr<wxConfigBase> GetNewConfig ( const wxString &  aProgName)

Create a new wxConfig so we can put configuration files in a more proper place for each platform.

This is generally $HOME/.config/kicad/ in Linux according to the FreeDesktop specification at http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html The config object created here should be destroyed by the caller.

Parameters
aProgNameis the name of the program calling this function - can be obtained by calling Pgm().App().GetAppName(). This will be the actual file name of the config file.
Returns
A pointer to a new wxConfigBase derived object is returned. The caller is in charge of deleting it.

Definition at line 231 of file common.cpp.

232 {
233  wxFileName configname;
234  configname.AssignDir( GetKicadConfigPath() );
235  configname.SetFullName( aProgName );
236 
237  // explicitly use wxFileConfig to prevent storing any settings in the system registry on Windows
238  return std::make_unique<wxFileConfig>( wxT( "" ), wxT( "" ), configname.GetFullPath() );
239 }
wxString GetKicadConfigPath()
Return the user configuration path used to store KiCad's configuration files.
Definition: common.cpp:242

References GetKicadConfigPath().

Referenced by BM2CMP_FRAME::BM2CMP_FRAME(), BIN_MOD::Init(), PGM_BASE::InitPgm(), PGM_BASE::loadCommonSettings(), EDA_BASE_FRAME::LoadSettings(), PCB_CALCULATOR_FRAME::PCB_CALCULATOR_FRAME(), SYMBOL_PREVIEW_WIDGET::SYMBOL_PREVIEW_WIDGET(), and PANEL_COMMON_SETTINGS::TransferDataToWindow().

◆ GetNewTimeStamp()

timestamp_t GetNewTimeStamp ( )
Returns
an unique time stamp that changes after each call

Definition at line 215 of file common.cpp.

216 {
217  static timestamp_t oldTimeStamp;
218  timestamp_t newTimeStamp;
219 
220  newTimeStamp = time( NULL );
221 
222  if( newTimeStamp <= oldTimeStamp )
223  newTimeStamp = oldTimeStamp + 1;
224 
225  oldTimeStamp = newTimeStamp;
226 
227  return newTimeStamp;
228 }
#define NULL
uint32_t timestamp_t
timestamp_t is our type to represent unique IDs for all kinds of elements; historically simply the ti...
Definition: common.h:52

References NULL.

Referenced by FOOTPRINT_VIEWER_FRAME::AddFootprintToPCB(), PCB_BASE_FRAME::AddModuleToBoard(), BOARD_NETLIST_UPDATER::addNewComponent(), Diagnose(), SCH_DRAWING_TOOLS::DrawSheet(), SCH_EDIT_TOOL::Duplicate(), DIALOG_FOOTPRINT_BOARD_EDITOR::EditFootprint(), EDIT_TOOL::EditFpInFpEditor(), CONNECTION_GRAPH::ercCheckBusToBusConflicts(), CONNECTION_GRAPH::ercCheckBusToBusEntryConflicts(), CONNECTION_GRAPH::ercCheckBusToNetConflicts(), CONNECTION_GRAPH::ercCheckLabels(), CONNECTION_GRAPH::ercCheckNoConnects(), BOARD::InsertArea(), COLLECTOR::IsSimilarPointAndTime(), SCH_EAGLE_PLUGIN::loadSchematic(), SCH_LEGACY_PLUGIN::loadSheet(), SCH_EDIT_FRAME::LoadSheetFromFile(), EDA_ITEM::operator=(), SCH_EDITOR_CONTROL::Paste(), SCH_DRAWING_TOOLS::PlaceComponent(), PCB_EDITOR_CONTROL::PlaceModule(), SCH_EDIT_TOOL::RepeatDrawItem(), SCH_SCREENS::ReplaceDuplicateTimeStamps(), CONNECTION_SUBGRAPH::ResolveDrivers(), FOOTPRINT_EDIT_FRAME::SaveFootprintToBoard(), SCH_COMPONENT::SCH_COMPONENT(), SCH_SHEET::SCH_SHEET(), COLLECTOR::SetTimeNow(), SimilarLabelsDiagnose(), TestDuplicateSheetNames(), DIALOG_ERC::TestErc(), and TestMultiunitFootprints().

◆ GetTextSize()

wxSize GetTextSize ( const wxString &  aSingleLine,
wxWindow *  aWindow 
)

Return the size of aSingleLine of text when it is rendered in aWindow using whatever font is currently set in that window.

Definition at line 113 of file common.cpp.

114 {
115  wxCoord width;
116  wxCoord height;
117 
118  {
119  wxClientDC dc( aWindow );
120  dc.SetFont( aWindow->GetFont() );
121  dc.GetTextExtent( aSingleLine, &width, &height );
122  }
123 
124  return wxSize( width, height );
125 }

Referenced by DIALOG_EDIT_COMPONENTS_LIBID::AdjustGridColumns(), LIB_TREE_MODEL_ADAPTER::AttachTo(), DIALOG_FIELDS_EDITOR_GLOBAL::DIALOG_FIELDS_EDITOR_GLOBAL(), EDA_DRAW_FRAME::EDA_DRAW_FRAME(), EnsureTextCtrlWidth(), FIELDS_EDITOR_GRID_DATA_MODEL::GetDataWidth(), DIALOG_FP_CONFLICT_ASSIGNMENT_SELECTOR::recalculateColumns(), ZONE_SETTINGS::SetupLayersList(), and NET_SELECTOR_COMBOPOPUP::updateSize().

◆ operator<<() [1/2]

std::ostream& operator<< ( std::ostream &  out,
const wxSize &  size 
)

Helper function to print the given wxSize to a stream.

Used for debugging functions like EDA_ITEM::Show and also in unit testing fixtures.

Definition at line 586 of file common.cpp.

587 {
588  out << " width=\"" << size.GetWidth() << "\" height=\"" << size.GetHeight() << "\"";
589  return out;
590 }

◆ operator<<() [2/2]

std::ostream& operator<< ( std::ostream &  out,
const wxPoint pt 
)

Helper function to print the given wxPoint to a stream.

Used for debugging functions like EDA_ITEM::Show and also in unit testing fixtures.

Definition at line 593 of file common.cpp.

594 {
595  out << " x=\"" << pt.x << "\" y=\"" << pt.y << "\"";
596  return out;
597 }

References wxPoint::x, and wxPoint::y.

◆ PrePendPath()

const wxString PrePendPath ( const wxString &  aEnvVar,
const wxString &  aPriorityPath 
)

Put aPriorityPath in front of all paths in the value of aEnvVar.

Definition at line 32 of file prependpath.cpp.

33 {
34  wxPathList paths;
35 
36  paths.AddEnvList( aEnvVar );
37  paths.Insert( aPriorityPath, 0 );
38 
39  return wxJoin( paths, wxPATH_SEP[0] );
40 }

◆ ProcessExecute()

int ProcessExecute ( const wxString &  aCommandLine,
int  aFlags = wxEXEC_ASYNC,
wxProcess *  callback = NULL 
)

Run a command in a child process.

Parameters
aCommandLineThe process and any arguments to it all in a single string.
aFlagsThe same args as allowed for wxExecute()
callbackwxProcess implementing OnTerminate to be run when the child process finishes
Returns
int - pid of process, 0 in case of error (like return values of wxExecute())

Definition at line 209 of file common.cpp.

210 {
211  return wxExecute( aCommandLine, aFlags, callback );
212 }

Referenced by doPrintFile(), ExecuteFile(), GetAssociatedDocument(), OpenFile(), OpenPDF(), and SCH_EDIT_FRAME::WriteNetListFile().

◆ ResolveUriByEnvVars()

const wxString ResolveUriByEnvVars ( const wxString &  aUri)

Replace any environment variables in file-path uris (leaving network-path URIs alone).

Definition at line 442 of file common.cpp.

443 {
444  // URL-like URI: return as is.
445  wxURL url( aUri );
446 
447  if( url.GetError() == wxURL_NOERR )
448  return aUri;
449 
450  // Otherwise, the path points to a local file. Resolve environment
451  // variables if any.
452  return ExpandEnvVarSubstitutions( aUri );
453 }
const wxString ExpandEnvVarSubstitutions(const wxString &aString)
Replace any environment variable references with their values.
Definition: common.cpp:429

References ExpandEnvVarSubstitutions().

Referenced by GetAssociatedDocument().

◆ SearchHelpFileFullPath()

wxString SearchHelpFileFullPath ( const SEARCH_STACK aSearchStack,
const wxString &  aBaseName 
)

Return the help file's full path.

Return the KiCad help file with path and extension. Help files can be html (.html ext) or pdf (.pdf ext) files. A <BaseName>.html file is searched and if not found, <BaseName>.pdf file is searched in the same path. If the help file for the current locale is not found, an attempt to find the English version of the help file is made. Help file is searched in directories in this order: help/<canonical name> like help/en_GB help/<short name> like help/en help/en

Parameters
aSearchStackcontains some possible base dirs that may be above the the one actually holding aBaseName. These are starting points for nested searches.
aBaseNameis the name of the help file to search for,

without extension

.

Returns
wxEmptyString is returned if aBaseName is not found, else the full path & filename.

Definition at line 67 of file searchhelpfilefullpath.cpp.

68 {
69  wxArrayString subdirs;
70  wxArrayString altsubdirs;
71  SEARCH_STACK ss = aSStack;
72 
73  // It might already be in aSStack, but why depend on other code
74  // far away when it's so easy to add it again (to our copy) as the first place to look.
75 
76  // This is CMAKE_INSTALL_PREFIX unless DEFAULT_INSTALL_PATH was defined during
77  // build configuration:
78  ss.AddPaths( wxT( DEFAULT_INSTALL_PATH ), 0 );
79 
80 #if defined(__WXMAC__)
81  ss.AddPaths( GetOSXKicadMachineDataDir() );
82  ss.AddPaths( Pgm().GetExecutablePath(), 0 );
83 
84  // OS X packages can have the help files in
85  // /Library/Application\ Support/kicad/help,
86  // and in Contents/SharedSupport/help inside the
87  // bundle.
88  // Below we account for an international subdirectory.
89  subdirs.Add( "help" );
90  altsubdirs.Add( "Contents" );
91  altsubdirs.Add( "SharedSupport" );
92  altsubdirs.Add( "help" );
93 #endif
94 
95 #if ! defined(__WXMAC__) // && defined(__linux__)
96  // This is the executable path minus the trailing bin directory used on Windows and Linux.
97  wxFileName tmp( Pgm().GetExecutablePath(), wxEmptyString );
98  wxArrayString binDirs = tmp.GetDirs();
99 
100  if( !binDirs.IsEmpty() && binDirs[ binDirs.GetCount() - 1 ].CmpNoCase( wxT( "bin" ) ) == 0 )
101  tmp.RemoveLastDir();
102 
103  ss.AddPaths( tmp.GetPath(), 0 );
104 
105  // Based on kicad-doc.bzr/CMakeLists.txt, line 20, the help files are
106  // installed into "<CMAKE_INSTALL_PREFIX>/share/doc/kicad/help" for linux.
107  // This is ${KICAD_HELP} var in that CMakeLists.txt file.
108  // Below we account for an international subdirectory.
109  subdirs.Add( "share" );
110  subdirs.Add( "doc" );
111  subdirs.Add( "kicad" );
112  subdirs.Add( "help" );
113 
114  // Based on kicad-doc.bzr/CMakeLists.txt, line 35, the help files are
115  // installed into "<CMAKE_INSTALL_PREFIX>/doc/help" for Windows.
116  // This is ${KICAD_HELP} var in that CMakeLists.txt file.
117  // Below we account for an international subdirectory.
118  altsubdirs.Add( "doc" );
119  altsubdirs.Add( "help" );
120 #endif
121 
122  // If there's a KICAD environment variable set, always use that guy's path first.
123  if( !Pgm().GetKicadEnvVariable().IsEmpty() )
124  ss.AddPaths( Pgm().GetKicadEnvVariable(), 0 );
125 
126  /* Search for a help file.
127  * we *must* find a help file.
128  * so help is searched in directories in this order:
129  * help/<canonical name> like help/en_GB
130  * help/<short name> like help/en
131  * help/en
132  */
133 
134  wxLocale* i18n = Pgm().GetLocale();
135 
136  // We try to find help file in help/<canonical name>
137  // If fails, try to find help file in help/<short canonical name>
138  // If fails, try to find help file in help/en
139  wxArrayString locale_name_dirs;
140  locale_name_dirs.Add( i18n->GetCanonicalName() ); // canonical name like fr_FR
141 
142  // wxLocale::GetName() does not return always the short name
143  locale_name_dirs.Add( i18n->GetName().BeforeLast( '_' ) ); // short canonical name like fr
144  locale_name_dirs.Add( "en" ); // default (en)
145 
146 #if defined(DEBUG) && 1
147  ss.Show( wxString( __func__ ) );
148  wxLogTrace( tracePathsAndFiles, "%s: m_help_file:'%s'", __func__, aBaseName );
149 #endif
150 
151  wxLogTrace( tracePathsAndFiles, "Checking SEARCH_STACK for file %s", aBaseName );
152 
153  // Help files can be html (.html ext) or pdf (.pdf ext) files.
154  // Therefore, <BaseName>.html file is searched and if not found,
155  // <BaseName>.pdf file is searched in the same paths
156  wxString fn;
157 
158  for( unsigned ii = 0; ii < locale_name_dirs.GetCount(); ii++ )
159  {
160  subdirs.Add( locale_name_dirs[ii] );
161  altsubdirs.Add( locale_name_dirs[ii] );
162 
163  fn = FindFileInSearchPaths( ss, aBaseName + wxT( ".html" ), &altsubdirs );
164 
165  if( !fn.IsEmpty() )
166  {
167  // Prepend URI protocol since we will open in a browser
168  fn = wxT( "file://" ) + fn;
169  break;
170  }
171 
172  fn = FindFileInSearchPaths( ss, aBaseName + wxT( ".pdf" ), &altsubdirs );
173 
174  if( !fn.IsEmpty() )
175  break;
176 
177  fn = FindFileInSearchPaths( ss, aBaseName + wxT( ".html" ), &subdirs );
178 
179  if( !fn.IsEmpty() )
180  {
181  // Prepend URI protocol since we will open in a browser
182  fn = wxT( "file://" ) + fn;
183  break;
184  }
185 
186  fn = FindFileInSearchPaths( ss, aBaseName + wxT( ".pdf" ), &subdirs );
187 
188  if( !fn.IsEmpty() )
189  break;
190 
191  subdirs.RemoveAt( subdirs.GetCount() - 1 );
192  altsubdirs.RemoveAt( altsubdirs.GetCount() - 1 );
193  }
194 
195  return fn;
196 }
KIWAY Kiway & Pgm(), KFCTL_STANDALONE
The global Program "get" accessor.
Definition: single_top.cpp:98
const wxChar *const tracePathsAndFiles
Flag to enable path and file name debug output.
SEARCH_STACK looks for files in a number of places.
Definition: search_stack.h:41
wxString FindFileInSearchPaths(const SEARCH_STACK &aStack, const wxString &aFilename, const wxArrayString *aSubdirs)
Function FindFileInSearchPaths looks in "this" for aFilename, but first modifies every search path by...
void AddPaths(const wxString &aPaths, int aIndex=-1)
Function AddPaths insert or append path(s)

References SEARCH_STACK::AddPaths(), FindFileInSearchPaths(), Pgm(), and tracePathsAndFiles.

◆ SelectReferenceNumber()

void SelectReferenceNumber ( wxTextEntry *  aTextEntry)

Select the number (or "?") in a reference for ease of editing.

Definition at line 157 of file common.cpp.

158 {
159  wxString ref = aTextEntry->GetValue();
160 
161  if( ref.find_first_of( '?' ) != ref.npos )
162  {
163  aTextEntry->SetSelection( ref.find_first_of( '?' ), ref.find_last_of( '?' ) + 1 );
164  }
165  else
166  {
167  wxString num = ref;
168 
169  while( !num.IsEmpty() && ( !isdigit( num.Last() ) || !isdigit( num.GetChar( 0 ) ) ) )
170  {
171  if( !isdigit( num.Last() ) )
172  num.RemoveLast();
173 
174  if( !isdigit( num.GetChar ( 0 ) ) )
175  num = num.Right( num.Length() - 1);
176  }
177 
178  aTextEntry->SetSelection( ref.Find( num ), ref.Find( num ) + num.Length() );
179 
180  if( num.IsEmpty() )
181  aTextEntry->SetSelection( -1, -1 );
182  }
183 }

Referenced by DIALOG_EDIT_ONE_FIELD::OnSetFocusText(), DIALOG_FOOTPRINT_BOARD_EDITOR::OnUpdateUI(), and DIALOG_TEXT_PROPERTIES::TransferDataToWindow().

◆ TimestampDir()

long long TimestampDir ( const wxString &  aDirPath,
const wxString &  aFilespec 
)

A copy of ConvertFileTimeToWx() because wxWidgets left it as a static function private to src/common/filename.cpp.

TimestampDir

This routine offers SIGNIFICANT performance benefits over using wxWidgets to gather timestamps from matching files in a directory.

Parameters
aDirPaththe directory to search
aFilespeca (wildcarded) file spec to match against
Returns
a hash of the last-mod-dates of all matching files in the directory

Definition at line 821 of file common.cpp.

822 {
823  long long timestamp = 0;
824 
825 #if defined( __WIN32__ )
826  // Win32 version.
827  // Save time by not searching for each path twice: once in wxDir.GetNext() and once in
828  // wxFileName.GetModificationTime(). Also cuts out wxWidgets' string-matching and case
829  // conversion by staying on the MSW side of things.
830  std::wstring filespec( aDirPath.t_str() );
831  filespec += '\\';
832  filespec += aFilespec.t_str();
833 
834  WIN32_FIND_DATA findData;
835  wxDateTime lastModDate;
836 
837  HANDLE fileHandle = ::FindFirstFile( filespec.data(), &findData );
838 
839  if( fileHandle != INVALID_HANDLE_VALUE )
840  {
841  do
842  {
843  ConvertFileTimeToWx( &lastModDate, findData.ftLastWriteTime );
844  timestamp += lastModDate.GetValue().GetValue();
845  }
846  while ( FindNextFile( fileHandle, &findData ) != 0 );
847  }
848 
849  FindClose( fileHandle );
850 #else
851  // POSIX version.
852  // Save time by not converting between encodings -- do everything on the file-system side.
853  std::string filespec( aFilespec.fn_str() );
854  std::string dir_path( aDirPath.fn_str() );
855 
856  DIR* dir = opendir( dir_path.c_str() );
857 
858  if( dir )
859  {
860  for( dirent* dir_entry = readdir( dir ); dir_entry; dir_entry = readdir( dir ) )
861  {
862  if( !matchWild( filespec.c_str(), dir_entry->d_name, true ) )
863  continue;
864 
865  std::string entry_path = dir_path + '/' + dir_entry->d_name;
866  struct stat entry_stat;
867 
868  if( wxCRT_Lstat( entry_path.c_str(), &entry_stat ) == 0 )
869  {
870  // Timestamp the source file, not the symlink
871  if( S_ISLNK( entry_stat.st_mode ) ) // wxFILE_EXISTS_SYMLINK
872  {
873  char buffer[ PATH_MAX + 1 ];
874  ssize_t pathLen = readlink( entry_path.c_str(), buffer, PATH_MAX );
875 
876  if( pathLen > 0 )
877  {
878  struct stat linked_stat;
879  buffer[ pathLen ] = '\0';
880  entry_path = dir_path + buffer;
881 
882  if( wxCRT_Lstat( entry_path.c_str(), &linked_stat ) == 0 )
883  {
884  entry_stat = linked_stat;
885  }
886  else
887  {
888  // if we couldn't lstat the linked file we'll have to just use
889  // the symbolic link info
890  }
891  }
892  }
893 
894  if( S_ISREG( entry_stat.st_mode ) ) // wxFileExists()
895  timestamp += entry_stat.st_mtime * 1000;
896  }
897  else
898  {
899  // if we couldn't lstat the file itself all we can do is use the name
900  timestamp += (signed) std::hash<std::string>{}( std::string( dir_entry->d_name ) );
901  }
902  }
903 
904  closedir( dir );
905  }
906 #endif
907 
908  return timestamp;
909 }
bool matchWild(const char *pat, const char *text, bool dot_special)
A copy of wxMatchWild(), which wxWidgets attributes to Douglas A.
Definition: common.cpp:679

References matchWild().

Referenced by FP_CACHE::GetTimestamp(), and GPCB_FPL_CACHE::GetTimestamp().

◆ wxStringSplit()

void wxStringSplit ( const wxString &  aText,
wxArrayString &  aStrings,
wxChar  aSplitter 
)

Split aString to a string list separated at aSplitter.

Parameters
aTextis the text to split
aStringswill contain the splitted lines
aSplitteris the 'split' character

Definition at line 186 of file common.cpp.

187 {
188  wxString tmp;
189 
190  for( unsigned ii = 0; ii < aText.Length(); ii++ )
191  {
192  if( aText[ii] == aSplitter )
193  {
194  aStrings.Add( tmp );
195  tmp.Clear();
196  }
197 
198  else
199  tmp << aText[ii];
200  }
201 
202  if( !tmp.IsEmpty() )
203  {
204  aStrings.Add( tmp );
205  }
206 }

Referenced by CINFO3D_VISU::AddShapeWithClearanceToContainer(), export_vrml_pcbtext(), EDA_TEXT::GetTextBox(), HTML_MESSAGE_BOX::ListSet(), DIALOG_FOOTPRINT_WIZARD_LIST::onShowTrace(), SCH_TEXT::Plot(), BRDITEMS_PLOTTER::PlotTextePcb(), EDA_TEXT::Print(), TEXTE_PCB::TransformShapeWithClearanceToPolygonSet(), and EDA_TEXT::TransformTextShapeToSegmentList().