/** \page userprefs User Preferences HOWTO Well, since I just explained this issue to Benoit on IRC, I thought I could just post it here. If somebody (Benoit?) considers it helpful, you might add it somewhere to CVS. \section userprefsadd How to add a preferences option This text explains how to add options to the global preference dialog from a module. The text uses the example of one simple boolean option in the import-export/hbci module ("Cache password in memory?"). The option is created in the file src/import-export/hbci/hbci.scm, with the following function call as a top-level function in that file: \verbatim (gnc:register-configuration-option (gnc:make-simple-boolean-option (N_ "Online Banking & Importing") (N_ "HBCI Remember PIN in memory") "b" (N_ "Remember the PIN for HBCI in memory during a session") #f)) \endverbatim The actual option is created by the function call to gnc:make-simple-boolean-option. Its first (string) argument is the tab (page) name. If the option is supposed to appear on an existing tab (page), the string has to match *exactly* the string used in src/app-utils/prefs.scm. The second (string) argument above is the actual option name. For lookup, this *exact* string will need to be used again. For other (more complex) types of options, look up the gnc:make-xyz-option function to create your favorite option type in src/app-utils/options.scm. Also, if one or more options are supposed to go on a *new* tab/page, simply specify a tab/page name that didn't exist yet. It will automatically be added. During the actual program run, the option is looked up only once, in src/import-export/hbci/hbci-interaction.c line 53: \verbatim cache_pin = gnc_lookup_boolean_option(N_("Online Banking & Importing"), "HBCI Remember PIN in memory", FALSE); \endverbatim The third argument here is the default value in case the lookup fails. The C function prototypes for lookup of other options can be found in src/app-utils/global-options.h. A lookup of a global preference in Scheme can be seen e.g. in src/report/reports/standard/register.scm line 556: \verbatim (gnc:option-value (gnc:lookup-global-option "User Info" "User Name")) \endverbatim I.e., the option itself has to be looked up first by gnc:lookup-global-option (from src/app-utils/prefs.scm), and then the function gnc:option-value returns the actual value of the option (defined in src/app-utils/options.scm). */