Perceptual Color

settings.h
1// SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
2// SPDX-License-Identifier: BSD-2-Clause OR MIT
3
4#ifndef SETTINGS_H
5#define SETTINGS_H
6
7#include <qfilesystemwatcher.h>
8#include <qglobal.h>
9#include <qobject.h>
10#include <qsettings.h>
11#include <qstring.h>
12
13#if (QT_VERSION >= QT_VERSION_CHECK(6, 0, 0))
14#include <qtmetamacros.h>
15#else
16#include <qobjectdefs.h>
17#endif
18
19namespace PerceptualColor
20{
21
22/** @internal
23 *
24 * @brief Represents the settings file and allows for inter-process
25 * communication of changes.
26 *
27 * This object provides persistent, platform-independent settings and writes
28 * changes to the settings file relatively quickly. Changes made to the
29 * settings file by other processes are read in immediately, and the
30 * corresponding NOTIFY signal is emitted for changed properties.
31 *
32 * Usage: The functionality is based on a tight collaboration between
33 * @ref Settings, @ref Setting and @ref SettingBase. To use it, subclass
34 * @ref Settings and add public data members of type @ref Setting for each
35 * setting you want to use. It might be useful to implement the subclass as
36 * a singleton. Example:
37 *
38 * Header:
39 * @include src/perceptualsettings.h
40 *
41 * Source:
42 * @include src/perceptualsettings.cpp
43 *
44 * @warning This object is not thread-safe.
45 * It must only be used in the main (widget) thread!
46 *
47 * @note For more sophisticated use cases requiring
48 * type-safe access to <tt>QSettings</tt>, there are
49 * <a href="https://www.vikingsoftware.com/blog/more-type-safety-with-qsettings/">
50 * alternative approaches available</a>, but they may be overkill for our
51 * limited requirements here. */
52class Settings : public QObject
53{
55
56public:
57 Settings(QSettings::Scope scope, const QString &organization, const QString &application);
58 virtual ~Settings() override;
59 // Prevent copy and assignment operations to force that only references
60 // to the instance are possible.
61 Settings(const Settings &) = delete;
62 Settings &operator=(const Settings &) = delete;
63
65 /** @brief The underlying file has changed.
66 *
67 * Notify that underlying file has changed and that @ref m_qSettings has
68 * been forced to synchronize with the underlying file again.
69 *
70 * The setting values in @ref m_qSettings might or might not have changed.
71 * This underlying file might have been changed by <em>this</em> process
72 * or by <em>another</em> process. */
73 void updatedAfterFileChange();
74
75private:
76 /** @brief The internal QSettings object. */
77 QSettings m_qSettings;
78 /** @brief A watcher for the file used by @ref m_qSettings.
79 *
80 * This allows to react immediately to settings changes done by other
81 * applications using this library. This is also useful as simple but
82 * cross-platform inter-process communication for synchronizing for
83 * example custom colors between various simultaneously running
84 * applications using this library. */
85 QFileSystemWatcher m_watcher;
86
87 void updateFromFile();
88
89 /** @internal @brief Only for unit tests. */
90 friend class TestSettings;
91
92 /** @internal @brief @ref Settings, @ref SettingBase and @ref Setting have
93 * tight collaboration. */
94 friend class SettingBase;
95};
96
97} // namespace PerceptualColor
98
99#endif // SETTINGS_H
The namespace of this library.
Q_OBJECTQ_OBJECT
Q_SIGNALSQ_SIGNALS
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 11:48:43 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.