Class Documentation

Name:Input
Version:1.0
ID:ID_INPUT
Status:Beta
Category:GUI
Date:January 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2003-2004. All rights reserved.
Short:  The Input class manages the display and interactivity of user input boxes.



Description

The Input class simplifies the creation and management of input boxes as part of the user interface. New input areas can be created by specifying as little as the graphical dimensions for the box area. The Input class allows for the specifics of the graphics to be altered, such as the colours and the font used.

The definitions for new input boxes are loaded by default from the environment file "templates:inputdef.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 input object.

You may need to set the object up so that when the user clicks or tabs away from the input box, it performs an action. There are three accepted 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 input box is activated. The second is to initialise child objects to the input object and they will be executed on activation. The third option is to listen to the Activate action by calling the SubscribeAction() function on the input.

The following example illustrates how you might create an input box in DML. Notice that the Set object is initialised as static and will be executed when the input object is activated:

  <input xoffset="[window.leftmargin]" yoffset="[window.bottommargin]"
    text="Hello World" width="70">
    <set static object="[text]" &string="[owner.text]"/>
  </input>

Actions

The Input class supports the following actions:

Activate  Activates the input object's response mechanism.
Disable  Turns the input box off.
Enable  Turns the input box back on if it has previously been disabled.
Focus  Sets the focus on the input box.
Hide  Removes the input box from the display.
MoveToBack  Moves the input box to the back of the display area.
MoveToFront  Moves the input box to the front of the display area.
Redimension  Changes the size and position of the input box.
Resize  Alters the size of the input box.
Show  Puts the input box on display.

Structure

The Input object consists of the following public fields:

ActionScript  Script to be executed when the input box is clicked.
Bottom  The bottom coordinate of the input box.
Colour  String-based field for setting the colour inside of the input box.
ColourRGB  Defines the internal colour of the input box in RGB format.
Drawable  The drawable that will contain the input graphic.
EnterFrame  The graphics frame to display when the user's pointer enters the input area.
ExitFrame  The graphics frame to display when the user's pointer leaves the input area.
Flags  Optional flags may be set here.
FocusActivate  If set to TRUE, the input box will automatically activate itself if the user leaves the input area.
FocusFrame  The graphics frame to display when the input box has the focus.
Height  Defines the height of an input box.
Highlight  String-based field for setting the border highlight.
HighlightRGB  Defines border highlight of the input box, in RGB format.
Label  The label is a string displayed to the left of the input area.
LabelWidth  The width of the input label.
Raised  If set to TRUE the input box will appear to be raised into the foreground.
Region  The drawable that represents the input box is referenced through this field.
ReleaseFrame  The graphics frame to display when the input box loses the focus.
Right  The right-most coordinate of the input box.
Shadow  String-based field for setting the input box shadow.
ShadowRGB  Defines the border shadow of the input box, in RGB format.
String  The string that is to be printed inside the input box is declared here.
Sunken  Set to TRUE to make the input box appear to sink into the background.
TabFocus  Setting this field to a valid TabFocus object will cause the input to add itself to the tab list.
Template  Defines the makeup of the input using a pre-defined template.
Thickness  The thickness of the input border.
Width  Defines the width of a input.
XCoord  The horizontal position of a input.
XOffset  The horizontal offset of a input.
YCoord  The vertical position of a input.
YOffset  The vertical offset of a input.
Field:ActionScript
Short:Script to be executed when the input box is clicked.
Type:STRING
Status:Get/Set

When an input box is activated, 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 the script execution text (e.g. DML code) can also be useful for optimising the execution of simple scripts.


Field:Bottom
Short:The bottom coordinate of the input box.
Type:LONG
Status:Get

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


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

The colour inside of an input box 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.


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

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


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

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

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

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

FlagDescription
COMMANDLINEPrepares the input box for 'command-line' mode. This option is typically used when the input box needs to remain persistent and is linked to an output system, such as a shell.
DISABLEDThis readable flag is automatically set when the input is disabled. You may set it on initialisation if the input is to be disabled on creation.
FOCUSACTIVATEIf the input box loses the focus, the presence of this option will force it to automtically activate itself (as if the user had pressed the enter key).
HIDEThis flag may be set on initialisation in order to hide the input on its creation (applies to script usage only).
LOCALWhen the input is activated, any child objects belonging to the input will be executed immediately within the input's execution process, rather than through the messaging system.
RAISED(Read-Only) Draws the input box with the raised effect.
SECRETUse the SECRET option when the input box is being used to enter secret user information, such as a password.
SUNKEN(Read-Only) Draws the input box using the sunken effect. This is the default.

Field:FocusActivate
Short:If set to TRUE, the input box will automatically activate itself if the user leaves the input area.
Type:LONG
Status:Read/Init

If this field is set to TRUE, the input box will automatically activate itself if the user enters the input area and then leaves. The activation will occur regardless of wether or not the user edited the content of the input box. The effect is the same as if the user had proactively pressed the enter key.


Field:FocusFrame
Short:The graphics frame to display when the input box has the focus.
Type:LONG
Status:Read/Write

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


Field:Height
Short:Defines the height of an input box.
Type:DOUBLE/PERCENTAGE
Status:Get/Set

An input box 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 border highlight.
Type:STRING
Status:Set

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

The border highlight of the input box 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:LabelWidth
Short:The width of the input label.
Type:LONG
Status:Read/Set

If a label has been set for an input box, its width may be read and adjusted at any time via the LabelWidth field. The input area will be arranged so that it immediately follows the width defined for the text label. If you define a width that is too short for the text that is to be printed in the label, the text will be trimmed to fit the defined area.

If you specify a label without setting the label width, the correct width will be automatically calculated for you on initialisation.


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

If you have set the Highlight and Shadow fields of an input 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:Region
Short:The drawable that represents the input box is referenced through this field.
Type:OBJECTID
Status:Read

The rendering area that represents the input 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 input control system. Where possible, all communication should be limited to the input object itself.


Field:ReleaseFrame
Short:The graphics frame to display when the input box loses the focus.
Type:LONG
Status:Read/Write

If the FocusFrame 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 FocusFrame field has not been set.


Field:Right
Short:The right-most coordinate of the input box.
Type:LONG
Status:Get

The right-most coordinate of the input box (calculated as XCoord + Width) is readable from this field.


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

The border shadow of an input box 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 the border shadow of the input box, in RGB format.
Type:RGB
Status:Read

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


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

The string that you would like to be displayed in the input box is specified in this field. The string must be in UTF-8 format and may not contain line feeds. You can read this field at any time to determine what the user has entered in the input box.

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


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

If you have set the Highlight and Shadow fields of an input 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:TabFocus
Short:Setting this field to a valid TabFocus object will cause the input to add itself to the tab list.
Type:OBJECTID
Status:Set

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

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

<?xml version="1.0"?>

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

<graphics>
  <box frame="1" boxes="(s0,0,!0,!0) (s1,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:Thickness
Short:The thickness of the input border.
Type:LONG
Status:Read/Write

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


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

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

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


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

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