src/preferences.h

   1 /** @file
   2  * @brief  Singleton class to access the preferences file in a convenient way.
   3  */
   4 /* Authors:
   5  *   Krzysztof Kosi_ski <tweenk.pl@gmail.com>
   6  *   Jon A. Cruz <jon@joncruz.org>
   7  *
   8  * Copyright (C) 2008,2009 Authors
   9  *
  10  * Released under GNU GPL.  Read the file 'COPYING' for more information.
  11  */
  12
  13 #ifndef INKSCAPE_PREFSTORE_H
  14 #define INKSCAPE_PREFSTORE_H
  15
  16 #include <string>
  17 #include <map>
  18 #include <vector>
  19 #include <climits>
  20 #include <cfloat>
  21 #include <glibmm/ustring.h>
  22 #include "xml/xml-forward.h"
  23 #include "xml/repr.h"
  24
  25 class SPCSSAttr;
  26
  27 namespace Inkscape {
  28
  29 class ErrorReporter {
  30 public:
  31     virtual ~ErrorReporter() {}
  32     virtual void handleError(Glib::ustring const& primary, Glib::ustring const& secondary ) const = 0;
  33 };
  34
  35 /**
  36  * @brief Preference storage class.
  37  *
  38  * This is a singleton that allows one to access the user preferences stored in
  39  * the preferences.xml file. The preferences are stored in a file system-like
  40  * hierarchy. They are generally typeless - it's up to the programmer to ensure
  41  * that a given preference is always accessed as the correct type. The backend
  42  * is not guaranteed to be tolerant to type mismatches.
  43  *
  44  * Preferences are identified by paths similar to file system paths. Components
  45  * of the path are separated by a slash (/). As an additional requirement,
  46  * the path must start with a slash, and not contain a trailing slash.
  47  * An example of a correct path would be "/options/some_group/some_option".
  48  *
  49  * All preferences are loaded when the first singleton pointer is requested.
  50  * To save the preferences, the method save() or the static function unload()
  51  * can be used.
  52  *
  53  * In future, this will be a virtual base from which specific backends
  54  * derive (e.g. GConf, flat XML file...)
  55  */
  56 class Preferences {
  57 public:
  58     // #############################
  59     // ## inner class definitions ##
  60     // #############################
  61
  62     class Entry;
  63     class Observer;
  64
  65     /**
  66      * @brief Base class for preference observers
  67      *
  68      * If you want to watch for changes in the preferences, you'll have to
  69      * derive a class from this one and override the notify() method.
  70      */
  71     class Observer {
  72         friend class Preferences;
  73     public:
  74
  75         /**
  76          * @brief Constructor.
  77          *
  78          * Since each Observer is assigned to a single path, the base
  79          * constructor takes this path as an argument. This prevents one from
  80          * adding a single observer to multiple paths, but this is intentional
  81          * to simplify the implementation of observers and notifications.
  82          *
  83          * After you add the object with Preferences::addObserver(), you will
  84          * receive notifications for everything below the attachment point.
  85          * You can also specify a single preference as the watch point.
  86          * For example, watching the directory "/foo" will give you notifications
  87          * about "/foo/some_pref" as well as "/foo/some_dir/other_pref".
  88          * Watching the preference "/options/some_group/some_option" will only
  89          * generate notifications when this single preference changes.
  90          *
  91          * @param path Preference path the observer should watch
  92          */
  93         Observer(Glib::ustring const &path);
  94         virtual ~Observer();
  95
  96         /**
  97          * @brief Notification about a preference change
  98          * @param new_val  Entry object containing information about
  99          *                 the modified preference
 100          */
 101         virtual void notify(Preferences::Entry const &new_val) = 0;
 102
 103         Glib::ustring const observed_path; ///< Path which the observer watches
 104     private:
 105         void *_data; ///< additional data used by the implementation while the observer is active
 106     };
 107
 108
 109     /**
 110      * @brief Data type representing a typeless value of a preference
 111      *
 112      * This is passed to the observer in the notify() method.
 113      * To retrieve useful data from it, use its member functions. Setting
 114      * any preference using the Preferences class invalidates this object,
 115      * so use its get methods before doing so.
 116      */
 117     class Entry {
 118     friend class Preferences; // Preferences class has to access _value
 119     public:
 120         ~Entry() {}
 121         Entry() : _pref_path(""), _value(NULL) {} // needed to enable use in maps
 122         Entry(Entry const &other) : _pref_path(other._pref_path), _value(other._value) {}
 123
 124         /**
 125          * @brief Check whether the received entry is valid.
 126          * @return If false, the default value will be returned by the getters.
 127          */
 128         bool isValid() const { return _value != NULL; }
 129
 130         /**
 131          * @brief Interpret the preference as a Boolean value.
 132          * @param def Default value if the preference is not set
 133          */
 134         inline bool getBool(bool def=false) const;
 135
 136         /**
 137          * @brief Interpret the preference as an integer.
 138          * @param def Default value if the preference is not set
 139          */
 140         inline int getInt(int def=0) const;
 141
 142         /**
 143          * @brief Interpret the preference as a limited integer.
 144          *
 145          * This method will return the default value if the interpreted value is
 146          * larger than @c max or smaller than @c min. Do not use to store
 147          * Boolean values as integers.
 148          *
 149          * @param def Default value if the preference is not set
 150          * @param min Minimum value allowed to return
 151          * @param max Maximum value allowed to return
 152          */
 153         inline int getIntLimited(int def=0, int min=INT_MIN, int max=INT_MAX) const;
 154
 155         /**
 156          * @brief Interpret the preference as a floating point value.
 157          * @param def Default value if the preference is not set
 158          */
 159         inline double getDouble(double def=0.0) const;
 160
 161         /**
 162          * @brief Interpret the preference as a limited floating point value.
 163          *
 164          * This method will return the default value if the interpreted value is
 165          * larger than @c max or smaller than @c min.
 166          *
 167          * @param def Default value if the preference is not set
 168          * @param min Minimum value allowed to return
 169          * @param max Maximum value allowed to return
 170          */
 171         inline double getDoubleLimited(double def=0.0, double min=DBL_MIN, double max=DBL_MAX) const;
 172
 173         /**
 174          * @brief Interpret the preference as an UTF-8 string.
 175          *
 176          * To store a filename, convert it using Glib::filename_to_utf8().
 177          */
 178         inline Glib::ustring getString() const;
 179
 180         /**
 181          * @brief Interpret the preference as an RGBA color value.
 182          */
 183         inline guint32 getColor(guint32 def) const;
 184
 185         /**
 186          * @brief Interpret the preference as a CSS style.
 187          * @return A CSS style that has to be unrefed when no longer necessary. Never NULL.
 188          */
 189         inline SPCSSAttr *getStyle() const;
 190
 191         /**
 192          * @brief Interpret the preference as a CSS style with directory-based
 193          *        inheritance
 194          *
 195          * This function will look up the preferences with the same entry name
 196          * in ancestor directories and return the inherited CSS style.
 197          *
 198          * @return Inherited CSS style that has to be unrefed after use. Never NULL.
 199          */
 200         inline SPCSSAttr *getInheritedStyle() const;
 201
 202         /**
 203          * @brief Get the full path of the preference described by this Entry.
 204          */
 205         Glib::ustring const &getPath() const { return _pref_path; }
 206
 207         /**
 208          * @brief Get the last component of the preference's path
 209          *
 210          * E.g. For "/options/some_group/some_option" it will return "some_option".
 211          */
 212         Glib::ustring getEntryName() const;
 213     private:
 214         Entry(Glib::ustring const &path, void const *v) : _pref_path(path), _value(v) {}
 215
 216         Glib::ustring _pref_path;
 217         void const *_value;
 218     };
 219
 220     // utility methods
 221
 222     /**
 223      * @brief Save all preferences to the hard disk.
 224      *
 225      * For some backends, the preferences may be saved as they are modified.
 226      * Not calling this method doesn't guarantee the preferences are unmodified
 227      * the next time Inkscape runs.
 228      */
 229     void save();
 230
 231     /**
 232      * @brief Check whether saving the preferences will have any effect.
 233      */
 234     bool isWritable() { return _writable; }
 235     /*@}*/
 236
 237     /**
 238      * @brief Return details of the last encountered error, if any.
 239      *
 240      * This method will return true if an error has been encountered, and fill
 241      * in the primary and secondary error strings of the last error. If an error
 242      * had been encountered, this will reset it.
 243      *
 244      * @param string to set to the primary error message.
 245      * @param string to set to the secondary error message.
 246      *
 247      * @return True if an error has occurred since last checking, false otherwise.
 248      */
 249     bool getLastError( Glib::ustring& primary, Glib::ustring& secondary );
 250
 251     /**
 252      * @name Iterate over directories and entries.
 253      * @{
 254      */
 255
 256     /**
 257      * @brief Get all entries from the specified directory
 258      *
 259      * This method will return a vector populated with preference entries
 260      * from the specified directory. Subdirectories will not be represented.
 261      */
 262     std::vector<Entry> getAllEntries(Glib::ustring const &path);
 263
 264     /**
 265      * @brief Get all subdirectories of the specified directory
 266      *
 267      * This will return a vector populated with full paths to the subdirectories
 268      * present in the specified @c path.
 269      */
 270     std::vector<Glib::ustring> getAllDirs(Glib::ustring const &path);
 271     /*@}*/
 272
 273     /**
 274      * @name Retrieve data from the preference storage.
 275      * @{
 276      */
 277
 278     /**
 279      * @brief Retrieve a Boolean value
 280      * @param pref_path Path to the retrieved preference
 281      * @param def The default value to return if the preference is not set
 282      */
 283     bool getBool(Glib::ustring const &pref_path, bool def=false) {
 284         return getEntry(pref_path).getBool(def);
 285     }
 286
 287     /**
 288      * @brief Retrieve an integer
 289      * @param pref_path Path to the retrieved preference
 290      * @param def The default value to return if the preference is not set
 291      */
 292     int getInt(Glib::ustring const &pref_path, int def=0) {
 293         return getEntry(pref_path).getInt(def);
 294     }
 295
 296     /**
 297      * @brief Retrieve a limited integer
 298      *
 299      * The default value is returned if the actual value is larger than @c max
 300      * or smaller than @c min. Do not use to store Boolean values.
 301      *
 302      * @param pref_path Path to the retrieved preference
 303      * @param def The default value to return if the preference is not set
 304      * @param min Minimum value to return
 305      * @param max Maximum value to return
 306      */
 307     int getIntLimited(Glib::ustring const &pref_path, int def=0, int min=INT_MIN, int max=INT_MAX) {
 308         return getEntry(pref_path).getIntLimited(def, min, max);
 309     }
 310     double getDouble(Glib::ustring const &pref_path, double def=0.0) {
 311         return getEntry(pref_path).getDouble(def);
 312     }
 313
 314     /**
 315      * @brief Retrieve a limited floating point value
 316      *
 317      * The default value is returned if the actual value is larger than @c max
 318      * or smaller than @c min.
 319      *
 320      * @param pref_path Path to the retrieved preference
 321      * @param def The default value to return if the preference is not set
 322      * @param min Minimum value to return
 323      * @param max Maximum value to return
 324      */
 325     double getDoubleLimited(Glib::ustring const &pref_path, double def=0.0, double min=DBL_MIN, double max=DBL_MAX) {
 326         return getEntry(pref_path).getDoubleLimited(def, min, max);
 327     }
 328
 329     /**
 330      * @brief Retrieve an UTF-8 string
 331      * @param pref_path Path to the retrieved preference
 332      */
 333     Glib::ustring getString(Glib::ustring const &pref_path) {
 334         return getEntry(pref_path).getString();
 335     }
 336
 337     guint32 getColor(Glib::ustring const &pref_path, guint32 def=0x000000ff) {
 338         return getEntry(pref_path).getColor(def);
 339     }
 340
 341     /**
 342      * @brief Retrieve a CSS style
 343      * @param pref_path Path to the retrieved preference
 344      * @return A CSS style that has to be unrefed after use.
 345      */
 346     SPCSSAttr *getStyle(Glib::ustring const &pref_path) {
 347         return getEntry(pref_path).getStyle();
 348     }
 349
 350     /**
 351      * @brief Retrieve an inherited CSS style
 352      *
 353      * This method will look up preferences with the same entry name in ancestor
 354      * directories and return a style obtained by inheriting properties from
 355      * ancestor styles.
 356      *
 357      * @param pref_path Path to the retrieved preference
 358      * @return An inherited CSS style that has to be unrefed after use.
 359      */
 360     SPCSSAttr *getInheritedStyle(Glib::ustring const &pref_path) {
 361         return getEntry(pref_path).getInheritedStyle();
 362     }
 363
 364     /**
 365      * @brief Retrieve a preference entry without specifying its type
 366      */
 367     Entry const getEntry(Glib::ustring const &pref_path);
 368     /*@}*/
 369
 370     /**
 371      * @name Update preference values.
 372      * @{
 373      */
 374
 375     /**
 376      * @brief Set a Boolean value
 377      */
 378     void setBool(Glib::ustring const &pref_path, bool value);
 379
 380     /**
 381      * @brief Set an integer value
 382      */
 383     void setInt(Glib::ustring const &pref_path, int value);
 384
 385     /**
 386      * @brief Set a floating point value
 387      */
 388     void setDouble(Glib::ustring const &pref_path, double value);
 389
 390     /**
 391      * @brief Set an UTF-8 string value
 392      */
 393     void setString(Glib::ustring const &pref_path, Glib::ustring const &value);
 394
 395     /**
 396      * @brief Set an RGBA color value
 397      */
 398     void setColor(Glib::ustring const &pref_path, guint32 value);
 399
 400     /**
 401      * @brief Set a CSS style
 402      */
 403     void setStyle(Glib::ustring const &pref_path, SPCSSAttr *style);
 404
 405     /**
 406      * @brief Merge a CSS style with the current preference value
 407      *
 408      * This method is similar to setStyle(), except that it merges the style
 409      * rather than replacing it. This means that if @c style doesn't have
 410      * a property set, it is left unchanged in the style stored in
 411      * the preferences.
 412      */
 413     void mergeStyle(Glib::ustring const &pref_path, SPCSSAttr *style);
 414     /*@}*/
 415
 416     /**
 417      * @name Receive notifications about preference changes.
 418      * @{
 419      */
 420
 421     /**
 422      * @brief Register a preference observer
 423      */
 424     void addObserver(Observer &);
 425
 426     /**
 427      * @brief Remove an observer an prevent further notifications to it.
 428      */
 429     void removeObserver(Observer &);
 430     /*@}*/
 431
 432     /**
 433      * @name Access and manipulate the Preferences object.
 434      * @{
 435      */
 436
 437
 438     /**
 439      * Copies values from old location to new.
 440      */
 441     static void migrate( std::string const& legacyDir, std::string const& prefdir );
 442
 443     /**
 444      * @brief Access the singleton Preferences object.
 445      */
 446     static Preferences *get() {
 447         if (!_instance) {
 448             _instance = new Preferences();
 449         }
 450         return _instance;
 451     }
 452
 453     void setErrorHandler(ErrorReporter* handler);
 454
 455     /**
 456      * @brief Unload all preferences
 457      * @param save Whether to save the preferences; defaults to true
 458      *
 459      * This deletes the singleton object. Calling get() after this function
 460      * will reinstate it, so you shouldn't. Pass false as the parameter
 461      * to suppress automatic saving.
 462      */
 463     static void unload(bool save=true);
 464     /*@}*/
 465
 466 protected:
 467     /* helper methods used by Entry
 468      * This will enable using the same Entry class with different backends.
 469      * For now, however, those methods are not virtual. These methods assume
 470      * that v._value is not NULL
 471      */
 472     bool _extractBool(Entry const &v);
 473     int _extractInt(Entry const &v);
 474     double _extractDouble(Entry const &v);
 475     Glib::ustring _extractString(Entry const &v);
 476     guint32 _extractColor(Entry const &v);
 477     SPCSSAttr *_extractStyle(Entry const &v);
 478     SPCSSAttr *_extractInheritedStyle(Entry const &v);
 479
 480 private:
 481     Preferences();
 482     ~Preferences();
 483     void _loadDefaults();
 484     void _load();
 485     void _getRawValue(Glib::ustring const &path, gchar const *&result);
 486     void _setRawValue(Glib::ustring const &path, gchar const *value);
 487     void _reportError(Glib::ustring const &, Glib::ustring const &);
 488     void _keySplit(Glib::ustring const &pref_path, Glib::ustring &node_key, Glib::ustring &attr_key);
 489     XML::Node *_getNode(Glib::ustring const &pref_path, bool create=false);
 490     XML::Node *_findObserverNode(Glib::ustring const &pref_path, Glib::ustring &node_key, Glib::ustring &attr_key, bool create);
 491
 492     // disable copying
 493     Preferences(Preferences const &);
 494     Preferences operator=(Preferences const &);
 495
 496     std::string _prefs_basename; ///< Basename of the prefs file
 497     std::string _prefs_dir; ///< Directory in which to look for the prefs file
 498     std::string _prefs_filename; ///< Full filename (with directory) of the prefs file
 499     Glib::ustring _lastErrPrimary; ///< Last primary error message, if any.
 500     Glib::ustring _lastErrSecondary; ///< Last secondary error message, if any.
 501     XML::Document *_prefs_doc; ///< XML document storing all the preferences
 502     ErrorReporter* _errorHandler; ///< Pointer to object reporting errors.
 503     bool _writable; ///< Will the preferences be saved at exit?
 504     bool _hasError; ///< Indication that some error has occurred;
 505
 506     /// Wrapper class for XML node observers
 507     class PrefNodeObserver;
 508
 509     typedef std::map<Observer *, PrefNodeObserver *> _ObsMap;
 510     /// Map that keeps track of wrappers assigned to PrefObservers
 511     _ObsMap _observer_map;
 512
 513     // privilege escalation methods for PrefNodeObserver
 514     static Entry const _create_pref_value(Glib::ustring const &, void const *ptr);
 515     static void *_get_pref_observer_data(Observer &o) { return o._data; }
 516
 517     static Preferences *_instance;
 518
 519 friend class PrefNodeObserver;
 520 friend class Entry;
 521 };
 522
 523 /* Trivial inline Preferences::Entry functions.
 524  * In fact only the _extract* methods do something, the rest is delegation
 525  * to avoid duplication of code. There should be no performance hit if
 526  * compiled with -finline-functions.
 527  */
 528
 529 inline bool Preferences::Entry::getBool(bool def) const
 530 {
 531     if (!this->isValid()) {
 532         return def;
 533     } else {
 534         return Inkscape::Preferences::get()->_extractBool(*this);
 535     }
 536 }
 537
 538 inline int Preferences::Entry::getInt(int def) const
 539 {
 540     if (!this->isValid()) {
 541         return def;
 542     } else {
 543         return Inkscape::Preferences::get()->_extractInt(*this);
 544     }
 545 }
 546
 547 inline int Preferences::Entry::getIntLimited(int def, int min, int max) const
 548 {
 549     if (!this->isValid()) {
 550         return def;
 551     } else {
 552         int val = Inkscape::Preferences::get()->_extractInt(*this);
 553         return ( val >= min && val <= max ? val : def );
 554     }
 555 }
 556
 557 inline double Preferences::Entry::getDouble(double def) const
 558 {
 559     if (!this->isValid()) {
 560         return def;
 561     } else {
 562         return Inkscape::Preferences::get()->_extractDouble(*this);
 563     }
 564 }
 565
 566 inline double Preferences::Entry::getDoubleLimited(double def, double min, double max) const
 567 {
 568     if (!this->isValid()) {
 569         return def;
 570     } else {
 571         double val = Inkscape::Preferences::get()->_extractDouble(*this);
 572         return ( val >= min && val <= max ? val : def );
 573     }
 574 }
 575
 576 inline Glib::ustring Preferences::Entry::getString() const
 577 {
 578     if (!this->isValid()) {
 579         return "";
 580     } else {
 581         return Inkscape::Preferences::get()->_extractString(*this);
 582     }
 583 }
 584
 585 inline guint32 Preferences::Entry::getColor(guint32 def) const
 586 {
 587     if (!this->isValid()) {
 588         return def;
 589     } else {
 590         return Inkscape::Preferences::get()->_extractColor(*this);
 591     }
 592 }
 593
 594 inline SPCSSAttr *Preferences::Entry::getStyle() const
 595 {
 596     if (!this->isValid()) {
 597         return sp_repr_css_attr_new();
 598     } else {
 599         return Inkscape::Preferences::get()->_extractStyle(*this);
 600     }
 601 }
 602
 603 inline SPCSSAttr *Preferences::Entry::getInheritedStyle() const
 604 {
 605     if (!this->isValid()) {
 606         return sp_repr_css_attr_new();
 607     } else {
 608         return Inkscape::Preferences::get()->_extractInheritedStyle(*this);
 609     }
 610 }
 611
 612 inline Glib::ustring Preferences::Entry::getEntryName() const
 613 {
 614     Glib::ustring path_base = _pref_path;
 615     path_base.erase(0, path_base.rfind('/') + 1);
 616     return path_base;
 617 }
 618
 619 } // namespace Inkscape
 620
 621 #endif // INKSCAPE_PREFSTORE_H
 622
 623 /*
 624   Local Variables:
 625   mode:c++
 626   c-file-style:"stroustrup"
 627   c-file-offsets:((innamespace . 0)(inline-open . 0))
 628   indent-tabs-mode:nil
 629   fill-column:75
 630   End:
 631 */
 632 // vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4 :