Class Documentation

Name:Ellipse
Version:1.0
ID:ID_ELLIPSE
Status:Unspecified
Category:GUI
Date:March 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2003. All rights reserved.
Short:  Draws elliptical and circular shapes.



Description

The Ellipse class is used to draw elliptical shapes and circles to graphics areas. All you need to specify are the dimensions of the ellipse and its colour. Here is a DML based example:

  <ellipse x="10%" y="10%" width="80" height="60" colour="#6090a0"/>

If you want to draw an unfilled ellipse, set the Border field as opposed to the Colour. Beyond this, there is little else that you need to know about the Ellipse class - but check the documented fields if you need more detial.

Structure

The Ellipse object consists of the following public fields:

Border  Set this field to define the colour of the elliptical border.
Colour  Set this field to define the colour of the ellipse.
ColourRGB  Read this field to get the ellipse colour in RGB format.
Drawable  This field can be set to define the drawable area for the ellipse.
Fill  Set to TRUE to fill the ellipse.
Frame  Limits the drawing of an ellipse graphic to a single frame.
Frames  Determines a sequence of frames that an ellipse may be drawn to.
Height  The height of the ellipse is specified here.
Highlight  String-based field for setting the highlight colour of a ellipse object.
HighlightRGB  Defines the highlight colour of the ellipse in RGB format.
Hollow  If set to TRUE the ellipse will be given a hollow appearance.
Raised  If set to TRUE the ellipse will appear to be raised into the foreground.
Shadow  String-based field for setting the shadow colour of an ellipse object.
ShadowRGB  Defines the shadow colour of an ellipse in RGB format.
Sunken  Set to TRUE to make an ellipse appear to sink into the background.
Thickness  The thickness of the ellipse border is managed by this field.
Width  The width of the ellipse is specified here.
XCoord  Defines the horizontal position of the ellipse.
XOffset  Defines the horizontal offset of the ellipse.
YCoord  Defines the vertical position of the ellipse.
YOffset  Defines the vertical offset of the ellipse.
Field:Border
Short:Set this field to define the colour of the elliptical border.
Type:STRING
Status:Write

To give an ellipse a plain-coloured border, set this field to the text-based colour value that you want to use (e.g. "255,0,0" for red). To set the thickness of the border, write a value to the Thickness field.


Field:Colour
Short:Set this field to define the colour of the ellipse.
Type:STRING
Status:Write

The internal colour of an ellipse 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.

If you create an ellipse without setting the Colour field, the result will be an unfilled rectangle. The colour is also intrinsically linked to the Fill field - if you want to switch the colour off temporarily, you can set the Fill field to FALSE.


Field:ColourRGB
Short:Read this field to get the ellipse colour in RGB format.
Type:RGB
Status:Read

The internal colour of an ellipse can be read in RGB format from this field.


Field:Drawable
Short:This field can be set to define the drawable area for the ellipse.
Type:OBJECTID
Status:Read/Write

In most cases, when you create an ellipse it should be contained by a drawable area, such as a Render object. If you do this correctly then the ellipse will detect the drawable area and set the Drawable field to the correct object. However, there may be occasions where you want to initialise an ellipse object to a non-graphical container. If this is the case then you must set the Drawable field to point to a valid drawable area, such as a Render object.


Field:Fill
Short:Set to TRUE to fill the ellipse.
Type:BOOLEAN
Status:Read/Write

If this field is set to TRUE then the ellipse will be filled when it is drawn. The colour used to fill the ellipse is determined by the Colour field.


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

Setting the Frame field to any value other than zero will force an ellipse 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 ellipse has a frame of 1, then no graphics will be drawn to represent the ellipse as the numbers do not match.


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

For long animation sequences you can set the Frames field to determine individual frames that an ellipse should be drawn to. For instance, if a drawable has been assigned 20 animation frames and you want an ellipse 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 ellipse is specified here.
Type:FLOAT/PERCENTAGE
Status:Read/Write

