Inkscape: Inkscape::Preferences Class Reference

Searching...

No Matches

Preference storage class. More...

#include <preferences.h>

Classes
class	Entry
	Data type representing a typeless value of a preference. More...

class	Observer
	Base class for preference observers. More...

class	PreferencesObserver
	Callback-based preferences observer. More...

Public Member Functions
	Preferences (Preferences const &)=delete

Preferences	operator= (Preferences const &)=delete

void	save ()
	Save all preferences to the hard disk.

void	reset ()
	Deletes the preferences.xml file.

bool	isWritable ()
	Check whether saving the preferences will have any effect.

bool	getLastError (Glib::ustring &primary, Glib::ustring &secondary)
	Return details of the last encountered error, if any.

Iterate over directories and entries.
std::vector< Entry >	getAllEntries (Glib::ustring const &path)
	Get all entries from the specified directory.

std::vector< Glib::ustring >	getAllDirs (Glib::ustring const &path)
	Get all subdirectories of the specified directory.

Retrieve data from the preference storage.
bool	hasPref (Glib::ustring const &pref_path)
	Return true if there is a value at this prefs-path.

bool	getBool (Glib::ustring const &pref_path, bool def=false)
	Retrieve a Boolean value.

std::optional< bool >	getOptionalBool (Glib::ustring const &pref_path)
	Retrieve a Boolean value, if it exists.

Geom::Point	getPoint (Glib::ustring const &pref_path, Geom::Point def=Geom::Point())
	Retrieve a point.

int	getInt (Glib::ustring const &pref_path, int def=0)
	Retrieve an integer.

int	getIntLimited (Glib::ustring const &pref_path, int def=0, int min=INT_MIN, int max=INT_MAX)
	Retrieve a limited integer.

unsigned int	getUInt (Glib::ustring const &pref_path, unsigned int def=0)
	Retrieve an unsigned integer.

double	getDouble (Glib::ustring const &pref_path, double def=0.0, Glib::ustring const &unit="")
	Retrieve a floating point value.

double	getDoubleLimited (Glib::ustring const &pref_path, double def=0.0, double min=DBL_MIN, double max=DBL_MAX, Glib::ustring const &unit="")
	Retrieve a limited floating point value.

Glib::ustring	getString (Glib::ustring const &pref_path, Glib::ustring const &def="")
	Retrieve an UTF-8 string.

Glib::ustring	getUnit (Glib::ustring const &pref_path)
	Retrieve the unit string.

Colors::Color	getColor (Glib::ustring const &pref_path, std::string const &def="black")

SPCSSAttr *	getStyle (Glib::ustring const &pref_path)
	Retrieve a CSS style.

SPCSSAttr *	getInheritedStyle (Glib::ustring const &pref_path)
	Retrieve an inherited CSS style.

Entry const	getEntry (Glib::ustring const &pref_path)
	Retrieve a preference entry without specifying its type.

Glib::ustring	getPrefsFilename () const
	Get the preferences file name in UTF-8.

Update preference values.
void	setBool (Glib::ustring const &pref_path, bool value)
	Set a Boolean value.

void	setPoint (Glib::ustring const &pref_path, Geom::Point value)
	Set a point value.

void	setInt (Glib::ustring const &pref_path, int value)
	Set an integer value.

void	setUInt (Glib::ustring const &pref_path, unsigned int value)
	Set an unsigned integer value.

void	setDouble (Glib::ustring const &pref_path, double value)
	Set a floating point value.

void	setDoubleUnit (Glib::ustring const &pref_path, double value, Glib::ustring const &unit_abbr)
	Set a floating point value with unit.

void	setString (Glib::ustring const &pref_path, Glib::ustring const &value)
	Set an UTF-8 string value.

void	setColor (Glib::ustring const &pref_path, Colors::Color const &color)
	Set an RGBA color value.

void	setStyle (Glib::ustring const &pref_path, SPCSSAttr *style)
	Set a CSS style.

void	mergeStyle (Glib::ustring const &pref_path, SPCSSAttr *style)
	Merge a CSS style with the current preference value.

Receive notifications about preference changes.
void	addObserver (Observer &)
	Register a preference observer.

void	removeObserver (Observer &)
	Remove an observer an prevent further notifications to it.

std::unique_ptr< PreferencesObserver >	createObserver (Glib::ustring path, std::function< void(const Preferences::Entry &new_value)> callback)
	Create an observer watching preference 'path' and calling provided function when preference changes.

std::unique_ptr< PreferencesObserver >	createObserver (Glib::ustring path, std::function< void()> callback)

Access and manipulate the Preferences object.
typedef std::map< Observer *, std::unique_ptr< PrefNodeObserver > >	_ObsMap

std::string	_prefs_filename
	Full filename (with directory) of the prefs file.

Glib::ustring	_lastErrPrimary
	Last primary error message, if any.

Glib::ustring	_lastErrSecondary
	Last secondary error message, if any.

XML::Document *	_prefs_doc = nullptr
	XML document storing all the preferences.

ErrorReporter *	_errorHandler = nullptr
	Pointer to object reporting errors.

bool	_writable = false
	Will the preferences be saved at exit?

bool	_hasError = false
	Indication that some error has occurred;.

bool	_initialized = false
	Is this instance fully initialized? Caching should be avoided before.

std::unordered_map< std::string, Entry >	cachedEntry
	Cache for getEntry()

_ObsMap	_observer_map
	Map that keeps track of wrappers assigned to PrefObservers.

