gnucash/libgnucash/doc/user-prefs-howto.txt

/** \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).

*/