Package swingtree.style

Class ImageConf

java.lang.Object
swingtree.style.ImageConf
@Immutable public final class ImageConf extends Object
This class represents the style of an image which can be drawn onto the inner area of a component. Note that the inner component area is the area enclosed by the border, which is itself not part of said area!

The following properties with their respective purpose are available:

  1. Layer: The layer onto which the image will be drawn. Layers exist to determine the order in which something is drawn onto the component. Here a list of available layers:
  2. Primer: The primer color of the image style which will be used as a filler color for the image background. It will fill whatever area was specified using clipTo(UI.ComponentArea).
    The default area used for rendering the image style is UI.ComponentArea.INTERIOR
  3. Image: The image which will be drawn onto the component, which may be specified as an instance of Image, ImageIcon or path to an image file (see UIFactoryMethods.findIcon(String)).
  4. Placement: The placement type determines where the image will be drawn onto the component. The following placement options are available:
  5. Repeat: If this flag is set to true, then the image may be painted multiple times so that it fills up the entire inner component area. There will not be a noticeable effect of this flag if the image already fills out the inner component area (see autoFit(boolean), size(int, int)).
  6. Fit-Mode: If this enum determines how the image will be stretched or shrunk to fill the inner component area dependent on the specified width and height, meaning that if the width was not specified explicitly through width(int) then the image will be scaled to fit the inner component width, and if a height was not specified through height(int) then the image will be scaled to fit the inner component height.
    Note that the inner component area is the area enclosed by the border, which is itself not part of said area!
  7. Width and Height: These properties allow you to specify the width and height of the image. If the width or height is not specified, then the image will be drawn with its original width or height or it will be scaled to fit the inner component area if autoFit(boolean) is set to true.
  8. Opacity: This property allows you to specify the opacity of the image. The opacity must be between 0.0f and 1.0f, where 0.0f means that the image is completely transparent and 1.0f means that the image is completely opaque.
  9. Padding: This property allows you to specify the padding of the image. The padding is the space between the image and the inner component area. The padding can be specified for each side of the image individually or for all sides at once.
  10. Offset: The offset consists of two integers, one for the horizontal offset and one for the vertical offset.
    It allows you to specify the offset of the image from the placement position. This means that after the image has been placed onto the component, it will be moved by the specified offset in the horizontal and vertical direction.
  11. Clip Area: The clip area determines onto which part of the component the image will be drawn. The following clip areas are available:
    • UI.ComponentArea.ALL - The entire component, which is the union of all other clip areas (INTERIOR + EXTERIOR + BORDER + CONTENT).
    • UI.ComponentArea.INTERIOR - The inner component area, which is defined as ALL - EXTERIOR - BORDER.
    • UI.ComponentArea.EXTERIOR - The outer component area, which can be expressed as ALL - INTERIOR - BORDER, or ALL - CONTENT.
    • UI.ComponentArea.BORDER - The border of the component, which is the area between the inner and outer component area and which can be expressed as ALL - INTERIOR - EXTERIOR.
    • UI.ComponentArea.BODY - The body of the component is the inner component area including the border area. It can be expressed as ALL - EXTERIOR, or INTERIOR + BORDER.
    Note that the inner/interior component area is the area enclosed by (and excluding) the border, whereas the exterior component area is the area surrounding the border. The component body area is the interior/inner component area plus the border.

    The default clip area is UI.ComponentArea.INTERIOR as this is the area which is most commonly used.

Take a look at the following example: 


      of(component).withStyle( it -> it
          .image( image -> image
              .layer(Layer.BACKGROUND)
              .image(image)
              .placement(Placement.CENTER)
              .autoFit(false)
              .repeat(true)
              .primer(Color.CYAN)
              .padding(12)
          )
      );

