mitk::Preferences Class Reference

Implementation of the IPreferences interface. More...

#include <mitkPreferences.h>

Inheritance diagram for mitk::Preferences:

Collaboration diagram for mitk::Preferences:

Public Types
using	Properties = std::unordered_map< std::string, std::string >
	Property map type: string keys to string values. More...

Public Member Functions
	Preferences (const Properties &properties, const std::string &name, Preferences *parent, IPreferencesStorage *storage)
	Construct a preferences node. More...
	~Preferences () override
	Preferences (const Preferences &)=delete
Preferences &	operator= (const Preferences &)=delete
	Preferences (Preferences &&)=default
Preferences &	operator= (Preferences &&)=default
std::string	Get (const std::string &key, const std::string &def) const override
	Get a property value as string. More...
void	Put (const std::string &key, const std::string &value) override
	Set a property value. More...
int	GetInt (const std::string &key, int def) const override
	Get a property value as int. More...
void	PutInt (const std::string &key, int value) override
	Set an int property value. More...
bool	GetBool (const std::string &key, bool def) const override
	Get a property value as bool. More...
void	PutBool (const std::string &key, bool value) override
	Set a bool property value. More...
float	GetFloat (const std::string &key, float def) const override
	Get a property value as float. More...
void	PutFloat (const std::string &key, float value) override
	Set a float property value. More...
double	GetDouble (const std::string &key, double def) const override
	Get a property value as double. More...
void	PutDouble (const std::string &key, double value) override
	Set a double property value. More...
std::vector< std::byte >	GetByteArray (const std::string &key, const std::byte *def, size_t size) const override
	Get a property value as typeless binary representation. More...
void	PutByteArray (const std::string &key, const std::byte *array, size_t size) override
	Put binary data into a property value. More...
void	Override (const std::string &key, const std::string &value) override
	Set a session-only override for a string property. More...
void	OverrideInt (const std::string &key, int value) override
	Set a session-only override for an int property. More...
void	OverrideBool (const std::string &key, bool value) override
	Set a session-only override for a bool property. More...
void	OverrideFloat (const std::string &key, float value) override
	Set a session-only override for a float property. More...
void	OverrideDouble (const std::string &key, double value) override
	Set a session-only override for a double property. More...
void	OverrideByteArray (const std::string &key, const std::byte *array, size_t size) override
	Set a session-only override for a byte array property. More...
bool	IsOverridden (const std::string &key) const override
	Check whether a property has a session-only override. More...
void	RemoveOverride (const std::string &key) override
	Remove a session-only override for a property. More...
void	ClearOverrides () override
	Remove all session-only overrides from this preferences node. More...
bool	Remove (const std::string &key, bool forceRemoval=false) override
	Remove a property from this preferences node. More...
void	Clear (bool includeOverrides=false) override
	Remove all properties from this preferences node. More...
std::vector< std::string >	Keys (bool includeOverrides=false) const override
	Get the names of all properties of this preferences node. More...
std::vector< std::string >	ChildrenNames () const override
	Get the names of all direct child preference nodes. More...
IPreferences *	Parent () override
	Get the parent preferences node or nullptr in case of the root node. More...
const IPreferences *	Parent () const override
IPreferences *	Root () override
	Get the root preferences node. More...
const IPreferences *	Root () const override
IPreferences *	Node (const std::string &path) override
	Get (and possibly create) the preferences node specified by the given path. More...
void	RemoveNode () override
	Remove this preferences node from its parent node. More...
std::string	Name () const override
	Get the name of this preferences node. More...
std::string	AbsolutePath () const override
	Get the absolute path (relative to the root node) of this preferences node. More...
void	Flush () override
	Write all (!) preferences to disk. More...
const Properties &	GetProperties () const
const std::vector< std::unique_ptr< Preferences > > &	GetChildren () const
Public Member Functions inherited from mitk::IPreferences
virtual	~IPreferences ()

Additional Inherited Members
Public Attributes inherited from mitk::IPreferences
Message1< const IPreferences * >	OnChanged
	Notify on node changes. More...
