KiCad PCB EDA Suite
ENV_VAR_ITEM Class Reference

KiCad uses environment variables internally for determining the base paths for libraries, templates, and other assets that can be relocated by packagers or users. More...

#include <environment.h>

Public Member Functions

 ENV_VAR_ITEM (const wxString &aValue=wxEmptyString, bool aIsDefinedExternally=false)
 
 ENV_VAR_ITEM (const wxString &aKey, const wxString &aValue, const wxString &aDefaultValue=wxEmptyString)
 
 ~ENV_VAR_ITEM () throw ()
 
bool GetDefinedExternally () const
 
void SetDefinedExternally (bool aIsDefinedExternally=true)
 
bool GetDefinedInSettings () const
 
void SetDefinedInSettings (bool aDefined=true)
 
wxString GetKey () const
 
const wxString & GetValue () const
 
void SetValue (const wxString &aValue)
 
wxString GetDefault () const
 
wxString GetSettingsValue () const
 
void SetSettingsValue (const wxString &aValue)
 
bool GetBuiltin () const
 
bool IsDefault () const
 Checks if the variable matches its default value (always false for non-built-in vars) More...
 

Private Attributes

wxString m_key
 The environment variable string key. More...
 
wxString m_value
 The environment variable string value. More...
 
wxString m_defaultValue
 The default value, for built-in variables that are always defined. More...
 
wxString m_settingsValue
 The value that was originally loaded from JSON. More...
 
bool m_isBuiltin
 Set to true for KiCad built-in variables that are always defined one way or another. More...
 
bool m_isDefinedExternally
 Flag to indicate if the environment variable was defined externally to the process. More...
 
bool m_isDefinedInSettings
 Flag to indicate if the environment variable was defined in the settings file. More...
 

Detailed Description

KiCad uses environment variables internally for determining the base paths for libraries, templates, and other assets that can be relocated by packagers or users.

Because setting environment variables is not user-friendly on most platforms, KiCad supports two backing stores for these internal variables: the system environment, and the settings system.

We also want to make it possible to change the names and values of environment variables over time with minimal impact to users. Since most users do not customize these variables beyond any customization provided by the packager for their platform, an easy way to get this possibility with minimal user impact is to just not store environment variables if they match the internal (compiled-in) default.

The way environment variables are resolved is (highest to lowest priority):

1) Variables set at runtime via the Configure Paths dialog 2) Variables set in the system environment 3) Variables loaded from the settings system (stored in COMMON_SETTINGS)

For all KiCad system variables, we allow users to change the values at runtime via the Configure Paths dialog. If these variables were set in the system environment, we do not persist any changes made at runtime (and warn the user about this). If the variables were not set in the environment (meaning they were either the default value, or loaded from the settings system), we persist the changes via the settings system. Any variables that match the internal default are not saved in the settings, so that the internal defaults can be changed and the change will not be overridden by an old value cached in the settings file. A simple helper class to store environment variable definitions and values. This is used to initialize the environment variables that are built-in to KiCad, and also to store any variables created by the user.

Definition at line 59 of file include/settings/environment.h.

Constructor & Destructor Documentation

◆ ENV_VAR_ITEM() [1/2]

ENV_VAR_ITEM::ENV_VAR_ITEM ( const wxString &  aValue = wxEmptyString,
bool  aIsDefinedExternally = false 
)
inline

Definition at line 62 of file include/settings/environment.h.

62 :
63 m_value( aValue ),
64 m_isBuiltin( true ),
65 m_isDefinedExternally( aIsDefinedExternally ),
67 {
68 }
bool m_isDefinedInSettings
Flag to indicate if the environment variable was defined in the settings file.
bool m_isDefinedExternally
Flag to indicate if the environment variable was defined externally to the process.
bool m_isBuiltin
Set to true for KiCad built-in variables that are always defined one way or another.
wxString m_value
The environment variable string value.

◆ ENV_VAR_ITEM() [2/2]

ENV_VAR_ITEM::ENV_VAR_ITEM ( const wxString &  aKey,
const wxString &  aValue,
const wxString &  aDefaultValue = wxEmptyString 
)
inline

Definition at line 70 of file include/settings/environment.h.

71 :
72 m_key( aKey ),
73 m_value( aValue ),
74 m_defaultValue( aDefaultValue ),
75 m_isBuiltin( true ),
76 m_isDefinedExternally( false ),
78 {
79 }
wxString m_key
The environment variable string key.
wxString m_defaultValue
The default value, for built-in variables that are always defined.

◆ ~ENV_VAR_ITEM()

ENV_VAR_ITEM::~ENV_VAR_ITEM ( )
throw (
)
inline

Definition at line 81 of file include/settings/environment.h.

81{} // tell SWIG no exception

Member Function Documentation

◆ GetBuiltin()

