Substance version 4.0 migration guide

# Migration guide for version 4.0 (Key Largo)

The version 4.0 (code-named Key Largo) introduces 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.0, some of the classes of the dependent laf-widget project and Substance itself were moved to new packages to provide better naming. In addition, some API methods that were deprecated in version 3.3 have been removed. In the following sections we provide the complete migration guide for applications that use the moved APIs and the classes that changed packages.

## Classes that were moved

The following classes were moved:

Class | From package | To package
FontPolicy | contrib.com.jgoodies.looks | org.jvnet.substance.fonts
FontSet | contrib.com.jgoodies.looks | org.jvnet.substance.fonts
FadeConfigurationManager | org.jvnet.lafwidget.utils | org.jvnet.lafwidget.animation
FadeIgnoreManager | org.jvnet.lafwidget.utils | org.jvnet.lafwidget.animation
FadeKind | org.jvnet.lafwidget.utils (inner class of FadeTracker) | org.jvnet.lafwidget.animation
FadeStateListener | org.jvnet.lafwidget.utils | org.jvnet.lafwidget.animation
FadeStep | org.jvnet.lafwidget.utils | org.jvnet.lafwidget.animation
FadeTracker | org.jvnet.lafwidget.utils | org.jvnet.lafwidget.animation
FadeTrackerCallback | org.jvnet.lafwidget.utils (inner class of FadeTracker) | org.jvnet.lafwidget.animation

The API of these classes has not been changed. In order to migrate application using these classes you will need to reorganize the import sections of the relevant application classes and recompile your application.

## Classes that were renamed

The following classes were renamed:

Class | From package | To package / class
ScrollThumbGripPainter | org.jvnet.substance.scroll | org.jvnet.substance.grip.GripPainter

The API of these classes has been renamed. In order to migrate application using these classes you will need to reorganize the import sections of the relevant application classes and refactor your application to call the renamed APIs.

## Removed API methods

The following methods have been removed. Consult the table to see the methods to use instead:

Removed method | From class | Instead use
getBasicFontSize() | org.jvnet.substance.SubstanceLookAndFeel | getFontPolicy()
getFontFamilyName() | org.jvnet.substance.SubstanceLookAndFeel | getFontPolicy()
isBasicFontBold() | org.jvnet.substance.SubstanceLookAndFeel | getFontPolicy()
setBasicFontSize() | org.jvnet.substance.SubstanceLookAndFeel | setFontPolicy(FontPolicy)
setFontSizeExtra() | org.jvnet.substance.SubstanceLookAndFeel | setFontPolicy(FontPolicy)
getColorScheme() | org.jvnet.substance.SubstanceLookAndFeel | getActiveColorScheme()
getMetallicColorScheme() | org.jvnet.substance.SubstanceLookAndFeel | getDefaultColorScheme()
getGrayColorScheme() | org.jvnet.substance.SubstanceLookAndFeel | getDisabledColorScheme()
enumerateThemes() | org.jvnet.substance.SubstanceLookAndFeel | getAllThemes()
enumerateWatermarks() | org.jvnet.substance.SubstanceLookAndFeel | getAllWatermarks()
getTabCloseListeners() | org.jvnet.substance.SubstanceLookAndFeel | getAllTabCloseListeners()
getTabCloseListeners(JTabbedPane) | org.jvnet.substance.SubstanceLookAndFeel | getAllTabCloseListeners(JTabbedPane)
enumerateWatermarks() | org.jvnet.substance.SubstanceLookAndFeel | getAllWatermarks()
setCellRendererBackgroundTheme() | org.jvnet.substance.theme.SubstanceComplexTheme | registerComponentHighlightStateTheme(SubstanceTheme)

In order to migrate application using these APIs follow the examples in the linked documentation and the sources of the Substance test applications.

## Removed client properties

The following client properties have been removed. Consult the table to see the properties to use instead:

Removed property | From class | Instead use
BUTTON_THEME_PROPERTY | org.jvnet.substance.SubstanceLookAndFeel | THEME_PROPERTY
BUTTON_PAINT_ACTIVE_PROPERTY | org.jvnet.substance.SubstanceLookAndFeel | PAINT_ACTIVE_PROPERTY
TOOLBAR_BUTTON_FLAT | org.jvnet.substance.SubstanceLookAndFeel | FLAT_PROPERTY
TABBED_PANE_TAB_ANIMATION_KIND | org.jvnet.substance.SubstanceLookAndFeel | Functionality removed
TABBED_PANE_CLOSE_BUTTONS_SIZE | org.jvnet.substance.SubstanceLookAndFeel | Functionality removed
CAN_BE_PINNED | org.jvnet.substance.SubstanceLookAndFeel | Functionality removed
PERMANENTLY_PINNED | org.jvnet.substance.SubstanceLookAndFeel | Functionality removed
SCROLLBAR_GRIP_PAINTER | org.jvnet.substance.SubstanceLookAndFeel | GRIP_PAINTER