Class Documentation

Name:Ellipse
Version:1.0
ID:ID_ELLIPSE
Status:Unspecified
Category:GUI
Date:May 2001
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2001. 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 field documentation 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.
Height  The height of the Ellipse is specified here.
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: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:Thickness
Short:The thickness of the Ellipse border is managed by this field.
Type:LONG
Status: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".