Add support for customizable window icons

Merged-by: Stefan Walter <stefan.walter@iml.fraunhofer.de>

Author: martingr

opentcs-common/src/main/java/org/opentcs/util/gui/Icons.java

@@ -4,8 +4,10 @@
 
 import java.awt.Image;
 import java.io.IOException;
+import java.net.URL;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Objects;
 import javax.imageio.ImageIO;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -24,13 +26,25 @@ public final class Icons {
    */
   private static final String ICON_PATH = "/org/opentcs/util/gui/res/icons/";
   /**
-   * File names of the openTCS window icons.
+   * File names of the default openTCS window icons.
    */
-  private static final String[] ICON_FILES = {"opentcs_icon_016.png",
+  private static final List<String> DEFAULT_ICON_FILES = List.of(
+      "opentcs_icon_016.png",
       "opentcs_icon_032.png",
       "opentcs_icon_064.png",
       "opentcs_icon_128.png",
-      "opentcs_icon_256.png"};
+      "opentcs_icon_256.png"
+  );
+  /**
+   * File names of custom window icons that can be provided by a user.
+   */
+  private static final List<String> CUSTOM_ICON_FILES = List.of(
+      "custom_icon_016.png",
+      "custom_icon_032.png",
+      "custom_icon_064.png",
+      "custom_icon_128.png",
+      "custom_icon_256.png"
+  );
 
   /**
    * Prevents instantiation.
@@ -40,23 +54,62 @@ private Icons() {
   }
 
   /**
-   * Get the icon for OpenTCS windows in different resolutions.
+   * Get the icon for openTCS windows in different resolutions.
    *
    * @return List of icons
    */
   public static List<Image> getOpenTCSIcons() {
+    List<Image> customIcons = loadCustomIcons();
+    return customIcons.isEmpty() ? loadDefaultIcons() : customIcons;
+  }
+
+  private static List<Image> loadCustomIcons() {
+    List<Image> icons = loadIcons(findFiles(ICON_PATH, CUSTOM_ICON_FILES));
+
+    if (icons.isEmpty()) {
+      LOG.debug(
+          "Couldn't find any custom icon files at '{}' (file names: {}). Using default icon files.",
+          ICON_PATH,
+          CUSTOM_ICON_FILES
+      );
+      return List.of();
+    }
+
+    if (icons.size() < CUSTOM_ICON_FILES.size()) {
+      LOG.warn(
+          "Couldn't find all custom icon files at '{}' (file names: {}). Using default icon files.",
+          ICON_PATH,
+          CUSTOM_ICON_FILES
+      );
+      return List.of();
+    }
+
+    return icons;
+  }
+
+  private static List<Image> loadDefaultIcons() {
+    return loadIcons(findFiles(ICON_PATH, DEFAULT_ICON_FILES));
+  }
+
+  private static List<URL> findFiles(String path, List<String> fileNames) {
+    return fileNames.stream()
+        .map(fileName -> Icons.class.getResource(path + fileName))
+        .filter(Objects::nonNull)
+        .toList();
+  }
+
+  private static List<Image> loadIcons(List<URL> files) {
     try {
       List<Image> icons = new ArrayList<>();
-      for (String iconFile : ICON_FILES) {
-        String iconURL = ICON_PATH + iconFile;
-        final Image icon = ImageIO.read(Icons.class.getResource(iconURL));
+      for (URL iconFile : files) {
+        final Image icon = ImageIO.read(iconFile);
         icons.add(icon);
       }
       return icons;
     }
-    catch (IOException | IllegalArgumentException exc) {
-      LOG.warn("Couldn't load icon images from path {}", ICON_PATH, exc);
-      return new ArrayList<>();
+    catch (IOException exc) {
+      LOG.warn("Couldn't load icon images from paths: {}", files, exc);
+      return List.of();
     }
   }
 }

opentcs-documentation/src/docs/developers-guide/05_extending-control-center.adoc

@@ -46,3 +46,19 @@ See the JDK's API documentation for more information about how this mechanism wo
 (The openTCS start scripts include all JAR files in that directory in the application's classpath.)
 
 Panels meeting these requirements are found automatically when you start the kernel control center application.
+
+=== How to change the window icon
+
+To change the image that is used as the icon for the application window:
+
+. Prepare custom icon files with the following names (the number at the end of the file name indicates the respective image's expected width and height in pixels):
+** `custom_icon_016.png`
+** `custom_icon_032.png`
+** `custom_icon_064.png`
+** `custom_icon_128.png`
+** `custom_icon_256.png`
+. Create a JAR file (with any name, e.g. `my-custom-icons.jar`) that contains the custom icon files in a folder named `/org/opentcs/util/gui/res/icons/`.
+* Place the JAR file in the subdirectory `lib/` of the kernel control center application's installation directory _before_ the application is started.
+  (The openTCS start scripts include all JAR files in that directory in the application's classpath.)
+
+Note that the default set of icons will be used if _any_ of the custom icons (as described above) could not be found.

opentcs-documentation/src/docs/developers-guide/06_extending-model-editor-and-operations-desk.adoc

@@ -100,3 +100,19 @@ To customize the appearance of locations and vehicles, new theme implementations
 . Set the `locationThemeClass` or `vehicleThemeClass` in the Operations Desk application's configuration file.
 
 Vehicles or locations in plant models are then rendered using your custom theme.
+
+=== How to change the window icon
+
+To change the image that is used as the icon for the application window:
+
+. Prepare custom icon files with the following names (the number at the end of the file name indicates the respective image's expected width and height in pixels):
+** `custom_icon_016.png`
+** `custom_icon_032.png`
+** `custom_icon_064.png`
+** `custom_icon_128.png`
+** `custom_icon_256.png`
+. Create a JAR file (with any name, e.g. `my-custom-icons.jar`) that contains the custom icon files in a folder named `/org/opentcs/util/gui/res/icons/`.
+* Place the JAR file in the subdirectory `lib/` of the Model Editor application's and/or Operations Desk application's installation directory _before_ the application is started.
+  (The openTCS start scripts include all JAR files in that directory in the respective application's classpath.)
+
+Note that the default set of icons will be used if _any_ of the custom icons (as described above) could not be found.

opentcs-documentation/src/docs/release-notes/changelog.adoc

@@ -22,6 +22,8 @@ This change log lists the most relevant changes for past releases in reverse chr
 ** Allow order sequences to contain multiple types of transport orders.
    Instead of a single type, order sequences now define a set of order types.
    Additionally, transport orders whose type is included in this set of order types can be added to the order sequence.
+** Add support for customizable window icons.
+   For more information, please refer to the developer's guide.
 ** Update web API specification and implementation to version 1.14.0:
 *** Extend the request body of the `POST /orderSequences/{NAME}` endpoint so that it also excepts a list of order types.
 *** Extend the response bodies where order sequences are returned to also include the list of order types.