If the ellipse is to be drawn with a fixed height, set this field to the desired value. A percentage may be specified if the FD_PERCENT flag is used when setting the field.


Field:Highlight
Short:String-based field for setting the highlight colour of a ellipse object.
Type:STRING
Status:Write

If an ellipse object should be highlighted around the edges, set this field to the desired colour for the highlighting. The colour specification must be in the standard hexadecimal or decimal separated format.

Passing a NULL value to this field will turn off highlighting.


Field:HighlightRGB
Short:Defines the highlight colour of the ellipse in RGB format.
Type:RGB
Status:Read

The highlight colour of an ellipse can be read in RGB format from this field.


Field:Hollow
Short:If set to TRUE the ellipse will be given a hollow appearance.
Type:BOOLEAN
Status:Write

If you have set the Highlight and Shadow fields of an ellipse object then you will need to decide whether or not the ellipse should be given a sunken or raised effect when it is drawn. Setting the Hollow field to TRUE will give you a raised appearance and the center of the ellipse will take the form of a hollow cylinder.


Field:Raised
Short:If set to TRUE the ellipse will appear to be raised into the foreground.
Type:BOOLEAN
Status:Write

If you have set the Highlight and Shadow fields of an ellipse object then you will need to decide whether or not the ellipse should be given a sunken or raised effect when it is drawn. To give it a raised effect you will need to set this field to TRUE, if not then you should set the Sunken field.


Field:Shadow
Short:String-based field for setting the shadow colour of an ellipse object.
Type:STRING
Status:Write

If an ellipse object should be shadowed around the edges, set this field to the desired colour for the shadowing. The colour specification must be in the standard hexadecimal or decimal separated format.

Passing a NULL value to this field will turn off shadowing.


Field:ShadowRGB
Short:Defines the shadow colour of an ellipse in RGB format.
Type:RGB
Status:Read

The shadow colour of an ellipse can be read in RGB format from this field.


Field:Sunken
Short:Set to TRUE to make an ellipse appear to sink into the background.
Type:BOOLEAN
Status:Write

If you have set the Highlight and Shadow fields of an ellipse object then you will need to decide whether or not the ellipse should be given a sunken or raised effect when it is drawn. To give it a sunken effect you will need to set this field to TRUE, if not then you should set the Raised field.


Field:Thickness
Short:The thickness of the ellipse border is managed by this field.
Type:LONG
Status:Read/Write

The thickness of the ellipse border is managed by this field. By default the Thickness value is set to 1, and larger values will inrease the border's pixel size. Setting the field to 0 will turn off the border.


Field:Width
Short:The width of the ellipse is specified here.
Type:FLOAT/PERCENTAGE
Status:Read/Write

If the ellipse is to be drawn with a fixed width, set this field to the desired value. 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 ellipse.
Type:FLOAT/PERCENTAGE
Status:Read/Write

The horizontal position of an ellipse can be fixed to an absolute coordinate by writing a value to the XCoord field. If you use the FD_PERCENT flag then you may write a relative (percentage) based value to the field. Negative values are permitted.


Field:XOffset
Short:Defines the horizontal offset of the ellipse.
Type:FLOAT/PERCENTAGE
Status:Read/Write

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 ellipse 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 Ellipse 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 ellipse will be drawn at an X coordinate calculated from the formula "XCoord = ContainerWidth - EllipseWidth - XOffset".


Field:YCoord
Short:Defines the vertical position of the ellipse.
Type:FLOAT/PERCENTAGE
Status:Read/Write

The vertical position of an ellipse can be fixed to an absolute coordinate by writing a value to the YCoord field. If you use the FD_PERCENT flag then you may write a relative (percentage) based value to the field. Negative values are permitted.


Field:YOffset
Short:Defines the vertical offset of the ellipse.
Type:FLOAT/PERCENTAGE
Status:Read/Write

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 ellipse 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 ellipse 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 ellipse will be drawn at a Y coordinate calculated from the formula "YCoord = ContainerHeight - EllipseHeight - YOffset".