Message1< const ChangeEvent & >	OnPropertyChanged
	Notify on property changes. More...

Detailed Description

Implementation of the IPreferences interface.

Stores preferences as string key-value pairs in a tree structure. Each node has a name, an absolute path, a parent, and zero or more children. Values are stored as strings and converted on access (int, bool, float, double, byte array). Supports overrides that shadow regular property values without modifying the persisted data.

Only used through the IPreferences interface.

See also

IPreferences

IPreferencesStorage

PreferencesService

Definition at line 41 of file mitkPreferences.h.

Member Typedef Documentation

Properties

using mitk::Preferences::Properties = std::unordered_map<std::string, std::string>

Property map type: string keys to string values.

Definition at line 45 of file mitkPreferences.h.

Constructor & Destructor Documentation

Preferences() [1/3]

mitk::Preferences::Preferences	(	const Properties &	properties,
		const std::string &	name,
		Preferences *	parent,
		IPreferencesStorage *	storage
	)

Construct a preferences node.

If parent is non-null, this node is automatically added as a child of the parent. The absolute path is computed from the parent's path and the given name.

Parameters

[in]	properties	Initial key-value properties for this node.
[in]	name	The name of this preferences node.
[in]	parent	The parent node, or nullptr for a root node.
[in]	storage	The backing storage. Must not be nullptr.

Exceptions

mitk::Exception

if storage is nullptr.

~Preferences()

mitk::Preferences::~Preferences ( )

override

Preferences() [2/3]

mitk::Preferences::Preferences ( const Preferences &  )

delete

Preferences() [3/3]

mitk::Preferences::Preferences ( Preferences &&  )

default

Member Function Documentation

AbsolutePath()

std::string mitk::Preferences::AbsolutePath ( ) const

overridevirtual

Get the absolute path (relative to the root node) of this preferences node.

See also

Name() const

Node()

Implements mitk::IPreferences.

ChildrenNames()

std::vector<std::string> mitk::Preferences::ChildrenNames ( ) const

overridevirtual

Get the names of all direct child preference nodes.

Implements mitk::IPreferences.

Clear()

void mitk::Preferences::Clear ( bool  includeOverrides = false )

overridevirtual

Remove all properties from this preferences node.

Session-only overrides are not affected by default. Set includeOverrides to true to also remove all overrides (equivalent to calling ClearOverrides() in addition).

Parameters

includeOverrides

If true, also clear all session-only overrides.

See also

ClearOverrides()

Implements mitk::IPreferences.

ClearOverrides()

void mitk::Preferences::ClearOverrides ( )

overridevirtual

Remove all session-only overrides from this preferences node.

Implements mitk::IPreferences.

Flush()

void mitk::Preferences::Flush ( )

overridevirtual

Write all (!) preferences to disk.

Enforce the persistence of the whole preferences tree. Session-only overrides are not written to disk.

Note

Preferences are flushed automatically at least on a regular application shutdown.

See also

IPreferencesStorage::Flush()

Implements mitk::IPreferences.

Get()

std::string mitk::Preferences::Get ( const std::string &  key, const std::string &  def  ) const

overridevirtual

Get a property value as string.

If the property cannot be found, return the provided default value instead. If a session-only override exists for the key, the override value is returned instead of the persistent property value.

Parameters

key	Name of the property
def	Default value

Returns

Property value or default value

See also

Override()

Implements mitk::IPreferences.

GetBool()

bool mitk::Preferences::GetBool ( const std::string &  key, bool  def  ) const

overridevirtual

Get a property value as bool.

Convenience wrapper of Get() checking if the string value literally equals "true". Returns false otherwise. The comparison is case-insensitive.

Implements mitk::IPreferences.

GetByteArray()

std::vector<std::byte> mitk::Preferences::GetByteArray ( const std::string &  key, const std::byte *  def, size_t  size  ) const

overridevirtual

Get a property value as typeless binary representation.

Decode a Base64-encoded property value into a typeless binary representation. Use reinterpret_cast to restore the original type:

