IlvGradientPattern: The Pattern Class Dedicated to Gradients

IlvGradientPattern class

The IlvGradientPattern class supports two different types of gradients:

Linear

Radial

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:

  • Width and height

  • Type of spread: Can take one of the following values:

IlvGradientPadSpread

IlvGradientRepeatSpread

IlvGradientReflectSpread

  • Color stops: Used to render the gradient. At least two color stops must be set on the gradient. A color stop is defined by an IlvColor instance, an alpha value specifying any transparency to be applied, and an offset value between 0 and 1 specifying the position of the color on the gradient. See the IlvColorStop class for details.

  • Alias: An optional attribute allowing you to control how the display shares the gradient pattern instance with the different palettes.

The IlvLinearGradientGeometry class

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, setWidth, IlvPattern::height and 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

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, setWidth, IlvPattern::height and 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

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:

  • Transform mode: Translate and scale the gradient relative to the graphic object or to the coordinates system of the container/manager to which the graphic object belongs.

  • Aspect ratio: Identify whether the gradient scaling keeps the gradient pattern aspect ratio or not. If the aspect ratio is kept, the gradient area will be centered on the graphic object and scaled uniformly to fit inside or outside the graphic or the port.

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:

Size:

Start circle:

End circle:

width = 200

height = 200

center

   x = 75

   y = 75

radius = 50

center

   x = 100

   y = 100

radius = 100

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:

IlvGradientTransformGraphic

In IlvGradientTransformGraphic mode, the gradient is translated and scaled relative to the graphic object bounding box. This is the most common way of using gradients.

There are three aspect ratio settings to take into consideration with this mode when defining how the gradient pattern should be scaled. These settings are described in the following table:

IlvGradientAspectRatioNo

IlvGradientAspectRatioInside

IlvGradientAspectRatioOutside

IlvGradientTransformGraphicNoResize

The IlvGradientTransformGraphicNoResize mode performs no scaling but the gradient is translated to the upper left corner of the graphic object bounding box.

In this mode, as no scaling is performed, the aspect ratio setting is ignored.

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.

IlvGradientNoTransform

The IlvGradientNoTransform mode performs no scaling but translates the gradient to the origin of the container or manager to which the graphic object belongs.

With a container, the origin is the upper left corner of the container.

With a view connected to a manager, the gradient geometry is translated to the origin of the manager. The gradient pattern will not be scaled in accordance with the manager view zoom level.

Gradient Patterns Sharing

There are two ways to create a gradient pattern instance:

  • ask the display to provide one

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, getLinearGradientPattern and 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.