Class Documentation

Name:Box
Version:1.0
ID:ID_BOX
Status:Stable
Category:GUI
Date:June 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2003. All rights reserved.
Short:  Draws rectangular graphics.



Description

The Box is a simple drawable object used for drawing bevelled boxes and filled areas inside rendered objects. By default a Box will take up the entire width and height of its container, but powerful features are also provided that allow you to create complicated shapes out of multiple rectangles.

Here are some examples for creating Box graphics. The first creates a raised, bevelled box with grey colouring.

   <box colour="#808080" shadow="#303030" highlight="#ffffff" raised/>

This example creates a 10x10 box with a black border that is 2 pixels thick:

   <box thickness="2" width="10" height="10" border="#000000"/>

If you want to draw multiple boxes with one object, you can use the Boxes field. This next example draws a box that fills up the area of its container, and also draws a smaller box that is offset by 5 pixels from each margin:

   <box boxes="(0,0,!0,!0) (5,5,!5,!5)" colour0="255,0,0"
     colour1="255,255,255"/>

For more detail on how to use the Box class, please refer to the documentation for the individual fields.

Actions

The Box class supports the following actions:

Hide  Hides a box from view.
SetUnlistedField  Used to set special box fields.
Show  Shows a box.

Structure

The Box object consists of the following public fields:

Border  String-based field for setting the border colour of a Box object.
BorderOpacity  Determines the level of translucency applied to box borders.
Boxes  Special field to create multiple boxes using one object.
Brightness  Alters the brightness level of the box colours.
ColourRGB  Defines the internal colour of a box in RGB format.
Colour  String-based field for setting the colour inside of the box.
Drawable  Defines the drawable area for the Box graphics.
Fill  Set to TRUE or FALSE to alter the filling of a box.
Frame  Limits the drawing of a box to a single frame.
Frames  Determines a sequence of frames that a box graphic may be drawn to.
Height  The height of a box graphic.
HighlightRGB  Defines the highlight colour of the box in RGB format.
Highlight  String-based field for setting the highlight colour of a box object.
Opacity  Determines the level of translucency applied to a box.
Raised  If set to TRUE the box will appear to be raised into the foreground.
Round  Pixel specification for rounding at each corner of the box.
Shadow  String-based field for setting the shadow colour of a Box object.
ShadowRGB  Defines the shadow colour of a box in RGB format.
Sunken  Set to TRUE to make a box appear to sink into the background.
Thickness  Defines the thickness of a box's border.
TotalBoxes  Defines the total amount of boxes to be drawn by a box object.
Width  The width of a box's graphic.
XCoord  The horizontal position of a box.
XOffset  The horizontal offset of a box.
YCoord  The vertical coordinate of a box.
YOffset  The vertical offset of a box.
Field:Border
Short:String-based field for setting the border colour of a Box object.
Type:STRING
Status:Write

To give a Box a plain-coloured border on all four sides, set this field to the text-based colour value that you want to use. If the Highlight or Shadow fields are set, giving the Box a border will over-ride those values with the new border colour.

To set the thickness of the border, write a value to the Thickness field.


Field:BorderOpacity
Short:Determines the level of translucency applied to box borders.
Type:FLOAT
Status:Get/Set

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


Field:Boxes
Short:Special field to create multiple boxes using one object.
Type:STRING (Unlisted)
Status:Write

This special field allows you to create multiple box definitions using a single Box object. This can help you save memory in cases where you might otherwise need to create many Box objects to get the effect that you want to achieve. 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 box in sets of four numbers - that is, the X and Y coordinate followed by either the Width and Height or XOffset and YOffset. To aid you in your visualisation of these numbers, you may insert brackets and commas to organise each box definition into a group. The following example illustrates the basic creation of two box graphics:

  "(0,0,20,20) (5,5,10,10)"

This would result in a box that is 20x20 pixels wide at position (0,0), and a box that is 10x10 pixels wide at position (5,5). If you need to set an offset or percentage based value, then you will need to use the exclamation and/or percentage symbols. This next example will create a box that surrounds its contained area with two box definitions:

  "(0,0,!0,!0) (1,1,!1,!1)"

This example uses percentages to create two boxes:

  "(0%,0%,20%,20%) (5%,5%,10%,10%)"