// Restore position and size of a widget from preferences
std::vector<std::byte> geometry = preferences->GetByteArray("widget geometry", nullptr, 0);
widget->restoreGeometry(QByteArray(reinterpret_cast<const char*>(geometry.data())), geometry.size());

Parameters

key	Name of the property
def	Raw pointer to the default binary data or nullptr
size	Size of the default binary data in bytes or 0 in case of nullptr

Returns

Decoded binary data encapsulated in a vector of bytes. Use std::vector::data() to get a raw pointer to the data.

Implements mitk::IPreferences.

GetChildren()

const std::vector<std::unique_ptr<Preferences> >& mitk::Preferences::GetChildren

(

)

const

GetDouble()

double mitk::Preferences::GetDouble ( const std::string &  key, double  def  ) const

overridevirtual

Get a property value as double.

Convenience wrapper of Get() undertaking string to double conversion.

Exceptions

Exception

The property value is not a valid string representation of a double value.

Implements mitk::IPreferences.

GetFloat()

float mitk::Preferences::GetFloat ( const std::string &  key, float  def  ) const

overridevirtual

Get a property value as float.

Convenience wrapper of Get() undertaking string to float conversion.

Exceptions

Exception

The property value is not a valid string representation of a float value.

Implements mitk::IPreferences.

GetInt()

int mitk::Preferences::GetInt ( const std::string &  key, int  def  ) const

overridevirtual

Get a property value as int.

Convenience wrapper of Get() undertaking string to integer conversion.

Exceptions

Exception

The property value is not a valid string representation of an int value.

Implements mitk::IPreferences.

GetProperties()

const Properties& mitk::Preferences::GetProperties

(

)

const

IsOverridden()

bool mitk::Preferences::IsOverridden ( const std::string &  key ) const

overridevirtual

Check whether a property has a session-only override.

Implements mitk::IPreferences.

Keys()

std::vector<std::string> mitk::Preferences::Keys ( bool  includeOverrides = false ) const

overridevirtual

Get the names of all properties of this preferences node.

Parameters

includeOverrides

If true, also include keys that only exist in the override layer.

Implements mitk::IPreferences.

Name()

std::string mitk::Preferences::Name ( ) const

overridevirtual

Get the name of this preferences node.

The name can be used in an absolute or relative path separated by forward slashes to address a specific properties node.

See also

AbsolutePath() const

Node()

Implements mitk::IPreferences.

Node()

IPreferences* mitk::Preferences::Node ( const std::string &  path )

overridevirtual

Get (and possibly create) the preferences node specified by the given path.

The path is considered to be absolute if it starts with a forward slash. It is relative to this preferences node otherwise. If any preferences node does not yet exist during traversal, it is created on the fly.

See also

Name() const

AbsolutePath() const

Implements mitk::IPreferences.

operator=() [1/2]

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

delete

operator=() [2/2]

Preferences& mitk::Preferences::operator= ( Preferences &&  )

default

Override()

void mitk::Preferences::Override ( const std::string &  key, const std::string &  value  )

overridevirtual

Set a session-only override for a string property.

Overrides are not persisted to disk. If the key does not yet exist in the persistent properties, the override still takes effect for Get operations.

Parameters

key	Name of the property
value	Override value

Implements mitk::IPreferences.

OverrideBool()

void mitk::Preferences::OverrideBool ( const std::string &  key, bool  value  )

overridevirtual

Set a session-only override for a bool property.

See also

Override()

Implements mitk::IPreferences.

OverrideByteArray()

void mitk::Preferences::OverrideByteArray ( const std::string &  key, const std::byte *  array, size_t  size  )

overridevirtual

Set a session-only override for a byte array property.

See also

Override()

Implements mitk::IPreferences.

OverrideDouble()

void mitk::Preferences::OverrideDouble ( const std::string &  key, double  value  )

overridevirtual

Set a session-only override for a double property.

See also

Override()

Implements mitk::IPreferences.

OverrideFloat()

void mitk::Preferences::OverrideFloat ( const std::string &  key, float  value  )