bool ENV_VAR_ITEM::GetBuiltin ( ) const
inline

Definition at line 102 of file include/settings/environment.h.

102{ return m_isBuiltin; }

References m_isBuiltin.

◆ GetDefault()

wxString ENV_VAR_ITEM::GetDefault ( ) const
inline

Definition at line 97 of file include/settings/environment.h.

97{ return m_defaultValue; }

References m_defaultValue.

◆ GetDefinedExternally()

bool ENV_VAR_ITEM::GetDefinedExternally ( ) const
inline

Definition at line 83 of file include/settings/environment.h.

83{ return m_isDefinedExternally; }

References m_isDefinedExternally.

◆ GetDefinedInSettings()

bool ENV_VAR_ITEM::GetDefinedInSettings ( ) const
inline

Definition at line 89 of file include/settings/environment.h.

89{ return m_isDefinedInSettings; }

References m_isDefinedInSettings.

◆ GetKey()

wxString ENV_VAR_ITEM::GetKey ( ) const
inline

Definition at line 92 of file include/settings/environment.h.

92{ return m_key; }

References m_key.

◆ GetSettingsValue()

wxString ENV_VAR_ITEM::GetSettingsValue ( ) const
inline

Definition at line 99 of file include/settings/environment.h.

99{ return m_settingsValue; }
wxString m_settingsValue
The value that was originally loaded from JSON.

References m_settingsValue.

◆ GetValue()

const wxString & ENV_VAR_ITEM::GetValue ( ) const
inline

Definition at line 94 of file include/settings/environment.h.

94{ return m_value; }

References m_value.

◆ IsDefault()

bool ENV_VAR_ITEM::IsDefault ( ) const
inline

Checks if the variable matches its default value (always false for non-built-in vars)

Returns
true if a built-in variable matches its default

Definition at line 108 of file include/settings/environment.h.

109 {
111 }

References m_defaultValue, m_isBuiltin, and m_value.

◆ SetDefinedExternally()

void ENV_VAR_ITEM::SetDefinedExternally ( bool  aIsDefinedExternally = true)
inline

Definition at line 84 of file include/settings/environment.h.

85 {
86 m_isDefinedExternally = aIsDefinedExternally;
87 }

References m_isDefinedExternally.

◆ SetDefinedInSettings()

void ENV_VAR_ITEM::SetDefinedInSettings ( bool  aDefined = true)
inline

Definition at line 90 of file include/settings/environment.h.

90{ m_isDefinedInSettings = aDefined; }

References m_isDefinedInSettings.

◆ SetSettingsValue()

void ENV_VAR_ITEM::SetSettingsValue ( const wxString &  aValue)
inline

Definition at line 100 of file include/settings/environment.h.

100{ m_settingsValue = aValue; }

References m_settingsValue.

◆ SetValue()

void ENV_VAR_ITEM::SetValue ( const wxString &  aValue)
inline

Definition at line 95 of file include/settings/environment.h.

95{ m_value = aValue; }

References m_value.

Member Data Documentation

◆ m_defaultValue

wxString ENV_VAR_ITEM::m_defaultValue
private

The default value, for built-in variables that are always defined.

Definition at line 121 of file include/settings/environment.h.

Referenced by GetDefault(), and IsDefault().

◆ m_isBuiltin

bool ENV_VAR_ITEM::m_isBuiltin
private

Set to true for KiCad built-in variables that are always defined one way or another.

Definition at line 127 of file include/settings/environment.h.

Referenced by GetBuiltin(), and IsDefault().

◆ m_isDefinedExternally

bool ENV_VAR_ITEM::m_isDefinedExternally
private

Flag to indicate if the environment variable was defined externally to the process.

Definition at line 130 of file include/settings/environment.h.

Referenced by GetDefinedExternally(), and SetDefinedExternally().

◆ m_isDefinedInSettings

bool ENV_VAR_ITEM::m_isDefinedInSettings
private

Flag to indicate if the environment variable was defined in the settings file.

Definition at line 133 of file include/settings/environment.h.

Referenced by GetDefinedInSettings(), and SetDefinedInSettings().

◆ m_key

wxString ENV_VAR_ITEM::m_key
private

The environment variable string key.

Definition at line 115 of file include/settings/environment.h.

Referenced by GetKey().

◆ m_settingsValue

wxString ENV_VAR_ITEM::m_settingsValue
private

The value that was originally loaded from JSON.

Definition at line 124 of file include/settings/environment.h.

Referenced by GetSettingsValue(), and SetSettingsValue().

◆ m_value

wxString ENV_VAR_ITEM::m_value
private

The environment variable string value.

Definition at line 118 of file include/settings/environment.h.

Referenced by GetValue(), IsDefault(), and SetValue().


The documentation for this class was generated from the following file: