Class Documentation

Name:Gradient
Version:1.0
ID:ID_GRADIENT
Status:Stable
Category:GUI
Date:August 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2003. All rights reserved.
Short:  The gradient class draws a range of gradually changing colours in a chosen direction.



Description

The Gradient class is an excellent tool for creating visually appealing backdrops for your graphics. Although the concept is quite simple, gradients can be used to simulate everything from images of the sky, fire, metals, water, horizons, or sun-sets.

To create a gradient you will need to decide on just a few factors - the colour to start the gradient, the colour to end it, the direction of the gradient, and if necessary the positioning and dimensions of the graphical area. A gradient may be drawn in four different directions - either horizontally, vertically, from the top left to the bottom right corner, or the bottom left to the top right corner. Specific angles from 0 to 360 degrees are not yet supported.

The following examples illustrate common usage of the Gradient class:

Horizontal Gradient, White to Black:

  <gradient direction="horziontal" firstcolour="#ffffff" lastcolour="#000000"/>

Vertical Gradient, Red to Blue, 200x200:

  <gradient direction="vertical" firstcolour="#ff0000" lastcolour="#0000ff"
    x="100" y="100" width="200" height="200"/>

All standard GUI constructs are supported, so percentage based dimensions and offsets can also be used. In cases where no coordinates or dimensions have been specified, the gradient will take up the entire graphical area of its related drawable.

Structure

The Gradient object consists of the following public fields:

Direction  Sets the direction of the Gradient colours.
FirstColour  String-based field for setting the first colour of the Gradient.
FirstColourRGB  Defines the first colour of the Gradient in RGB format.
Frame  Forces the Gradient to be drawn to a specific frame.
Frames  Determines a sequence of frames that a gradient graphic may be drawn to.
Height  Defines the height of a gradient.
LastColouRGB  Defines the last colour of the Gradient in RGB format.
LastColour  String-based field for setting the last colour of the Gradient.
Opacity  Determines the level of translucency applied to a gradient.
Width  Defines the width of a gradient.
XCoord  The horizontal position of a gradient.
XOffset  The horizontal offset of a gradient.
YCoord  The vertical position of a gradient.
YOffset  The vertical offset of a gradient.
Field:Direction
Short:Sets the direction of the Gradient colours.
Type:INDEX
Status:Read/Write

By default the Gradient will be drawn vertically, but you may want to have it drawn horizontally or diagonally. You will need to set this field to determine the exact orientation of the gradient. Valid settings are:

VERTICAL
HORIZONTAL
TOPDIAGONAL
BOTTOMDIAGONAL

For further clarification, the TOPDIAGONAL option will draw the Gradient from the top left down to the bottom right. The BOTTOMDIAGONAL option will draw the Gradient from the bottom left up to the top right. Vertical gradients start from the top down, and horizontal gradients start from the left to the right.


Field:FirstColour
Short:String-based field for setting the first colour of the Gradient.
Type:STRING
Status:Write

You need to set the first colour of the Gradient by writing a string-based colour to this field. The colour must be in hexadecimal or separated-decimal format - for example to create a pure red colour, a setting of '#ff0000' or '255,0,0' would be valid.

You may also set the alpha channel in the fourth value if you wish to use gradual alpha blending in your gradient. The maximum decimal value for attaining full opacity is 255.


Field:FirstColourRGB
Short:Defines the first colour of the Gradient in RGB format.
Type:RGB
Status:Read/Write

You can read or write the first colour of the Gradient using this RGB based field.


Field:Frame
Short:Forces the Gradient to be drawn to a specific frame.
Type:LONG
Status:Read/Write

If this field is set to a valid frame number, the Gradient will only be drawn when the frame of the container matches the Frame number in this field. When set to 0 (the default), the Gradient will be drawn regardless of the container's frame number.


Field:Frames
Short:Determines a sequence of frames that a gradient graphic may be drawn to.
Type:STRING
Status:Set

For long animation sequences you can set the Frames field to determine individual frames that a gradient graphic should be drawn to. For instance, if a drawable has been assigned 20 animation frames and you want a gradient graphic to appear in frames 5, 6, 7, 8, 17 and 19, you would use this frame specification:

   5-8,17,19

Individual frame sets are separated by any non-numeric character such as a comma, and ranges can be specified through the '-' character.

Setting the Frames field will override any setting that you may have previously set in the Frame field.


Field:Height
Short:Defines the height of a gradient.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A gradient can be given a fixed or relative height by setting this field to the desired value. To set a relative height, use the FD_PERCENT flag when setting the field.


Field:LastColouRGB
Short:Defines the last colour of the Gradient in RGB format.
Type:RGB
Status:Read/Write

You can read or write the last colour of the Gradient using this RGB based field.


Field:LastColour
Short:String-based field for setting the last colour of the Gradient.
Type:STRING
Status:Write

You need to set the last colour of the Gradient by writing a string-based colour to this field. The colour must be in hexadecimal or separated-decimal format - for example to create a pure red colour, a setting of '#ff0000' or '255,0,0' would be valid.

You may also set the alpha channel in the fourth value if you wish to use gradual alpha blending in your gradient. The maximum decimal value for attaining full opacity is 255.


Field:Opacity
Short:Determines the level of translucency applied to a gradient.
Type:FLOAT
Status:Get/Set

This field determines the translucency level of a gradient. The default setting is 100%, which means that the gradient will be solid. Any other value that you set here will alter the impact of a gradient over the destination drawable. High values will retain the boldness of the gradient, while low values can render it close to invisible.

Please note that the use of translucency will always have an impact on the time it normally takes to draw a gradient. The use of translucency also requires that the drawable area is buffered, as read access is required to perform the blending algorithm.


Field:Width
Short:Defines the width of a gradient.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A gradient can be given a fixed or relative width by setting this field to the desired value. To set a relative width, use the FD_PERCENT flag when setting the field.


Field:XCoord
Short:The horizontal position of a gradient.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The horizontal position of a gradient can be set to an absolute or relative coordinate by writing a value to the XCoord field. To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


Field:XOffset
Short:The horizontal offset of a gradient.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The XOffset has a dual purpose depending on whether or not it is set in conjunction with an X coordinate or a Width based field.

If set in conjunction with an X coordinate then the gradient will be drawn from that X coordinate up to the width of the container, minus the value given in the XOffset. This means that the width of the Gradient is dynamically calculated in relation to the width of the container.

If the XOffset field is set in conjunction with a fixed or relative width then the gradient will be drawn at an X coordinate calculated from the formula "XCoord = ContainerWidth - GradientWidth - XOffset".


Field:YCoord
Short:The vertical position of a gradient.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The vertical position of a Gradient can be set to an absolute or relative coordinate by writing a value to the YCoord field. To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


Field:YOffset
Short:The vertical offset of a gradient.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The YOffset has a dual purpose depending on whether or not it is set in conjunction with a Y coordinate or a Height based field.

If set in conjunction with a Y coordinate then the gradient will be drawn from that Y coordinate up to the height of the container, minus the value given in the YOffset. This means that the height of the gradient is dynamically calculated in relation to the height of the container.

If the YOffset field is set in conjunction with a fixed or relative height then the gradient will be drawn at a Y coordinate calculated from the formula "YCoord = ContainerHeight - GradientHeight - YOffset".