How to make use of icons in Gramps codebase
Gramps is cross-platform. This has some consequences on the icons you can use.
- Use GTK stock icons. For a list, see GTK stock icons.
- Package the icon with Gramps, giving them a stock gramps name.
So GNOME icons cannot be used, as installing GNOME is not a requirement for running Gramps. Also using standard theme names is not allowed, as users can choose their theme freely.
Using the GTK icons should integrate well with the icon set installed by the users, as this icon set will normally map the GTK stock icons onto icons of the icon theme used. (In case you are a user and this is not the case, read Overrule Gramps Icons).
How to add an Icon to Gramps
Icons reside in directory
src/images. You must follow the Tango Icon Theme Guidelines, and make a 48x48 svg icon, a 22x22 png icon and 16x16 png icon. At the moment, you also need to make a 48x48 png icon for use in Windows.
The icons need to placed in the directories named
scalable. Don't forget to add it to the
Makefile.am of all directories!
Next, register the icon in the code. Open the file
gramps_main.py, and add the icon to
items map of the
How to use an Icon in Gramps
To use an icon, check in Gramps icon set which icon you need. Let's say you want
gramps-person, then do:
image = gtk.Image() image.set_from_stock('gramps-person', gtk.ICON_SIZE_MENU)
You have as option for the sizes:
- ICON_SIZE_BUTTON, normally in GNOME 20px, but following Tango guidelines you should map this to a 22px gramps icon.
Do not use:
- ICON_SIZE_SMALL_TOOLBAR: this is 18px, use ICON_SIZE_MENU instead that will map to a specially reduced version of the SVG.
- ICON_SIZE_LARGE_TOOLBAR: this is 24px, use ICON_SIZE_BUTTON instead, which should be mapped to a 22px gramps-icons
The reason of not using this is to avoid making to many sizes. Everything of size 32px and above can be made from the SVG, two smaller scaled icons should suffice.
In Gramps the sizes DND and DIALOG are made from the svg icon. As the icon set is based on TANGO, the sizes for tango are used for the gramps- icons, meaning that ICON_SIZE_LARGE_TOOLBAR and ICON_SIZE_BUTTON map to 22x22 icons. This means only 16x16, 22x22 and svg need to be provided and encoded.