Class Documentation

Name:Arrow
Version:1.1
ID:ID_ARROW
Status:Unspecified
Category:GUI
Date:June 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2003. All rights reserved.
Short:  Draws arrows in various directions.



Description

The Arrow class provides graphical support for drawing arrows in any direction. Creating an Arrow object is straight-forward, and only requires that you set basic attributes such as the dimensions and the direction that the Arrow should point to. Support for setting the colour of the arrow and other common GUI constructs is also provided.

The following example creates an Arrow that points to the left:

  <arrow x="3" y="6" width="4" height="4" direction="left"
    colour="210,210,255"/>

The Arrow class supports all common GUI constructs including offsets and relative dimensions. For more detailed information, refer to the documentation for the individual fields.

Structure

The Arrow object consists of the following public fields:

Align  This field allows you to align an arrow within its drawable area.
Colour  String-based field for setting the internal colour of an Arrow.
ColourRGB  Defines the internal colour of the arrow in RGB format.
Direction  Determines the direction of the Arrow.
Frame  Determines the rendering frame that the Arrow will be applied to.
Height  The height of the Arrow.
Highlight  String-based field for setting the highlight colour of an arrow object.
HighlightRGB  Defines the highlight colour of the arrow in RGB format.
Opacity  Determines the level of translucency applied to an arrow.
Raised  If set to TRUE the arrow will appear to be raised into the foreground.
Scale  This field alters the width and height dimensions through scaling.
Shadow  String-based field for setting the shadow colour of an Arrow object.
ShadowRGB  Defines the shadow colour of the Arrow in RGB format.
Sunken  Set to TRUE to make the arrow appear to sink into the background.
Width  The width of the Arrow.
XCoord  The horizontal position of the Arrow.
XOffset  The horziontal offset for the Arrow.
YCoord  The vertical position of the Arrow..
YOffset  The vertical offset for the Arrow.
Field:Align
Short:This field allows you to align an arrow within its drawable area.
Type:LONG/FLAGS
Prefix:ALIGN
Status:Read/Write

If you would like to set an abstract position for an arrow, you can give it an alignment. Note that setting the alignment over-rides any settings in related coordinate fields. Valid alignment flags are as follows:

BOTTOM
CENTER/MIDDLE
LEFT
HORIZONTAL
RIGHT
TOP
VERTICAL


Field:Colour
Short:String-based field for setting the internal colour of an Arrow.
Type:STRING
Status:Write

The colour of an Arrow 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:ColourRGB
Short:Defines the internal colour of the arrow in RGB format.
Type:*RGB
Status:Get/Set

The colour of an arrow can be read or written in RGB format using this field.


Field:Direction
Short:Determines the direction of the Arrow.
Type:INDEX
Status:Read/Write

You can set the direction of an Arrow by writing to this field. The following index table illustrates the valid direction values:

  Name     Index         Value
  UP       ARROW_UP        1
  DOWN     ARROW_DOWN      2
  LEFT     ARROW_LEFT      3
  RIGHT    ARROW_RIGHT     4

Field:Frame
Short:Determines the rendering frame that the Arrow will be applied to.
Type:LONG
Status:Read/Write

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


Field:Height
Short:The height of the Arrow.
Type:FLOAT/PERCENTAGE
Status:Read/Write

To set the height of an Arrow, write a value to this field. A percentage may be specified if the FD_PERCENT flag is used, otherwise the setting is taken as being fixed. As an alternative to setting the Height, you can otherwise set the YCoord field in conjunction with the YOffset to create a dynamically calculated height value.


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

If an Arrow 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 arrow in RGB format.
Type:*RGB
Status:Read/Write

The highlight colour of an Arrow can be manipulated in RGB format using this field.


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

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


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

If you have set the Highlight and Shadow fields of an Arrow object then you will need to decide whether or not the Arrow 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:Scale
Short:This field alters the width and height dimensions through scaling.
Type:FLOAT
Status:Read/Write

The scale of an Arrow can be changed by writing a value to this field. Both the width and height will be adjusted by the factor that you set, using the calculation "ScaledValue = Value * Scale". The default scale of 1 will leave the width and height unchanged, 0.5 would halve the size of the arrow and a scale of 2 would double its size.

The Scale is limited to a range between 0 and 1000.


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

If an Arrow 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 the Arrow in RGB format.
Type:*RGB
Status:Read/Write

The shadow colour of an Arrow can be manipulated in RGB format using this field.


Field:Sunken
Short:Set to TRUE to make the arrow appear to sink into the background.
Type:BOOLEAN
Status:Read/Write

If you have set the Highlight and Shadow fields of an Arrow object then you will need to decide whether or not the Arrow 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:Width
Short:The width of the Arrow.
Type:FLOAT/PERCENTAGE
Status:Read/Write

To set the width of an Arrow, write a value to this field. A percentage may be specified if the FD_PERCENT flag is used, otherwise the setting is taken as being fixed. As an alternative to setting the Width, you can otherwise set the XCoord field in conjunction with the XOffset to create a dynamically calculated width value.


Field:XCoord
Short:The horizontal position of the Arrow.
Type:FLOAT/PERCENTAGE
Status:Read/Write

The horizontal position of an Arrow 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:The horziontal offset for the Arrow.
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 Arrow 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 Arrow 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 Arrow will be drawn at an X coordinate calculated from the formula "XCoord = ContainerWidth - ArrowWidth - XOffset".


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

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