Package swingtree.style

Class SvgIcon

java.lang.Object
javax.swing.ImageIcon
swingtree.style.SvgIcon
All Implemented Interfaces:
Serializable, Accessible, Icon
public final class SvgIcon extends ImageIcon
A specialized ImageIcon subclass that allows you to use SVG based icon images in your GUI. This in essence just a wrapper around the JSVG library, which renders SVG images using the Java2D graphics API.

You may use this like a regular ImageIcon, but have to keep in mind that SVG documents do not really have a fixed size, meaning that the getIconWidth() and getIconHeight() on a freshly loaded SvgIcon will return -1 which causes the icon to be rendered according to the width and height of the component it is rendered into (see paintIcon(Component, java.awt.Graphics, int, int)).

If you want to render the icon with a fixed size, you can use the withIconWidth(int) and withIconHeight(int) or withIconSize(int, int) methods to create a new SvgIcon with the given width and height.

An SvgIcon with an undefined width or height will also be using the UI.FitComponent and UI.Placement policies to determine how the icon should be placed and sized within a component. Use the withFitComponent(UI.FitComponent) and withPreferredPlacement(UI.Placement) methods to create a new SvgIcon with the given policies and use the getFitComponent() and getPreferredPlacement() methods to retrieve the current policies (Not that these will not have any effect if the width and height are both defined).

Also note that the direct use of this class and it's API is discouraged in favour of simply calling the UIFactoryMethods.findIcon(String) or UIFactoryMethods.findSvgIcon(String) methods, which will automatically load and cache all of the icons for you.

