mitk::IPreferences Class Reference

Interface to application preferences. More...

#include <mitkIPreferences.h>

Inheritance diagram for mitk::IPreferences:

Collaboration diagram for mitk::IPreferences:

Classes
class	ChangeEvent
	Event object sent on IPreferences::OnPropertyChanged events. More...

Public Member Functions
virtual	~IPreferences ()
virtual std::string	Get (const std::string &key, const std::string &def) const =0
	Get a property value as string. More...
virtual void	Put (const std::string &key, const std::string &value)=0
	Set a property value. More...
virtual int	GetInt (const std::string &key, int def) const =0
	Get a property value as int. More...
virtual void	PutInt (const std::string &key, int value)=0
	Set an int property value. More...
virtual bool	GetBool (const std::string &key, bool def) const =0
	Get a property value as bool. More...
virtual void	PutBool (const std::string &key, bool value)=0
	Set a bool property value. More...
virtual float	GetFloat (const std::string &key, float def) const =0
	Get a property value as float. More...
virtual void	PutFloat (const std::string &key, float value)=0
	Set a float property value. More...
virtual double	GetDouble (const std::string &key, double def) const =0
	Get a property value as double. More...
virtual void	PutDouble (const std::string &key, double value)=0
	Set a double property value. More...
virtual std::vector< std::byte >	GetByteArray (const std::string &key, const std::byte *def, size_t size) const =0
	Get a property value as typeless binary representation. More...
virtual void	PutByteArray (const std::string &key, const std::byte *array, size_t size)=0
	Put binary data into a property value. More...
virtual void	Flush ()=0
	Write all (!) preferences to disk. More...
virtual void	Remove (const std::string &key)=0
	Remove a property from this preferences node. More...
virtual void	Clear ()=0
	Remove all properties from this preferences node. More...
virtual std::vector< std::string >	Keys () const =0
	Get the names of all properties of this preferences node. More...
virtual std::string	Name () const =0
	Get the name of this preferences node. More...
virtual std::string	AbsolutePath () const =0
	Get the absolute path (relative to the root node) of this preferences node. More...
virtual std::vector< std::string >	ChildrenNames () const =0
	Get the names of all direct child preference nodes. More...
virtual IPreferences *	Parent ()=0
	Get the parent preferences node or nullptr in case of the root node. More...
virtual const IPreferences *	Parent () const =0
virtual IPreferences *	Root ()=0
	Get the root preferences node. More...
virtual const IPreferences *	Root () const =0
virtual IPreferences *	Node (const std::string &path)=0
	Get (and possibly create) the preferences node specified by the given path. More...
virtual void	RemoveNode ()=0
	Remove this preferences node from its parent node. More...

Public Attributes
Message1< const IPreferences * >	OnChanged
	Notify on node changes. More...
Message1< const ChangeEvent & >	OnPropertyChanged
	Notify on property changes. More...

Detailed Description

Interface to application preferences.

Preferences are implemented as nodes in a tree structure. Each preference node may consist of properties, i.e. key-value pairs, and child preferences nodes. The lifetime of nodes is managed by their respective parent node.

Use CoreServices::GetPreferencesService() and IPreferencesService::GetSystemPreferences() to access the application preferences, i.e. the preferences root node.

Use the Node() method to traverse through the tree.

Getters and setters for various data types, e.g. GetInt() and PutInt(), are provided to conveniently access properties as their intended data types. All preferences are ultimately stored as strings.

Call Flush() to enforce the persistence of the whole (!) preferences tree. Preferences are flushed automatically at least on a regular application shutdown.

Changes of a preference node can be observed via IPreferences::OnChanged. Property changes of a preference node can be observed additionally via IPreferences::OnPropertyChanged.

See also

CoreServices::GetPreferencesService()

IPreferencesService

Definition at line 50 of file mitkIPreferences.h.

Constructor & Destructor Documentation

~IPreferences()

virtual mitk::IPreferences::~IPreferences ( )

virtual

Member Function Documentation

AbsolutePath()

virtual std::string mitk::IPreferences::AbsolutePath ( ) const

pure virtual

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

See also

Name() const

Node()

Implemented in mitk::Preferences.

ChildrenNames()

virtual std::vector<std::string> mitk::IPreferences::ChildrenNames ( ) const

pure virtual

Get the names of all direct child preference nodes.

Implemented in mitk::Preferences.

Clear()

virtual void mitk::IPreferences::Clear ( )

pure virtual

Remove all properties from this preferences node.

Implemented in mitk::Preferences.

Flush()

virtual void mitk::IPreferences::Flush ( )

pure virtual

Write all (!) preferences to disk.

Enforce the persistence of the whole preferences tree.

Note

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

See also

IPreferencesStorage::Flush()

Implemented in mitk::Preferences.

Get()

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

pure virtual

Get a property value as string.

If the property cannot be found, return the provided default value instead.

Parameters

key	Name of the property
def	Default value

Returns

Property value or default value

Implemented in mitk::Preferences.

GetBool()

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

pure virtual

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.

Implemented in mitk::Preferences.

GetByteArray()

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

pure virtual

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.

Implemented in mitk::Preferences.

GetDouble()

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

pure virtual

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.

Implemented in mitk::Preferences.

GetFloat()

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

pure virtual

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.

Implemented in mitk::Preferences.

GetInt()

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

pure virtual

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.

Implemented in mitk::Preferences.

Keys()

virtual std::vector<std::string> mitk::IPreferences::Keys ( ) const

pure virtual

Get the names of all properties of this preferences node.

Implemented in mitk::Preferences.

Name()

virtual std::string mitk::IPreferences::Name ( ) const

pure virtual

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()

Implemented in mitk::Preferences.

Node()

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

pure virtual

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

Implemented in mitk::Preferences.

Parent() [1/2]

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

pure virtual

See also

Parent()

Implemented in mitk::Preferences.

Parent() [2/2]

virtual IPreferences* mitk::IPreferences::Parent ( )

pure virtual

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

Implemented in mitk::Preferences.

Put()

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

pure virtual

Set a property value.

Create the property if not yet existent. Otherwise change its value.

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.

Implemented in mitk::Preferences.

PutBool()

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

pure virtual

Set a bool property value.

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

Implemented in mitk::Preferences.

PutByteArray()

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

pure virtual

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

Implemented in mitk::Preferences.

PutDouble()

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

pure virtual

Set a double property value.

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

Implemented in mitk::Preferences.

PutFloat()

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

pure virtual

Set a float property value.

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

Implemented in mitk::Preferences.

PutInt()

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

pure virtual

Set an int property value.

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

Implemented in mitk::Preferences.

Remove()

virtual void mitk::IPreferences::Remove ( const std::string &  key )

pure virtual

Remove a property from this preferences node.

Parameters

key	Name of the property

Implemented in mitk::Preferences.

RemoveNode()

virtual void mitk::IPreferences::RemoveNode ( )

pure virtual

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.

Implemented in mitk::Preferences.

Root() [1/2]

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

pure virtual

See also

Root()

Implemented in mitk::Preferences.

Root() [2/2]

virtual IPreferences* mitk::IPreferences::Root ( )

pure virtual

Get the root preferences node.

Implemented in mitk::Preferences.

Member Data Documentation

OnChanged

Message1<const IPreferences*> mitk::IPreferences::OnChanged

Notify on node changes.

Definition at line 292 of file mitkIPreferences.h.

OnPropertyChanged

Message1<const ChangeEvent&> mitk::IPreferences::OnPropertyChanged

Notify on property changes.

Definition at line 293 of file mitkIPreferences.h.

---

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

• mitkIPreferences.h