Class Gradient

java.lang.Object
com.codename1.ui.Gradient
All Implemented Interfaces:
Paint
Direct Known Subclasses:
ConicGradient, LinearGradient, RadialGradient
public abstract class Gradient extends Object implements Paint

Abstract description of a CSS-style gradient that can be used as a background or painted directly via Graphics#fillGradient. Three concrete subclasses mirror the corresponding CSS functions:

  • LinearGradient for linear-gradient(<angle>, <stops>)
  • RadialGradient for radial-gradient([shape] [extent] [at pos], <stops>)
  • ConicGradient for conic-gradient([from <angle>] [at pos], <stops>)

A Gradient is a Paint, so it can also be assigned via Graphics#setColor(Paint) and consumed by fillRect / fillShape. The dedicated Graphics#fillGradient(Gradient, int, int, int, int) entry point gives the platform port the rectangle bounds up front so it can pick the fastest native shader path (Java2D LinearGradientPaint / RadialGradientPaint, Android LinearGradient / RadialGradient / SweepGradient, Core Graphics CGGradient).

Subclass instances are intended to be immutable after construction; modify via builder-style setters before handing the gradient off to Graphics or Style. copy() produces a defensive deep clone for places that must outlive caller mutation (e.g. async paint queues).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final byte
    CYCLE_NONE
    Cycle modes mirroring MultipleGradientPaint.CycleMethod.
    static final byte
    CYCLE_REFLECT
     
    static final byte
    CYCLE_REPEAT
     
    static final byte
    KIND_CONIC
    Sentinel returned by getKind() for ConicGradient instances.
    static final byte
    KIND_LINEAR
    Sentinel returned by getKind() for LinearGradient instances.
    static final byte
    KIND_RADIAL
    Sentinel returned by getKind() for RadialGradient instances.

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract Gradient
    copy()
    Returns a defensive deep copy.
    final Image
    getCachedRaster(int width, int height)
    Returns a software-rasterized image of this gradient at the requested rectangle size, reusing a weakly-cached bitmap when possible.
    final int[]
    getColors()
    ARGB stop colors (length >= 2).
    final byte
    getCycleMethod()
    One of CYCLE_NONE / CYCLE_REPEAT / CYCLE_REFLECT.
    abstract byte
    getKind()
    Returns one of KIND_LINEAR, KIND_RADIAL, KIND_CONIC.
    final float[]
    getPositions()
    Stop positions in [0,1] aligned with getColors().
    protected final void
    invalidateRasterCache()
    Drops the weak cached raster - call after any mutation that changes the painted pixels (cycle method change, subclass parameter change).
    final void
    paint(Graphics g, double x, double y, double w, double h)
    Paints in the given bounds.
    final void
    paint(Graphics g, Rectangle2D bounds)
    Paints in the given bounds.
    static Gradient
    parseCss(String css)
    Parses a CSS gradient function string and returns the corresponding Gradient subclass.
    abstract int
    sampleArgb(int px, int py, int width, int height)
    Software-rasterizer hook used by the default port implementation when no native gradient shader is available.
    protected final int
    sampleStops(float t)
    Samples one of the stops at fractional position t.
    final Gradient
    setCycleMethod(byte cycleMethod)
    Sets the cycle method.

    Methods inherited from class Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • KIND_LINEAR

      public static final byte KIND_LINEAR
      Sentinel returned by getKind() for LinearGradient instances.
      See Also:

    • KIND_RADIAL

      public static final byte KIND_RADIAL
      Sentinel returned by getKind() for RadialGradient instances.
      See Also:

    • KIND_CONIC

      public static final byte KIND_CONIC
      Sentinel returned by getKind() for ConicGradient instances.
      See Also:

    • CYCLE_NONE

      public static final byte CYCLE_NONE
      Cycle modes mirroring MultipleGradientPaint.CycleMethod. Repeated as byte constants here so that this class (and the .res serializer) does not pull the enum across the resource format boundary.
      See Also:

    • CYCLE_REPEAT

      public static final byte CYCLE_REPEAT
      See Also:

    • CYCLE_REFLECT

      public static final byte CYCLE_REFLECT
      See Also:

  • Method Details

    • parseCss

      public static Gradient parseCss(String css)

      Parses a CSS gradient function string and returns the corresponding Gradient subclass. Supports linear-gradient, radial-gradient, conic-gradient, and the repeating-* variants. Mirrors the syntax accepted by the build-time CSS compiler so a string copied verbatim from a .css file produces the same gradient at runtime.

      Returns null if css is null/empty or does not look like a gradient function call. Throws IllegalArgumentException on hard parse errors (unknown direction, missing stops, malformed colors).

    • getKind

      public abstract byte getKind()
      Returns one of KIND_LINEAR, KIND_RADIAL, KIND_CONIC.

    • getColors

      public final int[] getColors()
      ARGB stop colors (length >= 2).

    • getPositions

      public final float[] getPositions()
      Stop positions in [0,1] aligned with getColors().

    • getCycleMethod

      public final byte getCycleMethod()
      One of CYCLE_NONE / CYCLE_REPEAT / CYCLE_REFLECT. Defaults to NONE.

    • setCycleMethod

      public final Gradient setCycleMethod(byte cycleMethod)
      Sets the cycle method. Returns this for chaining.

    • getCachedRaster

      public final Image getCachedRaster(int width, int height)
      Returns a software-rasterized image of this gradient at the requested rectangle size, reusing a weakly-cached bitmap when possible. Ports without a hardware shader path can call this from their fillGradient override to avoid re-rasterizing on every frame; the cache is a Display.createSoftWeakRef so the bitmap is reclaimable when idle.

    • invalidateRasterCache

      protected final void invalidateRasterCache()
      Drops the weak cached raster - call after any mutation that changes the painted pixels (cycle method change, subclass parameter change). Public so subclass setters can keep the cache coherent.

    • copy

      public abstract Gradient copy()
      Returns a defensive deep copy. Implemented by each concrete subclass so async-paint queues can capture an immutable snapshot.

    • paint

      public final void paint(Graphics g, Rectangle2D bounds)
      Description copied from interface: Paint

      Paints in the given bounds.

      Parameters

      • g: Graphics context to paint in.

      • bounds: Bounds to paint in. User coordinates.

      Specified by:
      paint in interface Paint

    • paint

      public final void paint(Graphics g, double x, double y, double w, double h)
      Description copied from interface: Paint

      Paints in the given bounds.

      Parameters

      • g: Graphics context to paint in.

      • x: x coordinate. User space.

      • y: y coordinate. USer space.

      • w: width. User space.

      • h: Hight. User space.

      Specified by:
      paint in interface Paint

    • sampleArgb

      public abstract int sampleArgb(int px, int py, int width, int height)
      Software-rasterizer hook used by the default port implementation when no native gradient shader is available. Samples an ARGB color for the pixel at (px, py) within a rectangle of the given width / height. Ports overriding fillGradient directly do not call this.

    • sampleStops

      protected final int sampleStops(float t)

      Samples one of the stops at fractional position t. Honors the configured cycle method. Shared by the three subclasses' sampling implementations.

      CSS repeating-*-gradient stops define one period from positions[0] to positions[last], not [0, 1]. For white 0%, red 16% the period is 0.16 of the gradient extent and the pattern must wrap on that range; collapsing to t - floor(t) would leak the final color across the rest of the rect.