Package swingtree.api

Interface IconDeclaration

@Immutable public interface IconDeclaration
Primarily designed to be implemented by an Enum type that declares a set of icon paths so that the enum instances can be used to identify and load (cached) icons across your application.

Here an example of how to use this interface: 


 public enum Icons implements IconDeclaration
 {
     ADD("icons/add.png"),
     REMOVE("icons/remove.png"),
     EDIT("icons/edit.png"),
     SAVE("icons/save.png"),
     CANCEL("icons/cancel.png"),
     REFRESH("icons/refresh.png");
     // ...

     private final String path;

     Icons(String path) { this.path = path; }

     {@literal @}Override public String path() {
         return path;
     }
 }
You may then use the enum instances in the SwingTree API just like you would use the ImageIcon class: 

  UI.button(Icons.ADD)
  .onClick( it -> vm.add() )
The reason why enums should be used instead of Strings is so that you have some more compile time safety in your application! When it comes to resource loading Strings are brittle because they are susceptible to typos and refactoring mistakes.

Instances of this class are intended to be used as part of a view model instead of using the Icon or ImageIcon classes directly.

The reason for this is the fact that traditional Swing icons are often heavyweight objects whose loading may or may not succeed, and so they are not suitable for direct use in a property as part of your view model. Instead, you should use this IconDeclaration interface, which is a lightweight value object that merely models the resource location of the icon even if it is not yet loaded or even does not exist at all.

Not only does this make your view model more robust, but it also allows you to write unit tests much more easily, because you can now create instances where the icon may not be available at all, yet you can still test the behavior of your view model.

  • Method Summary

    Modifier and Type
    Method
    Description
    default Optional<ImageIcon>
    find()
    This method is used to find the icon resource and load it as an ImageIcon instance wrapped in an Optional, or return an empty Optional if the icon resource could not be found.
    default <T extends ImageIcon>
    Optional<T>
    find(Class<T> type)
    This method is used to find an ImageIcon of a specific type and load and return it wrapped in an Optional, or return an empty Optional if the icon resource could not be found.
    static IconDeclaration
    of(String path)
    A factory method for creating an IconDeclaration instance from the provided path to the icon resource.
    static IconDeclaration
    of(Size size, String path)
    A factory method for creating an IconDeclaration instance from the provided path to the icon resource and the preferred size.
    String
    path()
    The most important part of the identity of an icon declaration is the path to the icon resource.
    default Size
    size()
    The preferred size of the icon, which is not necessarily the actual size of the icon that is being loaded but rather the size that the icon should be scaled to when it is being loaded.
    default IconDeclaration
    withHeight(int height)
    Allows you to create an updated IconDeclaration instance with a new preferred height for the icon.
    default IconDeclaration
    withSize(int width, int height)
    Creates and returns an updated IconDeclaration instance with a new preferred width and height for the icon.
    default IconDeclaration
    withSize(Size size)
    Creates and returns an updated IconDeclaration instance with a new preferred size for the icon.
    default IconDeclaration
    withWidth(int width)
    Creates and returns an updated IconDeclaration instance with a new preferred width for the icon.

  • Method Details

    • path

      String path()
      The most important part of the identity of an icon declaration is the path to the icon resource. This path may be relative to the classpath or may be an absolute path.
      Returns:
      The path to the icon resource, which is relative to the classpath or may be an absolute path.

    • size

      default Size size()
      The preferred size of the icon, which is not necessarily the actual size of the icon that is being loaded but rather the size that the icon should be scaled to when it is being loaded.
      Returns:
      The preferred size of the icon or Size.unknown() if the size is unspecified, which means that the icon should be loaded in its original size.

    • find

      default Optional<ImageIcon> find()
      This method is used to find the icon resource and load it as an ImageIcon instance wrapped in an Optional, or return an empty Optional if the icon resource could not be found.
      Returns:
      An Optional that contains the ImageIcon if the icon resource was found, otherwise an empty Optional.

    • withSize

      default IconDeclaration withSize(Size size)
      Creates and returns an updated IconDeclaration instance with a new preferred size for the icon.
      Parameters:
      size - The preferred size of the icon in the form of a Size instance.
      Returns:
      A new IconDeclaration instance with the same path but with the given size.

    • withSize

      default IconDeclaration withSize(int width, int height)
      Creates and returns an updated IconDeclaration instance with a new preferred width and height for the icon.
      Parameters:
      width - The preferred width of the icon.
      height - The preferred height of the icon.
      Returns:
      A new IconDeclaration instance with the same path but with the specified width and height as preferred size.

    • withWidth

      default IconDeclaration withWidth(int width)
      Creates and returns an updated IconDeclaration instance with a new preferred width for the icon.
      Parameters:
      width - The preferred width of the icon.
      Returns:
      A new IconDeclaration instance with the same path but with the specified width as preferred width.

    • withHeight

      default IconDeclaration withHeight(int height)
      Allows you to create an updated IconDeclaration instance with a new preferred height for the icon.
      Parameters:
      height - The preferred height of the icon.
      Returns:
      A new IconDeclaration instance with the same path but with the specified height as preferred height.

    • find

      default <T extends ImageIcon> Optional<T> find(Class<T> type)
      This method is used to find an ImageIcon of a specific type and load and return it wrapped in an Optional, or return an empty Optional if the icon resource could not be found.
      Type Parameters:
      T - The type of icon to find.
      Parameters:
      type - The type of icon to find.
      Returns:
      An Optional that contains the ImageIcon of the given type.

    • of

      static IconDeclaration of(String path)
      A factory method for creating an IconDeclaration instance from the provided path to the icon resource.
      Parameters:
      path - The path to the icon resource, which may be relative to the classpath or may be an absolute path.
      Returns:
      A new IconDeclaration instance that represents the given icon resource as a constant.

    • of

      static IconDeclaration of(Size size, String path)
      A factory method for creating an IconDeclaration instance from the provided path to the icon resource and the preferred size.
      Parameters:
      size - The preferred size of the icon.
      path - The path to the icon resource, which may be relative to the classpath or may be an absolute path.
      Returns:
      A new IconDeclaration instance that represents the given icon resource as a constant.