mirror of
https://github.com/Gnucash/gnucash.git
synced 2024-11-30 12:44:01 -06:00
6157251573
A couple of preference callbacks are setup to track the 'negative_color_preference' and 'auto_raise_lists' which are setup with a call to 'g_once'. To be able to remove these, the the preference id is saved so that they can be used in gnc_main_window_remove_prefs to remove the callback.
573 lines
22 KiB
C
573 lines
22 KiB
C
/********************************************************************\
|
|
* gnc-prefs.h -- Api to load and store preferences to a *
|
|
* configurable backend *
|
|
* *
|
|
* Copyright (C) 2013 Geert Janssens <geert@kobaltwit.be> *
|
|
* *
|
|
* 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 <geert@kobaltwit.be>
|
|
*/
|
|
|
|
#ifndef GNC_PREFS_H
|
|
#define GNC_PREFS_H
|
|
|
|
#include <glib.h>
|
|
|
|
/* 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"
|
|
|
|
/** @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);
|
|
|
|
/** @} */
|
|
|
|
|
|
#endif /* GNC_PREFS_H */
|
|
|
|
/** @} */
|
|
/** @} */
|