Package swingtree.style

Class GradientConf

java.lang.Object
swingtree.style.GradientConf
@Immutable public final class GradientConf extends Object
An immutable config API for specifying a gradient style. as a sub-style of various other styles, like for example BaseConf or BorderConf accessed through the ComponentStyleDelegate.gradient(String, swingtree.api.Configurator) method. The state of a gradient style is immutable and can only be updated by wither like methods that return a new instance of the gradient style with the specified property updated.

The following properties with their respective purpose are available:

  • Transition The transition defines the direction of the gradient.
    The following transitions are available:
  • Type The type defines the shape of the gradient which can be either linear or radial.
    So the following types are available:
  • Colors An array of colors that will be used as a basis for the gradient transition.
  • Offset The offset defines the start position of the gradient on the x and y axis. This property, together with the span(UI.Span) property, defines the start position and direction of the gradient.
  • Size The size defines the size of the gradient in terms of the distance from the start position of the gradient to the end position of the gradient.
    If no size is specified, the size of the gradient will be based on the size of the component that the gradient is applied to.
  • Area The component are to which the gradient is clipped to. Which means that the gradient will only be visible within the specified area of the component.
  • Boundary The boundaries of a component define the outlines between the different UI.ComponentAreas. Setting a particular boundary causes the gradient to start at that boundary.
  • Focus Offset An offset property consisting of a x and y value which will be used together with the gradients position to calculate a focus point. This is only relevant for radial gradients!
  • Rotation The rotation of the gradient in degrees. This is typically only relevant for a linear gradient. However it is also applicable to a radial gradient with a focus offset, where the rotation will be applied to the focus offset.
  • Fractions An array of values between 0 and 1 that defines the relative position of each color in the gradient.
    Note that the number of fractions must match the number of colors in the gradient. However, if the number of fractions is less than the number of colors, then the remaining colors will be determined based on linear interpolation. If the number of fractions is greater than the number of colors, then the remaining fractions will be ignored.
  • Cycle The cycle of the gradient which can be one of the following constants:
    • UI.Cycle.NONE - The gradient is only rendered once, without repeating. The last color is used to fill the remaining area. This is the default cycle.
    • UI.Cycle.REFLECT - The gradient is rendered once and then reflected., which means that the gradient is rendered again in reverse order starting from the last color and ending with the first color. After that, the gradient is rendered again in the original order, starting from the first color and ending with the last color and so on.
    • UI.Cycle.REPEAT - The gradient is rendered repeatedly, which means that it is rendered again and again in the original order, starting from the first color and ending with the last color.
    Note that this property ultimately translates to the MultipleGradientPaint.CycleMethod of the LinearGradientPaint or RadialGradientPaint that is used to render the gradient inside the SwingTree style engine.

