Substance version 4.1 migration guide

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