File indexing completed on 2024-05-12 09:39:13

0001 /*
0002  * SPDX-FileCopyrightText: 2009 Nokia Corporation.
0003  * SPDX-FileCopyrightText: 2016 David Edmundson <davidedmundson@kde.org>
0004  *
0005  * Contact: Marius Vollmer <marius.vollmer@nokia.com>
0006  *
0007  * SPDX-License-Identifier: LGPL-2.1-only
0008  *
0009  */
0010 
0011 #ifndef GCONFITEM_H
0012 #define GCONFITEM_H
0013 
0014 #include <QObject>
0015 #include <QStringList>
0016 #include <QVariant>
0017 
0018 /*!
0019 
0020   \brief GConfItem is a simple C++ wrapper for GConf.
0021 
0022   Creating a GConfItem instance gives you access to a single GConf
0023   key.  You can get and set its value, and connect to its
0024   valueChanged() signal to be notified about changes.
0025 
0026   The value of a GConf key is returned to you as a QVariant, and you
0027   pass in a QVariant when setting the value.  GConfItem converts
0028   between a QVariant and GConf values as needed, and according to the
0029   following rules:
0030 
0031   - A QVariant of type QVariant::Invalid denotes an unset GConf key.
0032 
0033   - QVariant::Int, QVariant::Double, QVariant::Bool are converted to
0034     and from the obvious equivalents.
0035 
0036   - QVariant::String is converted to/from a GConf string and always
0037     uses the UTF-8 encoding.  No other encoding is supported.
0038 
0039   - QVariant::StringList is converted to a list of UTF-8 strings.
0040 
0041   - QVariant::List (which denotes a QList<QVariant>) is converted
0042     to/from a GConf list.  All elements of such a list must have the
0043     same type, and that type must be one of QVariant::Int,
0044     QVariant::Double, QVariant::Bool, or QVariant::String.  (A list of
0045     strings is returned as a QVariant::StringList, however, when you
0046     get it back.)
0047 
0048   - Any other QVariant or GConf value is essentially ignored.
0049 
0050   - This is fored by Dave from libqtgconf to really reduce the amount of QObjects needed
0051     to manipulate various items in a tree.
0052 
0053 
0054   \warning GConfItem is as thread-safe as GConf.
0055 
0056 */
0057 
0058 class GConfItem : public QObject
0059 {
0060     Q_OBJECT
0061 
0062 public:
0063     /*! Initializes a GConfItem to access the GConf key denoted by
0064         \a key.  Key names should follow the normal GConf conventions
0065         like "/myapp/settings/first".
0066 
0067         \param key    The name of the key.
0068         \param parent Parent object
0069     */
0070     explicit GConfItem(const QString &keyRoot, QObject *parent = nullptr);
0071 
0072     /*! Finalizes a GConfItem.
0073      */
0074     ~GConfItem() override;
0075 
0076     /*! Returns the root of this item, as given to the constructor.
0077      */
0078     QString root() const;
0079 
0080     /*! Returns the current value of this item, as a QVariant.
0081      * subkey is relative to the provided root.
0082      */
0083     QVariant value(const QString &subKey) const;
0084 
0085     /*! Returns the current value of this item, as a QVariant.  If
0086      *  there is no value for this item, return \a def instead.
0087 
0088     */
0089     void set(const QString &subKey, const QVariant &val);
0090 
0091     /*! Return a list of the directories below this item.  The
0092         returned strings are absolute key names like
0093         "/myapp/settings".
0094 
0095         A directory is a key that has children.  The same key might
0096         also have a value, but that is confusing and best avoided.
0097     */
0098     QList<QString> listDirs() const;
0099 
0100     /*! Return a list of entries below this item.  The returned
0101         strings are absolute key names like "/myapp/settings/first".
0102 
0103         A entry is a key that has a value.  The same key might also
0104         have children, but that is confusing and is best avoided.
0105     */
0106     QList<QString> listEntries() const;
0107 
0108 Q_SIGNALS:
0109     /*! Emitted when some value in subtree of this item changes
0110      */
0111 
0112     void subtreeChanged(const QString &key, const QVariant &value);
0113 
0114 private:
0115     friend struct GConfItemPrivate;
0116     struct GConfItemPrivate *priv;
0117 
0118     void update_value(bool emit_signal, const QString &key, const QVariant &value);
0119 };
0120 
0121 #endif // GCONFITEM_H