Class Documentation

Name:CheckBox
Version:1.0
ID:ID_CHECKBOX
Status:Beta
Category:GUI
Date:November 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2003. All rights reserved.
Short:  The CheckBox class manages check boxes in the user interface.



Description

The CheckBox class simplifies the creation and management of checkboxes as part of the user interface. Check boxes are simple gadgets that are limited to exhibiting an on/off state. By default, a checkbox that is turned off will be empty, and when turned on it will display a checkmark. The CheckBox class allows for its graphics to be edited, so you can redefine how the on/off states are displayed.

The definitions for new checkboxes are loaded by default from the environment file "templates:checkboxdef.xml". You can change the template file prior to initialisation by setting the Template field. Note that any values set in the template will override your original field settings for the checkbox.

Depending on your requirements, you may need to configure the checkbox so that when its state changes, it performs an action. There are three acceptable methods that you can use to achieve this. The first is to set the ActionScript field so that it refers to a script that executes when the checkbox changes. The second is to initialise child objects to the checkbox and they will be executed on activation. The third option is to listen to the Activate action by calling the SubscribeAction() function on the checkbox.

Actions

The CheckBox class supports the following actions:

Activate  Activates the checkbox.
Disable  Disables the checkbox.
Enable  Turns the checkbox on if it has been disabled.
Focus  Sets the focus on the checkbox and activates keyboard monitoring.
Hide  Removes the checkbox from the display.
LostFocus  Removes the focus from the checkbox and disables key monitoring.
MoveToBack  Moves the checkbox to the back of the display area.
MoveToFront  Moves the checkbox to the front of the display area.
Redimension  Changes the size and position of the checkbox.
Resize  Alters the size of the checkbox.
Show  Puts the checkbox on display.
UserClick  Emulates a user click on the checkbox.
UserMovement  Emulates user movement over the checkbox.

Structure

The CheckBox object consists of the following public fields:

ActionScript  Script to be executed when the checkbox is clicked.
Border  String-based field for setting a single-colour border for the checkbox.
Bottom  The bottom coordinate of the checkbox.
CheckImage  Defines the image that is displayed when the checkbox state is set to 'on'.
ClickFrame  The graphics frame to display when the checkbox is clicked.
Colour  String-based field for setting the colour inside of the checkbox.
ColourRGB  Defines the internal colour of the checkbox in RGB format.
Disable  Disables the checkbox on initalisation.
Drawable  The drawable that will contain the checkbox graphic.
EnterFrame  The graphics frame to display when the user's pointer enters the checkbox area.
ExitFrame  The graphics frame to display when the user's pointer leaves the checkbox area.
Flags  Optional flags may be set here.
Height  Defines the height of a checkbox.
Highlight  String-based field for setting the checkbox highlight.
HighlightRGB  Defines border highlight of the checkbox, in RGB format.
Label  The label is a string displayed to the left of the input area.
Region  The drawable that represents the checkbox is referenced through this field.
ReleaseFrame  The graphics frame to display when a user-click is released.
Right  The right coordinate of the checkbox.
Shadow  String-based field for setting the checkbox shadow.
ShadowRGB  Defines border shadow of the checkbox, in RGB format.
TabFocus  Set this field to a TabFocus object to register the checkbox in a tab-list.
Template  Defines the makeup of the checkbox using a pre-defined template.
Value  Indicates the current TRUE/FALSE status for the checkbox.
Width  Defines the width of a checkbox.
XCoord  The horizontal position of a checkbox.
XOffset  The horizontal offset of a checkbox.
YCoord  The vertical position of a checkbox.
YOffset  The vertical offset of a checkbox.
Field:ActionScript
Short:Script to be executed when the checkbox is clicked.
Type:STRING
Status:Get/Set

When a checkbox is clicked, you can elect to run a script that performs a responsive action. The ActionScript string will typically refer to a file location, although the special STRING: assignment followed with script execution text (e.g. DML) can also be useful for optimising execution for simple scripts.


Field:Border
Short:String-based field for setting a single-colour border for the checkbox.
Type:STRING
Status:Set

The border colour for a checkbox 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:Bottom
Short:The bottom coordinate of the checkbox.
Type:LONG
Status:Get

The bottom coordinate of the checkbox (calculated as YCoord + Height) is readable from this field.


Field:CheckImage
Short:Defines the image that is displayed when the checkbox state is set to 'on'.
Type:LONG
Status:Set

When the checkbox state is set to 'on', it will display an image inside the checkbox area. You can redefine the default image by providing the path to an image file in this field. If the image file cannot be loaded for any reason, the checkbox will revert to its default image on initialisation.


Field:ClickFrame
Short:The graphics frame to display when the checkbox is clicked.
Type:LONG
Status:Read/Write

This field specifies the drawable frame to switch to when the user clicks on the checkbox. By default this field is initially set to zero, which has no effect on the drawable frame. When the user releases the checkbox, it will revert to the frame indicated by the ReleaseFrame field.


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

The colour inside of a checkbox is 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 checkbox without setting the Colour field, the checkbox will be drawn in black.


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

The colour inside of the checkbox can be read in RGB format from this field.


Field:Disable
Short:Disables the checkbox on initalisation.
Type:BOOLEAN
Status:Get/Set

The checkbox can be disabled on initialisation by setting this field to TRUE. If you need to disable the combobox after it has been activated, it is preferred that you use the Disable action.

To enable the combobox after it has been disabled, use the Enable action.


Field:Drawable
Short:The drawable that will contain the checkbox graphic.
Type:OBJECTID
Status:Read/Init

The drawable that will contain the checkbox graphic is set here. If this field is not set prior to initialisation, the checkbox will attempt to scan for the correct drawable by analysing its parents until it finds a suitable candidate.


