Difference between revisions of "Adding Preferences"

Latest revision as of 18:28, 6 April 2023

Adding a new preference item in gnucash requires changes in several different places, most of which are not directly in c(++) code. This page will provide an overview of the different parts that will be affected.

Usually 2 GnuCash projects are affected: #Code and #Docs, in some cases also the #Wiki.

Preliminary Considerations

Some developers think Gnucash has already become very complex and try to avoid new preferences.

1. Are there probably better ways to achieve the same result?
2. Is it really a per user preference or a book option? Can 2 users with different settings for your preference share the same file without damage or other annoying effects?

Code

Assume you want to add a combobox in which the user can select the calendar widget to use (like a Gregorian vs a Jalali calendar widget).

There are several examples you can follow in the preferences already. The date-format combobox is probably a good start.

Start by defining your new combobox in the glade interface file (src/gnucash-git/gnucash/gtkbuilder/dialog-preferences.glade). Note the name needs a particular format, which I'll get back to later.

Each combobox needs a model, which you can also define in the same glade file. For the date-format combobox this is a gtkliststore with the name "date-formats". Define one similar for your combobox.

Next, all settings you see in the preferences dialog are stored in gsettings. Gsettings uses xml configuration files to define its settings. You'll need to create the schema for your specific preference. The schema are stored in gsettings subdirectories in various places of the code. The other date-time related settings are defined in src/gnome/gsettings/org.gnucash.gschema.xml.in.in so this would be a good place to add the calendar format gsettings schema as well. For other preferences there may be a better schema file.

Again you can follow the example of the date-format preference, that is add a key to the general schema for your preference. It will store an integer value which is the selected line number in the combobox' liststore (though 0-based). This sounds more complicated than it is really. If you offer the user two options in your combobox, like this:

• Gregorian calendar
• Jalali calendar

and the user selects "Jalali calendar", the value to store in the preference will be 1. Otherwise it will be 0. The new preference should also get a default value. In general the default for a new preference should be such that the most sensible behaviour is chosen for the user. In most cases this means the setting that would result in no change for existing users. A jalali format calendar is the new option here and the gregorian format is the current behaviour. So in this case it makes sense to choose 0 as the default value.

Choose an easy to understand and translate description.

And now for a crucial part: the name of your combobox in the glade file should be the gsettings path of your preference prefixed with "pref/". For the date-format preference for example this becomes:

pref/general/date-format

The combobox called that way will be tied automatically to the date-format gsettings preference in the general section in gsettings. This part is crucial. If the name of the widget is not correctly matched to the gsettings key, your preference will not work.

Add the description from gsettings as tooltip to your control element. The first label of your control element should have a comment to give translators a clue, where to find it in the program.

Lastly, due to the way gtkbuilder works, you'll have to explicitly tell gnucash to load the liststore you have defined for your combobox. It will load the combobox automatically, but not the liststore. This needs one more line in src/gnome-utils/dialog-preferences.c around line 1084. This is not relevant for other types of preferences (like check boxes).

After all that is done your preference should just work.

For readability you should add a #define for the key of your preference in your own code, starting with "GNC_PREF_" and use that in combination with GNC_PREFS_GROUP_GENERAL in your calls to gnc_prefs_get_int to query the value of the new preference.

Finally, you may want to listen for changes in your new preference in order to update date/time widgets on open registers, report-option dialogs and anywhere else you are offering the jalali calendar as alternative. You can register callbacks to your preference via "gnc_prefs_register_cb"

In summary, adding preferences will require changes to the following pages located in the src/gnucash-git directory:

• gnucash/gschemas/org.gnucash.gschema.xml.in
• gnucash/gtkbuilder/dialog-preferences.glade
• libgnucash/app-utils/migratable-prefs.xml.in
• libgnucash/core-utils/core-utils.i
• libgnucash/core-utils/gnc-prefs.h

Make sure you rebuild all modules after adding preferences or the new ones will not work.

Docs

Every change in the GUI should also be documented in the GnuCash Help Manual.

• Every preference should have at least a

  <listitem>
    <para><guilabel>New Preference</guilabel>
    Copy at least your tooltip from the glade file here. But you are not restricted in the size and can add more background information.</para>
  </listitem>
  

section in the respective section of gnucash-docs/C/manual/ch_Customize.xml. Feel free to add some more text.

• The respective screenshot has to be regenerated. See Documentation Update Instructions#Images and screenshots and Documentation Update Instructions#Graphics conventions for details.

• Review the guide for necessary changes or add there a section about the best way to use your preference.

Wiki

Search also the wiki for relevant places:

• Are there assumptions about the old behavior?

and update them.