You can also use the none() method to specify that no gradient should be used, as the instance returned by that method is a gradient without any colors, effectively making it a representation of the absence of a gradient style.

  • Method Details

    • none

      public static GradientConf none()
      Use the returned instance as a representation of the absence of a gradient.
      Returns:
      A gradient without any colors, effectively representing the absence of a gradient.

    • colors

      public GradientConf colors(Color... colors)
      Define a list of colors which will, as part of the gradient, transition from one to the next in the order they are specified.

      Note that you need to specify at least two colors for a gradient to be visible.

      Parameters:
      colors - The colors in the gradient.
      Returns:
      A new gradient style with the specified colors.
      Throws:
      NullPointerException - if any of the colors is null.

    • colors

      public GradientConf colors(String... colors)
      Define a list of String based colors which will, as part of the gradient, transition from one to the next in the order they are specified.

      Note that you need to specify at least two colors for a gradient to be visible.

      Parameters:
      colors - The colors in the gradient in String format.
      Returns:
      A new gradient style with the specified colors.
      Throws:
      NullPointerException - if any of the colors is null.

    • span

      public GradientConf span(UI.Span span)
      Define from where and to where the gradient should transition to within the UI.ComponentBoundary of the component.
      Parameters:
      span - The span policy of the gradient, which defines the direction of the gradient.
      Returns:
      A new gradient style with the specified alignment.
      Throws:
      NullPointerException - if the alignment is null.

    • type

      public GradientConf type(UI.GradientType type)
      Define the type of the gradient which is one of the following:
      Parameters:
      type - The type of the gradient.
      Returns:
      A new gradient style with the specified type.
      Throws:
      NullPointerException - if the type is null.

    • offset

      public GradientConf offset(double x, double y)
      Define the offset of the gradient which is the start position of the gradient on the x and y-axis.
      Note that the offset is relative to the component that the gradient is applied to.

      Parameters:
      x - The gradient start offset on the x-axis.
      y - The gradient start offset on the y-axis.
      Returns:
      A new gradient style with the specified offset.

    • size

      public GradientConf size(double size)
      Define the size of the gradient which is the size of the gradient in terms of the distance from the start position of the gradient to the end position of the gradient.

      Note that if no size is specified, the size of the gradient will be based on the size of the component that the gradient is applied to.

      Parameters:
      size - The gradient size.
      Returns:
      A new gradient style with the specified size.

    • clipTo

      public GradientConf clipTo(UI.ComponentArea area)
      Define the area of the component to which the gradient is clipped to. Which means that the gradient will only be visible within the specified area of the component.
      Parameters:
      area - The area of the component to which the gradient is clipped to.
      Returns:
      A new gradient style with the specified area.

    • boundary

      public GradientConf boundary(UI.ComponentBoundary boundary)
      Define the boundary at which the gradient should start in terms of its base position. So if the boundary is set to UI.ComponentBoundary.EXTERIOR_TO_BORDER then the gradient position will be determined by the margin of the component.
      Here a complete list of the available boundaries:
      • UI.ComponentBoundary.OUTER_TO_EXTERIOR - The outermost boundary of the entire component, including any margin that might be applied. Using this boundary will cause the gradient to be positioned somewhere at the outer most edge of the component.
      • UI.ComponentBoundary.EXTERIOR_TO_BORDER - The boundary located after the margin but before the border. This tightly wraps the entire UI.ComponentArea.BODY. Using this boundary will cause the gradient to be positioned somewhere at the outer most edge of the component's body, which is between the margin and the border.
      • UI.ComponentBoundary.BORDER_TO_INTERIOR - The boundary located after the border but before the padding. It represents the edge of the component's interior. Using this boundary will cause the gradient to be positioned somewhere at the outer most edge of the component's interior, which is between the border and the padding area.
      • UI.ComponentBoundary.INTERIOR_TO_CONTENT - The boundary located after the padding. It represents the innermost boundary of the component, where the actual content of the component begins, like for example the contents of a JPanel or JScrollPane. Using this boundary will cause the gradient to be positioned somewhere after the padding area and before the content area, which is where all of the child components are located.

      You can think of this property as a convenient way to define the base position of the gradient. So if you want to do the positioning yourself, then you may configure this property to UI.ComponentBoundary.OUTER_TO_EXTERIOR, which will cause the gradient to be positioned at the outermost edge of the component, and then use the offset(double, double) method to define the exact position of the gradient. (You may also want to set the span(UI.Span) property to UI.Span.TOP_LEFT_TO_BOTTOM_RIGHT to make sure that the gradient is positioned in the top left corner (origin position) of the component)

      Parameters:
      boundary - The boundary at which the gradient should start in terms of its offset.
      Returns:
      A new gradient style with the specified boundary.

    • focus

      public GradientConf focus(double x, double y)
      Define the focus offset of a radial gradient as a second position relative to the main position of the gradient (see offset(double, double) and boundary(UI.ComponentBoundary) which is used to define the direction of the gradient.

      Note that this property is only relevant for radial gradients.

      Parameters:
      x - The focus offset on the x-axis.
      y - The focus offset on the y-axis.

    • rotation

      public GradientConf rotation(float rotation)
      Define the rotation of the gradient in degrees.
      Parameters:
      rotation - The rotation of the gradient in degrees.

    • fractions

      public GradientConf fractions(double... fractions)
      Define the fractions of the gradient in the dorm of an array of values between 0 and 1 that each the relative position of each color in the gradient transition.

      Note that the number of fractions must match the number of colors in the gradient. If the number of fractions is less than the number of colors, then the remaining colors will be evenly distributed between the last two fractions.

      Parameters:
      fractions - The fractions of the gradient.
      Returns:
      An updated gradient configuration with the specified fractions.

    • cycle

      public GradientConf cycle(UI.Cycle cycle)
      Define the cycle of the gradient which is one of the following:
      • UI.Cycle.NONE - The gradient is only rendered once, without repeating. The last color is used to fill the remaining area. This is the default cycle.
      • UI.Cycle.REFLECT - The gradient is rendered once and then reflected., which means that the gradient is rendered again in reverse order starting from the last color and ending with the first color. After that, the gradient is rendered again in the original order, starting from the first color and ending with the last color and so on.
      • UI.Cycle.REPEAT - The gradient is rendered repeatedly, which means that it is rendered again and again in the original order, starting from the first color and ending with the last color.
      Note that this property ultimately translates to the MultipleGradientPaint.CycleMethod of the LinearGradientPaint or RadialGradientPaint that is used to render the gradient inside the SwingTree style engine.
      Parameters:
      cycle - The cycle of the gradient.
      Returns:
      A new gradient style with the specified cycle method.
      Throws:
      NullPointerException - if the cycle is null.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(@Nullable Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • simplified

      public GradientConf simplified()