The common library. More...

#include <kicommon.h>
#include <functional>
#include <memory>
#include <wx/fileconf.h>
#include <wx/string.h>
#include <wx/process.h>

Macros
#define	FOR_ERC_DRC 1
	Expand '${var-name}' templates in text.

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

KICOMMON_API bool	EnsureFileDirectoryExists (wxFileName aTargetFullFileName, const wxString &aBaseFilename, REPORTER aReporter=nullptr)
	Make aTargetFullFileName absolute and create the path of this file if it doesn't yet exist.

KICOMMON_API wxString	EnsureFileExtension (const wxString &aFilename, const wxString &aExtension)
	It's annoying to throw up nag dialogs when the extension isn't right.

KICOMMON_API const wxString	ExpandEnvVarSubstitutions (const wxString &aString, const PROJECT *aProject)
	Replace any environment variable & text variable references with their values.

KICOMMON_API wxString	ExpandTextVars (const wxString &aSource, const std::function< bool(wxString )> aResolver, int aFlags=0)

KICOMMON_API wxString	ExpandTextVars (const wxString &aSource, const PROJECT *aProject, int aFlags=0)

KICOMMON_API wxString	GetGeneratedFieldDisplayName (const wxString &aSource)
	Returns any variables unexpanded, e.g.

KICOMMON_API bool	IsGeneratedField (const wxString &aSource)
	Returns true if the string is generated, e.g contains a single text var reference.

KICOMMON_API wxString	DescribeRef (const wxString &aRef)
	Returns a user-visible HTML string describing a footprint reference designator.

KICOMMON_API const wxString	ResolveUriByEnvVars (const wxString &aUri, const PROJECT *aProject)
	Replace any environment and/or text variables in URIs.

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

KICOMMON_API bool	WarnUserIfOperatingSystemUnsupported ()
	Checks if the operating system is explicitly unsupported and displays a disclaimer message box.

Detailed Description

The common library.

Definition in file common.h.

Macro Definition Documentation

◆ FOR_ERC_DRC

#define FOR_ERC_DRC 1

Expand '${var-name}' templates in text.

Definition at line 91 of file common.h.

Referenced by ExpandTextVars(), ERC_TESTER::TestTextVars(), and DRC_TEST_PROVIDER_MISC::testTextVars().

Function Documentation

◆ DescribeRef()

KICOMMON_API wxString DescribeRef ( const wxString & aRef )

Returns a user-visible HTML string describing a footprint reference designator.

Definition at line 144 of file common.cpp.

References _, and EscapeHTML().

Referenced by BACK_ANNOTATE::applyChangelist(), BACK_ANNOTATE::applyPinSwaps(), BACK_ANNOTATE::checkForUnusedSymbols(), BACK_ANNOTATE::getChangeList(), BACK_ANNOTATE::getPcbModulesFromString(), DRC_ENGINE::loadImplicitRules(), and BACK_ANNOTATE::processNetNameChange().

◆ EnsureFileDirectoryExists()

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

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

Parameters

aTargetFullFileName	the wxFileName containing the full path and file name to modify. The path may be absolute or relative to aBaseFilename .
aBaseFilename	a full filename. Only its path is used to set the aTargetFullFileName path.
aReporter	a 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 386 of file common.cpp.

References _, REPORTER::Report(), RPT_SEVERITY_ERROR, and RPT_SEVERITY_INFO.

Referenced by DIALOG_GEN_FOOTPRINT_POSITION::CreateAsciiFiles(), DIALOG_GEN_FOOTPRINT_POSITION::CreateGerberFiles(), SCH_PLOTTER::createPlotFileName(), DIALOG_GENDRILL::genDrillAndMapFiles(), DIALOG_SYMBOL_FIELDS_TABLE::OnExport(), PLOT_CONTROLLER::OpenPlotfile(), and DIALOG_PLOT::Plot().

◆ EnsureFileExtension()

KICOMMON_API wxString EnsureFileExtension	(	const wxString &	aFilename,
		const wxString &	aExtension )

