Migration guide for version 4.1 (Lima)

The version 4.1 (code-named Key Largo) introduces minor binary incompatibilities with the previous versions. This document describes these incompatibilities and outlines the migration process for the client applications.

Background

During the development of version 4.1, two published Substance painter interfaces have been changed to better accomodate the new functionality.

SubstanceTitlePainter

The paintTitleBackground of org.jvnet.substance.title.SubstanceTitlePainter has been changed to the following signature:


  public void paintTitleBackground(Graphics2D graphics, Component comp,

      int width, int height, int leftTitleX, int rightTitleX,

      SubstanceTheme theme, float borderAlpha);

The change is in the last parameter. Prior to version 4.1, it has been a boolean. The value true signified that the painter should paint the border, and the value false signified that no border should be painted. The last parameter in the new signature specifies the alpha channel for border painting.

What does this mean to applications? There are two cases:

If you have provided a custom title painter that either extended an existing core Substance title painter, or provided a complete implementation, you will need to respect the new alpha channel setting. Instead of the old logic to paint the border with full opacity when the boolean parameter was true, set an AlphaComposite.SRC_OVER with the matching alpha value before painting the border. A possible optimization would be to not paint the border at all when the last parameter is 0.0.
If you used a title painter to provide some custom painting logic in your application, now you have more flexibility. All the places that passed false as the last parameter, should pass 0.0. All the places that passed true as the last parameter, should pass 1.0. In addition, you can set a custom alpha channel value to have greater control over the border painting of title painters.

SubstanceBorderPainter

The paintBorder of org.jvnet.substance.border.SubstanceBorderPainter has been changed to the following signature:


  public void paintBorder(Graphics g, Component c, int width, int height,

      Shape contour, Shape innerContour, ColorScheme colorScheme1,

      ColorScheme colorScheme2, float cyclePos,

      boolean useCyclePosAsInterpolation);

The change is the new innerContour parameter. One of the new features added in this release are border painters that paint lighter inner borders.

What does this mean to applications? There are two cases:

If you have provided a custom border painter that either extended an existing core Substance border painter, or provided a complete implementation, you can decide to ignore the new parameter (like most of the core border painters do) or respect it. In the second case, consider having your painter extend the org.jvnet.substance.border.InnerDelegateBorderPainter. See existing core painters for more details.
If you used a border painter to provide some custom painting logic in your application, you can either pass null which is respected by all core border painters or compute the properly inset inner contour. In the later case, skins that use inner border painters will respect that setting, which will result in better looking and more consistent custom painting.