Reference for the Mosaic class Graphics::Gradient
|
The class Graphics::Gradient provides common base functionality to define gradients. In practice you will never create instances of this class. Instead use the descending, more specialized classes Graphics::LinearGradient and Graphics::RadialGradient.
A gradient is determined by a list of color stops. To add new and modify existing color stops use the methods AddColorStop() and SetColorStop(). Before adding color stops, the maximum capacity of the gradient has to be specified by using the method SetMaxNoOfColorStops().
In case of simple gradients consisting of two color stops only, the convenience properties StartColor and EndColor can be used. In such case it is not necessary to explicitly specify the capacity of the gradient and it is not necessary to add any color stops. Just specify the start and the end colors of the gradient in the both mentioned properties.
To query the capacity of the gradient the method GetMaxNoOfColorStops() is available. To query the number of already specified color stops, use the method GetNoOfColorStops().
method int32 AddColorStop
(
arg float aOffset,
arg color aColor
);
The method AddColorStop() configures a new gradient color stop. The new color stop is appended to the end of the list of all previously specified color stops. If successful, the method returns a color stop number identifying the just added color stop. This number can be used to address and modify the color stop by the method SetColorStop(). If the gradient is full (there is no free color entry), the method fails returning -1.
The parameter aOffset is a floating point value in range 0.0 .. 1.0. It determines the position of the color stop within the gradient. The value 0.0 corresponds to the beginning of the gradient. The value 1.0 corresponds to the end of the gradient. Other values represent positions inbetween.
Please note, newly created gradient objects are per default configured to store only 2 color stops, which are specified in the properties StartColor and EndColor. If you plan to create a gradient with more than 2 color stops, increase the capacity of the gradient by invoking the method SetMaxNoOfColorStops() before adding the color stops.
property color EndColor = #00000000;
The property 'EndColor' specifies the last color stop found at the end of the gradient. To specify the color stop at the beginning of the gradient use the property StartColor.
The properties StartColor and EndColor are convenience properties to configure simple gradients. If your application case requires complex gradients consisting of more than 2 color stops, use the methods SetMaxNoOfColorStops() and AddColorStop() to specify each color stop individually.
method int32 GetMaxNoOfColorStops();
The method GetMaxNoOfColorStops() returns the capacity of this gradient, it means the maximum number of color stops this gradient can accomodate. To specify the capacity, the method SetMaxNoOfColorStops() is available.
method int32 GetNoOfColorStops();
The method GetNoOfColorStops() returns the number of color stops stored in this gradient. To append a new color stop, use the method AddColorStop(). To query the capacity of the gradient, use the method GetMaxNoOfColorStops().
method bool SetColorStop
(
arg int32 aColorStopNo,
arg float aOffset,
arg color aColor
);
The method SetColorStop() modifies a gradient color stop. The color stop has to be added previously by invoking the method AddColorStop(). The parameter aColorStopNo addresses the color stop in question.
The parameter aOffset is a floating point value in range 0.0 .. 1.0. It determines the position of the color stop within the gradient. The value 0.0 corresponds to the beginning of the gradient. The value 1.0 corresponds to the end of the gradient. Other values represent positions inbetween.
method bool SetMaxNoOfColorStops
(
arg int32 aMaxNoOfColorStops
);
The method SetMaxNoOfColorStops() configures the capacity - the maximum number of color stops this gradient can accomodate. Once the capacity is specified, the color stops can be added by using the method AddColorStop().
The capacity of a gradient is limited to 256 color stops. To query the configured capacity use the method GetMaxNoOfColorStops(). To query the number of already specified color stops the method GetNoOfColorStops() is available.
Please note, newly created gradient objects are per default configured to store 2 color stops, which are specified in the properties StartColor and EndColor. When changing the capacity of a gradient object, all previously specified color stops are discarded resulting in an empty gradient. Thus after invoking SetMaxNoOfColorStops() don't forget to invoke AddColorStop().
property color StartColor = #00000000;
The property 'StartColor' specifies the first color stop just at the beginning of the gradient. To specify the color stop at the end of the gradient use the property EndColor.
The properties StartColor and EndColor are convenience properties to configure simple gradients. If your application case requires complex gradients consisting of more than 2 color stops, use the methods SetMaxNoOfColorStops() and AddColorStop() to specify each color stop individually.