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:
   • UI.Layer.BACKGROUND
   • UI.Layer.CONTENT
   • UI.Layer.BORDER
   • UI.Layer.FOREGROUND
2. Primer: The primer color of the image style which will be used as a filler color for the image background. The background is the inner component area of the component.
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:
   • UI.Placement.CENTER
   • UI.Placement.TOP_LEFT
   • UI.Placement.TOP_RIGHT
   • UI.Placement.BOTTOM_LEFT
   • UI.Placement.BOTTOM_RIGHT
   • UI.Placement.TOP
   • UI.Placement.BOTTOM
   • UI.Placement.LEFT
   • UI.Placement.RIGHT
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(Integer) then the image will be scaled to fit the inner component width, and if a height was not specified through height(Integer) 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.BODY 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, and the primer color will be used as a filler color for the parts of the image which are transparent.

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, meaning that if the width was not specified explicitly through width(Integer) then the image will be scaled to fit the inner component width, and if a height was not specified through height(Integer) then the image will be scaled to fit the inner component 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(Integer height)	Ensures that the image has the specified height.
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 for which the icon will be loaded, cached and drawn 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 the path to the image in the form of an IconDeclaration for which the icon will be loaded and drawn onto the component.
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 the padding of the image.
ImageConf	padding(int top, int right, int bottom, int left)	This method allows you to specify the padding of the image.
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 a filler color for the image background.
ImageConf	repeat(boolean 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.
ImageConf	simplified()
ImageConf	size(int width, int height)	Ensures that the image has the specified width and height.
ImageConf	size(Size size)	Ensures that the image has the specified width and height.
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(Integer width)	Ensures that the image has the specified width.

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 a filler color for the image background.
Note that the primer color will not be visible if the image is opaque and it 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 an instance of Image implementation.

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.

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 the path to the image in the form of an IconDeclaration for which the icon will be loaded and drawn onto the component. 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.

Parameters:

image - The path to the (icon) image in the form of an IconDeclaration.

Returns:

A new ImageConf instance with the specified image.

Throws:

NullPointerException - If the specified image is null.

image

public ImageConf image(String path)

Here you can specify the path to the image for which the icon will be loaded, cached and drawn onto the component. 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)).

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.

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 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)).

Parameters:

repeat - Weather 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, meaning that if the width was not specified explicitly through width(Integer) then the image will be scaled to fit the inner component width, and if a height was not specified through height(Integer) 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!

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.
• UILayoutConstants.HEIGHT(int, int, int) - The image will be scaled to fit the inner component height.
• UI.FitComponent.WIDTH_AND_HEIGHT - The image will be scaled to fit both the component width and height.
• 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.

Parameters:

fit - The fit mode of the image.

Returns:

A new ImageConf instance with the specified fit mode.

width

public ImageConf width(Integer width)

Ensures that the image has the specified width.

Parameters:

width - The width of the image.

Returns:

A new ImageConf instance with the specified width.

height

public ImageConf height(Integer height)

Ensures that the image has the specified height.

Parameters:

height - The height of the image.

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.

Parameters:

width - The width of the image.

height - The height of the image.

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.

Parameters:

size - The size of the 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 the padding of the image. The padding is the space between the image and the inner component area.

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 the padding of the image. The padding is the space between the image and the inner component area.

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. The padding is the space between the image and the inner component area.

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.

Parameters:

x - The horizontal offset.

y - The vertical offset.

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.

Parameters:

x - The horizontal offset.

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.

Parameters:

y - The vertical offset.

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