static Preferences *	_instance = nullptr

class	PrefNodeObserver

class	Entry

void	setErrorHandler (ErrorReporter *handler)

void	remove (Glib::ustring const &pref_path)
	Remove a node from prefs.

auto	temporaryPreferences ()
	Create a temporary transaction which will be rolled back when the returned scope guard is destroyed.

static Preferences *	get ()
	Access the singleton Preferences object.

static void	unload (bool save=true)
	Unload all preferences.

SPCSSAttr *	_getInheritedStyleForPath (Glib::ustring const &prefPath)
	Interpret the preference as a CSS style with directory-based inheritance.

	Preferences ()

	~Preferences ()

void	_loadDefaults ()
	Load internal defaults.

void	_load ()
	Load the user's customized preferences.

std::optional< Glib::ustring >	_getRawValue (Glib::ustring const &path)
	Get raw value for preference path, without any caching.

void	_setRawValue (Glib::ustring const &path, Glib::ustring const &value)

void	_reportError (Glib::ustring const &, Glib::ustring const &)

void	_keySplit (Glib::ustring const &pref_path, Glib::ustring &node_key, Glib::ustring &attr_key)

XML::Node *	_getNode (Glib::ustring const &pref_path, bool create=false)
	Get the XML node corresponding to the given pref key.

XML::Node *	_findObserverNode (Glib::ustring const &pref_path, Glib::ustring &node_key, Glib::ustring &attr_key, bool create)
	Find the XML node to observe.

static _ObserverData *	_get_pref_observer_data (Observer &o)

Detailed Description

Preference storage class.

This is a singleton that allows one to access the user preferences stored in the preferences.xml file. The preferences are stored in a file system-like hierarchy. They are generally typeless - it's up to the programmer to ensure that a given preference is always accessed as the correct type. The backend is not guaranteed to be tolerant to type mismatches.

Preferences are identified by paths similar to file system paths. Components of the path are separated by a slash (/). As an additional requirement, the path must start with a slash, and not contain a trailing slash. An example of a correct path would be "/options/some_group/some_option".

All preferences are loaded when the first singleton pointer is requested. To save the preferences, the method save() or the static function unload() can be used.

In future, this will be a virtual base from which specific backends derive (e.g. GConf, flat XML file...)

Definition at line 66 of file preferences.h.

Member Typedef Documentation

◆ _ObsMap

typedef std::map<Observer *, std::unique_ptr<PrefNodeObserver> > Inkscape::Preferences::_ObsMap

private

Definition at line 765 of file preferences.h.

Constructor & Destructor Documentation

◆ Preferences() [1/2]

Inkscape::Preferences::Preferences ( Preferences const & )

delete

◆ Preferences() [2/2]

Inkscape::Preferences::Preferences ( )

private

Definition at line 67 of file preferences.cpp.

References _initialized, _load(), _loadDefaults(), _prefs_filename, and Inkscape::IO::Resource::profile_path().

Referenced by get().

◆ ~Preferences()

Inkscape::Preferences::~Preferences ( )

private

Definition at line 77 of file preferences.cpp.

References _prefs_doc, and Inkscape::GC::release().

Member Function Documentation

◆ _findObserverNode()

XML::Node * Inkscape::Preferences::_findObserverNode	(	Glib::ustring const &	pref_path,
		Glib::ustring &	node_key,
		Glib::ustring &	attr_key,
		bool	create
	)

private

Find the XML node to observe.

Definition at line 596 of file preferences.cpp.

References _getNode(), _keySplit(), child, create, Inkscape::XML::Node::firstChild(), and node.

Referenced by addObserver().

◆ _get_pref_observer_data()

static _ObserverData * Inkscape::Preferences::_get_pref_observer_data ( Observer & o )

inlinestaticprivate

Definition at line 770 of file preferences.h.

References Inkscape::Preferences::Observer::_data.

◆ _getInheritedStyleForPath()

SPCSSAttr * Inkscape::Preferences::_getInheritedStyleForPath ( Glib::ustring const & prefPath )

protected

Interpret the preference as a CSS style with directory-based inheritance.

This function will look up the preferences with the same entry name in ancestor directories and return the inherited CSS style.

Returns: Inherited CSS style that has to be unrefed after use. Never NULL.

Definition at line 1122 of file preferences.cpp.

References _getNode(), _keySplit(), node, and sp_repr_css_attr_inherited().

Referenced by Inkscape::Preferences::Entry::getInheritedStyle().

◆ _getNode()

Inkscape::XML::Node * Inkscape::Preferences::_getNode	(	Glib::ustring const &	pref_key,
		bool	create = `false`
	)

private

Get the XML node corresponding to the given pref key.

Parameters

pref_key	Preference key (path) to get.
create	Whether to create the corresponding node if it doesn't exist.
separator	The character used to separate parts of the pref key.

Returns: XML node corresponding to the specified key.

Derived from former inkscape_get_repr(). Private because it assumes that the backend is a flat XML file, which may not be the case e.g. if we are using GConf (in future).

Definition at line 677 of file preferences.cpp.

References _prefs_doc, Inkscape::XML::Node::appendChild(), child, create, Inkscape::XML::Document::createElement(), Inkscape::XML::Node::document(), Inkscape::XML::Node::firstChild(), node, Inkscape::XML::Node::root(), and Inkscape::XML::Node::setAttribute().

Referenced by _findObserverNode(), _getInheritedStyleForPath(), _getRawValue(), _setRawValue(), getAllDirs(), getAllEntries(), and remove().