It's annoying to throw up nag dialogs when the extension isn't right.

Just fix it.

Definition at line 439 of file common.cpp.

Referenced by AskSaveBoardFileName(), PCB_BASE_EDIT_FRAME::createNewLibrary(), BITMAP2CMP_FRAME::ExportEeschemaFormat(), FOOTPRINT_EDIT_FRAME::ExportFootprint(), BITMAP2CMP_FRAME::ExportPcbnewFormat(), GERBVIEW_CONTROL::ExportToPcbnew(), JOBS_OUTPUT_ARCHIVE::HandleOutputs(), SCH_EDIT_FRAME::NewProject(), PNS_LOG_VIEWER_FRAME::onSaveAs(), DIALOG_SHEET_PROPERTIES::onSheetFilenameChanged(), PCB_EDIT_FRAME::SaveBoard(), SCH_EDITOR_CONTROL::SaveCurrSheetCopyAs(), SCH_EDIT_FRAME::SaveProject(), FIELDS_GRID_TABLE::SetValue(), DIALOG_FIELD_PROPERTIES::TransferDataFromWindow(), and DIALOG_SHEET_PROPERTIES::TransferDataFromWindow().

◆ ExpandEnvVarSubstitutions()

KICOMMON_API const wxString ExpandEnvVarSubstitutions	(	const wxString &	aString,
		const PROJECT *	aProject )

Replace any environment variable & text variable references with their values.

Parameters

aString a string containing (perhaps) references to env var

Returns: the expanded environment variable.

Definition at line 365 of file common.cpp.

References KIwxExpandEnvVars().

Referenced by FILENAME_RESOLVER::addPath(), FILENAME_RESOLVER::checkEnvVarPath(), S3D_PLUGIN_MANAGER::checkPluginName(), DIALOG_GEN_FOOTPRINT_POSITION::CreateAsciiFiles(), DIALOG_GEN_FOOTPRINT_POSITION::CreateGerberFiles(), FILENAME_RESOLVER::createPathList(), LIBRARY_MANAGER::ExpandURI(), DIALOG_GENDRILL::genDrillAndMapFiles(), LIB_TABLE_ROW::GetFullURI(), LIBRARY_MANAGER::GetFullURI(), DIALOG_PLOT_SCHEMATIC::getOutputPath(), JOBS_OUTPUT_ARCHIVE::HandleOutputs(), JOBS_OUTPUT_FOLDER::HandleOutputs(), DIALOG_EXPORT_2581::onBrowseClicked(), DIALOG_EXPORT_ODBPP::onBrowseClicked(), DIALOG_EXPORT_STEP::onBrowseClicked(), DIALOG_GENCAD_EXPORT_OPTIONS::onBrowseClicked(), TEXT_BUTTON_FILE_BROWSER::OnButtonClick(), PANEL_SYM_LIB_TABLE::onConvertLegacyLibraries(), DIALOG_SYMBOL_FIELDS_TABLE::OnExport(), DIALOG_EXPORT_STEP::onExportButton(), DIALOG_GENDRILL::onGenReportFile(), PANEL_DESIGN_BLOCK_LIB_TABLE::onMigrateLibraries(), PANEL_FP_LIB_TABLE::onMigrateLibraries(), DIALOG_PLOT::onOpenOutputDirectory(), DIALOG_GEN_FOOTPRINT_POSITION::onOutputDirectoryBrowseClicked(), DIALOG_GENDRILL::onOutputDirectoryBrowseClicked(), DIALOG_PLOT::onOutputDirectoryBrowseClicked(), DIALOG_PLOT_SCHEMATIC::onOutputDirectoryBrowseClicked(), DIALOG_SYMBOL_FIELDS_TABLE::OnOutputFileBrowseClicked(), DIALOG_PAGES_SETTINGS::OnWksFileSelection(), PLOT_CONTROLLER::OpenPlotfile(), DIALOG_PLOT::Plot(), FILENAME_RESOLVER::ResolvePath(), ResolveUriByEnvVars(), JOBS_RUNNER::runSpecialCopyFiles(), JOBS_RUNNER::runSpecialExecute(), FILENAME_RESOLVER::Set3DConfigDir(), S3D_CACHE::Set3DConfigDir(), FILENAME_RESOLVER::SetProject(), FILENAME_RESOLVER::ShortenPath(), ERC_TESTER::TestTextVars(), DRC_TEST_PROVIDER_MISC::testTextVars(), and NETLIST_EXPORTER_SPICE::writeInclude().

