1 /* * This file is part of Maliit framework *
2  *
3  * Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
4  * All rights reserved.
5  *
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License version 2.1 as published by the Free Software Foundation
10  * and appearing in the file LICENSE.LGPL included in the packaging
11  * of this file.
12  */
13 
14 #ifndef MIMSETTINGS_H
15 #define MIMSETTINGS_H
16 
17 #ifndef MALIIT_FRAMEWORK_USE_INTERNAL_API
18 #error Internal API only.
19 #else
20 
21 #include <QVariant>
22 #include <QStringList>
23 #include <QObject>
24 #include <QScopedPointer>
25 
26 
27 //! \internal
28 
29 /*!
30   \ingroup maliitserver
31   \brief Implements a storage backend for MImSettings
32 */
33 class MImSettingsBackend : public QObject
34 {
35     Q_OBJECT
36 
37 public:
38     /*! Initialized a MImSettingsBackend.
39      */
40     explicit MImSettingsBackend(QObject *parent = 0);
41 
42     /*! Finalizes a MImSettingsBackend.
43      */
44     virtual ~MImSettingsBackend();
45 
46     /*! Returns the key of this item, as given to MImSettings constructor.
47 
48         \sa MImSettings::key()
49      */
50     virtual QString key() const = 0;
51 
52     /*! Returns the current value of this item, as a QVariant.  If
53         there is no value for this item, return \a def instead.
54 
55         The implementation is:
56         - return the value associated to the key (if present)
57         - otherwise return the value listed in MImSettings::getDefaults()
58           (if present)
59         - otherwise return the passed-in default value
60 
61         \sa MImSettings::value()
62      */
63     virtual QVariant value(const QVariant &def) const = 0;
64 
65     /*! Set the value of this item to \a val.
66 
67         Must emit valueChanged() if the new value differs from the old one.
68 
69         \param val  The new value (is always a valid QVariant).
70 
71         \sa MImSettings::set()
72     */
73     virtual void set(const QVariant &val) = 0;
74 
75     /*! Unset this item.
76 
77         Must emit valueChanged() if it deletes the entry.
78 
79         This backend method is called both for MImSettings::unset()
80         and MImSettings::set(QVariant()).
81 
82         \sa MImSettings::unset()
83         \sa MImSettings::set()
84      */
85     virtual void unset() = 0;
86 
87     /*! Return a list of the directories below this item.  The
88         returned strings are absolute key names like
89         "/myapp/settings".
90 
91         A directory is a key that has children.
92 
93         \sa MImSettings::listDirs()
94     */
95     virtual QList<QString> listDirs() const = 0;
96 
97     /*! Return a list of entries below this item.  The returned
98         strings are absolute key names like "/myapp/settings/first".
99 
100         A entry is a key that has a value.
101 
102         \sa MImSettings::listEntries()
103     */
104     virtual QList<QString> listEntries() const = 0;
105 
106 Q_SIGNALS:
107     /*! Emitted when the value is changed or unset.
108 
109         \sa MImSettingsBackend::valueChanged()
110     */
111     void valueChanged();
112 };
113 
114 
115 //! \internal
116 
117 /*!
118   \ingroup maliitserver
119   \brief Factory for MImSettings backend implementations
120 */
121 class MImSettingsBackendFactory
122 {
123 public:
124     /*! Creates a backend instance for the specified key.
125     */
126     virtual ~MImSettingsBackendFactory();
127     virtual MImSettingsBackend *create(const QString &key, QObject *parent) = 0;
128 };
129 
130 
131 //! \internal
132 
133 /*!
134   \ingroup maliitserver
135   \brief MImSettings is a generic interface to access configuration values
136 
137   Creating a MImSettings instance gives you access to a single configuration
138   key.  You can get and set its value, and connect to its
139   valueChanged() signal to be notified about changes.
140 
141   The value of the key is returned to you as a QVariant, and you
142   pass in a QVariant when setting the value.
143 
144   Before making use of MImSettings, you must call MImSettings::setPreferredSettingsType().
145 
146   \warning MImSettings is not reentrant.
147 */
148 
149 class MImSettings : public QObject
150 {
151     Q_OBJECT
152 
153 public:
154     enum SettingsType {
155         InvalidSettings,
156         TemporarySettings,
157         PersistentSettings
158     };
159 
160 public:
161     /*! Initializes a MImSettings to access the configuratin key denoted by
162         \a key.  Key names are formatted like Unix filesystem paths (es.
163         like "/myapp/settings/first").
164 
165         \param key    The name of the key.
166         \param parent Parent object
167     */
168     explicit MImSettings(const QString &key, QObject *parent = 0);
169 
170     /*! Finalizes a MImSettings.
171      */
172     virtual ~MImSettings();
173 
174     /*! Returns the key of this item, as given to the constructor.
175      */
176     QString key() const;
177 
178     /*! Returns the current value of this item, as a QVariant.
179      */
180     QVariant value() const;
181 
182     /*! Returns the current value of this item, as a QVariant.  If
183      *  there is no value for this item, return \a def instead.
184      */
185     QVariant value(const QVariant &def) const;
186 
187     /*! Set the value of this item to \a val.  If string \a val fails
188         for any reason, the current value is not changed and nothing happens.
189 
190         When the new value is different from the old value, the
191         changedValue() signal is emitted on this MImSettings and on all
192         other MImSettings instances for the same key.
193 
194         Depending on the backend, the signals might be emitted immediatly
195         or the next time the main event loop runs.
196 
197         \param val  The new value.
198     */
199     void set(const QVariant &val);
200 
201     /*! Unset this item.  This is equivalent to
202 
203         \code
204         item.set(QVariant(QVariant::Invalid));
205         \endcode
206      */
207     void unset();
208 
209     /*! Return a list of the directories below this item.  The
210         returned strings are absolute key names like
211         "/myapp/settings".
212 
213         A directory is a key that has children.  The same key might
214         also have a value, but that is confusing and best avoided.
215     */
216     QList<QString> listDirs() const;
217 
218     /*! Return a list of entries below this item.  The returned
219         strings are absolute key names like "/myapp/settings/first".
220 
221         A entry is a key that has a value.  The same key might also
222         have children, but that is confusing and is best avoided.
223     */
224     QList<QString> listEntries() const;
225 
226     /*! Set the factory used to create backend implementations.
227 
228         Should be called at most once at startup, and is meant to be used
229         only for tests. Takes ownership of the passed instance.
230     */
231     static void setImplementationFactory(MImSettingsBackendFactory *factory);
232 
233     /*! Set the preferred settings type for backend implementations
234      *
235      * Should be called at most once at startup, before creating MImSetting instances.
236      * This is not honored if using setImplementationFactory() manually.
237      */
238     static void setPreferredSettingsType(SettingsType setting);
239 
240     /*! Return the default values used for some keys
241     */
242     static QHash<QString, QVariant> defaults();
243 
244 Q_SIGNALS:
245     /*! Emitted when the value of this item has changed.
246      */
247     void valueChanged();
248 
249 private:
250     QScopedPointer<MImSettingsBackend> backend;
251     static QScopedPointer<MImSettingsBackendFactory> factory;
252     static SettingsType preferredSettingsType;
253 };
254 
255 //! \internal_end
256 
257 #endif // MALIIT_FRAMEWORK_USE_INTERNAL_API
258 
259 #endif // MIMSETTINGS_H
260