Class Documentation

Name:Dimple
Version:1.0
ID:ID_DIMPLE
Status:Stable
Category:GUI
Date:September 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2004. All rights reserved.
Short:  Overlays a dimple effect on drawable graphics.


Description

The Dimple class draws dot patterns to a drawable, using a set size for each dot and spacing inbetween them. The placing of the dots in the pattern can be perfectly linear (the default), or you can set the ALTERNATE flag to alternate the placement, creating a weaved pattern.

Using the Dimple class is simple - just set the Size of the dimples and the Spacing between them. For example:

   <dimple size="3" spacing="6"/>

Enhanced features such as variable translucency are provided. The Dimple class supports the standard GUI constructs for graphics placement and declaring the size of the graphics area.

Structure

The Dimple object consists of the following public fields:

ColourRGB  Defines the base colour of the object graphics.
Colour  String-based field for setting the base graphics colour.
Frame  Limits the drawing of the graphic to a single frame.
Frames  Determines a sequence of frames that a stripes graphic may be drawn to.
Height  The height of the ripple graphic is specified here.
Opacity  Determines the level of translucency applied to the dimples.
Width  The width of the ripple graphic is specified here.
XCoord  Defines the horizontal position of the ripple graphic.
XOffset  Defines the horizontal offset of the ripple graphic.
YCoord  Defines the vertical position of the ripple graphic.
YOffset  Defines the vertical offset of the ripple graphic.
Field:ColourRGB
Short:Defines the base colour of the object graphics.
Type:RGB
Status:Read

The base colour applied to the object graphics can be read in RGB format from this field.


Field:Colour
Short:String-based field for setting the base graphics colour.
Type:STRING
Status:Set

The colour of the object graphics can be declared by writing 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.


Field:Frame
Short:Limits the drawing of the graphic to a single frame.
Type:LONG
Status:Read/Write

Setting the Frame field to any value other than zero will force the object graphics to be drawn only when the drawable's frame matches the specified value. For instance, if the drawable container has a frame setting of 2, and the object has a frame of 1, then no graphics will be drawn to represent the object as the numbers do not match.


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

For long animation sequences you can set the Frames field to determine individual frames that the object graphics should be drawn to. For instance, if a drawable has been assigned 20 animation frames and you want the object graphics 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:The height of the ripple graphic is specified here.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

If a ripple graphic is to be limited to a specific drawable area, set this field to limit the clipping height. A percentage may be specified if the FD_PERCENT flag is used when setting the field.


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

This field determines the translucency level applied to the dimples. The default setting is 100%, which means that the reflection will be solid. Any other value that you set here will alter the impact of the reflection over the destination drawable.

Please note that the use of translucency will always have an impact on the time it normally takes to draw the reflection.


Field:Width
Short:The width of the ripple graphic is specified here.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

If a ripple graphic is to be limited to a specific drawable area, set this field to limit the clipping width. A percentage may be specified if the FD_PERCENT flag is used when setting the field.


Field:XCoord
Short:Defines the horizontal position of the ripple graphic.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The horizontal position of an image 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:Defines the horizontal offset of the ripple graphic.
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 image 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 image 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 image will be drawn at an X coordinate calculated from the formula "XCoord = ContainerWidth - DimpleWidth - XOffset".


Field:YCoord
Short:Defines the vertical position of the ripple graphic.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The vertical position of an image 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:Defines the vertical offset of the ripple graphic.
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 image 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 ripple 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 image will be drawn at a Y coordinate calculated from the formula "YCoord = ContainerHeight - Height - YOffset".