Class Documentation

Name:Button
Version:1.0
ID:ID_BUTTON
Status:Beta
Category:GUI
Date:November 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2003. All rights reserved.
Short:  The Button class manages the display and interactivity of user buttons.



Description

The Button class simplifies the creation and management of buttons as part of the user interface. New buttons are typically created by declaring the graphical dimensions and the text to be displayed within them. The Button class allows for the specifics of the button to be altered, such as the colours and the font style.

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

You will need to configure the button so that when it is clicked, 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 button is pressed. The second is to initialise child objects to the button and they will be executed on activation. The third option is to listen to the Activate action by calling the SubscribeAction() function on the button.

The following example illustrates how you might create a cancel button in DML. Notice that the Action object is initialised as static and will be executed when the button is clicked:

  <button xoffset="[window.leftmargin]" yoffset="[window.bottommargin]"
    text="Cancel" width="70">
    <action static call="free" object="[window]"/>
  </button>

Actions

The Button class supports the following actions:

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

Structure

The Button object consists of the following public fields:

ActionScript  A script to be executed when the button is clicked.
Bottom  The bottom coordinate of the button.
ClickFrame  The graphics frame to display when the button is clicked.
Colour  String-based field for setting the colour inside of the button.
ColourRGB  Defines the internal colour of the button in RGB format.
Drawable  The drawable that will contain the button graphic.
EnterFrame  The graphics frame to display when the user's pointer enters the button area.
ExitFrame  The graphics frame to display when the user's pointer leaves the button area.
Flags  Optional flags may be set here.
Height  Defines the height of a button.
Highlight  String-based field for setting the button highlight.
HighlightRGB  Defines border highlight of the button, in RGB format.
Image  The image field can be set in order to load a bitmap into the button.
Region  The drawable that represents the button is referenced through this field.
ReleaseFrame  The graphics frame to display when a user-click is released.
Right  The right coordinate of the button.
Shadow  String-based field for setting the button shadow.
ShadowRGB  Defines border shadow of the button, in RGB format.
String  The string that is to be printed inside the button is declared here.
TabFocus  Set this field to a TabFocus object to register the button in a tab-list.
Template  Defines the makeup of the button using a pre-defined template.
Thickness  The thickness of the button border.
Width  Defines the width of a button.
XCoord  The horizontal position of a button.
XOffset  The horizontal offset of a button.
YCoord  The vertical position of a button.
YOffset  The vertical offset of a button.
Field:ActionScript
Short:A script to be executed when the button is clicked.
Type:STRING
Status:Get/Set

When a button 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:Bottom
Short:The bottom coordinate of the button.
Type:LONG
Status:Get

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


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

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


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

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


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

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


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

The drawable that will contain the button graphic is set here. If this field is not set prior to initialisation, the button 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 button area.
Type:LONG
Status:Read/Write

This field specifies the drawable frame to switch to when the user's pointer enters the button 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 button area.
Type:LONG
Status:Read/Write

This field specifies the drawable frame to switch to when the user's pointer leaves the button 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 button object are as follows:

FlagDescription
HIDEThis flag may be set on initialisation in order to hide the button on its creation (applies to script usage only).
DISABLEDThis readable flag is automatically set when the button is disabled. You may set it on initialisation if the button is to be disabled on creation.
LOCALWhen the button is activated, any child objects belonging to the button will be executed immediately within the button's execution process, rather than through the messaging system.
NOBKGDTurns off the button's background graphics (border and background colour).
NOGFXTurns off the button's foreground graphics (text and images).
NOFOCUSTurns off the lines that are drawn around the button border when it has the user focus.

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

A button 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 button highlight.
Type:STRING
Status:Set

The border highlight of a button 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 button, in RGB format.
Type:RGB
Status:Read

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


Field:Image
Short:The image field can be set in order to load a bitmap into the button.
Type:STRING
Status:Set

To display an image inside the button, set the Image field. The image will be displayed on the left side of the text inside the button. If no text string has been set, the image will be shown at the exact center of the button.


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

The rendering area that represents the button 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 button control system. Where possible, all communication should be limited to the button 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 button.
Type:LONG
Status:Get

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


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

The border shadow of a button 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 button, in RGB format.
Type:RGB
Status:Read

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


Field:String
Short:The string that is to be printed inside the button is declared here.
Type:STRING
Status:Get/Set

The string that you would like to be displayed in the button is specified in this field. The string must be in UTF-8 format and be no longer than one line.

If the string is changed after initialisation, the button will be redrawn to show the updated text.


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

The TabFocus field provides a convenient way of adding the button 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 button using a pre-defined template.
Type:STRING
Status:Init

Setting the Template field allows a button defintion to be loaded from a pre-defined template file. The template may contain settings for all of the field values of a button object, as well as a customised graphics script for building the look and feel of the button. 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 button, while the graphics tag contains the graphical makeup of the button. The following example illustrates how a customised button can be created:

<?xml version="1.0"?>

<values>
  <exitframe value="1"/>
  <clickframe value="2"/>
  <enterframe value="3"/>
  <releaseframe value="1"/>
</values>

<graphics>
  <!-- Normal -->
  <box frame="1" 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"/>

  <!-- Clicked -->
  <box frame="2" boxes="(s0,0,!0,!0)" colour="200,200,200"
    highlight="120,120,120" shadow="80,80,80"/>

  <!-- OnMovement -->
  <box frame="3" boxes="(r0,0,!0,!0) (r1,1,!1,!1)" colour="245,245,245"
    highlight="120,120,120" highlight(1)="255,255,255" shadow="80,80,80"
    shadow(1)="200,200,200"/>
</graphics>

Field:Thickness
Short:The thickness of the button border.
Type:LONG
Status:Read/Write

This field specifies the thickness of the button border, expressed in pixels. By default the thickness is set to a value of 1.


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

A button 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 button.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

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


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

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