◆ _getRawValue()

std::optional< Glib::ustring > Inkscape::Preferences::_getRawValue ( Glib::ustring const & path )

private

Get raw value for preference path, without any caching.

std::nullopt is returned when the requested entry does not exist

Definition at line 740 of file preferences.cpp.

References _getNode(), _keySplit(), Inkscape::XML::Node::attribute(), and node.

Referenced by getEntry().

◆ _keySplit()

void Inkscape::Preferences::_keySplit	(	Glib::ustring const &	pref_path,
		Glib::ustring &	node_key,
		Glib::ustring &	attr_key
	)

private

Definition at line 1132 of file preferences.cpp.

Referenced by _findObserverNode(), _getInheritedStyleForPath(), _getRawValue(), and _setRawValue().

◆ _load()

void Inkscape::Preferences::_load ( )

private

Load the user's customized preferences.

Tries to load the user's preferences.xml file. If there is none, creates it.

Definition at line 107 of file preferences.cpp.

References _prefs_doc, _prefs_filename, _reportError(), _writable, Inkscape::loadImpl(), Inkscape::XML::Node::mergeFrom(), Inkscape::migrateDetails(), Inkscape::migrateFromDoc, msg, preferences_skeleton, Inkscape::IO::Resource::profile_path(), Inkscape::GC::release(), and Inkscape::XML::Node::root().

Referenced by Preferences(), and reset().

◆ _loadDefaults()

void Inkscape::Preferences::_loadDefaults ( )

private

Load internal defaults.

In the future this will try to load the system-wide file before falling back to the internal defaults.

Definition at line 89 of file preferences.cpp.

References _prefs_doc, preferences_skeleton, setBool(), setInt(), and sp_repr_read_mem().

Referenced by Preferences(), and reset().

◆ _reportError()

void Inkscape::Preferences::_reportError	(	Glib::ustring const &	msg,
		Glib::ustring const &	secondary
	)

private

Definition at line 1140 of file preferences.cpp.

References _errorHandler, _hasError, _lastErrPrimary, _lastErrSecondary, Inkscape::ErrorReporter::handleError(), and msg.

Referenced by _load().

◆ _setRawValue()

void Inkscape::Preferences::_setRawValue	(	Glib::ustring const &	path,
		Glib::ustring const &	value
	)

private

Definition at line 758 of file preferences.cpp.

References _getNode(), _initialized, _keySplit(), cachedEntry, node, and Inkscape::XML::Node::setAttribute().

Referenced by mergeStyle(), setBool(), setColor(), setDouble(), setDoubleUnit(), setInt(), setString(), setStyle(), and setUInt().

◆ addObserver()

void Inkscape::Preferences::addObserver ( Observer & o )

Limitations: If the observed preferences path does not exist or is removed, then the observer may stop working, even if the path is re-added later.

Definition at line 621 of file preferences.cpp.

References Inkscape::Preferences::Observer::_data, _findObserverNode(), _observer_map, Inkscape::XML::Node::addObserver(), Inkscape::XML::Node::addSubtreeObserver(), node, Inkscape::Preferences::Observer::observed_path, and PrefNodeObserver.

Referenced by Inkscape::UI::ThemeContext::add_gtk_css(), Inkscape::PrefBase< T >::enable(), Inkscape::Pref< void >::enable(), Inkscape::PrefBase< T >::init(), Inkscape::SelCue::SelCue(), Inkscape::SelTrans::SelTrans(), and Inkscape::UI::SimplePrefPusher::SimplePrefPusher().

◆ createObserver() [1/2]

PrefObserver Inkscape::Preferences::createObserver	(	Glib::ustring	path,
		std::function< void()>	callback
	)

Definition at line 1201 of file preferences.cpp.

References createObserver().

◆ createObserver() [2/2]

std::unique_ptr< PreferencesObserver > Inkscape::Preferences::createObserver	(	Glib::ustring	path,
		std::function< void(const Preferences::Entry &new_value)>	callback
	)

Create an observer watching preference 'path' and calling provided function when preference changes.

Function will be notified of changes to all leaves in a path: /path/ * Returned pointer should be stored for as long as notifications are expected and disposed of to remove observer object.

Referenced by Inkscape::UI::Widget::ColorNotebook::_initUI(), Inkscape::UI::Dialog::AlignAndDistribute::AlignAndDistribute(), createObserver(), Inkscape::UI::Dialog::ExtensionList::init(), Inkscape::UI::Toolbar::SnapToolbar::SnapToolbar(), Inkscape::UI::Widget::StatusBar::StatusBar(), Inkscape::Colors::CMS::System::System(), and Inkscape::UI::Toolbar::ToolToolbar::ToolToolbar().

◆ get()

static Preferences * Inkscape::Preferences::get ( )

inlinestatic

Access the singleton Preferences object.

Definition at line 680 of file preferences.h.

References _instance, and Preferences().

◆ getAllDirs()

std::vector< Glib::ustring > Inkscape::Preferences::getAllDirs ( Glib::ustring const & path )

Get all subdirectories of the specified directory.

Get the paths to all subdirectories of the specified path.

This will return a vector populated with full paths to the subdirectories present in the specified path.

Parameters

path	Preference path to query.

Returns: A vector containing absolute paths to all subdirectories in the given path.

Definition at line 332 of file preferences.cpp.

References _getNode(), Inkscape::XML::Node::firstChild(), and node.

