Author: substance.dev.java.net
Description: Substance look and feel
Keywords: java, look, feel, painters, plaf, swing, ui, pluggable, substance

# Substance look and feel - gradient painters

### Overview

The base class for Substance gradient painters is `org.jvnet.substance.painter.gradient.SubstanceGradientPainter`. Gradient painter is used to paint the inner fill of most Swing components, such as buttons, check boxes, radio buttons, progress bars, tabs, scroll bars and others. This allows providing a consistent and pluggable appearance to those components. In addition, it provides an external API for applications that wish to skin custom components in a visually consistent manner.

### Painting API

The only painting method in `org.jvnet.substance.painter.gradient.SubstanceGradientPainter` is

`/**
* Paints the background that matches the specified parameters.
*
* @param g
* Graphics context.
* @param width
* Width of a UI component.
* @param height
* Height of a UI component.
* @param contour
* Contour of a UI component.
* @param isFocused
* Indication whether component owns the focus.
* @param colorScheme1
* The first color scheme.
* @param colorScheme2
* The second color scheme.
* @param cyclePos
* Cycle position. Is used for rollover and pulsation effects.
* Must be in 0..1 range.
* @param hasShine
* Indication whether the returned image should have a 3D shine
* spot in its top half.
* @param useCyclePosAsInterpolation
* Indicates the algorithm to use for computing various colors.
* If <code>true</code>, the <code>cyclePos</code> is used
* to interpolate colors between different color components of
* both color schemes. If <code>false</code>, the
* <code>cyclePos</code> is used to interpolate colors between
* different color components of the first color scheme.
*/
public void paintContourBackground(Graphics g, int width, int height,
Shape contour, boolean isFocused,
SubstanceColorScheme colorScheme1,
SubstanceColorScheme colorScheme2, float cyclePos,
boolean hasShine, boolean useCyclePosAsInterpolation)`

The `contour` parameter specifies the actual shape to fill, the `colorScheme1` and `colorScheme2` specify the Substance color schemes to be used to compute the gradient colors, while `cyclePos` and `useCyclePosAsInterpolation` indicate how (and whether) to interpolate between the actual colors of the passed two color schemes. The internal implementation of a specific gradient painter may decide to ignore the `ifFocused` and `hasShine` if these are not relevant. In addition, specific implementation may maintain an internal cache of computed images if the computation is CPU-heavy.

Important thing to note - gradient painter should not paint the focus ring or the border; these are painted by separate painters. As noted above, the `ifFocused` can be ignored by the specific painter implementation.

Applications that wish to provide a custom (branding) gradient painter may utilize the existing `StandardGradientPainter` base class. It provides six extension points that compute gradient fill colors at four fill and two shine vertical locations (see `get*FillColor` and `get*ShineColor` methods). Most core Substance gradient painters extend this class. Note that if your gradient painter does not paint the shine spot, return `null` from the `get*ShineColor` methods.

### Management API

If you wish to use the gradient painter of the current skin to provide additional custom painting in your application, call:

- `SubstanceLookAndFeel.getCurrentSkin()` to retrieve the current skin.
- `SubstanceSkin.getGradientPainter()` to retrieve the gradient painter of the current skin.
- `SubstanceGradientPainter.paintContourBackground()` to paint the gradient background on the specific graphics context.