3.5.10.1. Icon Sets

Icon sets allow you to decouple usage of icons in visual components from real paths to images in theme or font element constants. They also simplify overriding of icons used in the UI inherited from application components.

Icon sets are enumerations with items corresponding to icons. An icon set must implement the Icons.Icon interface which has one parameter: a string which denotes the source of an icon, for example, font-icon:CHECK or icons/myawesomeicon.png. To obtain the source, use the Icons bean provided by the platform.

Icon sets can be created in the web or gui module. All names of icon set items should match the regexp: [A-Z]_, i.e. they should contain only upper-case letters and underscores.

For example:

public enum MyIcon implements Icons.Icon {

    COOL_ICON("icons/cool-icon.png"), (1)

    OK("icons/my-ok.png"); (2)

    protected String source;

    MyIcon(String source) {
        this.source = source;
    }

    @Override
    public String source() {
        return source;
    }

    @Override
    public String iconName() {
        return name();
    }
}
1 - adding new icon,
2 - overriding a CUBA default icon.

Icon sets should be registered in cuba.iconsConfig application property, e.g:

web-app.properties 
cuba.iconsConfig = +com.company.demo.gui.icons.MyIcon

To make the icon set from an application component accessible in the target project, this property should be added to the component descriptor.

Now you can use the icons from this icon set simply by its name declaratively in screen XML descriptor:

<button icon="COOL_ICON"/>

or programmatically in the screen controller:

button.setIconFromSet(MyIcon.COOL_ICON);

The following prefixes allow you to use icons from different sources in declarative way:

  • theme - the icon will be served from the current theme directory, for example, web/themes/halo/awesomeFolder/superIcon.png:

    <button icon="theme:awesomeFolder/superIcon.png"/>

  • file - the icon will be served from file system:

    <button icon="file:D:/superIcon.png"/>

  • classpath - icon will be served from classpath, for example, com/company/demo/web/superIcon.png

    <button icon="classpath:/com/company/demo/web/superIcon.png"/>

There is one predefined icon set provided by the platform - CubaIcon. It includes almost full FontAwesome icon set and CUBA-specific icons. These icons can be selected in Studio icon editor:

icon set