1 /****************************************************************************
3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
4 ** All rights reserved.
5 ** Contact: Nokia Corporation (qt-info@nokia.com)
7 ** This file is part of the Qt Mobility Components.
9 ** $QT_BEGIN_LICENSE:LGPL$
10 ** GNU Lesser General Public License Usage
11 ** This file may be used under the terms of the GNU Lesser General Public
12 ** License version 2.1 as published by the Free Software Foundation and
13 ** appearing in the file LICENSE.LGPL included in the packaging of this
14 ** file. Please review the following information to ensure the GNU Lesser
15 ** General Public License version 2.1 requirements will be met:
16 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
18 ** In addition, as a special exception, Nokia gives you certain additional
19 ** rights. These rights are described in the Nokia Qt LGPL Exception
20 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
22 ** GNU General Public License Usage
23 ** Alternatively, this file may be used under the terms of the GNU General
24 ** Public License version 3.0 as published by the Free Software Foundation
25 ** and appearing in the file LICENSE.GPL included in the packaging of this
26 ** file. Please review the following information to ensure the GNU General
27 ** Public License version 3.0 requirements will be met:
28 ** http://www.gnu.org/copyleft/gpl.html.
31 ** Alternatively, this file may be used in accordance with the terms and
32 ** conditions contained in a signed written agreement between you and Nokia.
40 ****************************************************************************/
46 #include <QStringList>
51 \brief GConfItem is a simple C++ wrapper for GConf.
53 Creating a GConfItem instance gives you access to a single GConf
54 key. You can get and set its value, and connect to its
55 valueChanged() signal to be notified about changes.
57 The value of a GConf key is returned to you as a QVariant, and you
58 pass in a QVariant when setting the value. GConfItem converts
59 between a QVariant and GConf values as needed, and according to the
62 - A QVariant of type QVariant::Invalid denotes an unset GConf key.
64 - QVariant::Int, QVariant::Double, QVariant::Bool are converted to
65 and from the obvious equivalents.
67 - QVariant::String is converted to/from a GConf string and always
68 uses the UTF-8 encoding. No other encoding is supported.
70 - QVariant::StringList is converted to a list of UTF-8 strings.
72 - QVariant::List (which denotes a QList<QVariant>) is converted
73 to/from a GConf list. All elements of such a list must have the
74 same type, and that type must be one of QVariant::Int,
75 QVariant::Double, QVariant::Bool, or QVariant::String. (A list of
76 strings is returned as a QVariant::StringList, however, when you
79 - Any other QVariant or GConf value is essentially ignored.
81 \warning GConfItem is as thread-safe as GConf.
85 class GConfItem : public QObject
90 /*! Initializes a GConfItem to access the GConf key denoted by
91 \a key. Key names should follow the normal GConf conventions
92 like "/myapp/settings/first".
94 \param key The name of the key.
95 \param parent Parent object
97 explicit GConfItem(const QString &key, QObject *parent = 0);
99 /*! Finalizes a GConfItem.
101 virtual ~GConfItem();
103 /*! Returns the key of this item, as given to the constructor.
107 /*! Returns the current value of this item, as a QVariant.
109 QVariant value() const;
111 /*! Returns the current value of this item, as a QVariant. If
112 * there is no value for this item, return \a def instead.
114 QVariant value(const QVariant &def) const;
116 /*! Set the value of this item to \a val. If \a val can not be
117 represented in GConf or GConf refuses to accept it for other
118 reasons, the current value is not changed and nothing happens.
120 When the new value is different from the old value, the
121 changedValue() signal is emitted on this GConfItem as part
122 of calling set(), but other GConfItem:s for the same key do
123 only receive a notification once the main loop runs.
125 \param val The new value.
127 void set(const QVariant &val);
129 /*! Unset this item. This is equivalent to
132 item.set(QVariant(QVariant::Invalid));
137 /*! Return a list of the directories below this item. The
138 returned strings are absolute key names like
141 A directory is a key that has children. The same key might
142 also have a value, but that is confusing and best avoided.
144 QList<QString> listDirs() const;
146 /*! Return a list of entries below this item. The returned
147 strings are absolute key names like "/myapp/settings/first".
149 A entry is a key that has a value. The same key might also
150 have children, but that is confusing and is best avoided.
152 QList<QString> listEntries() const;
155 /*! Emitted when the value of this item has changed.
160 friend struct GConfItemPrivate;
161 struct GConfItemPrivate *priv;
163 void update_value(bool emit_signal);
166 #endif // GCONFITEM_H