User Preferences
****************

This whole document is completely outdated. Don't read this. All function names and every described structure has changed completely. Only read this if you want to know how gnucash looked like in 1999. This is completely outdated!

The options system is used to obtain user preferences, both globally, and when displaying a report. A wide variety of option types are supported, so it should be possible to create an option for just about any property the user might wish to specify.  New option types can be added if necessary, but as the process requires detailed knowledge of GnuCash internals and GTK+/GNOME, it is not documented here.

At present, users are most likely to come across the options system when designing custom reports, and are consequently mostly going to use the Scheme interface. There is also a C interface to much of the options system which is used to access preferences for the UI, but it is not yet documented.

Option Databases
================

The options for a particular report are placed in an options database.  For doing a report, the option-generator function must return an options database.  The function

(gnc:new-option)

returns a new, empty options database that you can then add options to.

Options are organised into sections, which are each given a title string such as "Register" or "International".  The UI displays each section on a separate page.  Each section has a number of options.  Each option has a name that uniquely identifies it in that section, and an alphabetic sort tag that determines the relative ordering of the options for display.

Option Types
============

Sometimes, GnuCash requires the user to specify true/false properties. Others properties most easily specified by selections from a list, others from a number, others still by selecting dates, or one or more accounts in the account hierarchy, or even colors.  GnuCash supports all of these and more:

boolean

     These are displayed as a checkbox by the UI.  They are used to specify yes/no answers.

string

     The UI provides a text entry box where arbitrary text may be entered.

font

     This allows users to select fonts from those available on the system.

currency

     For specifying a currency such as "USD", "AUD", "UKP" etc.

date

     For specifying dates.  Depending on exactly what is required, you can choose to let the user specify an absolute date, a relative date such as "one month ago", or "start of the current accounting period", or let the user choose how whether to specify the required date in relative or absolute terms.

account-list

     For selecting a particular account or accounts.  The UI displays a tree of the account hierarchy.

multichoice

     For selecting one of a group of choices.

list

     Similar to the multichoice option, but allows the selection of one or more items from the group.

number-range

     For specifying a numeric quantity.  The programmer can bound the range and precision of the quantity.

pixmap

     For selecting a pixmap located on the filesystem.

color

     For selecting a color value.

internal

     An option that isn't specified through an options dialog box.  For instance, this is used to store the window dimensions so that they are preserved along with other preferences.

Option Creation
===============

To add an option to an options database, you first create that option, then register it with the database.  For example, to create a simple checkbox-style boolean option, you would use gnc:make-simple-boolean-option to create the option.  Once created, you can then register the option.  With gnc:register-option.

 -- Function: gnc:register-option database option
     Register OPTION in options database DATABASE

