1. Introduction
Ikonli provides icon packs that can be used in Java applications. Currently Swing and JavaFX UI toolkits are supported.
1.1. Download
Ikonli and all of its icon packs can be downloaded from Maven Central
.
You must select a binary that matches your target UI toolkit, such as
| Swing |
ikonli-swing-12.3.1 (JDK 11+) or ikonli-swing-2.6.0 (JDK 8) |
| JavaFX |
ikonli-javafx-12.3.1 (JDK 11+) or ikonli-javafx-2.6.0 (JDK 8) |
Not all icon packs are available in the JDK8 only version (2.6.0).
|
Next, select any of the icon packs you want to use. You may select more than one for the same application.
1.2. Breaking Changes
If you are upgrading to 12.0.0 or later be aware of the following changes:
-
The module names moved from
org.kordamp.iconlitoorg.kordamp.ikonli.*. -
The
icon-hawkconsfilled-packandicon-hawkconsstroke-packicon packs were merged into a singleicon-hawkcons-packicon pack. -
The method
getCode()oforg.kordamp.ikonli.Ikonnow returnsintinstead ofchar. This change is needed to accomodate icon packs whose icon codes are larger than a single char, such as MaterialDesign. -
The interface
org.kordamp.ikonli.IkonHandlerno longer has a methodString getFontResourcePath(); it has two new methods instead:URL getFontResource()andInputStream getFontResourceAsStream().
2. Usage
2.1. Swing
The ikonli-swing:12.3.1 JAR provides a new Icon class: org.kordamp.ikonli.swing.FontIcon.
You may use this class with any Swing component that supports an Icon property.
2.2. JavaFX
The ikonli-javafx:12.3.1 JAR provides a new Node class: org.kordamp.ikonli.javafx.FontIcon.
You may use this class with any JavaFX control that accepts a graphic property. You may also use the icon directly as
it is a subclass of javafx.scene.text.Text. The icon class can be used inside an FXML file too.
<?xml version="1.0" encoding="UTF-8"?>
<?import javafx.scene.control.Button?>
<?import javafx.scene.layout.GridPane?>
<?import org.kordamp.ikonli.javafx.FontIcon?>
<GridPane prefHeight="60.0" prefWidth="200.0"
xmlns:fx="http://javafx.com/fxml"
fx:controller="org.example.AppController">
<Button GridPane.columnIndex="0" GridPane.rowIndex="0"
mnemonicParsing="false"
prefWidth="200.0">
<graphic>
<FontIcon iconLiteral="di-java" iconSize="64"/>
</graphic>
</Button>
</GridPane>The iconLiteral property accepts any of these formats
-
icon-code
-
icon-code:icon-size
-
icon-code:icon-size:icon-color
where the following rules apply
- icon-code
-
An icon code literal such as
di-java. The prefix (di-) indicates the icon pack. For this example, DevIcons needs to be installed. - icon-size
-
A number (in pixels) specifying the width of the icon.
- icon-color
-
A
javafx.scene.paint.Color,javafx.scene.paint.LinearGradient, orjavafx.scene.paint.RadialGradientliteral.
di-java
di-java:32
di-java:64:BLUEorg.kordamp.ikonli.javafx.FontIcon exposes properties that can be styled using CSS. It defines a node class named ikonli-font-icon.
| -fx-icon-code |
An icon literal such as |
| -fx-icon-size |
The size of the icon, in pixels. |
| -fx-icon-color |
A JavaFX |
A stackable version is also available, org.kordamp.ikonli.javafx.StackedFontIcon. This is an specialized version of javafx.scene.layout.StackPane
that accepts instances of org.kordamp.ikonli.javafx.FontIcon as child content. You may use this class with FXML, like it’s shown
in the following example
<?xml version="1.0" encoding="UTF-8"?>
<?import javafx.scene.layout.GridPane?>
<?import org.kordamp.ikonli.javafx.FontIcon?>
<?import org.kordamp.ikonli.javafx.StackedFontIcon?>
<GridPane prefHeight="60.0" prefWidth="200.0"
xmlns:fx="http://javafx.com/fxml"
fx:controller="org.example.AppController">
<StackedFontIcon GridPane.columnIndex="0" GridPane.rowIndex="0" iconSize="48">
<FontIcon iconLiteral="fa-circle-thin" iconColor="red"/>
<FontIcon iconLiteral="fa-camera" StackedFontIcon.iconSize="0.5"/>
</StackedFontIcon>
</GridPane>org.kordamp.ikonli.javafx.StackedFontIcon exposes properties that can be styled using CSS. It defines a node class named stacked-ikonli-font-icon.
| -fx-icon-size |
The size of the icon, in pixels. |
| -fx-icon-color |
A JavaFX |
2.2.1. Installing
repositories {
mavenCentral()
}
dependencies {
implementation 'org.kordamp.ikonli:ikonli-javafx:12.3.1'
}<dependencies>
<dependency>
<groupId>org.kordamp.ikonli</groupId>
<artifactId>ikonli-javafx</artifactId>
<version>12.3.1</version>
</dependency>
</dependencies>Next, don’t forget to add entries to your module descriptor (module-info.java). Here’s for example the
minimum settings required for a JavaFX application
module com.acme.demo {
requires javafx.base;
requires javafx.graphics;
requires javafx.controls;
requires org.kordamp.ikonli.core;
requires org.kordamp.ikonli.javafx;
// add icon pack modules
requires org.kordamp.ikonli.fontawesome;
}2.3. Creating a Fat JAR
Ikonli’s icon packs rely on services files to provide their implementation. You must make sure that those services files are properly merged when creating a Fat JAR or Uber JAR and your application does not use the modulepath. Fortunately there are build plugins that can help with this task.
Configure the shadow plugin and merge service files
plugins {
id 'com.github.johnrengelman.shadow' version '6.1.0'
}
shadowJar {
mergeServiceFiles()
}Configure the maven-shade-plugin and apply the
org.apache.maven.plugins.shade.resource.ServicesResourceTransformer transformer.
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.2.4</version>
<configuration>
<transformers>
<transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
</transformers>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
</execution>
</executions>
</plugin>2.4. BOM
Starting with version 12.0.0 Ikonli offers a BOM for all core projects and icon packs. You may configure it with either
Gradle or Maven.
repositories {
mavenCentral()
}
dependencies {
implementation platform('org.kordamp.ikonli:ikonli-bom:12.3.1')
implementation 'org.kordamp.ikonli:ikonli-javafx'
implementation 'org.kordamp.ikonli:ikonli-fontawesome5-pack'
}<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.kordamp.ikonli</groupId>
<artifactId>ikonli-bom</artifactId>
<version>12.3.1</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>org.kordamp.ikonli</groupId>
<artifactId>ikonli-javafx</artifactId>
</dependency>
<dependency>
<groupId>org.kordamp.ikonli</groupId>
<artifactId>ikonli-fontawesome5-pack</artifactId>
</dependency>
</dependencies>3. Icon Packs
4. Authoring
Follow these steps to create and register custom icons.
4.1. Define an Ikon class
Create an Enum that implements the org.kordamp.ikonli.Ikon type. Each enum entry should define
the icon’s description and code. Make sure to use a unique prefix in the description, for example
package com.acme.mine;
import org.kordamp.ikonli.Ikon;
public enum MyIcon implements Ikon {
ICON_NAME("my-icon-name", '\ue600');
public static MyIcon findByDescription(String description) {
for (MyIcon font : values()) {
if (font.getDescription().equals(description)) {
return font;
}
}
throw new IllegalArgumentException("Icon description '" + description + "' is invalid!");
}
private String description;
private int code;
MyIcon(String description, int code) {
this.description = description;
this.code = code;
}
@Override
public String getDescription() {
return description;
}
@Override
public int getCode() {
return code;
}
}4.2. Define an Ikon handler
Implement the org.kordamp.ikonli.IkonHandler interface.
package com.acme.mine;
import org.kordamp.ikonli.AbstractIkonHandler;
import org.kordamp.ikonli.Ikon;
import org.kordamp.ikonli.IkonHandler;
import org.kordamp.jipsy.annotations.ServiceProviderFor;
import java.io.InputStream;
import java.net.URL;
@ServiceProviderFor(IkonHandler.class) (1)
public class MyIconIkonHandler extends AbstractIkonHandler {
private static final String FONT_RESOURCE = "/META-INF/resources/myicon/1.2.3/fonts/myicon.ttf";
@Override
public boolean supports(String description) {
return description != null && description.startsWith("my-"); (2)
}
@Override
public Ikon resolve(String description) {
return MyIcon.findByDescription(description);
}
@Override
public URL getFontResource() {
return getClass().getResource(FONT_RESOURCE); (3)
}
@Override
public InputStream getFontResourceAsStream() {
return getClass().getResourceAsStream(FONT_RESOURCE); (3)
}
@Override
public String getFontFamily() {
return "MyIcon-Font"; (4)
}
}| 1 | Generates an entry at META-INF/services/org.kordamp.ikonli.IkonHandler. |
| 2 | Note the use of the icon prefix. |
| 3 | Locate the font resource. |
| 4 | Name of the font family. |
The use of the @ServiceProviderFor annotation requires having jipsy configured
as an annotation processor. You may skip this dependency and manually create the service file yourself. You must provide
a service entry if the icon is to be consumed in the classpath, as not everyone uses the modulepath.
com.acme.mine.MyIconIkonHandler4.3. Define an Ikon provider
Implement the org.kordamp.ikonli.IkonProvider interface.
package com.acme.mine;
import org.kordamp.ikonli.IkonProvider;
import org.kordamp.jipsy.annotations.ServiceProviderFor;
@ServiceProviderFor(IkonProvider.class) (1)
public class MyIconIkonProvider implements IkonProvider<MyIcon> {
@Override
public Class<MyIcon> getIkon() {
return MyIcon.class;
}
}| 1 | Generates an entry at META-INF/services/org.kordamp.ikonli.IkonProvider. |
The use of the @ServiceProviderFor annotation requires having jipsy configured
as an annotation processor. You may skip this dependency and manually create the service file yourself. You must provide
a service entry if the icon is to be consumed in the classpath, as not everyone uses the modulepath.
com.acme.mine.MyIconIkonProvider4.4. Configure the module descriptor (Optional)
If you’re building a Java module then you must register the previous implementations in a module descriptor
module com.acme.mine {
requires org.kordamp.ikonli.core;
requires static org.kordamp.jipsy.annotations; (1)
exports com.acme.mine;
provides org.kordamp.ikonli.IkonHandler
with com.acme.mine.MyIconIkonHandler;
provides org.kordamp.ikonli.IkonProvider
with com.acme.mine.MyIconIkonProvider;
}| 1 | Needed only if you use jipsy. |