This will draw the specified image onto the background layer of the component. The image will be drawn at the center of the inner component area with a padding of 12, without being scaled to fit the inner component area, instead the size of the image will be used.
If it does not fill the entire inner component area based on its size, then it will be repeated across said area. The primer color serves as a consistent background color which will leak through the transparent parts of the image.

  • Method Summary

    Modifier and Type
    Method
    Description
    ImageConf
    autoFit(boolean autoFit)
    If this flag is set to true, then the image will be stretched or shrunk to fill the inner component area dependent on the specified width and height.
    ImageConf
    clipTo(UI.ComponentArea clipArea)
    Use this to specify the clip area of the image, which determines on which part of the component the image will be drawn.
    boolean
    equals(Object obj)
     
    ImageConf
    fitMode(UI.FitComponent fit)
    There are different kinds of strategies to fit the image onto the component.
    int
    hashCode()
     
    ImageConf
    height(int height)
    Ensures that the image has the specified height, irrespective of other configurations.
    So, if a UI.FitComponent policy was supplied to fitMode(UI.FitComponent) which, for example, stretches the image to fill out the entire component, then supplying a custom height to this method will force this stretched image to have that specific height without preserving its aspect ratio!
    So you may end up rendering a distorted image if not careful.
    Also note that the provided height is considered to include any padding supplied to methods like padding(int), padding(int, int), or padding(int, int, int, int).
    ImageConf
    horizontalOffset(int x)
    Use this to specify the horizontal offset by which the image will be moved and drawn onto the component.
    ImageConf
    image(Image image)
    Here you can specify the image which will be drawn onto the component.
    ImageConf
    image(String path)
    Here you can specify the path to the image you want to draw onto the component.
    ImageConf
    image(ImageIcon image)
    Here you can specify the image icon which will be drawn onto the component.
    ImageConf
    image(IconDeclaration image)
    Here you can specify an image in the form of an IconDeclaration, which typically has a IconDeclaration.source() that holds a path to an image. If the supplied IconDeclaration is path based, then it will be resolved relative to the classpath or as an absolute path.
    ImageConf
    offset(int x, int y)
    Use this to specify the vertical and horizontal offset by which the image will be moved and drawn onto the component.
    ImageConf
    opacity(float opacity)
    This method allows you to specify the opacity of the image.
    ImageConf
    padding(int padding)
    This method allows you to specify the padding for all sides of the image.
    ImageConf
    padding(int topBottom, int leftRight)
    This method allows you to specify extra padding of the image's bounding rectangle.
    ImageConf
    padding(int top, int right, int bottom, int left)
    This method allows you to specify extra padding to the rectangle where the image is drawn.
    ImageConf
    placement(UI.Placement placement)
    Here you can specify the placement of the image onto the component.
    ImageConf
    primer(Color color)
    Here you can specify the primer color of the image style which will be used as background color rendered before the image is rendered.
    ImageConf
    repeat(boolean repeat)
    If this flag is set to true, then the image may be painted multiple times so that it fills out the entire inner component area.
    ImageConf
    simplified()
     
    ImageConf
    size(int width, int height)
    Ensures that the image has the specified width and height (including padding).
    Note that the image may be rendered smaller than the specified dimensions if a padding was specified through methods like padding(int), padding(int, int), or padding(int, int, int, int).
    ImageConf
    size(Size size)
    Ensures that the image has the specified width and height.
    ImageConf
    svg(String svg)
    Use this to specify an image directly in the form of an SVG string in your style.
    String
    toString()
     
    ImageConf
    verticalOffset(int y)
    Use this to specify the vertical offset by which the image will be moved and drawn onto the component.
    ImageConf
    width(int width)
    Ensures that the image has the specified width, irrespective of other configurations.
    So, if a UI.FitComponent policy was supplied to fitMode(UI.FitComponent) which, for example, stretches the image to fill out the entire component, then supplying a custom width to this method will force this stretched image to have that specific width without preserving its aspect ratio!
    So you may end up rendering a distorted image if not careful.
    Also note that the provided width is considered to include any padding supplied to methods like padding(int), padding(int, int), or padding(int, int, int, int).

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • primer

      public ImageConf primer(Color color)
      Here you can specify the primer color of the image style which will be used as background color rendered before the image is rendered.
      Note that the primer color may not necessarily visible if the specified image is fully opaque, and fills the entire component.
      Parameters:
      color - The primer color of the image style.
      Returns:
      A new ImageConf instance with the specified primer color.

    • image

      public ImageConf image(Image image)
      Here you can specify the image which will be drawn onto the component. The supplied object must be aa subtype of Image, like BufferedImage for example.

      Please note that using this method will override whatever information was previously passed to image(ImageIcon), image(IconDeclaration), image(String) or svg(String)!

      Parameters:
      image - The image which will be drawn onto the component.
      Returns:
      A new ImageConf instance with the specified image.

    • image

      public ImageConf image(ImageIcon image)
      Here you can specify the image icon which will be drawn onto the component. The supplied object must be an instance of ImageIcon implementation. So this may also be an SvgIcon for example, which is a ImageIcon subtype...

      Please note that using this method will override whatever information was previously passed to svg(String), image(IconDeclaration), image(String) and image(Image)!

      Parameters:
      image - The image icon which will be drawn onto the component.
      Returns:
      A new ImageConf instance with the specified image.

    • image

      public ImageConf image(IconDeclaration image)
      Here you can specify an image in the form of an IconDeclaration, which typically has a IconDeclaration.source() that holds a path to an image. If the supplied IconDeclaration is path based, then it will be resolved relative to the classpath or as an absolute path. However, the declaration may also be based on an SVG String as source (see IconDeclaration.ofSvg(String)).
      If the icon could not be found or parsed, then the image will not be drawn.

      Please note that using this method will override whatever information was previously passed to image(ImageIcon), svg(String), image(String) and image(Image)!

      Parameters:
      image - The path to the (icon) image or SVG String in the form of an IconDeclaration.
      Returns:
      A new ImageConf instance with the specified icon declaration for resolving an image.
      Throws:
      NullPointerException - If the specified image is null.

    • svg

      public ImageConf svg(String svg)
      Use this to specify an image directly in the form of an SVG string in your style.
      The supplied String will be parsed and converted into a SvgIcon, which can render itself onto a component according to your desired configuration...
      This is equivalent to calling: 
      
     .image(IconDeclaration.ofSvg("..."))
      If the supplied SVG is invalid, then this will result in an empty SvgIcon, which will simply not render anything.

      Please note that using this method will override whatever information was previously passed to image(ImageIcon), image(IconDeclaration), image(String) and image(Image)!

      Parameters:
      svg - A String holding an XML based SVG document.
      Returns:
      A new ImageConf instance with the specified SVG String as source to be rendered as image.
      Throws:
      NullPointerException - If the specified svg is null.

    • image

      public ImageConf image(String path)
      Here you can specify the path to the image you want to draw onto the component. The underlying icon will be loaded, cached and rendered for you automatically. If the icon could not be found, then the image will not be drawn. The path is relative to the classpath or may be an absolute path. (see UIFactoryMethods.findIcon(String)).

      Please note that using this method will override whatever information was previously passed to image(ImageIcon), image(IconDeclaration), svg(String) and image(Image)!

      Parameters:
      path - The path to the (icon) image.
      Returns:
      A new ImageConf instance with the specified image.
      Throws:
      NullPointerException - If the specified path is null.

    • placement

      public ImageConf placement(UI.Placement placement)
      Here you can specify the placement of the image onto the component. The default placement is UI.Placement.CENTER.
      Here a list of available options and their effect:
      • UI.Placement.CENTER - The image will be drawn at the center of the component. So the center of the image will be at the center of the inner component area.
      • UI.Placement.TOP_LEFT - The image will be drawn beginning at the top left corner of the inner component area. So the top left corner of the image will be in the top left corner of the inner component area.
      • UI.Placement.TOP_RIGHT - The image will be placed in the top right corner of the inner component area. So the top right corner of the image will be in the top right corner of the inner component area.
      • UI.Placement.BOTTOM_LEFT - The image will be drawn in the bottom left corner of the inner component area. So the bottom left corner of the image will be in the bottom left corner of the inner component area.
      • UI.Placement.BOTTOM_RIGHT - The image will be drawn in the bottom right corner of the inner component area. So the bottom right corner of the image will be in the bottom right corner of the inner component area.
      • UI.Placement.TOP - The image will be drawn in the top center of the inner component area. So the top center of the image will be in the top center of the inner component area.
      • UI.Placement.BOTTOM - The image will be drawn in the bottom center of the inner component area. So the bottom center of the image will be in the bottom center of the inner component area.
      • UI.Placement.LEFT - The image will be drawn in the left center of the inner component area. So the left center of the image will be in the left center of the inner component area.
      • UI.Placement.RIGHT - The image will be drawn in the right center of the inner component area. So the right center of the image will be in the right center of the inner component area.
      • UI.Placement.UNDEFINED - The image will be drawn at a position which is determined by other factors such as the image size and the component size.
      Parameters:
      placement - The placement of the image onto the component.
      Returns:
      A new ImageConf instance with the specified placement.
      Throws:
      NullPointerException - If the supplied enum constant is null.

    • repeat

      public ImageConf repeat(boolean repeat)
      If this flag is set to true, then the image may be painted multiple times so that it fills out the entire inner component area. There will not be a noticeable effect of this flag if the image already fills out the inner component area (see autoFit(boolean), size(int, int)).
      Parameters:
      repeat - Whether the image should be painted repeatedly across the inner component area.
      Returns:
      A new ImageConf instance with the specified repeat flag value.

    • autoFit

      public ImageConf autoFit(boolean autoFit)
      If this flag is set to true, then the image will be stretched or shrunk to fill the inner component area dependent on the specified width and height. This means that if no custom width was specified through width(int) then the image will be scaled to fit the inner component width. Also, if no custom height was passed to height(int) then the image will be scaled to fit the inner component height.
      Note that what we mean by the "inner component area" is the area enclosed by the border. It is represented by the UI.ComponentArea.INTERIOR constant.
      Parameters:
      autoFit - If true the image will be scaled to fit the inner component area for every dimension which was not specified, otherwise the image will not be scaled to fit the inner component area.
      Returns:
      A new ImageConf instance with the specified autoFit flag value.

    • fitMode

      public ImageConf fitMode(UI.FitComponent fit)
      There are different kinds of strategies to fit the image onto the component. These strategies are identified using the UI.FitComponent enum which defines the following fit modes:
      • UI.FitComponent.NO - The image will not be scaled to fit the inner component area.
      • UILayoutConstants.WIDTH(int, int, int) - The image will be scaled to fit the inner component width. Note that this will only scale the width of the image, but not its height, and so the inherent aspect ratio of the image may not be preserved!
      • UILayoutConstants.HEIGHT(int, int, int) - The image will be scaled to fit the inner component height. Note that this will only scale the height of the image, but not its width, and so the inherent aspect ratio of the image may not be preserved!
      • UI.FitComponent.WIDTH_AND_HEIGHT - The image will be scaled to fit both the component width and height. Note that this may override the inherent aspect ratio of the image in favor of the aspect ratio of the component dimensions!
      • UI.FitComponent.MAX_DIM - The image will be scaled to fit the smaller of the two dimension of the inner component area.
      • UI.FitComponent.MIN_DIM - The image will be scaled to fit the larger of the two dimension of the inner component area.
      • UI.FitComponent.UNDEFINED - How the image will be scaled to fit the component is unclear. Another property may override this, but typically the behavior is similar to UI.FitComponent.NO.
        So for example, if you pass an SvgIcon to image(ImageIcon) which whose SvgIcon.getFitComponent() is not UNDEFINED, then this will override the "fit component" policy of this config object.
      Parameters:
      fit - The fit mode of the image.
      Returns:
      A new ImageConf instance with the specified fit mode.
      Throws:
      NullPointerException - If the supplied enum constant is null.

    • width

      public ImageConf width(int width)
      Ensures that the image has the specified width, irrespective of other configurations.
      So, if a UI.FitComponent policy was supplied to fitMode(UI.FitComponent) which, for example, stretches the image to fill out the entire component, then supplying a custom width to this method will force this stretched image to have that specific width without preserving its aspect ratio!
      So you may end up rendering a distorted image if not careful.
      Also note that the provided width is considered to include any padding supplied to methods like padding(int), padding(int, int), or padding(int, int, int, int).
      Parameters:
      width - The desired width of the rendered image.
      Returns:
      A new ImageConf instance with the specified width.

    • height

      public ImageConf height(int height)
      Ensures that the image has the specified height, irrespective of other configurations.
      So, if a UI.FitComponent policy was supplied to fitMode(UI.FitComponent) which, for example, stretches the image to fill out the entire component, then supplying a custom height to this method will force this stretched image to have that specific height without preserving its aspect ratio!
      So you may end up rendering a distorted image if not careful.
      Also note that the provided height is considered to include any padding supplied to methods like padding(int), padding(int, int), or padding(int, int, int, int).
      Parameters:
      height - The desired height of the rendered image, including top and bottom padding.
      Returns:
      A new ImageConf instance with the specified height.

    • size

      public ImageConf size(int width, int height)
      Ensures that the image has the specified width and height (including padding).
      Note that the image may be rendered smaller than the specified dimensions if a padding was specified through methods like padding(int), padding(int, int), or padding(int, int, int, int).
      Parameters:
      width - The width of the image, including left and right padding if specified.
      height - The height of the image, including top and bottom padding if specified.
      Returns:
      A new ImageConf instance with the specified width and height.

    • size

      public ImageConf size(Size size)
      Ensures that the image has the specified width and height. Note that if the aspect ratio of these two dimensions does not match the innate aspect ratio of the image, then the final render of the image will end up looking distorted.
      Parameters:
      size - The desired size of the rendered image.
      Returns:
      A new ImageConf instance with the specified size.

    • opacity

      public ImageConf opacity(float opacity)
      This method allows you to specify the opacity of the image. The opacity must be between 0.0f and 1.0f, where 0.0f means that the image is completely transparent and 1.0f means that the image is completely opaque.
      Parameters:
      opacity - The opacity of the image.
      Returns:
      A new ImageConf instance with the specified opacity.

    • padding

      public ImageConf padding(int top, int right, int bottom, int left)
      This method allows you to specify extra padding to the rectangle where the image is drawn. This will eat into the native size of the image, or the custom image dimensions supplied to methods like width(int), height(int) and size(int, int).
      Parameters:
      top - The top padding of the image.
      right - The right padding of the image.
      bottom - The bottom padding of the image.
      left - The left padding of the image.
      Returns:
      A new ImageConf instance with the specified padding.

    • padding

      public ImageConf padding(int topBottom, int leftRight)
      This method allows you to specify extra padding of the image's bounding rectangle. This will eat into the native size of the image, or the custom image dimensions supplied to methods like width(int), height(int) and size(int, int).
      Parameters:
      topBottom - The top and bottom padding of the image.
      leftRight - The left and right padding of the image.
      Returns:
      A new ImageConf instance with the specified padding.

    • padding

      public ImageConf padding(int padding)
      This method allows you to specify the padding for all sides of the image. This will eat into the native size of the image, or the custom image dimensions supplied to methods like width(int), height(int) and size(int, int).
      Parameters:
      padding - The padding of the image.
      Returns:
      A new ImageConf instance with the specified padding.

    • offset

      public ImageConf offset(int x, int y)
      Use this to specify the vertical and horizontal offset by which the image will be moved and drawn onto the component. Note that this is relative to the UI.Placement policy of the image specified through placement(UI.Placement).
      The default placement of an image is UI.Placement.CENTER, and so the offset will start from there...
      Parameters:
      x - The horizontal offset relative to the placement(UI.Placement) of the image.
      y - The vertical offset relative to the placement(UI.Placement) of the image.
      Returns:
      A new ImageConf instance with the specified offset.

    • horizontalOffset

      public ImageConf horizontalOffset(int x)
      Use this to specify the horizontal offset by which the image will be moved and drawn onto the component. Note that this is relative to the UI.Placement policy of the image specified through placement(UI.Placement).
      The default placement of an image is UI.Placement.CENTER, and so the offset will start from there...
      Parameters:
      x - The horizontal offset relative to the placement(UI.Placement) of the image.
      Returns:
      A new ImageConf instance with the specified offset.

    • verticalOffset

      public ImageConf verticalOffset(int y)
      Use this to specify the vertical offset by which the image will be moved and drawn onto the component. Note that this is relative to the UI.Placement policy of the image specified through placement(UI.Placement).
      The default placement of an image is UI.Placement.CENTER, and so the offset will start from there...
      Parameters:
      y - The vertical offset relative to the placement(UI.Placement) of the image.
      Returns:
      A new ImageConf instance with the specified offset.

    • clipTo

      public ImageConf clipTo(UI.ComponentArea clipArea)
      Use this to specify the clip area of the image, which determines on which part of the component the image will be drawn. The UI.ComponentArea enum defines the following clip areas:
      • UI.ComponentArea.ALL - The image will be drawn onto the entire component, which is the union of all other clip areas (INTERIOR + EXTERIOR + BORDER + CONTENT).
      • UI.ComponentArea.INTERIOR - The image will be drawn onto the inner component area, which is defined as ALL - EXTERIOR - BORDER.
      • UI.ComponentArea.EXTERIOR - The image will be drawn onto the outer component area, which can be expressed as ALL - INTERIOR - BORDER, or ALL - CONTENT.
      • UI.ComponentArea.BORDER - The image will be drawn onto the border of the component, which is the area between the inner and outer component area and which can be expressed as ALL - INTERIOR - EXTERIOR.
      • UI.ComponentArea.BODY - The image will be drawn onto the component body, which is the inner component area including the border area. It can be expressed as ALL - EXTERIOR, or INTERIOR + BORDER.
      The default clip area is UI.ComponentArea.INTERIOR, which means that the image will be drawn onto the inner component area.

      Use UI.ComponentArea.ALL to draw the image without any additional clipping onto the entire component, which may also cover the border and margin area of the component.

      Parameters:
      clipArea - The clip area of the image.
      Returns:
      A new ImageConf instance with the specified clip area.

    • simplified

      public ImageConf simplified()

    • 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 Object