Logo Search packages:      
Sourcecode: inkscape version File versions  Download package

preferences.h

Go to the documentation of this file.
/** @file
 * @brief  Singleton class to access the preferences file in a convenient way.
 */
/* Authors:
 *   Krzysztof Kosi_ski <tweenk.pl@gmail.com>
 *   Jon A. Cruz <jon@joncruz.org>
 *
 * Copyright (C) 2008,2009 Authors
 *
 * Released under GNU GPL.  Read the file 'COPYING' for more information.
 */

#ifndef INKSCAPE_PREFSTORE_H
#define INKSCAPE_PREFSTORE_H

#include <string>
#include <map>
#include <vector>
#include <climits>
#include <cfloat>
#include <glibmm/ustring.h>
#include "xml/xml-forward.h"
#include "xml/repr.h"

class SPCSSAttr;

namespace Inkscape {

00029 class ErrorReporter {
public:
    virtual ~ErrorReporter() {}
    virtual void handleError(Glib::ustring const& primary, Glib::ustring const& secondary ) const = 0;
};

/**
 * @brief Preference storage class.
 *
 * This is a singleton that allows one to access the user preferences stored in
 * the preferences.xml file. The preferences are stored in a file system-like
 * hierarchy. They are generally typeless - it's up to the programmer to ensure
 * that a given preference is always accessed as the correct type. The backend
 * is not guaranteed to be tolerant to type mismatches.
 *
 * Preferences are identified by paths similar to file system paths. Components
 * of the path are separated by a slash (/). As an additional requirement,
 * the path must start with a slash, and not contain a trailing slash.
 * An example of a correct path would be "/options/some_group/some_option".
 *
 * All preferences are loaded when the first singleton pointer is requested.
 * To save the preferences, the method save() or the static function unload()
 * can be used.
 *
 * In future, this will be a virtual base from which specific backends
 * derive (e.g. GConf, flat XML file...)
 */
00056 class Preferences {
public:
    // #############################
    // ## inner class definitions ##
    // #############################

    class Entry;
    class Observer;

    /**
     * @brief Base class for preference observers
     *
     * If you want to watch for changes in the preferences, you'll have to
     * derive a class from this one and override the notify() method.
     */
00071     class Observer {
        friend class Preferences;
    public:

        /**
         * @brief Constructor.
         *
         * Since each Observer is assigned to a single path, the base
         * constructor takes this path as an argument. This prevents one from
         * adding a single observer to multiple paths, but this is intentional
         * to simplify the implementation of observers and notifications.
         *
         * After you add the object with Preferences::addObserver(), you will
         * receive notifications for everything below the attachment point.
         * You can also specify a single preference as the watch point.
         * For example, watching the directory "/foo" will give you notifications
         * about "/foo/some_pref" as well as "/foo/some_dir/other_pref".
         * Watching the preference "/options/some_group/some_option" will only
         * generate notifications when this single preference changes.
         *
         * @param path Preference path the observer should watch
         */
        Observer(Glib::ustring const &path);
        virtual ~Observer();

        /**
         * @brief Notification about a preference change
         * @param new_val  Entry object containing information about
         *                 the modified preference
         */
        virtual void notify(Preferences::Entry const &new_val) = 0;

00103         Glib::ustring const observed_path; ///< Path which the observer watches
    private:
00105         void *_data; ///< additional data used by the implementation while the observer is active
    };


    /**
     * @brief Data type representing a typeless value of a preference
     *
     * This is passed to the observer in the notify() method.
     * To retrieve useful data from it, use its member functions. Setting
     * any preference using the Preferences class invalidates this object,
     * so use its get methods before doing so.
     */
00117     class Entry {
    friend class Preferences; // Preferences class has to access _value
    public:
        ~Entry() {}
        Entry() : _pref_path(""), _value(NULL) {} // needed to enable use in maps
        Entry(Entry const &other) : _pref_path(other._pref_path), _value(other._value) {}

        /**
         * @brief Check whether the received entry is valid.
         * @return If false, the default value will be returned by the getters.
         */
00128         bool isValid() const { return _value != NULL; }

        /**
         * @brief Interpret the preference as a Boolean value.
         * @param def Default value if the preference is not set
         */
        inline bool getBool(bool def=false) const;

        /**
         * @brief Interpret the preference as an integer.
         * @param def Default value if the preference is not set
         */
        inline int getInt(int def=0) const;

        /**
         * @brief Interpret the preference as a limited integer.
         *
         * This method will return the default value if the interpreted value is
         * larger than @c max or smaller than @c min. Do not use to store
         * Boolean values as integers.
         *
         * @param def Default value if the preference is not set
         * @param min Minimum value allowed to return
         * @param max Maximum value allowed to return
         */
        inline int getIntLimited(int def=0, int min=INT_MIN, int max=INT_MAX) const;

        /**
         * @brief Interpret the preference as a floating point value.
         * @param def Default value if the preference is not set
         */
        inline double getDouble(double def=0.0) const;

        /**
         * @brief Interpret the preference as a limited floating point value.
         *
         * This method will return the default value if the interpreted value is
         * larger than @c max or smaller than @c min.
         *
         * @param def Default value if the preference is not set
         * @param min Minimum value allowed to return
         * @param max Maximum value allowed to return
         */
        inline double getDoubleLimited(double def=0.0, double min=DBL_MIN, double max=DBL_MAX) const;

        /**
         * @brief Interpret the preference as an UTF-8 string.
         *
         * To store a filename, convert it using Glib::filename_to_utf8().
         */
        inline Glib::ustring getString() const;

        /**
         * @brief Interpret the preference as a CSS style.
         * @return A CSS style that has to be unrefed when no longer necessary. Never NULL.
         */
        inline SPCSSAttr *getStyle() const;

        /**
         * @brief Interpret the preference as a CSS style with directory-based
         *        inheritance
         *
         * This function will look up the preferences with the same entry name
         * in ancestor directories and return the inherited CSS style.
         *
         * @return Inherited CSS style that has to be unrefed after use. Never NULL.
         */
        inline SPCSSAttr *getInheritedStyle() const;

        /**
         * @brief Get the full path of the preference described by this Entry.
         */
00200         Glib::ustring const &getPath() const { return _pref_path; }

        /**
         * @brief Get the last component of the preference's path
         *
         * E.g. For "/options/some_group/some_option" it will return "some_option".
         */
        Glib::ustring getEntryName() const;
    private:
        Entry(Glib::ustring const &path, void const *v) : _pref_path(path), _value(v) {}

        Glib::ustring _pref_path;
        void const *_value;
    };

    // utility methods

    /**
     * @brief Save all preferences to the hard disk.
     *
     * For some backends, the preferences may be saved as they are modified.
     * Not calling this method doesn't guarantee the preferences are unmodified
     * the next time Inkscape runs.
     */
    void save();

    /**
     * @brief Check whether saving the preferences will have any effect.
     */
00229     bool isWritable() { return _writable; }
    /*@}*/

    /**
     * @brief Return details of the last encountered error, if any.
     *
     * This method will return true if an error has been encountered, and fill
     * in the primary and secondary error strings of the last error. If an error
     * had been encountered, this will reset it.
     *
     * @param string to set to the primary error message.
     * @param string to set to the secondary error message.
     *
     * @return True if an error has occurred since last checking, false otherwise.
     */
    bool getLastError( Glib::ustring& primary, Glib::ustring& secondary );

    /**
     * @name Iterate over directories and entries.
     * @{
     */

    /**
     * @brief Get all entries from the specified directory
     *
     * This method will return a vector populated with preference entries
     * from the specified directory. Subdirectories will not be represented.
     */
    std::vector<Entry> getAllEntries(Glib::ustring const &path);

    /**
     * @brief Get all subdirectories of the specified directory
     *
     * This will return a vector populated with full paths to the subdirectories
     * present in the specified @c path.
     */
    std::vector<Glib::ustring> getAllDirs(Glib::ustring const &path);
    /*@}*/

    /**
     * @name Retrieve data from the preference storage.
     * @{
     */

    /**
     * @brief Retrieve a Boolean value
     * @param pref_path Path to the retrieved preference
     * @param def The default value to return if the preference is not set
     */
00278     bool getBool(Glib::ustring const &pref_path, bool def=false) {
        return getEntry(pref_path).getBool(def);
    }

    /**
     * @brief Retrieve an integer
     * @param pref_path Path to the retrieved preference
     * @param def The default value to return if the preference is not set
     */
00287     int getInt(Glib::ustring const &pref_path, int def=0) {
        return getEntry(pref_path).getInt(def);
    }

    /**
     * @brief Retrieve a limited integer
     *
     * The default value is returned if the actual value is larger than @c max
     * or smaller than @c min. Do not use to store Boolean values.
     *
     * @param pref_path Path to the retrieved preference
     * @param def The default value to return if the preference is not set
     * @param min Minimum value to return
     * @param max Maximum value to return
     */
00302     int getIntLimited(Glib::ustring const &pref_path, int def=0, int min=INT_MIN, int max=INT_MAX) {
        return getEntry(pref_path).getIntLimited(def, min, max);
    }
    double getDouble(Glib::ustring const &pref_path, double def=0.0) {
        return getEntry(pref_path).getDouble(def);
    }

    /**
     * @brief Retrieve a limited floating point value
     *
     * The default value is returned if the actual value is larger than @c max
     * or smaller than @c min.
     *
     * @param pref_path Path to the retrieved preference
     * @param def The default value to return if the preference is not set
     * @param min Minimum value to return
     * @param max Maximum value to return
     */
00320     double getDoubleLimited(Glib::ustring const &pref_path, double def=0.0, double min=DBL_MIN, double max=DBL_MAX) {
        return getEntry(pref_path).getDoubleLimited(def, min, max);
    }

    /**
     * @brief Retrieve an UTF-8 string
     * @param pref_path Path to the retrieved preference
     */
00328     Glib::ustring getString(Glib::ustring const &pref_path) {
        return getEntry(pref_path).getString();
    }

    /**
     * @brief Retrieve a CSS style
     * @param pref_path Path to the retrieved preference
     * @return A CSS style that has to be unrefed after use.
     */
00337     SPCSSAttr *getStyle(Glib::ustring const &pref_path) {
        return getEntry(pref_path).getStyle();
    }

    /**
     * @brief Retrieve an inherited CSS style
     *
     * This method will look up preferences with the same entry name in ancestor
     * directories and return a style obtained by inheriting properties from
     * ancestor styles.
     *
     * @param pref_path Path to the retrieved preference
     * @return An inherited CSS style that has to be unrefed after use.
     */
00351     SPCSSAttr *getInheritedStyle(Glib::ustring const &pref_path) {
        return getEntry(pref_path).getInheritedStyle();
    }

    /**
     * @brief Retrieve a preference entry without specifying its type
     */
    Entry const getEntry(Glib::ustring const &pref_path);
    /*@}*/

    /**
     * @name Update preference values.
     * @{
     */

    /**
     * @brief Set a Boolean value
     */
    void setBool(Glib::ustring const &pref_path, bool value);

    /**
     * @brief Set an integer value
     */
    void setInt(Glib::ustring const &pref_path, int value);

    /**
     * @brief Set a floating point value
     */
    void setDouble(Glib::ustring const &pref_path, double value);

    /**
     * @brief Set an UTF-8 string value
     */
    void setString(Glib::ustring const &pref_path, Glib::ustring const &value);

    /**
     * @brief Set a CSS style
     */
    void setStyle(Glib::ustring const &pref_path, SPCSSAttr *style);

    /**
     * @brief Merge a CSS style with the current preference value
     *
     * This method is similar to setStyle(), except that it merges the style
     * rather than replacing it. This means that if @c style doesn't have
     * a property set, it is left unchanged in the style stored in
     * the preferences.
     */
    void mergeStyle(Glib::ustring const &pref_path, SPCSSAttr *style);
    /*@}*/

    /**
     * @name Receive notifications about preference changes.
     * @{
     */

    /**
     * @brief Register a preference observer
     */
    void addObserver(Observer &);

    /**
     * @brief Remove an observer an prevent further notifications to it.
     */
    void removeObserver(Observer &);
    /*@}*/

    /**
     * @name Access and manipulate the Preferences object.
     * @{
     */


    /**
     * Copies values from old location to new.
     */
    static void migrate( std::string const& legacyDir, std::string const& prefdir );

    /**
     * @brief Access the singleton Preferences object.
     */
00432     static Preferences *get() {
        if (!_instance) {
            _instance = new Preferences();
        }
        return _instance;
    }

    void setErrorHandler(ErrorReporter* handler);

    /**
     * @brief Unload all preferences
     * @param save Whether to save the preferences; defaults to true
     *
     * This deletes the singleton object. Calling get() after this function
     * will reinstate it, so you shouldn't. Pass false as the parameter
     * to suppress automatic saving.
     */
    static void unload(bool save=true);
    /*@}*/

protected:
    /* helper methods used by Entry
     * This will enable using the same Entry class with different backends.
     * For now, however, those methods are not virtual. These methods assume
     * that v._value is not NULL
     */
    bool _extractBool(Entry const &v);
    int _extractInt(Entry const &v);
    double _extractDouble(Entry const &v);
    Glib::ustring _extractString(Entry const &v);
    SPCSSAttr *_extractStyle(Entry const &v);
    SPCSSAttr *_extractInheritedStyle(Entry const &v);

private:
    Preferences();
    ~Preferences();
    void _loadDefaults();
    void _load();
    void _getRawValue(Glib::ustring const &path, gchar const *&result);
    void _setRawValue(Glib::ustring const &path, gchar const *value);
    void _reportError(Glib::ustring const &, Glib::ustring const &);
    void _keySplit(Glib::ustring const &pref_path, Glib::ustring &node_key, Glib::ustring &attr_key);
    XML::Node *_getNode(Glib::ustring const &pref_path, bool create=false);
    XML::Node *_findObserverNode(Glib::ustring const &pref_path, Glib::ustring &node_key, Glib::ustring &attr_key, bool create);

    // disable copying
    Preferences(Preferences const &);
    Preferences operator=(Preferences const &);

00481     std::string _prefs_basename; ///< Basename of the prefs file
00482     std::string _prefs_dir; ///< Directory in which to look for the prefs file
00483     std::string _prefs_filename; ///< Full filename (with directory) of the prefs file
00484     Glib::ustring _lastErrPrimary; ///< Last primary error message, if any.
00485     Glib::ustring _lastErrSecondary; ///< Last secondary error message, if any.
00486     XML::Document *_prefs_doc; ///< XML document storing all the preferences
00487     ErrorReporter* _errorHandler; ///< Pointer to object reporting errors.
00488     bool _writable; ///< Will the preferences be saved at exit?
00489     bool _hasError; ///< Indication that some error has occurred;

    /// Wrapper class for XML node observers
    class PrefNodeObserver;

    typedef std::map<Observer *, PrefNodeObserver *> _ObsMap;
    /// Map that keeps track of wrappers assigned to PrefObservers
00496     _ObsMap _observer_map;

    // privilege escalation methods for PrefNodeObserver
    static Entry const _create_pref_value(Glib::ustring const &, void const *ptr);
    static void *_get_pref_observer_data(Observer &o) { return o._data; }

    static Preferences *_instance;

friend class PrefNodeObserver;
friend class Entry;
};

/* Trivial inline Preferences::Entry functions.
 * In fact only the _extract* methods do something, the rest is delegation
 * to avoid duplication of code. There should be no performance hit if
 * compiled with -finline-functions.
 */

00514 inline bool Preferences::Entry::getBool(bool def) const
{
    if (!this->isValid()) {
        return def;
    } else {
        return Inkscape::Preferences::get()->_extractBool(*this);
    }
}

00523 inline int Preferences::Entry::getInt(int def) const
{
    if (!this->isValid()) {
        return def;
    } else {
        return Inkscape::Preferences::get()->_extractInt(*this);
    }
}

00532 inline int Preferences::Entry::getIntLimited(int def, int min, int max) const
{
    if (!this->isValid()) {
        return def;
    } else {
        int val = Inkscape::Preferences::get()->_extractInt(*this);
        return ( val >= min && val <= max ? val : def );
    }
}

00542 inline double Preferences::Entry::getDouble(double def) const
{
    if (!this->isValid()) {
        return def;
    } else {
        return Inkscape::Preferences::get()->_extractDouble(*this);
    }
}

00551 inline double Preferences::Entry::getDoubleLimited(double def, double min, double max) const
{
    if (!this->isValid()) {
        return def;
    } else {
        double val = Inkscape::Preferences::get()->_extractDouble(*this);
        return ( val >= min && val <= max ? val : def );
    }
}

00561 inline Glib::ustring Preferences::Entry::getString() const
{
    if (!this->isValid()) {
        return "";
    } else {
        return Inkscape::Preferences::get()->_extractString(*this);
    }
}

00570 inline SPCSSAttr *Preferences::Entry::getStyle() const
{
    if (!this->isValid()) {
        return sp_repr_css_attr_new();
    } else {
        return Inkscape::Preferences::get()->_extractStyle(*this);
    }
}

00579 inline SPCSSAttr *Preferences::Entry::getInheritedStyle() const
{
    if (!this->isValid()) {
        return sp_repr_css_attr_new();
    } else {
        return Inkscape::Preferences::get()->_extractInheritedStyle(*this);
    }
}

00588 inline Glib::ustring Preferences::Entry::getEntryName() const
{
    Glib::ustring path_base = _pref_path;
    path_base.erase(0, path_base.rfind('/') + 1);
    return path_base;
}

} // namespace Inkscape

#endif // INKSCAPE_PREFSTORE_H

/*
  Local Variables:
  mode:c++
  c-file-style:"stroustrup"
  c-file-offsets:((innamespace . 0)(inline-open . 0))
  indent-tabs-mode:nil
  fill-column:75
  End:
*/
// vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4 :

Generated by  Doxygen 1.6.0   Back to index