Referenced by Inkscape::UI::Toolbar::get_presets_list(), and Inkscape::UI::Dialog::IconPreviewPanel::IconPreviewPanel().

◆ getAllEntries()

std::vector< Preferences::Entry > Inkscape::Preferences::getAllEntries ( Glib::ustring const & path )

Get all entries from the specified directory.

Get names of all entries in the specified path.

This method will return a vector populated with preference entries from the specified directory. Subdirectories will not be represented.

Parameters

path	Preference path to query.

Returns: A vector containing all entries in the given directory.

Definition at line 314 of file preferences.cpp.

References _getNode(), Inkscape::XML::Node::attributeList(), and node.

Referenced by Inkscape::UI::Toolbar::CalligraphyToolbar::change_profile(), SPStyle::readFromPrefs(), and Inkscape::UI::Toolbar::CalligraphyToolbar::update_presets_list().

◆ getBool()

bool Inkscape::Preferences::getBool	(	Glib::ustring const &	pref_path,
		bool	def = `false`
	)

inline

Retrieve a Boolean value.

Parameters

pref_path	Path to the retrieved preference.
def	The default value to return if the preference is not set.

Definition at line 429 of file preferences.h.

References Inkscape::Preferences::Entry::getBool(), and getEntry().

◆ getColor()

Colors::Color Inkscape::Preferences::getColor	(	Glib::ustring const &	pref_path,
		std::string const &	def = `"black"`
	)

Definition at line 1205 of file preferences.cpp.

References Inkscape::Preferences::Entry::getColor(), and getEntry().

Referenced by Inkscape::UI::Tools::PenTool::_bsplineSpiroColor(), Inkscape::UI::Tools::PencilTool::_fitAndSplit(), Inkscape::UI::MultiPathManipulator::_getOutlineColor(), Inkscape::UI::Dialog::CloneTiler::apply(), Inkscape::UI::Widget::PrefColorPicker::init(), and Inkscape::UI::Dialog::InkscapePreferences::symbolicThemeCheck().

◆ getDouble()

double Inkscape::Preferences::getDouble	(	Glib::ustring const &	pref_path,
		double	def = `0.0`,
		Glib::ustring const &	unit = `""`
	)

inline

Retrieve a floating point value.

Parameters

pref_path	Path to the retrieved preference.
def	The default value to return if the preference is not set.
unit	Specifies the unit of the returned result. Will be ignored when equal to "". If the preference has no unit set, the default unit will be assumed.

Definition at line 501 of file preferences.h.

References Inkscape::Preferences::Entry::getDouble(), and getEntry().

◆ getDoubleLimited()

double Inkscape::Preferences::getDoubleLimited	(	Glib::ustring const &	pref_path,
		double	def = `0.0`,
		double	min = `DBL_MIN`,
		double	max = `DBL_MAX`,
		Glib::ustring const &	unit = `""`
	)

inline

Retrieve a limited floating point value.

The default value is returned if the actual value is larger than max or smaller than min.

Parameters

pref_path	Path to the retrieved preference.
def	The default value to return if the preference is not set.
min	Minimum value to return.
max	Maximum value to return.
unit	Specifies the unit of the returned result. Will be ignored when equal to "". If the preference has no unit set, the default unit will be assumed.

Definition at line 517 of file preferences.h.

References Inkscape::Preferences::Entry::getDoubleLimited(), and getEntry().

Referenced by Inkscape::UI::PathManipulator::_deleteStretch(), Inkscape::UI::Tools::PencilTool::_interpolate(), Inkscape::UI::ControlPointSelection::_keyboardScale(), Inkscape::UI::Tools::ToolBase::_schedule_delayed_snap_event(), Inkscape::UI::Tools::PencilTool::_sketchInterpolate(), Inkscape::UI::Tools::PencilTool::addPowerStrokePencil(), Inkscape::Application::Application(), Inkscape::UI::Dialog::CloneTiler::apply(), canvas_color_mode_gray(), canvas_transform(), Inkscape::UI::ThemeContext::getFontScale(), Inkscape::UI::Widget::PrefSpinUnit::init(), Inkscape::UI::Widget::PrefSpinButton::init(), Inkscape::UI::Widget::PrefSlider::init(), Inkscape::UI::Widget::ZoomCorrRulerSlider::init(), Inkscape::SnappedPoint::isOtherSnapBetter(), Inkscape::Pref< double >::read(), Inkscape::UI::PathManipulator::scaleHandle(), Inkscape::UI::Tools::SprayTool::setCloneTilerPrefs(), Inkscape::UI::Tools::spdc_check_for_and_apply_waiting_LPE(), and transform_grow_step().

◆ getEntry()

Preferences::Entry const Inkscape::Preferences::getEntry ( Glib::ustring const & pref_path )

Retrieve a preference entry without specifying its type.

Definition at line 349 of file preferences.cpp.

References _getRawValue(), _initialized, and cachedEntry.

Referenced by Inkscape::UI::ThemeContext::add_gtk_css(), Inkscape::UI::Tools::PencilTool::addPowerStrokePencil(), Inkscape::LivePathEffect::LPEJoinType::doOnApply(), Inkscape::LivePathEffect::LPERoughen::doOnApply(), Inkscape::LivePathEffect::LPETaperStroke::doOnApply(), getBool(), getColor(), getDouble(), getDoubleLimited(), getInheritedStyle(), getInt(), getIntLimited(), getPoint(), getString(), getStyle(), getUInt(), getUnit(), Inkscape::LivePathEffect::Effect::hasDefaultParameters(), hasPref(), Inkscape::UI::Tools::MeshTool::new_default(), Inkscape::LivePathEffect::Effect::readallParameters(), Inkscape::UI::Dialog::InkscapePreferences::resetIconsColors(), Inkscape::UI::Tools::sp_event_context_read(), Inkscape::UI::Dialog::InkscapePreferences::symbolicThemeCheck(), Inkscape::UI::Dialog::InkscapePreferences::toggleSymbolic(), and Inkscape::LivePathEffect::Effect::unsetDefaultParam().