◆ ExpandTextVars() [1/2]

KICOMMON_API wxString ExpandTextVars	(	const wxString &	aSource,
		const PROJECT *	aProject,
		int	aFlags = 0 )

Definition at line 60 of file common.cpp.

References ExpandTextVars(), and PROJECT::TextVarResolver().

Referenced by AddGerberX2Header(), GERBER_JOBFILE_WRITER::addJSONGeneralSpecs(), DS_DRAW_ITEM_LIST::BuildFullText(), DIALOG_GEN_FOOTPRINT_POSITION::CreateAsciiFiles(), EXPRESSION_EVALUATOR::createCombinedCallback(), DIALOG_GEN_FOOTPRINT_POSITION::CreateGerberFiles(), GENCAD_EXPORTER::createHeaderInfoData(), SCH_PLOTTER::createPDFFile(), KIGFX::SCH_PAINTER::expandLibItemTextVars(), ExpandTextVars(), DIALOG_GENDRILL::genDrillAndMapFiles(), FIELDS_EDITOR_GRID_DATA_MODEL::getFieldShownText(), JOB::GetFullOutputPath(), GetGeneratedFieldDisplayName(), DIALOG_PLOT_SCHEMATIC::getOutputPath(), LIB_SYMBOL::GetShownKeyWords(), PCB_TEXT::GetShownText(), PCB_TEXTBOX::GetShownText(), SCH_FIELD::GetShownText(), SCH_LABEL_BASE::GetShownText(), SCH_TEXT::GetShownText(), SCH_TEXTBOX::GetShownText(), FIELDS_EDITOR_GRID_DATA_MODEL::GetValue(), API_HANDLER_COMMON::handleExpandTextVariables(), API_HANDLER_PCB::handleExpandTextVariables(), JOBS_OUTPUT_ARCHIVE::HandleOutputs(), JOBS_OUTPUT_FOLDER::HandleOutputs(), DRC_ENGINE::loadRules(), NETLIST_EXPORTER_XML::makeDesignHeader(), PANEL_SETUP_RULES::OnCompile(), DIALOG_SYMBOL_FIELDS_TABLE::OnExport(), DIALOG_EXPORT_STEP::onExportButton(), DIALOG_PLOT::onOpenOutputDirectory(), DIALOG_PLOT::onOutputDirectoryBrowseClicked(), PLOT_CONTROLLER::OpenPlotfile(), DIALOG_PLOT::Plot(), PCB_PLOTTER::Plot(), ResolveUriByEnvVars(), and TITLE_BLOCK::TextVarResolver().

◆ ExpandTextVars() [2/2]

KICOMMON_API wxString ExpandTextVars	(	const wxString &	aSource,
		const std::function< bool(wxString )>	aResolver,
		int	aFlags = 0 )

Definition at line 72 of file common.cpp.

References FOR_ERC_DRC.

◆ GetGeneratedFieldDisplayName()

KICOMMON_API wxString GetGeneratedFieldDisplayName ( const wxString & aSource )

Returns any variables unexpanded, e.g.

${VAR} -> VAR

Definition at line 124 of file common.cpp.

References ExpandTextVars().

