How to Use a Gradient Fill in JavaFX

By Doug Lowe

Instead of using a solid color, you can specify a gradient fill, which blends two colors evenly across the shape. JavaFX provides two classes for working with gradients: LinearGradient and RadialGradient.

A linear gradient is created from two color points. Imagine a line drawn between these two points. The gradient fill varies the color smoothly from the color that’s set at the first point to the color set at the second point. Then it extends the colors on this line at 90-degree angles to the line to fill an entire area.

A radial gradient is created from a center point of one color and a second color on the radius of a circle. The fill varies the color smoothly from the center color to the outside color.

The table shows the constructors for the LinearGradient and RadialGradient classes, along with the constructor for the Stop class, which is used to specify the colors used for the gradient.

Constructors for Gradient Classes
Class Constructor Description
LinearGradient(double startX,
double startY,
double endX,
double endY,
boolean proportional,
CycleMethod cycleMethod,
Stop… stops)
Creates a linear gradient. The stops appear along the line
defined by the start and end points.

Cyclemethod can be CycleMethod.NO_CYCLE,
CycleMethod.REPEAT, or CycleMethod.REFLECT.

RadialGradient(double focusAngle,
double focusDistance,
double centerX,
double centerY,
double radius,
boolean proportional,
CycleMethod cycleMethod,
Stop… stops)
Creates a radial gradient. The stops are circular, starting
from the center point of the gradient and extending to the radius.
FocusAngle is usually set to zero.
Stop(double offset, Color color) Defines a color stop on the gradient. The offset is a double
that ranges from 0.0 to 1.0. For a linear gradient, 0.0 represents
the start point of the gradient and 1.0 represents the end point.
For a radial gradient, 0.0 represents the center and 1.0 represents
the radius.

Several of the parameters used with these constructors merit a bit of explanation:

  • Proportional: This parameter determines the units of measure used for the start and end points for a linear gradient or the center point and radius for a circle. If this parameter is false, the coordinates are expressed in pixels.

    If true, the coordinates range from 0.0 to 1.0 and are proportional to the size of the shape being filled. In most cases, it’s easier to work with proportional coordinates, so this parameter should usually be set to true.

  • CyclicalMethod: The default is for a gradient to start with one color, transition to another color, and then end. However, you can create gradients that cycle through their colors repeatedly by using a cycle method other than NO_CYCLE.

    If you specify REPEAT, the gradient repeats itself for each cycle. If you specify REFLECT, the gradient reverses the order of stops for each cycle.

  • Stop offset: The stops represent the colors used for the gradient transition. The offset parameter for a stop determines where along the gradient the stop appears.

    A value of 0.0 means that the stop appears at the start of a linear gradient or the center of a radial gradient. A value of 1.0 means that the stop appears at the end of the linear gradient or at the radius of a radial gradient.

    All gradients must have at least two stops, one at the start or center and the other at the end or radius. However, you can create more complex gradients by adding additional stops. In that case, the stop offset represents a proportional position along the length of the gradient. For example, a stop offset of 0.5 places the stop at the center of the gradient line or radius.

    Also, the start and end stops don’t have to be at offset 0.0 or 1.0. For example, if you don’t want a bit of solid color on either end of the gradient before the color transition starts, you could specify 0.2 and 0.8 as the start and end stop offsets.

This example creates a gradient fill that varies the color from magenta to yellow:

GradientPaint gp = 
    new GradientPaint(0, 0, Color.MAGENTA, 
                      0, 100, Color.YELLOW);