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