◆ getInheritedStyle()

SPCSSAttr * Inkscape::Preferences::getInheritedStyle ( Glib::ustring const & pref_path )

inline

Retrieve an inherited CSS style.

This method will look up preferences with the same entry name in ancestor directories and return a style obtained by inheriting properties from ancestor styles.

Parameters

pref_path Path to the retrieved preference.

Returns: An inherited CSS style that has to be unrefed after use.

Definition at line 562 of file preferences.h.

References getEntry(), and Inkscape::Preferences::Entry::getInheritedStyle().

Referenced by SPDesktop::applyCurrentOrToolStyle(), sp_desktop_apply_style_tool(), and Inkscape::UI::Dialog::StyleFromSelectionToTool().

◆ getInt()

int Inkscape::Preferences::getInt	(	Glib::ustring const &	pref_path,
		int	def = `0`
	)

inline

Retrieve an integer.

Parameters

pref_path	Path to the retrieved preference.
def	The default value to return if the preference is not set.

Definition at line 464 of file preferences.h.

References getEntry(), and Inkscape::Preferences::Entry::getInt().

◆ getIntLimited()

int Inkscape::Preferences::getIntLimited	(	Glib::ustring const &	pref_path,
		int	def = `0`,
		int	min = `INT_MIN`,
		int	max = `INT_MAX`
	)

inline

Retrieve a limited integer.

The default value is returned if the actual value is larger than max or smaller than min. Do not use to store Boolean values.

Parameters

pref_path	Path to the retrieved preference.
def	The default value to return if the preference is not set.
min	Minimum value to return.
max	Maximum value to return.

Definition at line 479 of file preferences.h.

References getEntry(), and Inkscape::Preferences::Entry::getIntLimited().

Referenced by Inkscape::UI::Tools::PencilTool::_addFreehandPoint(), Inkscape::UI::PathManipulator::_getStrokeTolerance(), Inkscape::UI::Tools::PenTool::_handleMotionNotify(), Inkscape::UI::Tools::PencilTool::_handleMotionNotify(), Inkscape::UI::ControlPointSelection::_keyboardRotate(), Inkscape::UI::Dialog::LayerPropertiesDialog::_setup_position_controls(), Inkscape::UI::TransformHandleSet::_updateVisibility(), Inkscape::UI::Dialog::AlignAndDistribute::AlignAndDistribute(), Inkscape::UI::Dialog::AttrDialog::AttrDialog(), Inkscape::Trace::Depixelize::DepixelizeTracingEngine::DepixelizeTracingEngine(), Inkscape::UI::Handle::dragged(), Inkscape::UI::Node::dragged(), Inkscape::get_size_default(), Inkscape::Colors::CMS::System::getDisplayTransform(), Inkscape::UI::Widget::PrefSpinButton::init(), Inkscape::UI::Tools::PagesTool::PagesTool(), Inkscape::SVG::PathString::PathString(), Inkscape::UI::Widget::PatternEditor::PatternEditor(), Inkscape::Pref< int >::read(), Inkscape::UI::PathManipulator::rotateHandle(), Inkscape::UI::snap_increment_degrees(), and Inkscape::UI::Dialog::XmlTree::XmlTree().

◆ getLastError()

bool Inkscape::Preferences::getLastError	(	Glib::ustring &	primary,
		Glib::ustring &	secondary
	)

Return details of the last encountered error, if any.

This method will return true if an error has been encountered, and fill in the primary and secondary error strings of the last error. If an error had been encountered, this will reset it.

Parameters

string	to set to the primary error message.
string	to set to the secondary error message.

Returns: True if an error has occurred since last checking, false otherwise.

Definition at line 290 of file preferences.cpp.

References _hasError, _lastErrPrimary, _lastErrSecondary, and result.

Referenced by Inkscape::Application::Application().

◆ getOptionalBool()

std::optional< bool > Inkscape::Preferences::getOptionalBool ( Glib::ustring const & pref_path )

inline

Retrieve a Boolean value, if it exists.

Parameters

pref_path Path to the retrieved preference.

Definition at line 438 of file preferences.h.

References getBool(), and hasPref().

◆ getPoint()

Geom::Point Inkscape::Preferences::getPoint	(	Glib::ustring const &	pref_path,
		Geom::Point	def = `Geom::Point()`
	)

inline

Retrieve a point.

Parameters

pref_path	Path to the retrieved preference.
def	The default value to return if the preference is not set.

Definition at line 451 of file preferences.h.

References getDouble(), getEntry(), Geom::X, and Geom::Y.

Referenced by Inkscape::UI::NewFromTemplate::NewFromTemplate(), and Inkscape::UI::Tools::MeasureTool::readMeasurePoint().

◆ getPrefsFilename()

Glib::ustring Inkscape::Preferences::getPrefsFilename ( ) const

Get the preferences file name in UTF-8.

Definition at line 1166 of file preferences.cpp.

