The IlvGradientPattern class supports two different types of gradients:

The IlvGradientPattern class is a subclass of IlvPattern. The IlvPalette class enables you to get and set the gradient pattern attribute using the following methods:

IlvFillGradientPattern is a dedicated fill style value for gradient patterns.

To use your palette to draw gradients, you must set an instance of IlvGradientPattern on the palette, and set the palette fill style to IlvFillGradientPattern.

Gradients can only be drawn if your application is properly set to use GDI+ or Cairo for rendering.

The IlvGradientPattern class has the following attributes:

The IlvLinearGradientGeometry class enables you to specify geometrical properties dedicated to linear gradients.

A linear gradient geometry is defined by a start and end point. The coordinates of the two points must be contained in the IlvGradientPattern area defined by its width and height. See IlvPattern::width, IlvGradientPattern::setWidth, IlvPattern::height and IlvGradientPattern::setHeight for more details.

The abscissas of these points must be between 0 and IlvPattern::width.

The ordinates of these points must be between 0 and IlvPattern::height.

The IlvRadialGradientGeometry class enables you to specify geometrical properties dedicated to radial gradients.

A radial gradient geometry is defined by a start and end circle. The centers of the two circles must be contained in the IlvGradientPattern area defined by its width and height. See IlvPattern::width, IlvGradientPattern::setWidth, IlvPattern::height and IlvGradientPattern::setHeight for more details.

The abscissas of these centers must be between 0 and IlvPattern::width.

The ordinates of these centers must be between 0 and IlvPattern::height.

In addition, the start circle must be contained within the end circle otherwise the rendering becomes unpredictable. The resultant rendering depends whether you are drawing using Cairo or GDI+.

The IlvGradientGeometry class is the base class of the IlvLinearGradientGeometry and IlvRadialGradientGeometry classes. The attributes of this class are common to both types of gradients. They allow you to define how the gradient pattern area and its geometrical settings will be transformed when drawing your graphic objects. The following attributes can be set:

The following example shows the effect of gradient transformation and aspect ratio combinations on the gradient pattern.

A radial gradient is defined with the following parameters:

With this gradient and spread mode IlvGradientPadSpread, depending on the transform mode and aspect ratio settings, an IlvFilledRectangle instance will be drawn with the following gradient patterns:

When the gradient transform mode is relative to the graphic object bounding box (IlvGradientTransformGraphic or IlvGradientTransformGraphicNoResize), you must provide the palette with the bounding box where the gradient should be stretched or translated to.

IlvGradientGraphicBBoxManager is a dedicated class to define the bounding box which the gradient should use. When instantiating this class, a bounding box is set on the gradient if none has previously been set before. On destruction of this instance, the bounding box is unset from the gradient. See the reference manual for more details.

There are two ways to create a gradient pattern instance:

If you create an IlvGradientPattern instance using the IlvGradientPattern constructor, you are responsible for deleting it when the application no longer needs it.

If you ask the display to provide an instance of IlvGradientPattern, use one of the following methods:

When these methods are called, the display first checks if there is already an IlvGradientPattern instance matching the query. If none is found, the display will create one and keep a reference to it, as it does for other types of stored resources. The display will then manage the gradient pattern reference count and lifetime through the IlvResource::lock and IlvResource::unLock methods.

This design makes it easier to create gradient instances as only one method call is required. However, it is not possible to control which IlvPalette instances share the returned gradient, and if the gradient attributes are modified, other palettes may also be impacted.

It is possible to keep track of a gradient pattern instance managed by the display using a unique identifier of your choice. This unique identifier is called an alias.

To create an aliased gradient pattern, use the same methods, IlvDisplay::getLinearGradientPattern and IlvDisplay::getRadialGradientPattern, and specify the alias as an input argument.

The methods first check if an IlvGradientPattern instance with the specified alias already exists. If one is found, it is returned, even if other input arguments do not match. If none is found, an instance is created based on other input arguments such as gradient geometry and color stops. It is your responsibility to set this aliased gradient pattern to the appropriate IlvPalette instances and, knowing who shares this IlvGradientPattern instance, to control the result of modifying the attributes.

To retrieve an aliased gradient pattern already stored in the display, use the IlvDisplay:: getGradientPattern method specifying the alias as a string parameter.