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.

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