References _prefs_filename.

Referenced by Inkscape::UI::Dialog::InkscapePreferences::initPageSystem().

◆ getString()

Glib::ustring Inkscape::Preferences::getString	(	Glib::ustring const &	pref_path,
		Glib::ustring const &	def = `""`
	)

inline

Retrieve an UTF-8 string.

Parameters

pref_path Path to the retrieved preference.

Definition at line 526 of file preferences.h.

References getEntry(), and Inkscape::Preferences::Entry::getString().

◆ getStyle()

SPCSSAttr * Inkscape::Preferences::getStyle ( Glib::ustring const & pref_path )

inline

Retrieve a CSS style.

Parameters

pref_path Path to the retrieved preference.

Returns: A CSS style that has to be unrefed after use.

Definition at line 548 of file preferences.h.

References getEntry(), and Inkscape::Preferences::Entry::getStyle().

Referenced by Inkscape::UI::Dialog::InkscapePreferences::AddNewObjectsStyle(), mergeStyle(), sp_desktop_get_color_tool(), sp_desktop_get_master_opacity_tool(), and sp_desktop_get_opacity_tool().

◆ getUInt()

unsigned int Inkscape::Preferences::getUInt	(	Glib::ustring const &	pref_path,
		unsigned int	def = `0`
	)

inline

Retrieve an unsigned integer.

Parameters

pref_path	Path to the retrieved preference.
def	The default value to return if the preference is not set.

Definition at line 489 of file preferences.h.

References getEntry(), and Inkscape::Preferences::Entry::getUInt().

Referenced by Inkscape::UI::Dialog::InkscapePreferences::changeIconsColors(), Inkscape::UI::ThemeContext::get_symbolic_colors(), and Inkscape::UI::Widget::ColorTagRenderer::snapshot_vfunc().

◆ getUnit()

Glib::ustring Inkscape::Preferences::getUnit ( Glib::ustring const & pref_path )

inline

Retrieve the unit string.

Parameters

pref_path Path to the retrieved preference.

Definition at line 536 of file preferences.h.

References getEntry(), and Inkscape::Preferences::Entry::getUnit().

Referenced by Inkscape::Preferences::Entry::getDouble(), Inkscape::UI::Widget::PrefSpinUnit::init(), and Inkscape::Preferences::Entry::isConvertibleTo().

◆ hasPref()

bool Inkscape::Preferences::hasPref ( Glib::ustring const & pref_path )

inline

Return true if there is a value at this prefs-path.

Parameters

pref_path Path to preference to check.

Definition at line 419 of file preferences.h.

References getEntry(), and Inkscape::Preferences::Entry::isSet().

Referenced by getOptionalBool().

◆ isWritable()

bool Inkscape::Preferences::isWritable ( )

inline

Check whether saving the preferences will have any effect.

Definition at line 370 of file preferences.h.

References _writable.

◆ mergeStyle()

void Inkscape::Preferences::mergeStyle	(	Glib::ustring const &	pref_path,
		SPCSSAttr *	style
	)

Merge a CSS style with the current preference value.

This method is similar to setStyle(), except that it merges the style rather than replacing it. This means that if style doesn't have a property set, it is left unchanged in the style stored in the preferences.

Definition at line 479 of file preferences.cpp.

References _setRawValue(), current, getStyle(), SP_ATTRCLEAN_DEFAULT_REMOVE, sp_attribute_purge_default_style(), sp_repr_css_attr_unref(), sp_repr_css_merge(), and sp_repr_css_write_string().

Referenced by Inkscape::UI::Dialog::TextEdit::apply_changes(), Inkscape::UI::Toolbar::TextToolbar::mergeDefaultStyle(), Inkscape::UI::Dialog::TextEdit::onSetDefault(), and sp_desktop_set_style().

◆ operator=()

Preferences Inkscape::Preferences::operator= ( Preferences const & )

delete

◆ remove()

void Inkscape::Preferences::remove ( Glib::ustring const & pref_path )

Remove a node from prefs.

Remove an entry Make sure observers have been removed before calling.

Parameters

pref_path　Path to entry

Definition at line 494 of file preferences.cpp.

References _getNode(), _prefs_doc, cachedEntry, child, Inkscape::XML::Node::firstChild(), node, Inkscape::XML::Node::parent(), Inkscape::XML::Node::removeAttribute(), Inkscape::XML::Node::removeChild(), and Inkscape::XML::Node::root().

Referenced by Inkscape::LivePathEffect::Effect::unsetDefaultParam().

◆ removeObserver()

void Inkscape::Preferences::removeObserver ( Observer & o )

Remove an observer an prevent further notifications to it.

Definition at line 647 of file preferences.cpp.

References Inkscape::Preferences::Observer::_data, _observer_map, node, Inkscape::XML::Node::removeObserver(), and Inkscape::XML::Node::removeSubtreeObserver().

Referenced by Inkscape::PrefBase< T >::disable(), Inkscape::Pref< void >::disable(), Inkscape::Preferences::Observer::~Observer(), and Inkscape::UI::SimplePrefPusher::~SimplePrefPusher().

◆ reset()

void Inkscape::Preferences::reset ( )

Deletes the preferences.xml file.

Definition at line 264 of file preferences.cpp.

References _load(), _loadDefaults(), _observer_map, _prefs_doc, _prefs_filename, Inkscape::GC::release(), and save().

Referenced by Inkscape::UI::Dialog::InkscapePreferences::on_reset_prefs_clicked().