overridevirtual

Set a session-only override for a float property.

See also

Override()

Implements mitk::IPreferences.

OverrideInt()

void mitk::Preferences::OverrideInt ( const std::string &  key, int  value  )

overridevirtual

Set a session-only override for an int property.

See also

Override()

Implements mitk::IPreferences.

Parent() [1/2]

const IPreferences* mitk::Preferences::Parent ( ) const

overridevirtual

See also

Parent()

Implements mitk::IPreferences.

Parent() [2/2]

IPreferences* mitk::Preferences::Parent ( )

overridevirtual

Get the parent preferences node or nullptr in case of the root node.

Implements mitk::IPreferences.

Put()

void mitk::Preferences::Put ( const std::string &  key, const std::string &  value  )

overridevirtual

Set a property value.

Create the property if not yet existent. Otherwise change its value. This only affects the persistent property, not any session-only override that may exist for the same key.

Trigger an IPreferences::OnPropertyChanged event if the new value is different or if a new property has been created, except the string value is empty in the latter case.

Implements mitk::IPreferences.

PutBool()

void mitk::Preferences::PutBool ( const std::string &  key, bool  value  )

overridevirtual

Set a bool property value.

Convenience wrapper of Put() using the literal strings "true" and "false" to encode the bool value.

Implements mitk::IPreferences.

PutByteArray()

void mitk::Preferences::PutByteArray ( const std::string &  key, const std::byte *  array, size_t  size  )

overridevirtual

Put binary data into a property value.

The Base64 algorithm is used to encode binary data into a valid text representation. Use reinterpret_cast to pass a raw pointer to binary data and specify its total number of bytes:

// Store position and size of a widget in preferences
QByteArray geometry = widget->saveGeometry();
preferences->PutByteArray("widget geometry", reinterpret_cast<const std::byte*>(geometry.data()), geometry.size());

Parameters

key	Name of the property
array	Raw pointer to binary data
size	Size of the binary data in bytes

Implements mitk::IPreferences.

PutDouble()

void mitk::Preferences::PutDouble ( const std::string &  key, double  value  )

overridevirtual

Set a double property value.

Convenience wrapper of Put() undertaking double to string conversion.

Implements mitk::IPreferences.

PutFloat()

void mitk::Preferences::PutFloat ( const std::string &  key, float  value  )

overridevirtual

Set a float property value.

Convenience wrapper of Put() undertaking float to string conversion.

Implements mitk::IPreferences.

PutInt()

void mitk::Preferences::PutInt ( const std::string &  key, int  value  )

overridevirtual

Set an int property value.

Convenience wrapper of Put() undertaking integer to string conversion.

Implements mitk::IPreferences.

Remove()

bool mitk::Preferences::Remove ( const std::string &  key, bool  forceRemoval = false  )

overridevirtual

Remove a property from this preferences node.

If the key has a session-only override and forceRemoval is false, the removal is denied and the method returns false. If forceRemoval is true, both the persistent property and the override are removed.

Parameters

key	Name of the property
forceRemoval	If true, also remove any override for the key

Returns

True if the key is not present in preferences anymore (either it was removed or it did not exist in the first place), false if removal was denied due to an override

Implements mitk::IPreferences.

RemoveNode()

void mitk::Preferences::RemoveNode ( )

overridevirtual

Remove this preferences node from its parent node.

Note

Since preferences nodes are owned by their parents, this preferences node is immediately deleted after removal.

Implements mitk::IPreferences.

RemoveOverride()

void mitk::Preferences::RemoveOverride ( const std::string &  key )

overridevirtual

Remove a session-only override for a property.

The underlying persistent value is revealed again.

Implements mitk::IPreferences.

Root() [1/2]

const IPreferences* mitk::Preferences::Root ( ) const

overridevirtual

See also

Root()

Implements mitk::IPreferences.

Root() [2/2]

IPreferences* mitk::Preferences::Root ( )

overridevirtual

Get the root preferences node.

Implements mitk::IPreferences.

---

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

• mitkPreferences.h