ism/src/scim_config_base.h

   1 /** @file scim_config_base.h
   2  *  @brief scim::ConfigBase Interface.
   3  *
   4  *  Provide a unified interface to access the configuration data.
   5  *  All of SCIM objects should use this interface if they have any
   6  *  configuration data.
   7  */
   8
   9 /* ISF is based on SCIM 1.4.7 and extended for supporting more mobile fitable. */
  10
  11 /*
  12  * Smart Common Input Method
  13  *
  14  * Copyright (c) 2002-2005 James Su <suzhe@tsinghua.org.cn>
  15  *
  16  *
  17  * This library is free software; you can redistribute it and/or
  18  * modify it under the terms of the GNU Lesser General Public
  19  * License as published by the Free Software Foundation; either
  20  * version 2 of the License, or (at your option) any later version.
  21  *
  22  * This library is distributed in the hope that it will be useful,
  23  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  24  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  25  * GNU Lesser General Public License for more details.
  26  *
  27  * You should have received a copy of the GNU Lesser General Public
  28  * License along with this program; if not, write to the
  29  * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  30  * Boston, MA  02111-1307  USA
  31  *
  32  * $Id: scim_config_base.h,v 1.22 2005/04/09 15:38:39 suzhe Exp $
  33  */
  34
  35 #ifndef __SCIM_CONFIG_BASE_H
  36 #define __SCIM_CONFIG_BASE_H
  37
  38 namespace scim {
  39 /**
  40  * @addtogroup Config
  41  * @ingroup InputServiceFramework
  42  * The base classes for config modules
  43  * @{
  44  */
  45
  46 /**
  47  * @brief An exception class to hold Config related errors.
  48  *
  49  * scim::ConfigBase and its derived classes must throw
  50  * scim::ConfigError object when error.
  51  */
  52 class ConfigError: public Exception
  53 {
  54 public:
  55     ConfigError (const String& what_arg)
  56         : Exception (String("scim::Config: ") + what_arg) { }
  57 };
  58
  59 class ConfigBase;
  60 /**
  61  * @typedef typedef Pointer <ConfigBase> ConfigPointer;
  62  *
  63  * A smart pointer for scim::ConfigBase and its derived classes.
  64  */
  65 typedef Pointer <ConfigBase> ConfigPointer;
  66
  67 /**
  68  * @typedef typedef Slot1<void, const ConfigPointer &> ConfigSlotVoid;
  69  *
  70  * The slot type to connect to the coresponding signal.
  71  */
  72 typedef Slot1<void, const ConfigPointer &> ConfigSlotVoid;
  73
  74 /**
  75  * @typedef typedef Signal1<void, const ConfigPointer &> ConfigSignalVoid;
  76  *
  77  * The signal type to connect with the ConfigSlotVoid slot type.
  78  */
  79 typedef Signal1<void, const ConfigPointer &> ConfigSignalVoid;
  80
  81 /**
  82  * @brief The interface class to access the configuration data.
  83  *
  84  * This is an interface class to access the configuration data.
  85  * All of the SCIM objects which have configuration data should
  86  * use this interface to store and load them.
  87  */
  88 class ConfigBase : public ReferencedObject
  89 {
  90     ConfigSignalVoid m_signal_reload;
  91
  92 public:
  93     /**
  94      * @name Constructor and Destructor.
  95      * @{
  96      */
  97
  98     /**
  99      * @brief Contrustor
 100      */
 101     ConfigBase ();
 102
 103     /**
 104      * @brief Virtual destructor
 105      * empty but ensures that dtor of all derived classes is virtual
 106      */
 107     virtual ~ConfigBase ();
 108
 109     /**
 110      * @}
 111      */
 112
 113     /**
 114      * @name Pure virtual methods which should be implemented in derived classes.
 115      * @{
 116      */
 117
 118     /**
 119      * @brief Check if this Config object is valid.
 120      * @return true if its valid and ready to work.
 121      */
 122     virtual bool valid () const = 0;
 123
 124     /**
 125      * @brief Return the name of this configuration module.
 126      *
 127      * This name must be same as the config module's name.
 128      */
 129     virtual String get_name () const = 0;
 130
 131     /**
 132      * @brief Read a string from the given key.
 133      * @param key - the key to be read.
 134      * @param ret - the result will be stored into *ret.
 135      * @return true if the string is read successfully, otherwise return false.
 136      */
 137     virtual bool read (const String& key, String *ret) const = 0;
 138
 139     /**
 140      * @brief Read an int value from the given key.
 141      * @param key - the key to be read.
 142      * @param ret - the result will be stored into *ret.
 143      * @return true if the value is read successfully, otherwise return false.
 144      */
 145     virtual bool read (const String& key, int *ret) const = 0;
 146
 147     /**
 148      * @brief Read a double value from the given key.
 149      * @param key - the key to be read.
 150      * @param ret - the result will be stored into *ret.
 151      * @return true if the value is read successfully, otherwise return false.
 152      */
 153     virtual bool read (const String& key, double *ret) const = 0;
 154
 155     /**
 156      * @brief Read a bool value from the given key.
 157      * @param key - the key to be read.
 158      * @param ret - the result will be stored into *ret.
 159      * @return true if the value is read successfully, otherwise return false.
 160      */
 161     virtual bool read (const String& key, bool *ret) const = 0;
 162
 163     /**
 164      * @brief Read a string list from the given key.
 165      * @param key - the key to be read.
 166      * @param ret - the result will be stored into *ret.
 167      * @return true if the string list is read successfully, otherwise return false.
 168      */
 169     virtual bool read (const String& key, std::vector <String> *ret) const = 0;
 170
 171     /**
 172      * @brief Read an int list from the given key.
 173      * @param key - the key to be read.
 174      * @param ret - the result will be stored into *ret.
 175      * @return true if the int list is read successfully, otherwise return false.
 176      */
 177     virtual bool read (const String& key, std::vector <int> *ret) const = 0;
 178
 179     /**
 180      * @brief Write a string to the given key.
 181      * @param key   - the key to be written.
 182      * @param value - the string to be written to the key.
 183      * @return true if success, otherwise false.
 184      */
 185     virtual bool write (const String& key, const String& value) = 0;
 186
 187     /**
 188      * @brief Write an int value to the given key.
 189      * @param key   - the key to be written.
 190      * @param value - the int value to be written to the key.
 191      * @return true if success, otherwise false.
 192      */
 193     virtual bool write (const String& key, int value) = 0;
 194
 195     /**
 196      * @brief Write a double value to the given key.
 197      * @param key   - the key to be written.
 198      * @param value - the double value to be written to the key.
 199      * @return true if success, otherwise false.
 200      */
 201     virtual bool write (const String& key, double value) = 0;
 202
 203     /**
 204      * @brief Write a bool value to the given key.
 205      * @param key   - the key to be written.
 206      * @param value - the bool value to be written to the key.
 207      * @return true if success, otherwise false.
 208      */
 209     virtual bool write (const String& key, bool value) = 0;
 210
 211     /**
 212      * @brief Write a string list to the given key.
 213      * @param key   - the key to be written.
 214      * @param value - the string list to be written to the key.
 215      * @return true if success, otherwise false.
 216      */
 217     virtual bool write (const String& key, const std::vector <String>& value) = 0;
 218
 219     /**
 220      * @brief Write an int list to the given key.
 221      * @param key   - the key to be written.
 222      * @param value - the int list to be written to the key.
 223      * @return true if success, otherwise false.
 224      */
 225     virtual bool write (const String& key, const std::vector <int>& value) = 0;
 226
 227     /**
 228      * @brief Permanently writes all changes.
 229      * @return true if success.
 230      */
 231     virtual bool flush() = 0;
 232
 233     /**
 234      * @brief Erase a key and its value
 235      * @param key - the key to be erased.
 236      * @return true if success.
 237      */
 238     virtual bool erase (const String& key) = 0;
 239
 240     /**
 241      * @brief Reload the configurations from storage.
 242      *
 243      * All modified keys after the last flush maybe lost.
 244      *
 245      * The derived method should call this base method
 246      * after reload the configurations successfully,
 247      * in order to emit the reload signal.
 248      *
 249      * The derived method should have some machanism to avoid
 250      * reload again if there is no update after
 251      * the previous reload.
 252      *
 253      * @return true if success.
 254      */
 255     virtual bool reload () = 0;
 256
 257     /**
 258      * @}
 259      */
 260
 261     /**
 262      * @name Other helper methods.
 263      * @{
 264      */
 265
 266     /**
 267      * @brief Read a string from the given key with a default fallback value.
 268      *
 269      * If failed to read from the given key, then return the given default value.
 270      *
 271      * @param key    - the key to be read.
 272      * @param defVal - the default value to be return if failed to read.
 273      * @return The result string.
 274      */
 275     String read (const String& key, const String& defVal = String ()) const;
 276
 277     /**
 278      * @brief Read an int value from the given key with a default fallback value.
 279      *
 280      * If failed to read from the given key, then return the given default value.
 281      *
 282      * @param key    - the key to be read.
 283      * @param defVal - the default value to be return if failed to read.
 284      * @return The result int value.
 285      */
 286     int read (const String& key, int defVal) const;
 287
 288     /**
 289      * @brief Read a double value from the given key with a default fallback value.
 290      *
 291      * If failed to read from the given key, then return the given default value.
 292      *
 293      * @param key    - the key to be read.
 294      * @param defVal - the default value to be return if failed to read.
 295      * @return The result double value.
 296      */
 297     double read (const String& key, double defVal) const;
 298
 299     /**
 300      * @brief Read a bool value from the given key with a default fallback value.
 301      *
 302      * If failed to read from the given key, then return the given default value.
 303      *
 304      * @param key    - the key to be read.
 305      * @param defVal - the default value to be return if failed to read.
 306      * @return The result bool value.
 307      */
 308     bool read (const String& key, bool defVal) const;
 309
 310     /**
 311      * @brief Read a string list from the given key with a default fallback value.
 312      *
 313      * If failed to read from the given key, then return the given default value.
 314      *
 315      * @param key    - the key to be read.
 316      * @param defVal - the default value to be return if failed to read.
 317      * @return The result string list.
 318      */
 319     std::vector <String> read (const String& key, const std::vector <String>& defVal) const;
 320
 321     /**
 322      * @brief Read an int list from the given key with a default fallback value.
 323      *
 324      * If failed to read from the given key, then return the given default value.
 325      *
 326      * @param key    - the key to be read.
 327      * @param defVal - the default value to be return if failed to read.
 328      * @return The result int list.
 329      */
 330     std::vector <int> read (const String& key, const std::vector <int>& defVal) const;
 331
 332     /**
 333      * @brief connect the given slot to the reload signal.
 334      * @param slot - the given slot to be connected.
 335      * @return the Connection object, can be used to disconnect this slot.
 336      */
 337     Connection signal_connect_reload (ConfigSlotVoid *slot);
 338
 339     /** @} */
 340
 341 public:
 342     /**
 343      * @brief Set the default global Config object.
 344      *
 345      * There is only one global Config object in an application.
 346      * All other objects should use it by default.
 347      *
 348      * @param p_config - a smart pointer to the Config object.
 349      * @return a smart pointer to the old default Config object.
 350      */
 351     static ConfigPointer set (const ConfigPointer &p_config);
 352
 353     /**
 354      * @brief Get the default global Config object.
 355      *
 356      * The default global Config object can be set with function ConfigBase::set.
 357      * If there is no default object set, a new object can be created if needed.
 358      *
 359      * @param create_on_demand - if it's true then a new object will be created,
 360      *                           if there is no one available.
 361      * @param default_module   - the Config module should be used to create the
 362      *                           default Config object. If omitted, then use the
 363      *                           default module defined in global config file.
 364      * @return a smart pointer to the default global Config object.
 365      */
 366     static ConfigPointer get (bool create_on_demand = true,
 367                               const String &default_module = String (""));
 368 };
 369
 370 /**
 371  * @brief A dummy implementation of interface class scim::ConfigBase.
 372  *
 373  * The read methods will just return false and the default value (if available).
 374  * The write methods will do nothing.
 375  */
 376 class DummyConfig : public ConfigBase
 377 {
 378
 379 public:
 380     DummyConfig ();
 381
 382     virtual ~DummyConfig ();
 383
 384     virtual bool valid () const;
 385     virtual String get_name () const;
 386
 387     virtual bool read (const String& key, String *ret) const;
 388     virtual bool read (const String& key, int *ret) const;
 389     virtual bool read (const String& key, double *ret) const;
 390     virtual bool read (const String& key, bool *ret) const;
 391     virtual bool read (const String& key, std::vector <String> *ret) const;
 392     virtual bool read (const String& key, std::vector <int> *ret) const;
 393
 394     virtual bool write (const String& key, const String& value);
 395     virtual bool write (const String& key, int value);
 396     virtual bool write (const String& key, double value);
 397     virtual bool write (const String& key, bool value);
 398     virtual bool write (const String& key, const std::vector <String>& value);
 399     virtual bool write (const String& key, const std::vector <int>& value);
 400
 401     virtual bool flush();
 402
 403     virtual bool erase (const String& key );
 404
 405     virtual bool reload ();
 406 };
 407
 408 /** @} */
 409
 410 } // namespace scim
 411
 412 #endif //__SCIM_CONFIG_BASE_H
 413 /*
 414 vi:ts=4:nowrap:ai:expandtab
 415 */