JSignage:LinearGradient

.linearGradient()

$.linearGradient( attributes );

Returns: jSignage Object

Description

Creates a linear gradient that maps colors and opacity values at specific offsets along a gradient vector.

The linear gradient is not directly rendered, instead it needs to be referenced (using its id or calling the .ref() function) by attributes expecting a color (like 'fill', 'stroke', 'backColor', 'frameColor' etc.). The gradient must exist or be added into the DOM in order to be referenced (it does not matter where the gradient is added though).

See Linear gradients in the SVG specification for reference.

Parameters

• attributes

  Type: Plain Object.

  Contains the linear gradient attributes.

Attributes

The following attributes can be specified:

• x1, y1, x2, y2

  Type: Number. Default: 0.

  x and y coordinates of the starting point, respectively the ending point, of the gradient vector.

• gradientUnits

  Type: String. Default: 'userSpaceOnUse'.

  Defines the coordinate system for attributes 'x1', 'y1', 'x2', 'y2' to be used when rendering the gradient. Can be 'userSpaceOnUse' or 'objectBoundingBox'. Note that when using 'objectBoundingBox', the x and y attributes need to take values between 0 and 1 for the gradient to be visible.

• stops

  Type: Array.<Plain Object>.

  List of the gradient stops. Each stop is an object with the following properties:

  • offset

    Type: Number. Default: 0.

    Relative position of the stop along the gradient vector. It takes values from 0 to 1, where offset 0 corresponds to the starting point of the vector (specified by x1 and y1 attributes) and offset 1 corresponds to the ending point of the vector (specified by x2 and y2 attributes).

  • color

    Type: Color. Default: 'black'.

    The color to be used at the gradient stop.

  • opacity

    Type: Number. Default: 1.

    The opacity to be used at the gradient stop.

Notes:

• At least two offsets should be specified to produce a gradient. If no stops are specified, the gradient will have the same effect as color: 'none' and if only one stop is specified, the result is a solid color. Each stop offset must be greater than or equal to the previous stop offset.
• An offset can be repeated to produce a discontinuity in the gradient, i.e. the first stop will terminate a linear interpolation and the second stop will start a new one, allowing for an immediate jump in color or opacity. See example #2.
• The color and opacity of each stop can be animated using animateColor and respectively animateOpacity, by specifying an index into the stop array as the first argument to these functions. See example #3.

Examples

Horizontal gradient from blue to red

Simple linear gradient

var grad = $.linearGradient({
   x1: 320,
   y1: 0,
   x2: 960,
   y2: 0,
   stops: [
     { offset: 0, color: 'blue' },
     { offset: 1, color: 'red' }
   ]
}).addTo('svg');
$.rect({ x: 320, y: 180, width: 640, height: 360, fill: grad.ref() }).addTo('svg');

Vertical gradient with discontinuity

Linear gradient with discontinuity

var grad = $.linearGradient({
   x1: 0,
   y1: 100,
   x2: 0,
   y2: 300,
   stops: [
     { offset:   0, color: '#c0c0ff' },
     { offset: 0.5, color: '#8080ff' },
     { offset: 0.5, color: '#6060ff' },
     { offset:   1, color: '#6060ff' },
   ]
}).addTo('svg');
$.rect({ x: 100, y:100, width: 600, height: 200, fill: grad.ref() }).addTo('svg');

Horizontal gradient animated from red to green

Animated linear gradient at t=1s.

Animated linear gradient at t=3s.

var grad = $.linearGradient({
   x1: 320,
   y1: 0,
   x2: 960,
   y2: 0,
   stops: [
     { offset: 0, color: 'white' },
     { offset: 1, color: 'red' }
   ]
}).addTo('svg');
$.rect({ x: 320, y: 180, width: 640, height: 360, fill: grad.ref() }).addTo('svg');
grad.animateColor( 1, {
   begin: 1,
   from: 'red',
   to: 'green',
   dur: 2,
   fill: 'freeze',   
});

• Note that in the color animation, 1 is used to reference the second stop of the gradient (stops are numbered from 0).