digiKam Developer Documentation
Professional Photo Management with the Power of Open Source
Loading...
Searching...
No Matches
Digikam::StateSavingObject Class Referenceabstract

An interface-like class with utility methods and a general public interface to support state saving and restoring for objects via KConfig. More...

+ Inheritance diagram for Digikam::StateSavingObject:

Public Types

enum  StateSavingDepth { INSTANCE , DIRECT_CHILDREN , RECURSIVE }
 This enum defines the "depth" of the StateSavingObject::loadState() and StateSavingObject::saveState() methods. More...
 

Public Member Functions

 StateSavingObject (QObject *const host)
 Constructor.
 
virtual ~StateSavingObject ()
 Destructor.
 
StateSavingDepth getStateSavingDepth () const
 Returns the depth used for state saving or loading.
 
void loadState ()
 Invokes loading the class' state.
 
void saveState ()
 Invokes saving the class' state.
 
virtual void setConfigGroup (const KConfigGroup &group)
 Sets a dedicated config group that will be used to store and reload the state from.
 
virtual void setEntryPrefix (const QString &prefix)
 Define a prefix that will be used for every entry in the config group.
 
void setStateSavingDepth (const StateSavingDepth depth)
 Sets the depth used for state saving or loading.
 

Protected Member Functions

virtual void doLoadState ()=0
 Implement this hook method for state loading.
 
virtual void doSaveState ()=0
 Implement this hook method for state saving.
 
QString entryName (const QString &base) const
 Always use this method to create config group entry names.
 
KConfigGroup getConfigGroup () const
 Returns the config group that must be used for state saving and loading.
 

Detailed Description

Use this class as a Mixin.

The public interface for loading and saving state is implemented designed as template methods. To store or restore the state of a class, inherit from this class via multiple inheritance and implement doLoadState() and doSaveState(). In these methods always use the protected method getConfigGroup() to access a config group. Also always use the entryName() method for generating keys in the config (for prefixes, see below).

Ensure that this class is inherited after a QObject-based class and pass "this" as constructor argument.

By default a config group based on Qt's object name of the class is used. This behaviour can be changed by setting a dedicated config group via setConfigGroup(). This is useful for to externally control the config group and shouldn't be used inside the implementing class.

Additionally to setting the config group, also a prefix for each config group entry can be defined via setEntryPrefix(). This may be useful if multiple instances of the same class shall be stored in the same config group or can generally be a good idea to make the config more readable and recognizable. By default this prefix is empty.

This class also supports recursive saving / loading invocations based on the QT object hierarchy. As default, calls to loadState() or saveState() only invoke the doLoadState() or doStateSave() method of the called instance. This behaviour can be changed with setStateSavingDepth() to automatically call children of the instance. Various modes are supported as documented in StateSavingDepth.

Author
jwienke

Member Enumeration Documentation

◆ StateSavingDepth

Enumerator
INSTANCE 

Only the instance the saving / restoring was invoked on is saved / restored.

DIRECT_CHILDREN 

The instance itself and all direct children of this instance implementing StateSavingObject are saved / restored.

RECURSIVE 

The instance and all children in the complete hierarchy are saved / restored.

Constructor & Destructor Documentation

◆ StateSavingObject()

Digikam::StateSavingObject::StateSavingObject ( QObject *const  host)
explicit

Must be called after any QObject-based constructor.

Parameters
hostself-reference to access the object name, simply pass "this" as argument

Member Function Documentation

◆ doLoadState()

◆ doSaveState()

◆ entryName()

QString Digikam::StateSavingObject::entryName ( const QString &  base) const
protected

This allows to manipulate the entry keys externally by eg. setting a prefix.

Parameters
baseoriginal name planned for the config group entry
Returns
entry name after manipulating it with externally set parameters

◆ getConfigGroup()

KConfigGroup Digikam::StateSavingObject::getConfigGroup ( ) const
protected
Returns
config group for state saving and loading

◆ getStateSavingDepth()

StateSavingObject::StateSavingDepth Digikam::StateSavingObject::getStateSavingDepth ( ) const

Default is StateSavingDepth::INSTANCE.

Returns
state saving / restoring depth

◆ setConfigGroup()

void Digikam::StateSavingObject::setConfigGroup ( const KConfigGroup &  group)
virtual

If this method is not called, a group based on the object name is used.

You can re-implement this method to pass the group set here to child objects. Don't forget to call this method in your implementation.

Parameters
groupconfig group to use for state saving and restoring

Reimplemented in Digikam::DateFolderView, Digikam::FilterSideBarWidget, Digikam::FuzzySearchView, and Digikam::GPSSearchView.

◆ setEntryPrefix()

void Digikam::StateSavingObject::setEntryPrefix ( const QString &  prefix)
virtual

The default prefix is empty.

You can re-implement this method to pass the prefix set here to child objects. Don't forget to call this method in your implementation.

Parameters
prefixthe prefix to use for the config entries

◆ setStateSavingDepth()

void Digikam::StateSavingObject::setStateSavingDepth ( const StateSavingDepth  depth)
Parameters
depthnew depth to use