digiKam Developer Documentation: Digikam::StateSavingObject Class Reference

| digiKam Developer Documentation Professional Photo Management with the Power of Open Source

Loading...
Searching...
No Matches
Public Types | Public Member Functions | Protected Member Functions | List of all members
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

enum Digikam::StateSavingObject::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

  host | self-reference to access the object name, simply pass "this" as argument

## Member Function Documentation

## ◆ doLoadState()

virtual void Digikam::StateSavingObject::doLoadState | ( |  | ) |
| protectedpure virtual

Use getConfigGroup() and entryName() for the implementation.

Implemented in Digikam::DateFolderView, Digikam::FilterSideBarWidget, Digikam::AlbumFolderViewSideBarWidget, Digikam::DateFolderViewSideBarWidget, Digikam::FuzzySearchSideBarWidget, Digikam::GPSSearchSideBarWidget, Digikam::LabelsSideBarWidget, Digikam::PeopleSideBarWidget, Digikam::SearchSideBarWidget, Digikam::TagViewSideBarWidget, Digikam::TimelineSideBarWidget, Digikam::MapWidgetView, Digikam::TrashView, Digikam::TableView, Digikam::AbstractAlbumTreeView, Digikam::AbstractCheckableAlbumTreeView, Digikam::LabelsTreeView, Digikam::FaceScanWidget, Digikam::ImageQualityWidget, Digikam::ImportItemPropertiesSideBarImport, Digikam::ItemPropertiesSideBar, Digikam::ItemPropertiesSideBarDB, Digikam::AutotagsScanWidget, Digikam::TagsManager, Digikam::TagCheckView, Digikam::Sidebar, Digikam::SearchTextBar, ShowFoto::ShowfotoFolderViewSideBar, ShowFoto::ShowfotoStackViewSideBar, Digikam::FuzzySearchView, and Digikam::GPSSearchView.

## ◆ doSaveState()

virtual void Digikam::StateSavingObject::doSaveState | ( |  | ) |
| protectedpure virtual

Use getConfigGroup() and entryName() for the implementation.

Implemented in Digikam::DateFolderView, Digikam::FilterSideBarWidget, Digikam::AlbumFolderViewSideBarWidget, Digikam::DateFolderViewSideBarWidget, Digikam::FuzzySearchSideBarWidget, Digikam::GPSSearchSideBarWidget, Digikam::LabelsSideBarWidget, Digikam::PeopleSideBarWidget, Digikam::SearchSideBarWidget, Digikam::TagViewSideBarWidget, Digikam::TimelineSideBarWidget, Digikam::MapWidgetView, Digikam::TrashView, Digikam::TableView, Digikam::AbstractAlbumTreeView, Digikam::AbstractCheckableAlbumTreeView, Digikam::LabelsTreeView, Digikam::FaceScanWidget, Digikam::ImageQualityWidget, Digikam::ImportItemPropertiesSideBarImport, Digikam::ItemPropertiesSideBar, Digikam::ItemPropertiesSideBarDB, Digikam::AutotagsScanWidget, Digikam::TagsManager, Digikam::TagCheckView, Digikam::Sidebar, Digikam::SearchTextBar, ShowFoto::ShowfotoFolderViewSideBar, ShowFoto::ShowfotoStackViewSideBar, Digikam::FuzzySearchView, and Digikam::GPSSearchView.

## ◆ entryName()

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

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

Parameters

  base | original 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

  group | config 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

  prefix | the prefix to use for the config entries

## ◆ setStateSavingDepth()

void Digikam::StateSavingObject::setStateSavingDepth | ( | const StateSavingDepth | depth | ) |

Parameters

  depth | new depth to use