Class Documentation

Name:Line
Version:1.0
ID:ID_LINE
Status:Stable
Category:GUI
Date:January 2002
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2002. All rights reserved.
Short:  Draws lines to graphical areas.



Description

The Line class is used to draw single and multiple lines to graphics areas. The class supports individual colour settings for each line, scaling and variable line thickness. Lines can be drawn in a sequence of points and support is provided for offsets, fixed coordinates and relative coordinates. Here are four DML examples that demonstrate different ways to use the Line class:

  <line points="(100,100) (150,76) (187,560) (0,0)" col0="#ffffff"
    col1="#ff0000" col2="#00ff00"/>

  <line p0="1,1" p1="!100,!400" colour="#ffffff"/>

  <line p0="50%,50%" p1="!25%,!25%" colour="#ffffff"/>

  <line x0="=[logo.x]-10" y0="0" x1="=[logo.x]-10"
    y1="=[systemdisplay.height]-1" colour="#FFFFFF"/>

Because the Line class produces graphical objects, they should always be initialised to a drawable container, such as a Render object. For more detail on how to use the Line class, please refer to the documentation for the individual fields.

Actions

The Line class supports the following actions:

Hide  Hides the graphics of a line object.
Show  Displays the graphics of a line object.

Structure

The Line object consists of the following public fields:

ColourRGB  Defines the colour of the line in RGB format.
Colour  String-based field for setting the colour of a Line.
Frame  Limits the drawing of a line to a single frame.
Frames  Determines a sequence of frames that a line graphic may be drawn to.
Opacity  Determines the level of translucency applied to a line.
Points  This field provides an easy way to draw multiple and connected lines.
Scale  Adjusts the scale of the Line.
Thickness  Defines the thickness of the Line in pixels.
Field:ColourRGB
Short:Defines the colour of the line in RGB format.
Type:*RGB
Status:Read/Write

The colour of a line can be read or written in RGB format through this field.

If you are creating multiple lines and need to set the colour of each line individually, you need to use unlisted fields to do this. Refer to the Points field for more detail.


Field:Colour
Short:String-based field for setting the colour of a Line.
Type:STRING
Status:Write

The colour of a Line 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 are creating multiple lines and need to set the colour of each line individually, you need to use unlisted fields to do this. Refer to the Points field for more detail.


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

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


Field:Frames
Short:Determines a sequence of frames that a line 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 line graphic should be drawn to. For instance, if a drawable has been assigned 20 animation frames and you want a line 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:Opacity
Short:Determines the level of translucency applied to a line.
Type:FLOAT
Status:Get/Set

This field determines the translucency level of a line graphic. The default setting is 100%, which means that the line will be solid. Any other value that you set here will alter the impact of a line graphic over the destination drawable. High values will retain the boldness of the line, 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 line.


Field:Points
Short:This field provides an easy way to draw multiple and connected lines.
Type:STRING
Status:Write

This special field allows you to create multiple line definitions using a single Line object. This can help you save memory in cases where you might otherwise need to create many Line objects to get the effect that you want. Setting this field requires that you follow some basic rules and use the correct symbols, or you may get unpredictable results.

Basic use requires that you specify the coordinates and dimensions for each line in sets of four numbers - that is, the X and Y coordinates followed by the XEnd and YEnd coordinates. To aid you in your visualisation of these numbers, you may insert brackets and commas to organise each line definition into a group. The following example illustrates the creation of a series of line graphics:

  "(10,10) (50,50) (100,0) (85,150) (400,30) (34,300)"

This would result in five lines being drawn across the graphics area from one point to the next. If you need to set offsets or percentage based values, then you will need to use the exclamation and/or percentage symbols. This next example shows all possible symbol combinations being used:

  "(10,10) (50,50) (25%,33%) (!60,!25) (!103%,!95%)"

If you need to break the line so that it is not fully connected, you can use the 'B' character to set a disconnection. This next example shows the previous set of lines being broken into two via use of the B character:

  "(10,10) (50,50) B (25%,33%) (!60,!25) (!103%,!95%)"

If you need to set individual colours for each line, the unlisted field mechanism needs to be used, and you need to know the correct index for each line. To demonstrate, setting the colour for the first line in the list would require us to set the field 'col0'. If you are using broken lines then be aware that the index is based on the point settings, so in our previous example the second line starts at point 3 and thus its colour is accessed through 'col2'. In situations where a specific colour has not been set, the value in the Colour field is used as a default.


Field:Scale
Short:Adjusts the scale of the Line.
Type:DOUBLE
Status:Read/Set

The scale of a Line can be adjusted by writing a value to this line. By default the Scale is set to 1, which tells the object not to use the scaling multiplier. In all other cases, the coordinates of the line will be multiplied by the Scale. For example, a line from (25,60) to (90,104) with a scale of 0.5 would be drawn as a line from (12,30) to (45,52).

Writing to the Scale field results in an immediate graphics update. Negative values are not permitted.


Field:Thickness
Short:Defines the thickness of the Line in pixels.
Type:LONG
Status:Read/Write

The thickness of a line can be adjusted by writing a value to this field. The default value is 1, which creates a thin line that is a single pixel wide. Note that the thicker the line, the more time that will need to be taken to draw it.