...and they shall know me by my speling errors.

Danno Ferrin (aka shemnon) on stuff that matters to him.

Adding Icons With the Gradle JavaFX Plugin

The 0.2.0 release of the Gradle JavaFX Plugin is just around the corner. I want to spend some time building all the samples on all of the platforms and making sure smoke doesn’t come out. Expect it in a day or two.

The major feature for this release is better handling of packaged icons across the platforms. There is a file convention manner and a build script configuration method that will allow you to take a set of PNG images and let the build tool create the needed specialty file for each platform.

A quick word of warning before I dive into the details. You have to choose either the convention or the configuration, not both. If you do any configuration of your icons then none of the file conventions will be applied.

Icons By Convention

The easiest method is just to place specifically named icons in a specific place. The directory you should place the icons in is src/deploy/package. The icons also all need to be PNG images. The real magic is in how you name your icons. If they have the right pattern for their name then icon will be used and the sizes and other metadata are calculated by the plugin.

When naming icons for the conventional method the first part of the name describes the role of the icon. Right now the values are shortcut, volume, and setup. An icon of type shortcut will be the icon in the launcher, executable, taskbar, menu, or dock. An icon of type volume will be used for the MacOSX DMG folder icon. And an icon of type setup will appear in the corner of a Windows EXE setup wizard.

The second part of the name is any random set of characters. You would do this to distinguish the various sizes of the icons. However multiple icons are only recommend for the shortcut and volume icon sets, since the setup icon is converted into a BMP by the plugin. For MacOSX you also need to pay attention to the icon sizes, since only certain sizes are used by the MacOSX ICNS file. Those size are 16, 32, 128, 256, and 512 square. Note that 64x64 is not in that list!

The final part of the name is only relevant to MacOSX installers. If the file has ‘@2x’ in it’s name anywhere, it is presumed to be a HDPI icon for that size. This means that the pixel dimensions are twice as large for that icon then the size it is considered to be. Right now the string can occur anywhere, but future versions of the plugin may require it to be at the end of the name.

For example, a 16x16 icon named shortcut.png would be used as the shortcut icon. If there was another 512x512 icon named shortcut-awesome.png that icon would be used as well. And if a 1024x1024 icon was also in the correct directory and it was named shortcutReallyAwesome@2x.png then it would be a shortcut icon, at HDPI scale 2, used for the 512x512 icon. For a functional example of this see the brickbreaker sample in the source code.

Icons by Configuration

If you want to have the build script configure the icons you can do that as well. This will allow the re-use of icons across different usage kinds. There are two methods of configuration both of which are supported when using the configuration option.

The shorthand method involved adding an icons configuration setting inside the javafx configuration setting. Inside this configuration you set a value for each kind of icon you are using to either a string or list of strings. These strings will be resolved as files against the src/deploy/package directory. For example, from the FullyExpressed sample (which is a junk project that turns every knob and flips every switch just to do it) the icons are configured like this:

1
2
3
4
5
6
7
8
9
10
11
12

javafx {
    /*. . . snip . . .*/
    icons {
        shortcut = ['shortcut-16.png', 'shortcut-32.png', 
                    'shortcut-128.png', 'shortcut-256.png', 
                    'shortcut-16@2x.png', 'shortcut-32@2x.png', 
                    'shortcut-128@2x.png']
        volume = 'javafx-icon.png'
        setup = 'javafx-icon.png'
    }
    /*. . . snip . . .*/
}

Like the conventional way the sizes of the icons are sniffed out and the HDPI icons all contain ‘@2x’ at the end of their name. The icons also all must be PNG icons. Finally, remember that any text between the kind and the possible end of the name is not used by the plugin, unless it is the @2x at the end to tell the icon it is a HDPI icon.

If you need total control over the JNLP descriptor you can specify each one in an icon setting. You repeat the setting for each icon. You can then set each attribute individually. For example, form the same FullyExpressed sample the splash and selected icons are configured manually.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

javafx {
    /*. . . snip . . .*/
    icon {
        href = 'src/main/resources/javafx-icon.png'
        kind = 'splash'
        width = 128
        height = 128
    }
    icon {
        href = 'shortcut-32@2x.png'
        kind = 'selected'
        width = 16
        height = 16
        scale = 1
    }
    /*. . . snip . . .*/
}

Packager Defaults

The defaults provided buy the JavaFX packaging library were not changed. So if you see a grey embossed java coffee cup then the default for that icon has not been changed.

If you want to use the current code, you can add apply from: 'https://repository-javafx-gradle-plugin.forge.cloudbees.com/snapshot/javafx.plugin to the top of your gradle file. Or you can wait a few days until I push the bits to BinTray.

Comments