Set the window icon

A window has an icon in its title bar, on its taskbar button, and in the switcher of the windows. Packaging gives the application its icon, see Give the application an icon and a name, but a run from the IDE has none, and an application may want a window or a state of its own: a different icon for a document, for a warning, for a recording that is on. In this guide, a window starts with a blue icon, and Java changes it to green and back.

Give a window an icon

public class WindowIcons {
  public static void main(String[] args) {
    try (Application application = Application.create()) {
      Window window =
          application.open(
              WindowParameters.builder()
                  .title("Icon")
                  .size(new WindowSize(520, 130))
                  .icon("icon/blue.png")
                  .resource("icon/index.html")
                  .build());
      window.bind("setIcon", WindowIcons.chooser(window));
      window.show();
      application.run();
    }
  }

  private static Function<String, String> chooser(Window window) {
    return color -> {
      switch (color) {
        case "blue" -> window.icon("icon/blue.png");
        case "green" -> window.icon("icon/green.png");
        default -> window.icon((byte[]) null);
      }
      return color;
    };
  }
}

The icon is a PNG image, from the resources of the application as above, or as bytes: .icon(bytes) and window.icon(bytes). A square of 256 pixels or more is enough, because the platform scales it down to the sizes that it needs, from 16 pixels in a title bar to 32 and more on a taskbar. Anything that isn't a PNG throws IllegalArgumentException, and the window keeps the icon that it had.

The page calls the binding like any other:

document.querySelector("#green").addEventListener("click", () => window.setIcon("green"));

window.icon(null) brings the icon of the platform back. Pass (byte[]) null, because a plain null also fits the overload for a resource.

Where the icon shows

Platform	What the icon is
Windows	The title bar, the taskbar button, and Alt+Tab
macOS	The Dock and the switcher: the icon of the whole application, so every window of it shares it. macOS has no icon of a single window, and the title bar has none
Linux, GTK 3	On X11, the title bar and the taskbar. A window manager may go on showing the last icon after null. On Wayland the compositor takes the icon from the .desktop file of the application and ignores this one
Linux, GTK 4	None: GTK 4 has no call that takes an image for a window, and the desktop takes the icon from the .desktop file

Good to know

• On Linux, the icon of the .desktop file is the reliable one for a shipped application, and the Gradle plugin writes it. icon(...) is for a development run, and for a window that changes its icon while the application runs.
• On macOS, icon(...) changes the icon of the Dock for the whole run, not for one window, and null brings back the one of the bundle.
• Set the icon before show(), or in the parameters, so that the window never shows the generic icon for a moment.