Using icons

From Gramps
Jump to: navigation, search

How to make use of icons in Gramps codebase

Which Icons?

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 16x16, 22x22, 48x48 and scalable. Don't forget to add it to the of all directories!

Next, register the icon in the code. Open the file, and add the icon to items map of the register_stock_icons() function.

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.
  • ICON_SIZE_DND=32px

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.

See also