/********************************************************************\ * gnc-prefs.h -- Api to load and store preferences to a * * configurable backend * * * * Copyright (C) 2013 Geert Janssens * * * * This program is free software; you can redistribute it and/or * * modify it under the terms of the GNU General Public License as * * published by the Free Software Foundation; either version 2 of * * the License, or (at your option) any later version. * * * * This program is distributed in the hope that it will be useful, * * but WITHOUT ANY WARRANTY; without even the implied warranty of * * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * * GNU General Public License for more details. * * * * You should have received a copy of the GNU General Public License* * along with this program; if not, contact: * * * * Free Software Foundation Voice: +1-617-542-5942 * * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * * Boston, MA 02110-1301, USA gnu@gnu.org * * * ********************************************************************/ /** @addtogroup Engine @{ */ /** @addtogroup Preferences Preferences The API in this file is used to read and store preferences used by gnucash. This api is a generic one. To actually store and load preferences, a preferences backend should be configured. Currently only one backend is defined: the preferences backend. Note that preferences are organized in groups. Most functions will require both a group and a preference name to find the exact preference to work with. @{ */ /** @file gnc-prefs.h * @brief Generic api to store and retrieve preferences. * @author Copyright (C) 2013 Geert Janssens */ #ifndef GNC_PREFS_H #define GNC_PREFS_H #include /* Preference groups used across multiple modules */ #define GNC_PREFS_GROUP_GENERAL "general" #define GNC_PREFS_GROUP_GENERAL_REGISTER "general.register" #define GNC_PREFS_GROUP_GENERAL_REPORT "general.report" #define GNC_PREFS_GROUP_WARNINGS "general.warnings" #define GNC_PREFS_GROUP_WARNINGS_TEMP "warnings.temporary" #define GNC_PREFS_GROUP_WARNINGS_PERM "warnings.permanent" #define GNC_PREFS_GROUP_ACCT_SUMMARY "window.pages.account-tree.summary" /* Preference names used across multiple modules */ #define GNC_PREF_VERSION "prefs-version" #define GNC_PREF_SAVE_GEOMETRY "save-window-geometry" #define GNC_PREF_LAST_PATH "last-path" #define GNC_PREF_USE_NEW "use-new-window" #define GNC_PREF_ACCOUNTING_LABELS "use-accounting-labels" #define GNC_PREF_ACCOUNT_SEPARATOR "account-separator" #define GNC_PREF_NEGATIVE_IN_RED "negative-in-red" #define GNC_PREF_NUM_SOURCE "num-source" #define GNC_PREF_DATE_FORMAT "date-format" #define GNC_PREF_DATE_COMPL_THISYEAR "date-completion-thisyear" #define GNC_PREF_DATE_COMPL_SLIDING "date-completion-sliding" #define GNC_PREF_DATE_BACKMONTHS "date-backmonths" #define GNC_PREF_SHOW_LEAF_ACCT_NAMES "show-leaf-account-names" #define GNC_PREF_ENTER_MOVES_TO_END "enter-moves-to-end" /* Register preferences */ #define GNC_PREF_DRAW_HOR_LINES "draw-horizontal-lines" #define GNC_PREF_DRAW_VERT_LINES "draw-vertical-lines" #define GNC_PREF_ALT_COLOR_BY_TRANS "alternate-color-by-transaction" #define GNC_PREF_USE_THEME_COLORS "use-theme-colors" // Obsolete, to remove in a future major version (> 2.8) #define GNC_PREF_USE_GNUCASH_COLOR_THEME "use-gnucash-color-theme" #define GNC_PREF_TAB_TRANS_MEMORISED "tab-to-transfer-on-memorised" #define GNC_PREF_FUTURE_AFTER_BLANK "future-after-blank-transaction" /* Date preferences */ #define GNC_PREF_START_CHOICE_ABS "start-choice-absolute" #define GNC_PREF_START_CHOICE_REL "start-choice-relative" #define GNC_PREF_START_DATE "start-date" #define GNC_PREF_START_PERIOD "start-period" #define GNC_PREF_END_CHOICE_ABS "end-choice-absolute" #define GNC_PREF_END_CHOICE_REL "end-choice-relative" #define GNC_PREF_END_DATE "end-date" #define GNC_PREF_END_PERIOD "end-period" /* Currency preferences */ #define GNC_PREF_CURRENCY_OTHER "currency-other" #define GNC_PREF_CURRENCY_CHOICE_LOCALE "currency-choice-locale" #define GNC_PREF_CURRENCY_CHOICE_OTHER "currency-choice-other" #ifdef __cplusplus extern "C" { #endif /** @name Early bird functions, needed before any backend has been set up @{ */ const gchar *gnc_prefs_get_namespace_regexp(void); void gnc_prefs_set_namespace_regexp(const gchar *str); gboolean gnc_prefs_is_debugging_enabled(void); void gnc_prefs_set_debugging(gboolean d); gboolean gnc_prefs_is_extra_enabled(void); void gnc_prefs_set_extra(gboolean enabled); gboolean gnc_prefs_get_file_save_compressed(void); void gnc_prefs_set_file_save_compressed(gboolean compressed); gint gnc_prefs_get_file_retention_policy(void); void gnc_prefs_set_file_retention_policy(gint policy); gint gnc_prefs_get_file_retention_days(void); void gnc_prefs_set_file_retention_days(gint days); guint gnc_prefs_get_long_version( void ); /** @} */ /** Test if preferences backend is set up */ gboolean gnc_prefs_is_set_up (void); /** Block all preference callbacks */ void gnc_prefs_block_all (void); /** Unblock all preferences callbacks */ void gnc_prefs_unblock_all (void); /** @name Listening for changes @{ */ /** Register a callback that gets triggered when the given preference changes. * Any time the preference's value changes, the routine * will be invoked and will be passed both the changed preference * and the user data passed to this function. * * @param group This string contains the group name of the preference * to watch. * * @param preference This string contains the name of the preference to watch. * * @param func This is a pointer to the function to call when the preference * changes. * * @param user_data This pointer will be passed to the callback * function. * * @return This function returns the handler id for the registered * callback. */ gulong gnc_prefs_register_cb (const char *group, const gchar *pref_name, gpointer func, gpointer user_data); /** Remove a function that was registered for a callback when the * given preference changed. Both the func and user_data * arguments are used to match up the callback to remove. * If no matching func and user_data are found to be registered * for the given preference, nothing will happen. * * @param group This string contains the group name of the preference * that is being watched. * * @param preference This string contains the name of the preference being watched. * * @param func This is a pointer to the function that was registered * earlier. * * @param user_data This pointer was passed to the callback * function when it was registered. */ void gnc_prefs_remove_cb_by_func (const gchar *group, const gchar *pref_name, gpointer func, gpointer user_data); /** Remove a function that was registered for a callback when a * specific preference in the settings group changed. The handler id * that was generated when the callback was registered is * use to find the callback to remove. * If no handler id is found nothing will happen. * * @param group This string contains the group name of the preference * that is being watched. * * @param id The handler id of the callback to be removed. */ void gnc_prefs_remove_cb_by_id (const gchar *group, guint id); /** Register a callback for when any preference in the settings group * is changed. Any time the value of a preference in this group changes, * the routine will be invoked and will be passed the specified * user data. * * @param group This string contains the name of the group * that is being watched. * * @param func This is a pointer to the function to call when a preference * changes. * * @param user_data This pointer will be passed to the callback * function. */ guint gnc_prefs_register_group_cb (const gchar *group, gpointer func, gpointer user_data); /** Remove a function that was registered for a callback when any preference * in the given settings group changed. Both the func and user_data * arguments are used to match up the callback to remove. * If no matching func and user_data are found to be registered * for the given preference, nothing will happen. * * @param group This string contains the name of the group * that is being watched. * * @param func This is a pointer to the function that was registered * earlier. * * @param user_data This pointer was passed to the callback * function when it was registered. * * @note there is no gnc_settings_remove_any_cb_by_id. Use * gnc_settings_remove_cb_by_id instead if you want to * remove a callback set with gnc_settings_register_any_cb * by its handler id. */ void gnc_prefs_remove_group_cb_by_func (const gchar *group, gpointer func, gpointer user_data); /** Bind a setting to a g_object property. When this succeeds a change * of the setting will automatically update the bound object property * and vice versa. * * @param group This string contains the group name of the preference to bind to. * * @param preference This string is the name of the particular preference to * bind to. * * @param object The object to be bound. * * @param property The property of the object to bind to. */ void gnc_prefs_bind (const gchar *group, /*@ null @*/ const gchar *pref_name, gpointer object, const gchar *property); /** @} */ /** @name Preference Getters @{ */ /** Get a boolean value from the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @return This function returns the TRUE or FALSE value stored at * the requested preference in the preferences backend. If the preference has never * been set, this function passes on the default value returned by * the preferences backend. */ gboolean gnc_prefs_get_bool (const gchar *group, /*@ null @*/ const gchar *pref_name); /** Get an integer value from the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @return This function returns the integer value stored at the * requested preference in the preferences backend. If the preference has never been * set, this function passes on the default value returned by the preferences backend. * If there is an error in processing, zero will be returned. */ gint gnc_prefs_get_int (const gchar *group, const gchar *pref_name); /** Get an 64 bit integer value from the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @return This function returns the 64 bit integer value stored at the * requested preference in the preferences backend. If the preference has never been * set, this function passes on the default value returned by the preferences backend. * If there is an error in processing, zero will be returned. */ gint64 gnc_prefs_get_int64 (const gchar *group, const gchar *pref_name); /** Get an float value from the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @return This function returns the float value stored at the * requested preference in the preferences backend. If the preference has never been * set, this function passes on the default value returned by the preferences backend. * If there is an error in processing, zero will be returned. */ gdouble gnc_prefs_get_float (const gchar *group, const gchar *pref_name); /** Get a string value from the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @return This function returns the string value stored at the * requested preference in the preferences backend. If the preference has never been * set, this function passes on the default value returned by the preferences backend * If there is an error in processing, NULL will be returned. */ gchar *gnc_prefs_get_string (const gchar *group, const gchar *pref_name); /** Get an enum value from the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @return This function returns the enum value stored at the * requested preference in the preferences backend. If the preference has never been * set, this function passes on the default value returned by the preferences backend. * If there is an error in processing, zero will be returned. */ gint gnc_prefs_get_enum (const gchar *group, const gchar *pref_name); /** Get a pair of coordinates from the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @param x The x coordinate to retrieve. * * @param y The y coordinate to retrieve. * * If there is an error in processing, both coordinates will be set to zero. */ void gnc_prefs_get_coords (const gchar *group, const gchar *pref_name, gdouble *x, gdouble *y); /** Get an arbitrary combination of values from the preferences backend. This * combination of values can be anything that can be encapsulated * in a GVariant structure. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @return This function returns the a GVariant encapsulating the combination * of values stored at the requested preference in the preferences backend. * If the preference has never been set, this function passes on the default * value returned by the preferences backend. * If there is an error in processing, NULL will be returned. * It is the callers responsibility to free any GVariant data returned * by this function. */ GVariant *gnc_prefs_get_value (const gchar *group, const gchar *pref_name); /** @} */ /** @name Preference Setters and Unset Functions @{ */ /** Store a boolean value into the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @param value The boolean value to be stored. * * @return This function returns true if the value was set successfully * on the preference or false if not. */ gboolean gnc_prefs_set_bool (const gchar *group, const gchar *pref_name, gboolean value); /** Store an integer value into the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @param value The integer number to be stored. * * @return This function returns true if the value was set successfully * on the preference or false if not. */ gboolean gnc_prefs_set_int (const gchar *group, const gchar *pref_name, gint value); /** Store a 64 bit integer value into the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @param value The 64 bit integer number to be stored. * * @return This function returns true if the value was set successfully * on the preference or false if not. */ gboolean gnc_prefs_set_int64 (const gchar *group, const gchar *pref_name, gint64 value); /** Store a float value into the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @param value The floating point number to be stored. * * @return This function returns true if the value was set successfully * on the preference or false if not. */ gboolean gnc_prefs_set_float (const gchar *group, const gchar *pref_name, gdouble value); /** Store a string into the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @param value The string to be stored. the preferences backend will make a copy of this * string, so it is the callers responsibility to free the space used * by this string (if necessary). * * @return This function returns true if the value was set successfully * on the preference or false if not. */ gboolean gnc_prefs_set_string (const gchar *group, const gchar *pref_name, const gchar *value); /** Store an enum value into the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @param value The enum number to be stored. * * @return This function returns true if the value was set successfully * on the preference or false if not. */ gboolean gnc_prefs_set_enum (const gchar *group, const gchar *pref_name, gint value); /** Store coordinates into the preferences backend. Coordinates consist of * a pair of floating point values (x and y). * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @param x The x coordinate to be stored. * * @param y The y coordinate to be stored. * * @return This function returns true if the value was set successfully * on the preference or false if not. */ gboolean gnc_prefs_set_coords (const gchar *group, const gchar *pref_name, gdouble x, gdouble y); /** Store an arbitrary combination of values into the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. * * @param value The combination of values encapsulated in a GVariant * to be stored. * * @return This function returns true if the value was set successfully * on the preference or false if not. */ gboolean gnc_prefs_set_value (const gchar *group, const gchar *pref_name, GVariant *value); /** Reset a preference to its default value in the preferences backend. * * @param group This string specifies the group to which the preference belongs * * @param preference This string is the name of the particular preference within * the named group of the preferences backend. */ void gnc_prefs_reset (const gchar *group, const gchar *pref_name); /** Reset all preferences in a group to their default values in the preferences backend. * * @param group This string specifies the group to which the preference belongs */ void gnc_prefs_reset_group (const gchar *group); /** Get and Set registered preference id for register auto_raise_lists */ gulong gnc_prefs_get_reg_auto_raise_lists_id (void); void gnc_prefs_set_reg_auto_raise_lists_id (gulong id); /** Get and Set registered preference id for register negative_color_pref */ gulong gnc_prefs_get_reg_negative_color_pref_id (void); void gnc_prefs_set_reg_negative_color_pref_id (gulong id); /** @} */ #ifdef __cplusplus } #endif #endif /* GNC_PREFS_H */ /** @} */ /** @} */