The only issues left are in the setting of colours, and whether or not individual boxes should be given a raised or sunken appearance. Creating a raised or sunken box requires you to set an "R" or "S" character prior to a box definition. The following example creates two separate raised and sunken boxes:

  "r(0,0,20,20) s(5,5,10,10)"

In order to set colours for individual boxes, the unlisted field mechanism needs to be used, and you need to know the correct index for each box. To demonstrate, setting the border for the second box in the list would require us to set the field "Border1" (indexing starts from zero, so the second box is #1). Other colour indexes are supported, including the Highlight, Shadow and Colour fields. If a colour is not set for a particular box definition, the box will remain unfilled. The final example demonstrates the creation of four boxes with their own individual border colours:

  <box boxes="(0,0,!0,!0) (1,1,!1,!1) (2,2,!2,!2) (3,3,!3,!3)"
    border0="#5e4fcd" border1="#8793e8" border2="#6F7fdd" border3="#5e4fcd"/>

Field:Brightness
Short:Alters the brightness level of the box colours.
Type:FLOAT
Status:Read/Write

The brightness of the colours in the box graphic can be dynamically altered through this field. By default the brightness value is set to 100%. Lowering the brightness will darken the colours, while increasing the level will brighten them.

If the ACTIVEDRAW flag is in use, the box will automatically redraw itself when the Brightness field is set.


Field:ColourRGB
Short:Defines the internal colour of a box in RGB format.
Type:RGB
Status:Read

The colour drawn inside of a box can be read in RGB format from this field.


Field:Colour
Short:String-based field for setting the colour inside of the box.
Type:STRING
Status:Set

The internal colour of a box 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 a Box 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:Drawable
Short:Defines the drawable area for the Box graphics.
Type:OBJECTID
Status:Read/Write

In most cases, when you create a new box object it should be contained by a drawable area, such as a Render object. If you do this correctly then the box will detect the drawable area and set the Drawable field to the correct object. However, there may be occasions where you want to initialise a box 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 or FALSE to alter the filling of a box.
Type:BOOLEAN
Status:Write

Manipulation of the Fill field can provide an easy mechanism for turning the internal colour of the box on and off. By default a box object will manage filling based on your colour specifications, but you can force the issue by writing directly to this field.


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

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


Field:Frames
Short:Determines a sequence of frames that a box 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 box graphic should be drawn to. For instance, if a drawable has been assigned 20 animation frames and you want a box 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:Height
Short:The height of a box graphic.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A Box can be given a fixed height by setting this field to the desired value. A percentage may be specified if the FD_PERCENT flag is used when setting the field.


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

The highlight colour of a Box can be read in RGB format from this field.


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

If a Box 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:Opacity
Short:Determines the level of translucency applied to a box.
Type:FLOAT
Status:Get/Set

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


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

If you have set the Highlight and Shadow fields of a box object then you will need to decide whether or not the box 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:Round
Short:Pixel specification for rounding at each corner of the box.
Type:LONG
Status:Set

Rounded corners can be enabled by setting this field to a value of at least two.


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

If a Box 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 a box in RGB format.
Type:RGB
Status:Read

The shadow colour of a Box can be read in RGB format from this field.


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

If you have set the Highlight and Shadow fields of a Box object then you will need to decide whether or not the Box 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:Defines the thickness of a box's border.
Type:LONG
Status:Read/Write

The pixel-based thickness of the Box' border is defined by this field. A minimum value of 0 will prevent a border from being drawn, effectively switching off the functionality of the Highlight, Shadow and Border fields. The default border thickness is a value of 1.


Field:TotalBoxes
Short:Defines the total amount of boxes to be drawn by a box object.
Type:LONG
Status:Read/Set

The TotalBoxes field can be dynamically adjusted if you wish to lower or increase the amount of boxes being drawn. This feature works in situations where a box object contains multiple box definitions.

You cannot set a value less than one or greater than the amount of boxes that you have already defined.


Field:Width
Short:The width of a box's graphic.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

If the Box 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:The horizontal position of a box.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The horizontal position of a Box 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 horizontal offset of a box.
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 Box 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 Box 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 Box will be drawn at an X coordinate calculated from the formula "XCoord = ContainerWidth - BoxWidth - XOffset".


Field:YCoord
Short:The vertical coordinate of a box.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The vertical position of a Box 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 of a box.
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 Box 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 Box 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 Box will be drawn at a Y coordinate calculated from the formula "YCoord = ContainerHeight - BoxHeight - YOffset".