Substance version 5.1 migration guide

# Migration guide for version 5.1 (Panama)

The version 5.1 (code-named Panama) 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 5.1, two published Substance interfaces have been changed to better accomodate the new functionality.

## SubstanceButtonShaper

The `getButtonOutline` APIs of `org.jvnet.substance.shaper.SubstanceButtonShaper` now return `Shape` instead of `GeneralPath`.

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

- If you have provided a custom button shaper that either extended an existing core Substance button shaper or provided a complete implementation, you will need to change the return type. The implementation itself does not need to change because `GeneralPath` is a subclass of `Shape`. The added flexibility is that now you can return other subclasses of the `Shape` class, such as `Ellipse2D`, for example.
- If you call `SubstanceSkin.getButtonShaper` to obtain the current button shaper and use it to compute the outline of your custom visuals, you can no longer assume that the result is a `GeneralPath`. Both `SubstanceGradientPainter` and `SubstanceBorderPainter` APIs accept `Shape` parameters, and these calls should not be affected. Only application code that used non-`Shape` APIs will need to be changed.

## SubstanceHighlightPainter

The `paintHighlight` of `org.jvnet.substance.painter.highlight.SubstanceHighlightPainter` has been changed to the following signature:

`/**
* Paints the highlight.
*
* @param graphics
* Graphics context.
* @param comp
* Component.
* @param width
* Width.
* @param height
* Height.
* @param borderAlpha
* Border alpha factor.
* @param openSides
* The sides specified in this set will not be painted. Can be
* <code>null</code> or empty.
* @param colorScheme1
* The first color scheme.
* @param colorScheme2
* The second color scheme.
* @param borderColorScheme1
* The first border color scheme.
* @param borderColorScheme2
* The second border color scheme.
* @param cyclePos
* Cycle position. Is used for rollover and selection animations.
* Must be in 0..1 range.
*/
public void paintHighlight(Graphics2D graphics, Component comp, int width,
int height, float borderAlpha, Set<Side> openSides,
SubstanceColorScheme colorScheme1,
SubstanceColorScheme colorScheme2,
SubstanceColorScheme borderColorScheme1,
SubstanceColorScheme borderColorScheme2, float cyclePos)`

The changes are the new `borderColorScheme1` and `borderColorScheme2` parameters.

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

- If you have provided a custom highlight painter that either extended an existing core Substance highlight painter, or provided a complete implementation, you are highly advised to use the new parameters to paint the border part of the highlight region (respecting the `openSides` and `borderAlpha`). See existing core painters for more details.
- If you used a highlight painter to provide some custom painting logic in your application, you can retrieve the relevant border color schemes by using the new `SubstanceSkin.getColorScheme` API, passing the `ColorSchemeAssociationKind.BORDER` as the second parameter. This is highly advised to keep the custom application visuals consistent with the visuals of core and third-party components painted by Substance.