Referenced by DIALOG_SYMBOL_FIELDS_TABLE::DIALOG_SYMBOL_FIELDS_TABLE(), DIALOG_SYMBOL_FIELDS_TABLE::doApplyBomPreset(), SCH_FIELD::GetShownName(), EESCHEMA_JOBS_HANDLER::JobExportBom(), DIALOG_SYMBOL_FIELDS_TABLE::LoadFieldNames(), DIALOG_LIB_FIELDS_TABLE::OnAddField(), DIALOG_SYMBOL_FIELDS_TABLE::OnAddField(), DIALOG_LIB_FIELDS_TABLE::OnRenameField(), DIALOG_SYMBOL_FIELDS_TABLE::OnRenameField(), and DIALOG_LIB_FIELDS_TABLE::UpdateFieldList().

◆ IsGeneratedField()

KICOMMON_API bool IsGeneratedField ( const wxString & aSource )

Returns true if the string is generated, e.g contains a single text var reference.

Definition at line 137 of file common.cpp.

Referenced by FIELDS_EDITOR_GRID_DATA_MODEL::ApplyData(), LIB_FIELDS_EDITOR_GRID_DATA_MODEL::ApplyData(), DIALOG_SYMBOL_FIELDS_TABLE::DIALOG_SYMBOL_FIELDS_TABLE(), FIELDS_EDITOR_GRID_DATA_MODEL::getFieldShownText(), FIELDS_EDITOR_GRID_DATA_MODEL::GetValue(), FIELDS_EDITOR_GRID_DATA_MODEL::groupMatch(), EESCHEMA_JOBS_HANDLER::JobExportBom(), DIALOG_LIB_FIELDS_TABLE::SetupColumnProperties(), DIALOG_SYMBOL_FIELDS_TABLE::SetupColumnProperties(), FIELDS_EDITOR_GRID_DATA_MODEL::SetValue(), and FIELDS_EDITOR_GRID_DATA_MODEL::updateDataStoreSymbolField().

◆ ResolveUriByEnvVars()

KICOMMON_API const wxString ResolveUriByEnvVars	(	const wxString &	aUri,
		const PROJECT *	aProject )

Replace any environment and/or text variables in URIs.

Definition at line 378 of file common.cpp.

References ExpandEnvVarSubstitutions(), and ExpandTextVars().

Referenced by PDF_PLOTTER::endPlotEmitResources(), GetAssociatedDocument(), and SCH_NAVIGATE_TOOL::HypertextCommand().

◆ SearchHelpFileFullPath()

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

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

Referenced by COMMON_CONTROL::ShowHelp().

◆ TimestampDir()

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

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

Parameters

aDirPath	is the directory to search.
aFilespec	is a (wildcarded) file spec to match against.

Returns: a hash of the last-mod-dates of all matching files in the directory.

Definition at line 614 of file common.cpp.

References matchWild().

Referenced by SCH_IO_LIB_CACHE::GetLibModificationTime(), DESIGN_BLOCK_IO::GetLibraryTimestamp(), FP_CACHE::GetTimestamp(), GPCB_FPL_CACHE::GetTimestamp(), SCH_IO_LIB_CACHE::IsFileChanged(), and SCH_IO_KICAD_LEGACY_LIB_CACHE::Save().

◆ WarnUserIfOperatingSystemUnsupported()

KICOMMON_API bool WarnUserIfOperatingSystemUnsupported ( )

Checks if the operating system is explicitly unsupported and displays a disclaimer message box.

Returns: true if the operating system is unsupported

Definition at line 713 of file common.cpp.

References _, and KIPLATFORM::APP::IsOperatingSystemUnsupported().

Referenced by PGM_BASE::InitPgm(), and COMMON_CONTROL::ReportBug().

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ FOR_ERC_DRC

Function Documentation

◆ DescribeRef()

◆ EnsureFileDirectoryExists()

◆ EnsureFileExtension()

◆ ExpandEnvVarSubstitutions()

◆ ExpandTextVars() [1/2]

◆ ExpandTextVars() [2/2]

◆ GetGeneratedFieldDisplayName()

◆ IsGeneratedField()

◆ ResolveUriByEnvVars()

◆ SearchHelpFileFullPath()

◆ TimestampDir()

◆ WarnUserIfOperatingSystemUnsupported()