See Also:

  • Method Details

    • at

      public static SvgIcon at(String path)
      Tries to create an SvgIcon from a resource path defined by the supplied string.
      Parameters:
      path - The path to the SVG document.

    • at

      public static SvgIcon at(String path, Size size)
      Creates an SvgIcon from a resource path and a custom size.
      Parameters:
      path - The path to the SVG document.
      size - The size of the icon in the form of a Size.

    • at

      public static SvgIcon at(URL svgUrl)
      Creates an SvgIcon from the supplied URL pointing to an SVG document. If parsing the SVG document fails, an empty icon will be created, which does not render anything. The resulting icon will have an unknown size, placement and fit policy, meaning that it will be rendered according to the size of the component it is rendered into (see paintIcon(Component, Graphics, int, int)).
      Parameters:
      svgUrl - The URL to the SVG document.

    • at

      public static SvgIcon at(URL svgUrl, Size size)
      Parameters:
      svgUrl - The URL to the SVG document.
      size - The size of the icon in the form of a Size.

    • of

      public static SvgIcon of(String svgString)
      Allows you to directly create an SvgIcon from a string containing an SVG text.
      Parameters:
      svgString - A string containing SVG text.
      Returns:
      A new SvgIcon created from a String containing an SVG document.

    • of

      public static SvgIcon of(String svgString, Size size)
      Allows you to directly create an SvgIcon from a string containing an SVG text, with a custom width and height defined by the supplied Size.
      Parameters:
      svgString - A string containing SVG text.
      size - A Size object containing the desired SVG width and height.
      Returns:
      A new SvgIcon created from a String containing an SVG document and a custom width and height...

    • of

      public static SvgIcon of(InputStream stream)
      Reads the SVG document from the supplied input stream and creates an SvgIcon from it. If parsing the SVG document fails, an empty icon will be created, which does not render anything. The resulting icon will have an unknown size, placement and fit policy, meaning that it will be rendered according to the size of the component it is rendered into (see paintIcon(Component, Graphics, int, int)). If you want to customize the size, layout and placement of the icon, consider creating derived versions using the withIconWidth(int), withIconHeight(int), withIconSize(int, int), withFitComponent(UI.FitComponent) and withPreferredPlacement(UI.Placement) methods.
      Parameters:
      stream - The input stream supplying the text data of the SVG document.

    • of

      public static SvgIcon of(InputStream stream, Size size)
      Reads the SVG document from the supplied input stream and creates an SvgIcon from it with a custom width and height defined by the supplied Size.
      If parsing the SVG document fails, an empty icon will be created, which does not render anything. The resulting icon will have the given size, but the default placement and fit policy, meaning that it will be rendered according to the size of the component it is rendered into (see paintIcon(Component, Graphics, int, int)).
      If you want to customize the layout and placement of the icon, consider creating derived versions using the withFitComponent(UI.FitComponent) and withPreferredPlacement(UI.Placement) methods.
      Parameters:
      stream - The input stream supplying the text data of the SVG document.
      size - The size of the icon in the form of a Size.

    • of

      public static SvgIcon of(com.github.weisj.jsvg.SVGDocument svgDocument)
      Allows you to create an SvgIcon from an already loaded SVGDocument. The icon will be created with an unknown size, meaning that it will be rendered according to the size of the component it is rendered into (see paintIcon(Component, Graphics, int, int)). If you want to customize the size, layout and placement of the icon, consider creating derived versions using the withIconWidth(int), withIconHeight(int), withIconSize(int, int), withFitComponent(UI.FitComponent) and withPreferredPlacement(UI.Placement) methods.
      Parameters:
      svgDocument - The already loaded SVG document, which will be used to render the icon.

    • of

      public static SvgIcon of(com.github.weisj.jsvg.SVGDocument svgDocument, Size size)
      Allows you to create an SvgIcon from an already loaded SVGDocument with a custom width and height defined by the supplied Size.
      If you want to customize the layout and placement of the icon, consider creating derived versions using the withFitComponent(UI.FitComponent) and withPreferredPlacement(UI.Placement) methods.
      Parameters:
      svgDocument - The already loaded SVG document, which will be used to render the icon.
      size - The size of the icon in the form of a Size.

    • getIconWidth

      public int getIconWidth()
      Exposes the width of the icon, or -1 if the icon should be rendered according to the width of a given component or the width of the SVG document itself. (...or other policies such as UI.FitComponent and UI.Placement).
      Note that the returned width is dynamically scaled according to the current UI.scale() value. This is to ensure that the icon is rendered at the correct size according to the current DPI settings. If you want the unscaled width, use getBaseWidth().
      Specified by:
      getIconWidth in interface Icon
      Overrides:
      getIconWidth in class ImageIcon
      Returns:
      The width of the icon, or -1 if the icon should be rendered according to the width of a given component or the width of the SVG document itself.

    • withIconWidth

      public SvgIcon withIconWidth(int newWidth)
      Creates an updated SvgIcon with the given width returned by getIconWidth().
      Parameters:
      newWidth - The width of the icon, or -1 if the icon should be rendered according to the width of a given component or the width of the SVG document itself.
      Returns:
      A new SvgIcon with the given width. If the width is -1, the icon will be rendered according to the width of a given component or the width of the SVG document itself.

    • getIconHeight

      public int getIconHeight()
      Exposes the height of the icon, or -1 if the icon should be rendered according to the height of a given component or the height of the SVG document itself. (...or other policies such as UI.FitComponent and UI.Placement).
      Note that the returned height is dynamically scaled according to the current UI.scale() value. This is to ensure that the icon is rendered at the correct size according to the current DPI settings. If you want the unscaled height, use getBaseHeight().
      Specified by:
      getIconHeight in interface Icon
      Overrides:
      getIconHeight in class ImageIcon
      Returns:
      A new SvgIcon with the given width and height. If the width or height is -1, the icon will be rendered according to the width or height of a given component or the width or height of the SVG document itself.

    • getBaseWidth

      public int getBaseWidth()
      Exposes the fixed width defined for the icon, which is the width that was set when the icon was created or updated using the withIconWidth(int) method.
      Note that this width is not scaled according to the current UI.scale() value. If you want a scaled width, that is more suitable for rendering the icon, use the getIconWidth() method.
      Returns:
      The width of the icon without scaling.

    • getBaseHeight

      public int getBaseHeight()
      Exposes the fixed height defined for the icon, which is the height that was set when the icon was created or updated using the withIconHeight(int) method.
      Note that this height is not scaled according to the current UI.scale() value. If you want a scaled height, that is more suitable for rendering the icon, use the getIconHeight() method.
      Returns:
      The height of the icon without scaling.

    • withIconHeight

      public SvgIcon withIconHeight(int height)
      Creates an updated SvgIcon with the supplied integer used as the icon height, which you can retrieve using getIconHeight(). If the height is -1, the icon will be rendered according to the height of a given component or the height of the SVG document itself. (...or other policies such as UI.FitComponent and UI.Placement).
      Parameters:
      height - The height of the icon, or -1 if the icon should be rendered according to the height of a given component or the height of the SVG document itself.
      Returns:
      A new SvgIcon with the given height. If the height is -1, the icon will be rendered according to the height of a given component or the height of the SVG document itself.

    • withIconSize

      public SvgIcon withIconSize(int newWidth, int newHeight)
      Creates an updated SvgIcon with the given width and height. Dimensions smaller than 0 are considered "undefined". When the icon is being rendered then these will be determined according to the aspect ratio of the SVG document, the UI.FitComponent / UI.Placement policies or the size of the component the SVG is rendered into.
      Parameters:
      newWidth - The width of the icon, or -1 if the icon should be rendered according to the width of a given component or the width of the SVG document itself.
      newHeight - The height of the icon, or -1 if the icon should be rendered according to the height of a given component or the height of the SVG document itself.
      Returns:
      A new SvgIcon with the given width and height. If the width or height is -1, the icon will be rendered according to the width or height of a given component or the width or height of the SVG document itself.

    • withIconSize

      public SvgIcon withIconSize(Size size)
      Allows you to create an updated SvgIcon with the given size in the form of a Size object containing the width and height. If the width or height is -1, the icon will be rendered according to the width or height of a given component, the width or height of the SVG document and the UI.FitComponent / UI.Placement policies.
      Parameters:
      size - The size of the icon in the form of a Size.
      Returns:
      A new SvgIcon with the given width and height.

    • withIconSizeFromWidth

      public SvgIcon withIconSizeFromWidth(int newWidth)
      Determines the size of the icon (both width and height) using the provided width and the aspect ratio of the SVG document. If the width is -1, the icon will lose its fixed width and will be rendered according to the width of a given component.

      For example, if the SVG document has an aspect ratio of 2:1, and the width is 200, then the height will be 100.

      Also see withIconSizeFromHeight(int).

      Parameters:
      newWidth - The width of the icon, or -1 if the icon should be rendered according to the width of a given component or the width of the SVG document itself.
      Returns:
      A new SvgIcon with the given width and a logical height that is determined by the aspect ratio of the SVG document.

    • withIconSizeFromHeight

      public SvgIcon withIconSizeFromHeight(int newHeight)
      Determines the size of the icon (both width and height) using the provided height and the aspect ratio of the SVG document. If the height is -1, the icon will lose its fixed height and will be rendered according to the height of a given component.

      For example, if the SVG document has an aspect ratio of 2:1, and the height is 100, then the width will be 200.

      Also see withIconSizeFromWidth(int).

      Parameters:
      newHeight - The height of the icon, or -1 if the icon should be rendered according to the height of a given component or the height of the SVG document itself.
      Returns:
      A new SvgIcon with the given height and a logical width that is determined by the aspect ratio of the SVG document.

    • getSvgSize

      public Size getSvgSize()
      The underlying SVG document contains a size object, which is the width and height of the root SVG element inside the document.
      Returns:
      The size of the SVG document in the form of a Size.

    • getSvgDocument

      public @Nullable com.github.weisj.jsvg.SVGDocument getSvgDocument()
      Allows you to access the underlying SVGDocument that is used to render the icon.
      Returns:
      The underlying SVGDocument that is used to render the icon.

    • getFitComponent

      public UI.FitComponent getFitComponent()
      Allows you to access the UI.FitComponent policy, which determines if and how the icon should be fitted onto a component when rendered through the paintIcon(Component, Graphics, int, int) method.
      The following fit modes are available: See withFitComponent(UI.FitComponent) if you want to create a new SvgIcon with an updated fit policy.
      Returns:
      The UI.FitComponent that determines if and how the icon should be fitted into a any given component (see paintIcon(Component, Graphics, int, int) ).

    • withFitComponent

      public SvgIcon withFitComponent(UI.FitComponent fit)
      There are different kinds of strategies to fit an SVG icon onto the component. These strategies are identified using the UI.FitComponent enum which defines the following fit modes:
      Parameters:
      fit - The UI.FitComponent that determines if and how the icon should be fitted into a any given component (see paintIcon(Component, Graphics, int, int) ).
      Returns:
      A new SvgIcon with the given UI.FitComponent policy.

    • getPreferredPlacement

      public UI.Placement getPreferredPlacement()
      The preferred placement policy determines where the icon should be placed within a component when rendered through the paintIcon(Component, Graphics, int, int) method.
      Returns:
      The UI.Placement that determines where the icon should be placed within a component (see paintIcon(Component, Graphics, int, int)).

    • withPreferredPlacement

      public SvgIcon withPreferredPlacement(UI.Placement placement)
      Allows you to get an updated SvgIcon with the given UI.Placement policy which determines where the icon should be placed within a component when rendered through the paintIcon(Component, Graphics, int, int) method.
      Parameters:
      placement - The UI.Placement that determines where the icon should be placed within a component (see paintIcon(Component, Graphics, int, int)).
      Returns:
      A new SvgIcon with the given UI.Placement policy.

    • getImage

      public Image getImage()
      Creates a new Image from the SVG document.
      Overrides:
      getImage in class ImageIcon
      Returns:
      A new Image where the SVG document has been rendered into.

    • setImage

      public void setImage(Image image)
      We don't support this. An SVG document is not really an image, it's a vector graphic. Extending ImageIcon is just for compatibility reasons...
      Overrides:
      setImage in class ImageIcon

    • paintIcon

      public void paintIcon(Component c, Graphics g, int x, int y)
      Specified by:
      paintIcon in interface Icon
      Overrides:
      paintIcon in class ImageIcon
      Parameters:
      c - The component to render the icon into.
      g - the graphics context
      x - the X coordinate of the icon's top-left corner
      y - the Y coordinate of the icon's top-left corner

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • toString

      public String toString()
      Overrides:
      toString in class ImageIcon