16.5.18 Adding stock icons

XML files can be used to define “stock icons”. Stock icons are pictures that are identified by their label, and which are used through GPS in various places, such as buttons, menus, toolbars, and so on.

The stock icons must be declared using the tag <icon>, within the global tag <stock>. The attribute id indicates the label used to identify the stock icon, and the attribute file points to the file which contains the actual picture, either in absolute format, or relative to the directory which contains the XML file.

If the stock icon is to be used in a toolbar, use the attribute label to specify the text to display in the toolbar, under the button, when the toolbar is configured to show text.

For icons that are intended to be displayed at multiple sizes, you can specify multiple files corresponding to these multiple sizes. This is done by adding children to the main icon node, with the tag alternate, containing a file attribute and a size attribute which correspond to the size for which this alternate source should be used.

Possible sizes are:

1

Menu item (ideal size: 16x16 pixels)

2

Button in a small toolbar (ideal size: 18x18 pixels)

3

Button in a large toolbar (ideal size: 24x24 pixels)

4

Image for a standard button (ideal size: 20x20 pixels)

5

Image used during drag-and-drop operation (ideal size: 32x32 pixels)

6

Main image in a dialog (ideal size: 48x48 pixels)

Here is an example:

     <?xml version="1.0"?>
     <my_visual_preferences>
       <stock>
         <icon id="myproject-my-picture" file="icons/my-picture.png" />
     
         <icon id="myproject-multipurpose-image"
                label="do something"
                file="icons/icon_default.png">
            <alternate file"icons/icon_16.png" size="menu" />
            <alternate file"icons/icon_24.png" size="large_toolbar" />
            <alternate file"icons/icon_20.png" size="button" />
         </icon>
     
       </stock>
     </my_visual_preferences>

Note: as shown in the example above, it is a good practice to prefix the label by a unique name (e.g. myproject-), in order to make sure that predefined stock icons will not get overridden by your icons.