The example below shows how to create an options database, then register a boolean option with it:

     (define gnc:*hello-world-options* (gnc:new-options))
     (gnc:register-option gnc:*hello-world-options*
          (gnc:make-simple-boolean-option
           "Hello, World!" "Boolean Option"
           "a" "This is a boolean option." #t))

Option Creation Functions
-------------------------

 -- Function: gnc:make-simple-boolean-option section name sort-tag documentation-string default-value

     Creates a boolean option, with option section SECTION and name NAME specified as strings.  Note that the section and name strings uniquely specify the option for the option database that they get registered to, and are used for looking up the option when the value is required.  SORT-TAG is a string tag that specifies the relative order when displaying the options.  Options are displayed top to bottom in case-sensitive alphabetical order.  DOCUMENTATION-STRING is a string containing a short string describing the purpose of the option, which the UI displays as a tooltip.  DEFAULT-VALUE should be a boolean value indicating the default value of this option.

     Note that SECTION, NAME, SORT-TAG, and DOCUMENTATION-STRING are common to all the following functions.

 -- Function: gnc:make-complex-boolean-option section name sort-tag documentation-string default-value setter-function-called-cb option-widget-changed-cb

     As above, but the function specified in OPTION-WIDGET-CHANGED-CB is called when the GUI widget representing the option is changed (the user clicks on the toggle button), and SETTER-FUNCTION-CALLED-CB is called when the option's setter is called (when the user selects "OK" or "Apply").

     One use for having a non-false OPTION-WIDGET-CHANGED-CB is to make another option mutable (in concert with gnc:option-set-sensitive, discussed later).

 -- Function: gnc:make-string-option section name sort-tag documentation-string default-value

     Make an option where the user can specify a string.

 -- Function: gnc:make-date-option section name sort-tag documentation-string default-getter show-time subtype relative-date-list

     Create a date option.  There are three different variations of date options, specified by the variable SUBTYPE, which should be one of 'relative, 'absolute, or both.  absolute date options allow the selection of a specific day/month/year combination.  relative date options allow the selection from a list of different dates specified in relation to the current date, such as "today", "start of the current month", or "six months ago".  Finally both allows the user to choose either using absolute or relative date options.

DEFAULT-GETTER should be a thunk (Scheme function taking no arguments) that returns a pair.  The car of the pair should contain either 'relative or 'absolute, to indicate whether the default value is relative or absolute.  If the car is relative, then the cdr should be a one of the relative date symbols listed in RELATIVE-DATE-LIST.  If the car is absolute, it should be a timepair containing the default date/time.

SHOW-TIME is a boolean that indicates whether when selecting an absolute date, the user can specify a time.  It is ignored if the SUBTYPE is relative.

RELATIVE-DATE-LIST is a list of symbols that indicate the relative dates permitted.  The symbols used must have been previously defined as indicating a particular relative date.  GNC:RELATIVE-DATES contains a list of symbols that have already been set up for the most common relative dates.  FIXME: document relative date system.

 -- Function: gnc:make-multichoice-option section name sort-tag documentation-string default-value value-list

     Create a multichoice option.  VALUE-LIST is a list of vectors of length 3, each representing a different choice.  Each vector should contain - in the following order:

       * A symbol identifying this choice.

       * A string naming this choice - this string will be the main one displayed.

       * A string describing this choice slightly more fully.  This string will appear as a tooltip.

 -- Function: gnc:make-list-option section name sort-key documentation-string default-values value-list

     Like a multichoice option, but users can select one or more values from a list.  DEFAULT-VALUES is a list of selected values instead of just one.

 -- Function: gnc:make-font-option section name sort-tag documentation-string default-value

     Allow the user to specify the font.  Font options store font descriptions as strings, like the X Logical Font Description.  You must provide a default value, as there is unfortunately no easy way for the GUI to pick a default value.

 -- Function: gnc:make-color-option section name sort-key documentation-string default-value
     scale use-alpha?

     Allow the user to select a color.  The default value should be a list of length 4 containing the red, green, blue, and alpha channel values for the color.  The scale is the maximum value for a channel, and the use-alpha? is a boolean that, if false, disregards the alpha channel (note: if you don't know what an alpha channel is, you don't need it).

 -- Function: gnc:make-currency-option section name sort-tag documentation-string default-value

     Let the user specify a currency using a currency code.  The GUI provides a specialised widget for currency selection.

 -- Function: gnc:make-account-list-option section name sort-tag documentation-string default-getter value-validator multiple-selection

 -- Function: gnc:make-internal-option section name sort-key documentation-string default-value
     Create an option that isn't controlled through the options GUI.  This is used mainly by the GUI to store state that should be preserved from session to session but isn't really configurable from a dialog box, such as the size of the GnuCash main window.

 -- Function: gnc:make-number-range-option section name sort-tag documentation-string default-value lower-bound upper-bound num-decimals step-size

     Create an option for selecting a numerical quantity.  lower-bound and upper-bound specify the domain of acceptable figures, and num-decimals specifies the range to which the option will be displayed (FIXME:and rounded to?).  Step-size specifies the step size for the UI's up/down buttons.

Option Values
=============

To get the value of an option, you must first lookup the option in the options database.

 -- Function: gnc:lookup-option options section name

     Looks up the option in section SECTION and name NAME in the options database OPTIONS.

Once you have looked up the option, you can get its value using the function gnc:option-value.

 -- Function: gnc:option-value option

     Get the value of an option.  Option values returned are of the same type as how the default values are specified (except the date option which needs to be fixed).