◆ save()

void Inkscape::Preferences::save ( )

Save all preferences to the hard disk.

Flush all pref changes to the XML file.

For some backends, the preferences may be saved as they are modified. Not calling this method doesn't guarantee the preferences are unmodified the next time Inkscape runs.

Definition at line 238 of file preferences.cpp.

References _prefs_doc, _prefs_filename, _writable, and sp_repr_save_file().

Referenced by reset(), save_preferences(), and unload().

◆ setBool()

void Inkscape::Preferences::setBool	(	Glib::ustring const &	pref_path,
		bool	value
	)

Set a Boolean value.

Set a boolean attribute of a preference.

Parameters

pref_path	Path of the preference to modify.
value	The new value of the pref attribute.

Todo:: Boolean values should be stored as "true" and "false", but this is not possible due to an interaction with event contexts. Investigate this in depth.

Definition at line 388 of file preferences.cpp.

References _setRawValue().

◆ setColor()

void Inkscape::Preferences::setColor	(	Glib::ustring const &	pref_path,
		Colors::Color const &	color
	)

Set an RGBA color value.

Definition at line 456 of file preferences.cpp.

References _setRawValue(), and Inkscape::Colors::Color::toString().

Referenced by Inkscape::Extension::ParamColor::_onColorChanged(), Inkscape::UI::Widget::PrefColorPicker::on_changed(), and Inkscape::UI::Dialog::CloneTiler::on_picker_color_changed().

◆ setDouble()

void Inkscape::Preferences::setDouble	(	Glib::ustring const &	pref_path,
		double	value
	)

Set a floating point value.

Set a floating point attribute of a preference.

Parameters

pref_path	Path of the preference to modify.
value	The new value of the pref attribute.

Definition at line 436 of file preferences.cpp.

References _setRawValue(), and Inkscape::ustring::format_classic().

◆ setDoubleUnit()

void Inkscape::Preferences::setDoubleUnit	(	Glib::ustring const &	pref_path,
		double	value,
		Glib::ustring const &	unit_abbr
	)

Set a floating point value with unit.

Set a floating point attribute of a preference.

Parameters

pref_path	Path of the preference to modify.
value	The new value of the pref attribute.
unit_abbr	The string of the unit (abbreviated).

Definition at line 449 of file preferences.cpp.

References _setRawValue(), and Inkscape::ustring::format_classic().

Referenced by Inkscape::Extension::Internal::BlurEdge::effect(), Inkscape::UI::Widget::PrefSpinUnit::init(), and Inkscape::UI::Widget::PrefSpinUnit::on_my_value_changed().

◆ setErrorHandler()

void Inkscape::Preferences::setErrorHandler ( ErrorReporter * handler )

Definition at line 1149 of file preferences.cpp.

References _errorHandler.

Referenced by Inkscape::Application::Application().

◆ setInt()

void Inkscape::Preferences::setInt	(	Glib::ustring const &	pref_path,
		int	value
	)

Set an integer value.

Set an integer attribute of a preference.

Parameters

pref_path	Path of the preference to modify.
value	The new value of the pref attribute.

Definition at line 414 of file preferences.cpp.

References _setRawValue(), and Inkscape::ustring::format_classic().

◆ setPoint()

void Inkscape::Preferences::setPoint	(	Glib::ustring const &	pref_path,
		Geom::Point	value
	)

Set a point value.

Set an point attribute of a preference.

Parameters

pref_path	Path of the preference to modify.
value	The new value of the pref attribute.

Definition at line 402 of file preferences.cpp.

References setDouble(), Geom::X, and Geom::Y.

Referenced by Inkscape::UI::NewFromTemplate::NewFromTemplate(), and Inkscape::UI::Tools::MeasureTool::writeMeasurePoint().

◆ setString()

void Inkscape::Preferences::setString	(	Glib::ustring const &	pref_path,
		Glib::ustring const &	value
	)

Set an UTF-8 string value.

Set a string attribute of a preference.

Parameters

pref_path	Path of the preference to modify.
value	The new value of the pref attribute.

Definition at line 467 of file preferences.cpp.

References _setRawValue().

◆ setStyle()

void Inkscape::Preferences::setStyle	(	Glib::ustring const &	pref_path,
		SPCSSAttr *	style
	)

Set a CSS style.

Definition at line 472 of file preferences.cpp.

References _setRawValue(), and sp_repr_css_write_string().

Referenced by Inkscape::UI::Tools::TweakTool::set_style(), and Inkscape::UI::Dialog::StyleFromSelectionToTool().

◆ setUInt()

void Inkscape::Preferences::setUInt	(	Glib::ustring const &	pref_path,
		unsigned int	value
	)

Set an unsigned integer value.

Set an unsigned integer attribute of a preference.

Parameters

pref_path	Path of the preference to modify.
value	The new value of the pref attribute.

Definition at line 425 of file preferences.cpp.

References _setRawValue(), and Inkscape::ustring::format_classic().

Referenced by Inkscape::UI::Dialog::InkscapePreferences::resetIconsColors().

◆ temporaryPreferences()

auto Inkscape::Preferences::temporaryPreferences ( )

inline

Create a temporary transaction which will be rolled back when the returned scope guard is destroyed.

This will allow you to change preferences and have them revert/rollback when your local process is complete.

Definition at line 713 of file preferences.h.

References _prefs_doc, Inkscape::XML::Document::beginTransaction(), cachedEntry, Inkscape::XML::Document::inTransaction(), and Inkscape::XML::Document::rollback().

