Class Documentation
Gradient |
1.0 |
ID_GRADIENT |
Stable |
GUI |
August 2003 |
Rocklyte Systems |
Rocklyte Systems (c) 2000-2003. All rights reserved. |
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".
|
|