Medical Imaging Interaction Toolkit  2024.12.99-0da743f6
Medical Imaging Interaction Toolkit
mitk::IPreferences Class Referenceabstract

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 IPreferencesParent ()=0
 Get the parent preferences node or nullptr in case of the root node. More...
 
virtual const IPreferencesParent () const =0
 
virtual IPreferencesRoot ()=0
 Get the root preferences node. More...
 
virtual const IPreferencesRoot () const =0
 
virtual IPreferencesNode (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
keyName of the property
defDefault 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
keyName of the property
defRaw pointer to the default binary data or nullptr
sizeSize 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
ExceptionThe 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
ExceptionThe 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
ExceptionThe 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
keyName of the property
arrayRaw pointer to binary data
sizeSize 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
keyName 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: