Howto add preference options (was: GnuCash developper documentation)

[Christian Stimming]

-----BEGIN PGP SIGNED MESSAGE-----

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.



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:

(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))

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:

  cache_pin = 
    gnc_lookup_boolean_option(N_("Online Banking & Importing"),
			      "HBCI Remember PIN in memory",
                              FALSE);

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/standard-reports/register.scm
line 556:

  (gnc:option-value (gnc:lookup-global-option "User Info" "User Name"))

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).
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iQCVAwUBPdwDD2XAi+BfhivFAQEiwwP9HOB15IM3ZQUyWnx5HwfZmDY5OuZYbI2B
b454IPyJg20+2L55exIEDS8baaP+9cxMgOAQjhCa+2QvdlhfSTaFu03cVEU8ww7G
J/tlxx+ZJ0jVqKdbca0MO9wPRdzLlhVm6ZvToGr7DEFOPQ3Df49D/QbDWFMm62sp
Ko3WiAjwxbI=
=bWRN
-----END PGP SIGNATURE-----