◆ unload()

void Inkscape::Preferences::unload ( bool save = true )

static

Unload all preferences.

Parameters

save	Whether to save the preferences; defaults to true.

This deletes the singleton object. Calling get() after this function will reinstate it, so you shouldn't. Pass false as the parameter to suppress automatic saving.

Definition at line 1154 of file preferences.cpp.

References _instance, and save().

Referenced by Inkscape::Application::crash_handler(), Inkscape::Application::exit(), and Inkscape::Application::~Application().

Friends And Related Symbol Documentation

◆ Entry

friend class Entry

friend

Definition at line 775 of file preferences.h.

◆ PrefNodeObserver

friend class PrefNodeObserver

friend

Definition at line 774 of file preferences.h.

Referenced by addObserver().

Member Data Documentation

◆ _errorHandler

ErrorReporter* Inkscape::Preferences::_errorHandler = nullptr

private

Pointer to object reporting errors.

Definition at line 754 of file preferences.h.

Referenced by _reportError(), and setErrorHandler().

◆ _hasError

bool Inkscape::Preferences::_hasError = false

private

Indication that some error has occurred;.

Definition at line 756 of file preferences.h.

Referenced by _reportError(), and getLastError().

◆ _initialized

bool Inkscape::Preferences::_initialized = false

private

Is this instance fully initialized? Caching should be avoided before.

Definition at line 757 of file preferences.h.

Referenced by _setRawValue(), getEntry(), and Preferences().

◆ _instance

Preferences * Inkscape::Preferences::_instance = nullptr

staticprivate

Definition at line 772 of file preferences.h.

Referenced by get(), and unload().

◆ _lastErrPrimary

Glib::ustring Inkscape::Preferences::_lastErrPrimary

private

Last primary error message, if any.

Definition at line 751 of file preferences.h.

Referenced by _reportError(), and getLastError().

◆ _lastErrSecondary

Glib::ustring Inkscape::Preferences::_lastErrSecondary

private

Last secondary error message, if any.

Definition at line 752 of file preferences.h.

Referenced by _reportError(), and getLastError().

◆ _observer_map

_ObsMap Inkscape::Preferences::_observer_map

private

Map that keeps track of wrappers assigned to PrefObservers.

Definition at line 767 of file preferences.h.

Referenced by addObserver(), removeObserver(), and reset().

◆ _prefs_doc

XML::Document* Inkscape::Preferences::_prefs_doc = nullptr

private

XML document storing all the preferences.

Definition at line 753 of file preferences.h.

Referenced by _getNode(), _load(), _loadDefaults(), remove(), reset(), save(), temporaryPreferences(), and ~Preferences().

◆ _prefs_filename

std::string Inkscape::Preferences::_prefs_filename

private

Full filename (with directory) of the prefs file.

Definition at line 750 of file preferences.h.

Referenced by _load(), getPrefsFilename(), Preferences(), reset(), and save().

◆ _writable

bool Inkscape::Preferences::_writable = false

private

Will the preferences be saved at exit?

Definition at line 755 of file preferences.h.

Referenced by _load(), isWritable(), and save().

◆ cachedEntry

std::unordered_map<std::string, Entry> Inkscape::Preferences::cachedEntry

private

Cache for getEntry()

Definition at line 760 of file preferences.h.

Referenced by _setRawValue(), getEntry(), remove(), and temporaryPreferences().

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

/builds/inkscape/inkscape/src/preferences.h
/builds/inkscape/inkscape/src/preferences.cpp

Classes

Public Member Functions

Access and manipulate the Preferences object.

Detailed Description

Member Typedef Documentation

◆ _ObsMap

Constructor & Destructor Documentation

◆ Preferences() [1/2]

◆ Preferences() [2/2]

◆ ~Preferences()

Member Function Documentation

◆ _findObserverNode()

◆ _get_pref_observer_data()

◆ _getInheritedStyleForPath()

◆ _getNode()

◆ _getRawValue()

◆ _keySplit()

◆ _load()

◆ _loadDefaults()

◆ _reportError()

◆ _setRawValue()

◆ addObserver()

◆ createObserver() [1/2]

◆ createObserver() [2/2]

◆ get()

◆ getAllDirs()

◆ getAllEntries()

◆ getBool()

◆ getColor()

◆ getDouble()

◆ getDoubleLimited()

◆ getEntry()

◆ getInheritedStyle()

◆ getInt()

◆ getIntLimited()

◆ getLastError()

◆ getOptionalBool()

◆ getPoint()

◆ getPrefsFilename()

◆ getString()

◆ getStyle()

◆ getUInt()

◆ getUnit()

◆ hasPref()

◆ isWritable()

◆ mergeStyle()

◆ operator=()

◆ remove()

◆ removeObserver()

◆ reset()

◆ save()

◆ setBool()

◆ setColor()

◆ setDouble()

◆ setDoubleUnit()

◆ setErrorHandler()

◆ setInt()

◆ setPoint()

◆ setString()

◆ setStyle()

◆ setUInt()

◆ temporaryPreferences()

◆ unload()

Friends And Related Symbol Documentation

◆ Entry

◆ PrefNodeObserver

Member Data Documentation

◆ _errorHandler

◆ _hasError

◆ _initialized

◆ _instance

◆ _lastErrPrimary

◆ _lastErrSecondary

◆ _observer_map

◆ _prefs_doc

◆ _prefs_filename

◆ _writable

◆ cachedEntry