Package swingtree.api

Interface Painter

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface Painter
A functional interface for doing custom painting on a component using the Graphics2D API. This is typically used to paint custom styles on components as part of the style API exposed by UIForAnySwing.withStyle(Styler), like so: 

  UI.label("I am a label")
  .withStyle( it -> it
    .size(120, 50)
    .padding(6)
    .painter(UI.Layer.BACKGROUND, g -> {
      g.setColor(Color.ORANGE);
      var e = new Ellipse2D.Double(5,5,25,25);
      g.fill(UI.scale(e);
    })
    .fontSize(12)
  )
Which is based on the ComponentStyleDelegate.painter(UI.Layer, Painter). You may also want to take a look at
ComponentStyleDelegate.painter(UI.Layer, UI.ComponentArea, Painter),
ComponentStyleDelegate.painter(UI.Layer, String, Painter) and
ComponentStyleDelegate.painter(UI.Layer, UI.ComponentArea, String, Painter).

You can also use painter implementations for defining custom component event based animations by registering through the AbstractDelegate.paint(AnimationState, Painter) method inside of an Animation registered through AbstractDelegate.animateFor(double, TimeUnit, Animation).

Note that inside the painter the Graphics2D context may not be scaled according to the current UI scale factor (for high DPI displays).
Check out the following methods for scaling your paint operations:


Note that your custom painters will yield the best performance if they are stateless and immutable as well has if they have a good Object.hashCode() and Object.equals(Object) implementation. This is because it allows SwingTree to cache the rendering of the painters and avoid unnecessary repaints.
If you do not want to create a custom class just for painting but instead just want to pass an immutable cache key to a painter, then consider using the of(Object, Painter) factory method to create a painter that has the with Object.hashCode() and Object.equals(Object) implemented as a delegate to the data object.

Also consider taking a look at the
living swing-tree documentation where you can browse a large collection of examples demonstrating how to use the API of Swing-Tree in general.

  • Method Summary

    Modifier and Type
    Method
    Description
    default Painter
    andThen(Painter after)
    Returns a new painter that paints this painter's style and then the given painter's style.
    default boolean
    canBeCached()
    If a painter implementation reports that it can be cached, SwingTree will use the painter as a cache key and the result of its painting operations will be cached and reused for equal cache keys.
    static Painter
    none()
    Exposes a constant painter that paints nothing.
    static <D> Painter
    of(D data, Painter painter)
    Allows you to create a cacheable painter that uses the given data object as a cache key.
    void
    paint(Graphics2D g2d)
    Paints a custom style on a component using the given graphics context.

  • Method Details

    • none

      static Painter none()
      Exposes a constant painter that paints nothing. This is useful as a no-op null object pattern.
      Returns:
      A painter that paints nothing.

    • of

      static <D> Painter of(D data, Painter painter)
      Allows you to create a cacheable painter that uses the given data object as a cache key. The provided data object should be immutable and have exhaustive Object.hashCode() and Object.equals(Object) implementations.
      The data object is expected to be the sole source of information for the painter's painting operations. Otherwise, the usage of this method is discouraged as cache based rendering may not reflect the actual state of the component.
      Type Parameters:
      D - The type of the data object to use as a cache key.
      Parameters:
      data - The data object to use as a cache key, must be immutable and have exhaustive Object.hashCode() and Object.equals(Object) implementations.
      painter - The painter to use for painting, must be stateless and immutable as well. It is expected to use the given data object as the sole source of information for its painting operations.
      Returns:
      A cache friendly painter that uses the given data object as a cache key.

    • paint

      void paint(Graphics2D g2d)
      Paints a custom style on a component using the given graphics context.
      Parameters:
      g2d - the graphics context to use for painting.

    • canBeCached

      default boolean canBeCached()
      If a painter implementation reports that it can be cached, SwingTree will use the painter as a cache key and the result of its painting operations will be cached and reused for equal cache keys.
      So a painter that can be cached should be stateless and immutable as well as have exhaustive Object.hashCode() and Object.equals(Object) implementations.
      Returns:
      true If the painting operation is cachable, false otherwise.

    • andThen

      default Painter andThen(Painter after)
      Returns a new painter that paints this painter's style and then the given painter's style.
      Parameters:
      after - the painter to paint after this painter.
      Returns:
      a new painter that paints this painter's style and then the given painter's style.