1 /********************************************************************\ 2 * gnc-prefs.h -- Api to load and store preferences to a * 3 * configurable backend * 4 * * 5 * Copyright (C) 2013 Geert Janssens <geert@kobaltwit.be> * 6 * * 7 * This program is free software; you can redistribute it and/or * 8 * modify it under the terms of the GNU General Public License as * 9 * published by the Free Software Foundation; either version 2 of * 10 * the License, or (at your option) any later version. * 11 * * 12 * This program is distributed in the hope that it will be useful, * 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of * 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * 15 * GNU General Public License for more details. * 16 * * 17 * You should have received a copy of the GNU General Public License* 18 * along with this program; if not, contact: * 19 * * 20 * Free Software Foundation Voice: +1-617-542-5942 * 21 * 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 * 22 * Boston, MA 02110-1301, USA gnu@gnu.org * 23 * * 24 ********************************************************************/ 25 26 /** @addtogroup Engine 27 @{ */ 28 /** @addtogroup Preferences Preferences 29 30 The API in this file is used to read and store preferences used 31 by gnucash. This api is a generic one. To actually store and 32 load preferences, a preferences backend should be configured. 33 Currently only one backend is defined: the preferences backend. 34 35 Note that preferences are organized in groups. Most functions 36 will require both a group and a preference name to find the 37 exact preference to work with. 38 39 @{ */ 40 /** @file gnc-prefs.h 41 * @brief Generic api to store and retrieve preferences. 42 * @author Copyright (C) 2013 Geert Janssens <geert@kobaltwit.be> 43 */ 44 45 #ifndef GNC_PREFS_H 46 #define GNC_PREFS_H 47 48 #ifdef __cplusplus 49 extern "C++" { 50 #include <glib.h> 51 } 52 #endif 53 54 /* Preference groups used across multiple modules */ 55 #define GNC_PREFS_GROUP_GENERAL "general" 56 #define GNC_PREFS_GROUP_GENERAL_REGISTER "general.register" 57 #define GNC_PREFS_GROUP_GENERAL_REPORT "general.report" 58 #define GNC_PREFS_GROUP_WARNINGS "general.warnings" 59 #define GNC_PREFS_GROUP_WARNINGS_TEMP "warnings.temporary" 60 #define GNC_PREFS_GROUP_WARNINGS_PERM "warnings.permanent" 61 #define GNC_PREFS_GROUP_ACCT_SUMMARY "window.pages.account-tree.summary" 62 63 /* Preference names used across multiple modules */ 64 #define GNC_PREF_VERSION "prefs-version" 65 #define GNC_PREF_SAVE_GEOMETRY "save-window-geometry" 66 #define GNC_PREF_LAST_PATH "last-path" 67 #define GNC_PREF_USE_NEW "use-new-window" 68 #define GNC_PREF_ACCOUNTING_LABELS "use-accounting-labels" 69 #define GNC_PREF_ACCOUNT_SEPARATOR "account-separator" 70 #define GNC_PREF_NEGATIVE_IN_RED "negative-in-red" 71 #define GNC_PREF_NUM_SOURCE "num-source" 72 #define GNC_PREF_DATE_FORMAT "date-format" 73 #define GNC_PREF_DATE_COMPL_THISYEAR "date-completion-thisyear" 74 #define GNC_PREF_DATE_COMPL_SLIDING "date-completion-sliding" 75 #define GNC_PREF_DATE_BACKMONTHS "date-backmonths" 76 #define GNC_PREF_SHOW_LEAF_ACCT_NAMES "show-leaf-account-names" 77 #define GNC_PREF_ENTER_MOVES_TO_END "enter-moves-to-end" 78 /* Register preferences */ 79 #define GNC_PREF_DRAW_HOR_LINES "draw-horizontal-lines" 80 #define GNC_PREF_DRAW_VERT_LINES "draw-vertical-lines" 81 #define GNC_PREF_ALT_COLOR_BY_TRANS "alternate-color-by-transaction" 82 #define GNC_PREF_USE_THEME_COLORS "use-theme-colors" // Obsolete, to remove in a future major version (> 2.8) 83 #define GNC_PREF_USE_GNUCASH_COLOR_THEME "use-gnucash-color-theme" 84 #define GNC_PREF_TAB_TRANS_MEMORISED "tab-to-transfer-on-memorised" 85 #define GNC_PREF_FUTURE_AFTER_BLANK "future-after-blank-transaction" 86 /* Date preferences */ 87 #define GNC_PREF_START_CHOICE_ABS "start-choice-absolute" 88 #define GNC_PREF_START_CHOICE_REL "start-choice-relative" 89 #define GNC_PREF_START_DATE "start-date" 90 #define GNC_PREF_START_PERIOD "start-period" 91 #define GNC_PREF_END_CHOICE_ABS "end-choice-absolute" 92 #define GNC_PREF_END_CHOICE_REL "end-choice-relative" 93 #define GNC_PREF_END_DATE "end-date" 94 #define GNC_PREF_END_PERIOD "end-period" 95 /* Currency preferences */ 96 #define GNC_PREF_CURRENCY_OTHER "currency-other" 97 #define GNC_PREF_CURRENCY_CHOICE_LOCALE "currency-choice-locale" 98 #define GNC_PREF_CURRENCY_CHOICE_OTHER "currency-choice-other" 99 100 /** @name Early bird functions, needed before any backend has been set up 101 @{ 102 */ 103 104 const gchar *gnc_prefs_get_namespace_regexp(void); 105 void gnc_prefs_set_namespace_regexp(const gchar *str); 106 107 gboolean gnc_prefs_is_debugging_enabled(void); 108 void gnc_prefs_set_debugging(gboolean d); 109 110 gboolean gnc_prefs_is_extra_enabled(void); 111 void gnc_prefs_set_extra(gboolean enabled); 112 113 gboolean gnc_prefs_get_file_save_compressed(void); 114 void gnc_prefs_set_file_save_compressed(gboolean compressed); 115 116 gint gnc_prefs_get_file_retention_policy(void); 117 void gnc_prefs_set_file_retention_policy(gint policy); 118 119 gint gnc_prefs_get_file_retention_days(void); 120 void gnc_prefs_set_file_retention_days(gint days); 121 122 guint gnc_prefs_get_long_version( void ); 123 124 /** @} */ 125 126 127 /** Test if preferences backend is set up 128 */ 129 gboolean gnc_prefs_is_set_up (void); 130 131 /** Block all preference callbacks 132 */ 133 void gnc_prefs_block_all (void); 134 135 /** Unblock all preferences callbacks 136 */ 137 void gnc_prefs_unblock_all (void); 138 139 /** @name Listening for changes 140 @{ 141 */ 142 143 144 /** Register a callback that gets triggered when the given preference changes. 145 * Any time the preference's value changes, the routine 146 * will be invoked and will be passed both the changed preference 147 * and the user data passed to this function. 148 * 149 * @param group This string contains the group name of the preference 150 * to watch. 151 * 152 * @param preference This string contains the name of the preference to watch. 153 * 154 * @param func This is a pointer to the function to call when the preference 155 * changes. 156 * 157 * @param user_data This pointer will be passed to the callback 158 * function. 159 * 160 * @return This function returns the handler id for the registered 161 * callback. 162 */ 163 gulong gnc_prefs_register_cb (const char *group, 164 const gchar *pref_name, 165 gpointer func, 166 gpointer user_data); 167 168 169 /** Remove a function that was registered for a callback when the 170 * given preference changed. Both the func and user_data 171 * arguments are used to match up the callback to remove. 172 * If no matching func and user_data are found to be registered 173 * for the given preference, nothing will happen. 174 * 175 * @param group This string contains the group name of the preference 176 * that is being watched. 177 * 178 * @param preference This string contains the name of the preference being watched. 179 * 180 * @param func This is a pointer to the function that was registered 181 * earlier. 182 * 183 * @param user_data This pointer was passed to the callback 184 * function when it was registered. 185 */ 186 void gnc_prefs_remove_cb_by_func (const gchar *group, 187 const gchar *pref_name, 188 gpointer func, 189 gpointer user_data); 190 191 192 /** Remove a function that was registered for a callback when a 193 * specific preference in the settings group changed. The handler id 194 * that was generated when the callback was registered is 195 * use to find the callback to remove. 196 * If no handler id is found nothing will happen. 197 * 198 * @param group This string contains the group name of the preference 199 * that is being watched. 200 * 201 * @param id The handler id of the callback to be removed. 202 */ 203 void gnc_prefs_remove_cb_by_id (const gchar *group, 204 guint id); 205 206 207 /** Register a callback for when any preference in the settings group 208 * is changed. Any time the value of a preference in this group changes, 209 * the routine will be invoked and will be passed the specified 210 * user data. 211 * 212 * @param group This string contains the name of the group 213 * that is being watched. 214 * 215 * @param func This is a pointer to the function to call when a preference 216 * changes. 217 * 218 * @param user_data This pointer will be passed to the callback 219 * function. 220 */ 221 guint gnc_prefs_register_group_cb (const gchar *group, 222 gpointer func, 223 gpointer user_data); 224 225 226 /** Remove a function that was registered for a callback when any preference 227 * in the given settings group changed. Both the func and user_data 228 * arguments are used to match up the callback to remove. 229 * If no matching func and user_data are found to be registered 230 * for the given preference, nothing will happen. 231 * 232 * @param group This string contains the name of the group 233 * that is being watched. 234 * 235 * @param func This is a pointer to the function that was registered 236 * earlier. 237 * 238 * @param user_data This pointer was passed to the callback 239 * function when it was registered. 240 * 241 * @note there is no gnc_settings_remove_any_cb_by_id. Use 242 * gnc_settings_remove_cb_by_id instead if you want to 243 * remove a callback set with gnc_settings_register_any_cb 244 * by its handler id. 245 */ 246 void gnc_prefs_remove_group_cb_by_func (const gchar *group, 247 gpointer func, 248 gpointer user_data); 249 250 251 /** Bind a setting to a g_object property. When this succeeds a change 252 * of the setting will automatically update the bound object property 253 * and vice versa. 254 * 255 * @param group This string contains the group name of the preference to bind to. 256 * 257 * @param preference This string is the name of the particular preference to 258 * bind to. 259 * 260 * @param object The object to be bound. 261 * 262 * @param property The property of the object to bind to. 263 */ 264 void gnc_prefs_bind (const gchar *group, 265 /*@ null @*/ const gchar *pref_name, 266 gpointer object, 267 const gchar *property); 268 269 /** @} */ 270 271 /** @name Preference Getters 272 @{ 273 */ 274 275 /** Get a boolean value from the preferences backend. 276 * 277 * @param group This string specifies the group to which the preference belongs 278 * 279 * @param preference This string is the name of the particular preference within 280 * the named group of the preferences backend. 281 * 282 * @return This function returns the TRUE or FALSE value stored at 283 * the requested preference in the preferences backend. If the preference has never 284 * been set, this function passes on the default value returned by 285 * the preferences backend. 286 */ 287 gboolean gnc_prefs_get_bool (const gchar *group, 288 /*@ null @*/ const gchar *pref_name); 289 290 /** Get an integer value from the preferences backend. 291 * 292 * @param group This string specifies the group to which the preference belongs 293 * 294 * @param preference This string is the name of the particular preference within 295 * the named group of the preferences backend. 296 * 297 * @return This function returns the integer value stored at the 298 * requested preference in the preferences backend. If the preference has never been 299 * set, this function passes on the default value returned by the preferences backend. 300 * If there is an error in processing, zero will be returned. 301 */ 302 gint gnc_prefs_get_int (const gchar *group, 303 const gchar *pref_name); 304 305 /** Get an 64 bit integer value from the preferences backend. 306 * 307 * @param group This string specifies the group to which the preference belongs 308 * 309 * @param preference This string is the name of the particular preference within 310 * the named group of the preferences backend. 311 * 312 * @return This function returns the 64 bit integer value stored at the 313 * requested preference in the preferences backend. If the preference has never been 314 * set, this function passes on the default value returned by the preferences backend. 315 * If there is an error in processing, zero will be returned. 316 */ 317 gint64 gnc_prefs_get_int64 (const gchar *group, 318 const gchar *pref_name); 319 320 /** Get an float value from the preferences backend. 321 * 322 * @param group This string specifies the group to which the preference belongs 323 * 324 * @param preference This string is the name of the particular preference within 325 * the named group of the preferences backend. 326 * 327 * @return This function returns the float value stored at the 328 * requested preference in the preferences backend. If the preference has never been 329 * set, this function passes on the default value returned by the preferences backend. 330 * If there is an error in processing, zero will be returned. 331 */ 332 gdouble gnc_prefs_get_float (const gchar *group, 333 const gchar *pref_name); 334 335 /** Get a string value from the preferences backend. 336 * 337 * @param group This string specifies the group to which the preference belongs 338 * 339 * @param preference This string is the name of the particular preference within 340 * the named group of the preferences backend. 341 * 342 * @return This function returns the string value stored at the 343 * requested preference in the preferences backend. If the preference has never been 344 * set, this function passes on the default value returned by the preferences backend 345 * If there is an error in processing, NULL will be returned. 346 */ 347 gchar *gnc_prefs_get_string (const gchar *group, 348 const gchar *pref_name); 349 350 /** Get an enum value from the preferences backend. 351 * 352 * @param group This string specifies the group to which the preference belongs 353 * 354 * @param preference This string is the name of the particular preference within 355 * the named group of the preferences backend. 356 * 357 * @return This function returns the enum value stored at the 358 * requested preference in the preferences backend. If the preference has never been 359 * set, this function passes on the default value returned by the preferences backend. 360 * If there is an error in processing, zero will be returned. 361 */ 362 gint gnc_prefs_get_enum (const gchar *group, 363 const gchar *pref_name); 364 365 /** Get a pair of coordinates from the preferences backend. 366 * 367 * @param group This string specifies the group to which the preference belongs 368 * 369 * @param preference This string is the name of the particular preference within 370 * the named group of the preferences backend. 371 * 372 * @param x The x coordinate to retrieve. 373 * 374 * @param y The y coordinate to retrieve. 375 * 376 * If there is an error in processing, both coordinates will be set to zero. 377 */ 378 void gnc_prefs_get_coords (const gchar *group, 379 const gchar *pref_name, 380 gdouble *x, gdouble *y); 381 382 /** Get an arbitrary combination of values from the preferences backend. This 383 * combination of values can be anything that can be encapsulated 384 * in a GVariant structure. 385 * 386 * @param group This string specifies the group to which the preference belongs 387 * 388 * @param preference This string is the name of the particular preference within 389 * the named group of the preferences backend. 390 * 391 * @return This function returns the a GVariant encapsulating the combination 392 * of values stored at the requested preference in the preferences backend. 393 * If the preference has never been set, this function passes on the default 394 * value returned by the preferences backend. 395 * If there is an error in processing, NULL will be returned. 396 * It is the callers responsibility to free any GVariant data returned 397 * by this function. 398 */ 399 GVariant *gnc_prefs_get_value (const gchar *group, 400 const gchar *pref_name); 401 402 /** @} */ 403 404 /** @name Preference Setters and Unset Functions 405 @{ 406 */ 407 408 409 /** Store a boolean value into the preferences backend. 410 * 411 * @param group This string specifies the group to which the preference belongs 412 * 413 * @param preference This string is the name of the particular preference within 414 * the named group of the preferences backend. 415 * 416 * @param value The boolean value to be stored. 417 * 418 * @return This function returns true if the value was set successfully 419 * on the preference or false if not. 420 */ 421 gboolean gnc_prefs_set_bool (const gchar *group, 422 const gchar *pref_name, 423 gboolean value); 424 425 /** Store an integer value into the preferences backend. 426 * 427 * @param group This string specifies the group to which the preference belongs 428 * 429 * @param preference This string is the name of the particular preference within 430 * the named group of the preferences backend. 431 * 432 * @param value The integer number to be stored. 433 * 434 * @return This function returns true if the value was set successfully 435 * on the preference or false if not. 436 */ 437 gboolean gnc_prefs_set_int (const gchar *group, 438 const gchar *pref_name, 439 gint value); 440 441 /** Store a 64 bit integer value into the preferences backend. 442 * 443 * @param group This string specifies the group to which the preference belongs 444 * 445 * @param preference This string is the name of the particular preference within 446 * the named group of the preferences backend. 447 * 448 * @param value The 64 bit integer number to be stored. 449 * 450 * @return This function returns true if the value was set successfully 451 * on the preference or false if not. 452 */ 453 gboolean gnc_prefs_set_int64 (const gchar *group, 454 const gchar *pref_name, 455 gint64 value); 456 457 /** Store a float value into the preferences backend. 458 * 459 * @param group This string specifies the group to which the preference belongs 460 * 461 * @param preference This string is the name of the particular preference within 462 * the named group of the preferences backend. 463 * 464 * @param value The floating point number to be stored. 465 * 466 * @return This function returns true if the value was set successfully 467 * on the preference or false if not. 468 */ 469 gboolean gnc_prefs_set_float (const gchar *group, 470 const gchar *pref_name, 471 gdouble value); 472 473 474 /** Store a string into the preferences backend. 475 * 476 * @param group This string specifies the group to which the preference belongs 477 * 478 * @param preference This string is the name of the particular preference within 479 * the named group of the preferences backend. 480 * 481 * @param value The string to be stored. the preferences backend will make a copy of this 482 * string, so it is the callers responsibility to free the space used 483 * by this string (if necessary). 484 * 485 * @return This function returns true if the value was set successfully 486 * on the preference or false if not. 487 */ 488 gboolean gnc_prefs_set_string (const gchar *group, 489 const gchar *pref_name, 490 const gchar *value); 491 492 /** Store an enum value into the preferences backend. 493 * 494 * @param group This string specifies the group to which the preference belongs 495 * 496 * @param preference This string is the name of the particular preference within 497 * the named group of the preferences backend. 498 * 499 * @param value The enum number to be stored. 500 * 501 * @return This function returns true if the value was set successfully 502 * on the preference or false if not. 503 */ 504 gboolean gnc_prefs_set_enum (const gchar *group, 505 const gchar *pref_name, 506 gint value); 507 508 /** Store coordinates into the preferences backend. Coordinates consist of 509 * a pair of floating point values (x and y). 510 * 511 * @param group This string specifies the group to which the preference belongs 512 * 513 * @param preference This string is the name of the particular preference within 514 * the named group of the preferences backend. 515 * 516 * @param x The x coordinate to be stored. 517 * 518 * @param y The y coordinate to be stored. 519 * 520 * @return This function returns true if the value was set successfully 521 * on the preference or false if not. 522 */ 523 gboolean gnc_prefs_set_coords (const gchar *group, 524 const gchar *pref_name, 525 gdouble x, gdouble y); 526 527 /** Store an arbitrary combination of values into the preferences backend. 528 * 529 * @param group This string specifies the group to which the preference belongs 530 * 531 * @param preference This string is the name of the particular preference within 532 * the named group of the preferences backend. 533 * 534 * @param value The combination of values encapsulated in a GVariant 535 * to be stored. 536 * 537 * @return This function returns true if the value was set successfully 538 * on the preference or false if not. 539 */ 540 gboolean gnc_prefs_set_value (const gchar *group, 541 const gchar *pref_name, 542 GVariant *value); 543 544 /** Reset a preference to its default value in the preferences backend. 545 * 546 * @param group This string specifies the group to which the preference belongs 547 * 548 * @param preference This string is the name of the particular preference within 549 * the named group of the preferences backend. 550 */ 551 void gnc_prefs_reset (const gchar *group, 552 const gchar *pref_name); 553 554 /** Reset all preferences in a group to their default values in the preferences backend. 555 * 556 * @param group This string specifies the group to which the preference belongs 557 */ 558 void gnc_prefs_reset_group (const gchar *group); 559 560 /** Get and Set registered preference id for register auto_raise_lists 561 */ 562 gulong gnc_prefs_get_reg_auto_raise_lists_id (void); 563 void gnc_prefs_set_reg_auto_raise_lists_id (gulong id); 564 565 /** Get and Set registered preference id for register negative_color_pref 566 */ 567 gulong gnc_prefs_get_reg_negative_color_pref_id (void); 568 void gnc_prefs_set_reg_negative_color_pref_id (gulong id); 569 570 /** @} */ 571 572 573 #endif /* GNC_PREFS_H */ 574 575 /** @} */ 576 /** @} */ 577