Field:EnterFrame
Short:The graphics frame to display when the user's pointer enters the checkbox area.
Type:LONG
Status:Read/Write

This field specifies the drawable frame to switch to when the user's pointer enters the checkbox area. By default this field is initially set to zero, which has no effect on the drawable frame.


Field:ExitFrame
Short:The graphics frame to display when the user's pointer leaves the checkbox area.
Type:LONG
Status:Read/Write

This field specifies the drawable frame to switch to when the user's pointer leaves the checkbox area. This field is unused if the EnterFrame field has not been set.


Field:Flags
Short:Optional flags may be set here.
Type:LONG
Status:Read/Init

Optional flags that may be set against a checkbox object are as follows:

FlagDescription
DISABLEDThis readable flag is automatically set when the checkbox is disabled. You may set it on initialisation if the checkbox is to be disabled on creation.
HIDEThis flag may be set on initialisation in order to hide the checkbox on its creation (applies to script usage only).
LOCALBy default, the checkbox will send messages to its child objects when the checkbox state changes. If you set the LOCAL option, the checkbox will execute the objects within its own process space.

Field:Height
Short:Defines the height of a checkbox.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A checkbox can be given a fixed or relative height by setting this field to the desired value. To set a relative height, use the FD_PERCENT flag when setting the field.


Field:Highlight
Short:String-based field for setting the checkbox highlight.
Type:STRING
Status:Set

The border highlight of a checkbox is set 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:HighlightRGB
Short:Defines border highlight of the checkbox, in RGB format.
Type:RGB
Status:Read

The border highlight of the checkbox can be read in RGB format from this field.


Field:Label
Short:The label is a string displayed to the left of the input area.
Type:STRING
Status:Get/Set

A label can be drawn next to the input area by setting the Label field. The label should be a short, descriptive string of one or two words. It is common practice for the label to be followed with a colon character.


Field:Region
Short:The drawable that represents the checkbox is referenced through this field.
Type:OBJECTID
Status:Read

The rendering area that represents the checkbox display can be accessed through this field. For further information, refer to the Render class. Note that talking to the drawable directly can have adverse effects on the checkbox control system. Where possible, all communication should be limited to the checkbox object itself.


Field:ReleaseFrame
Short:The graphics frame to display when a user-click is released.
Type:LONG
Status:Read/Write

If the ClickFrame field has been set, you may want to match that value by indicating the frame that should be used when the click is released. By default, the value in this field will initially be set to 1. This field is unused if the ClickFrame field has not been set.


Field:Right
Short:The right coordinate of the checkbox.
Type:LONG
Status:Get

The right coordinate of the checkbox (calculated as XCoord + Width) is readable from this field.


Field:Shadow
Short:String-based field for setting the checkbox shadow.
Type:STRING
Status:Set

The border shadow of a checkbox is set 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:ShadowRGB
Short:Defines border shadow of the checkbox, in RGB format.
Type:RGB
Status:Read

The border shadow of the checkbox can be read in RGB format from this field.


Field:TabFocus
Short:Set this field to a TabFocus object to register the checkbox in a tab-list.
Type:OBJECTID
Status:Set

The TabFocus field provides a convenient way of adding the checkbox to a TabFocus object, so that it can be focussed on via the tab key. Simply set this field to the ID of the TabFocus object that is managing the tab-list for the application window.


Field:Template
Short:Defines the makeup of the checkbox using a pre-defined template.
Type:STRING
Status:Init

Setting the Template field allows a checkbox defintion to be loaded from a pre-defined template file. The template may contain settings for all of the field values of a checkbox object, as well as a customised graphics script for building the look and feel of the checkbox. The template must be provided as an XML file that can contain two possible root tags - 'value' and 'graphics'. The value tag contains a list of field values for setting against the checkbox, while the graphics tag contains the graphical makeup of the checkbox. The following example illustrates how a customised checkbox can be created:

<?xml version="1.0"?>

<values>
  <border value="#000000"/>
</values>

<graphics>
  <box boxes="(r0,0,!0,!0) (r1,1,!1,!1)" colour="230,230,230"
    highlight(0)="120,120,120" highlight(1)="255,255,255" shadow(0)="80,80,80"
    shadow(1)="200,200,200"/>
</graphics>

Field:Value
Short:Indicates the current TRUE/FALSE status for the checkbox.
Type:BOOLEAN
Status:Read/Set

To get the TRUE/FALSE status of the checkbox, read this field. You can also set this field if you wish to change the state of the checkbox. Only values of 0 and 1 are valid.


Field:Width
Short:Defines the width of a checkbox.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

A checkbox can be given a fixed or relative width by setting this field to the desired value. To set a relative width, use the FD_PERCENT flag when setting the field.


Field:XCoord
Short:The horizontal position of a checkbox.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

The horizontal position of a checkbox can be set to an absolute or relative coordinate by writing a value to the XCoord field. To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


Field:XOffset
Short:The horizontal offset of a checkbox.
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 checkbox 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 CheckBox 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 checkbox will be drawn at an X coordinate calculated from the formula "XCoord = ContainerWidth - CheckBoxWidth - XOffset".


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

The vertical position of a CheckBox can be set to an absolute or relative coordinate by writing a value to the YCoord field. To set a relative/percentage based value, you must use the FD_PERCENT flag or the value will be interpreted as fixed. Negative values are permitted.


Field:YOffset
Short:The vertical offset of a checkbox.
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 checkbox 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 checkbox 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 checkbox will be drawn at a Y coordinate calculated from the formula "YCoord = ContainerHeight - CheckBoxHeight - YOffset".