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.