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 */
13 #ifndef INKSCAPE_PREFSTORE_H
14 #define INKSCAPE_PREFSTORE_H
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"
25 class SPCSSAttr;
27 namespace Inkscape {
29 class ErrorReporter {
30 public:
31 virtual ~ErrorReporter() {}
32 virtual void handleError(Glib::ustring const& primary, Glib::ustring const& secondary ) const = 0;
33 };
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 // #############################
62 class Entry;
63 class Observer;
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:
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();
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;
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 };
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) {}
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; }
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;
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;
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;
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;
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;
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;
180 /**
181 * @brief Interpret the preference as an RGBA color value.
182 */
183 inline guint32 getColor(guint32 def) const;
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;
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;
202 /**
203 * @brief Get the full path of the preference described by this Entry.
204 */
205 Glib::ustring const &getPath() const { return _pref_path; }
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) {}
216 Glib::ustring _pref_path;
217 void const *_value;
218 };
220 // utility methods
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();
231 /**
232 * @brief Check whether saving the preferences will have any effect.
233 */
234 bool isWritable() { return _writable; }
235 /*@}*/
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 );
251 /**
252 * @name Iterate over directories and entries.
253 * @{
254 */
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);
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 /*@}*/
273 /**
274 * @name Retrieve data from the preference storage.
275 * @{
276 */
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 }
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 }
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 }
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 }
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 }
337 guint32 getColor(Glib::ustring const &pref_path, guint32 def=0x000000ff) {
338 return getEntry(pref_path).getColor(def);
339 }
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 }
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 }
364 /**
365 * @brief Retrieve a preference entry without specifying its type
366 */
367 Entry const getEntry(Glib::ustring const &pref_path);
368 /*@}*/
370 /**
371 * @name Update preference values.
372 * @{
373 */
375 /**
376 * @brief Set a Boolean value
377 */
378 void setBool(Glib::ustring const &pref_path, bool value);
380 /**
381 * @brief Set an integer value
382 */
383 void setInt(Glib::ustring const &pref_path, int value);
385 /**
386 * @brief Set a floating point value
387 */
388 void setDouble(Glib::ustring const &pref_path, double value);
390 /**
391 * @brief Set an UTF-8 string value
392 */
393 void setString(Glib::ustring const &pref_path, Glib::ustring const &value);
395 /**
396 * @brief Set an RGBA color value
397 */
398 void setColor(Glib::ustring const &pref_path, guint32 value);
400 /**
401 * @brief Set a CSS style
402 */
403 void setStyle(Glib::ustring const &pref_path, SPCSSAttr *style);
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 /*@}*/
416 /**
417 * @name Receive notifications about preference changes.
418 * @{
419 */
421 /**
422 * @brief Register a preference observer
423 */
424 void addObserver(Observer &);
426 /**
427 * @brief Remove an observer an prevent further notifications to it.
428 */
429 void removeObserver(Observer &);
430 /*@}*/
432 /**
433 * @name Access and manipulate the Preferences object.
434 * @{
435 */
438 /**
439 * Copies values from old location to new.
440 */
441 static void migrate( std::string const& legacyDir, std::string const& prefdir );
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 }
453 void setErrorHandler(ErrorReporter* handler);
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 /*@}*/
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);
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);
492 // disable copying
493 Preferences(Preferences const &);
494 Preferences operator=(Preferences const &);
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;
506 /// Wrapper class for XML node observers
507 class PrefNodeObserver;
509 typedef std::map<Observer *, PrefNodeObserver *> _ObsMap;
510 /// Map that keeps track of wrappers assigned to PrefObservers
511 _ObsMap _observer_map;
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; }
517 static Preferences *_instance;
519 friend class PrefNodeObserver;
520 friend class Entry;
521 };
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 */
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 }
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 }
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 }
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 }
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 }
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 }
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 }
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 }
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 }
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 }
619 } // namespace Inkscape
621 #endif // INKSCAPE_PREFSTORE_H
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 :