Package edu.cnu.mdi.graphics

Class ImageManager

java.lang.Object
edu.cnu.mdi.graphics.ImageManager
public final class ImageManager extends Object
Centralized image/icon loading for MDI using classpath resources.

This manager is designed for applications packaged as a JAR where icons/images live under src/main/resources and are loaded from the classpath. This works the same way when MDI is used as a Maven dependency: resources packaged inside the mdi-<version>.jar remain accessible via the classpath.

Resource path convention

Resources are resolved using Class.getResourceAsStream(String) anchored to ImageManager.class. This class accepts resource paths either:

  • Absolute: starting with "/" (recommended), e.g. "/edu/cnu/mdi/icons/zoom_in.svg"
  • Classpath-relative: without a leading "/", e.g. "edu/cnu/mdi/icons/zoom_in.svg" or "icons/zoom_in.svg". In these cases, this class will automatically prepend "/" so the lookup is still absolute in the classpath.

If you want ImageManager to remain agnostic about where resources live, your calling code can keep prepending whatever prefix you like (e.g. "/edu/cnu/mdi/"). This class will load MDI’s icons properly from the MDI dependency JAR, and also load application-provided icons, as long as the resource path is unique on the classpath.

FlatLaf considerations

  • SVG UI icons: Uses FlatSVGIcon. FlatLaf handles HiDPI scaling correctly and SVG icons remain crisp at all scales.
  • Raster UI icons: When an icon is requested at a "logical" size (e.g. 16), raster icons are scaled to device pixels via UIScale.scale(int).
  • Avoid eager static initialization. Look-and-feel setup can affect scaling; this class caches lazily.

Threading

All caches are thread-safe. Icon creation may occur off the EDT, but icons are typically requested during UI construction on the EDT.

  • Field Details

    • MDI_RESOURCE_PATH

      public static final String MDI_RESOURCE_PATH
      Optional convenience prefix for MDI’s own resources.

      This class does not automatically apply this prefix; it is provided so callers can build MDI resource paths consistently.

      See Also:

  • Method Details

    • getInstance

      public static ImageManager getInstance()
      Get the singleton instance.
      Returns:
      the singleton ImageManager

    • loadUiIcon

      public Icon loadUiIcon(String resourcePath, int logicalW, int logicalH)
      Load a UI icon at a given logical size.

      For SVG resources, returns a FlatSVGIcon of the requested size. For raster resources (png/jpg/gif), loads the image and scales it to the requested logical size, then wraps it in an ImageIcon.

      "Logical size" means the size in typical UI coordinates (e.g. 16, 20, 24). Under HiDPI displays, FlatLaf uses a scale factor; for raster icons we convert logical size to device pixels using UIScale.scale(int).

      Parameters:
      resourcePath - classpath resource path (absolute preferred), e.g. "/edu/cnu/mdi/icons/zoom_in.svg" or "edu/cnu/mdi/icons/zoom_in.svg"
      logicalW - requested logical width (e.g. 16, 20, 24)
      logicalH - requested logical height
      Returns:
      an Icon, or null if the resource cannot be found/read
      Throws:
      NullPointerException - if resourcePath is null
      IllegalArgumentException - if logicalW <= 0 or logicalH <= 0

    • loadUiIcon

      public Icon loadUiIcon(String resourcePath, int logicalSize)
      Convenience for square UI icons (e.g. 16x16, 20x20).
      Parameters:
      resourcePath - classpath resource path
      logicalSize - logical size in both dimensions
      Returns:
      an Icon, or null if the resource cannot be found/read
      Throws:
      NullPointerException - if resourcePath is null
      IllegalArgumentException - if logicalSize <= 0

    • loadRaster

      public BufferedImage loadRaster(String resourcePath)
      Load a raster image (PNG/JPG/GIF/etc.) from the classpath as a BufferedImage.

      This returns the original image at its native pixel dimensions. It is cached.

      Parameters:
      resourcePath - classpath resource path (absolute preferred), e.g. "/edu/cnu/mdi/images/background.png"
      Returns:
      the image, or null if the resource cannot be found/read
      Throws:
      NullPointerException - if resourcePath is null

    • loadImage

      public Image loadImage(String resourcePath)
      Load an arbitrary image as an Image.

      Thin convenience wrapper around loadRaster(String) for code that expects Image instead of BufferedImage.

      Parameters:
      resourcePath - classpath resource path
      Returns:
      the image, or null if not found/read

    • loadImageIcon

      public ImageIcon loadImageIcon(String resourcePath)
      Load an ImageIcon without applying any HiDPI logical sizing.

      Prefer loadUiIcon(String, int) for toolbar/menu icons. This method is intended for legacy usage where the caller expects the icon at its native pixel size.

      Parameters:
      resourcePath - classpath resource path
      Returns:
      the image icon, or null if not found/read

    • clearCaches

      public void clearCaches()
      Clear all cached images and icons.

      Useful if you support runtime theme changes and want to rebuild icons, or when memory pressure suggests cache eviction.