Class Documentation

Name:ComboBox
Version:1.0
ID:ID_COMBOBOX
Status:Beta
Category:GUI
Date:December 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2003. All rights reserved.
Short:  The ComboBox class manages the display and interaction of user combo boxes.



Description

The ComboBox class is used to create combo boxes, also known as 'drop-down menus' in application interfaces. A combo box typically looks like a text entry area, but features a button positioned to the right-hand side of the gadget. Clicking on the button will pop-up a menu that the user can use to select a pre-defined menu item. Clicking on one of those items will paste the item text into the combo box.

Definitions for the combobox are loaded by default from the environment file "templates:comboboxdef.xml". You can change the template file prior to initialisation by setting the Template field. Note that the values set in the template will override the original field settings for the combobox.

The most important feature of the combobox is the drop-down menu. The combobox uses the Menu class to support its menu construction. To add items to the drop-down menu, you need to pass instructions to it using XML. You can find out more about this XML specification in the documentation for the Menu class. The following example illustrates the simplest way to create a combobox with a pre-defined set of items:

  <combobox label="Options:" x="[owner.leftmargin]" y="[owner.topmargin]"
    width="200">
    <xml>
      <item text="Tamarillo"/">
      <item text="Kumquat"/">
      <item text="Mango"/">
    </xml>
  </combobox>

When the user selects a combobox item, you may need to respond with an action. You can do this by initialising child objects to the combobox. These will be executed when the combobox is activated. You can also set the ActionScript field to run a script on activation. When programming, you can also subscribe to the combobox's Activate action and write a customised response routine.

Actions

The ComboBox class supports the following actions:

Activate  Activates the combobox object's response mechanism.
Disable  Turns the combobox off.
Enable  Turns the combobox back on if it has previously been disabled.
Focus  Sets the focus on the combobox.
Hide  Removes the combobox from the display.
MoveToBack  Moves the combobox to the back of the display area.
MoveToFront  Moves the combobox to the front of the display area.
Redimension  Changes the size and position of the combobox.
Resize  Alters the size of the combobox.
SetUnlistedField  Arguments can be passed through to the combobox menu via unlisted fields.
Show  Puts the combobox on display.

Structure

The ComboBox object consists of the following public fields:

ActionScript  Script to be executed when the combobox is clicked.
Border  String-based field for setting a single-colour border for the combobox.
Bottom  The bottom coordinate of the combobox.
ButtonOffset  Defines the button's pixel offset against the combobox borders.
Colour  String-based field for setting the colour inside of the combobox.
ColourRGB  Defines the internal colour of the combobox in RGB format.
Disable  Disables the combobox on initalisation.
Drawable  The drawable that will contain the combobox graphic.
Flags  Optional flags may be set here.
FocusActivate  If TRUE, activation occurs when the user leaves the combobox area.
FocusFrame  The graphics frame to display when the combobox has the focus.
Height  Defines the height of a combobox.
Highlight  String-based field for setting the border highlight.
HighlightRGB  Defines border highlight of the combobox, in RGB format.
Label  The label is a string displayed to the left of the combobox area.
LabelWidth  A set-width for the label area of the combobox may be defined here.
Menu  Provides direct access to the drop-down menu.
Region  The drawable that represents the combobox is referenced through this field.
ReleaseFrame  The graphics frame to display when the combobox loses the focus.
Right  The right-most coordinate of the combobox.
Shadow  String-based field for setting the combobox shadow.
ShadowRGB  Defines the border shadow of the combobox, in RGB format.
String  The string that is to be printed inside the combobox is declared here.
TabFocus  Set this field to a TabFocus object to register the combobox in a tab-list.
Template  Defines the makeup of the combobox using a pre-defined template.
Thickness  The thickness of the combobox border.
Width  Defines the width of a combobox.
XCoord  The horizontal position of a combobox.
XOffset  The horizontal offset of a combobox.
YCoord  The vertical position of a combobox.
YOffset  The vertical offset of a combobox.
Field:ActionScript
Short:Script to be executed when the combobox is clicked.
Type:STRING
Status:Get/Set

When a combobox 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:Border
Short:String-based field for setting a single-colour border for the combobox.
Type:STRING
Status:Set

The border colour for a combo 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.


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

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


Field:ButtonOffset
Short:Defines the button's pixel offset against the combobox borders.
Type:LONG
Status:Read/Init

The positioning of the combobox button can be altered by setting a value in this field. Normally the button is offset from the combobox border by 1 pixel, but depending on the combobox graphical setup, you may wish to change this to a value of 0 or 2 for improved aesthetics.


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

The colour inside of a combobox 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 combobox in RGB format.
Type:RGB
Status:Read

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


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

The combobox 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 combobox graphic.
Type:OBJECTID
Status:Read/Init

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


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

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

FlagDescription
AUTOCOMPLETEThis option will assist the user when the combobox is in EDIT mode. The combobox will attempt to help the user by automatically completing text as it is typed into the box.
DISABLEDThis readable flag is automatically set when the combobox is disabled. You may set it on initialisation if the combobox is to be disabled on creation.
EDITIf you put the combobox into EDIT mode, the user will be able to type customised text into the combobox text area.
FOCUSACTIVATEWhen in EDIT mode, if the combobox 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 combobox on its creation (applies to script usage only).
LIMITTOLISTIf the combobox is in EDIT mode, the user will be able to type customised text data by default. If you would prefer that the text is limited to that provided the combobox list, set this flag.
LOCALBy default, the combobox will send messages to its child objects when the combobox value changes. If you set the LOCAL option, the combobox will execute the objects within its own process space.

Field:FocusActivate
Short:If TRUE, activation occurs when the user leaves the combobox area.
Type:LONG
Status:Read/Init

If this field is set to TRUE, the combobox will automatically activate itself if the user enters the combobox area and then leaves. The activation will occur regardless of wether or not the user edited the content of the combobox. 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 combobox has the focus.
Type:LONG
Status:Read/Write

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


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

An combobox 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 a combobox 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 combobox, in RGB format.
Type:RGB
Status:Read

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


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

A label can be drawn next to the combobox 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:A set-width for the label area of the combobox may be defined here.
Type:LONG
Status:Read/Init

If you set a label for the combobox, the width of the label area is automatically calculated according to the width of the label string. You may override this behaviour by setting a value in the LabelWidth field.


Field:Menu
Short:Provides direct access to the drop-down menu.
Type:OBJECTPTR
Status:Read

The drop-down menu that is used for the combobox can be accessed directly through this field. You may find this useful for manipulating the content of the drop-down menu following initialisation of the combobox.


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

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


Field:ReleaseFrame
Short:The graphics frame to display when the combobox 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 combobox.
Type:LONG
Status:Get

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


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

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

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


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

The string that you would like to be displayed in the combobox 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 combobox.

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


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

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

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

<?xml version="1.0"?>

<values>
  <thickness value="2"/>
</values>

<graphics>
  <box colour="#000000" opacity="50%" x="[{scriptowner}.labelwidth]"/>
  <box border="#ffffff" opacity="50%" x="[{scriptowner}.labelwidth]"/>

  <render xoffset="1" y="1" yoffset="1" width="=[{owner}.height]-2" region>
    <box colour="#a0a0a0" opacity="45%"/>
    <arrow align="center" direction="down" arrowwidth="11" arrowheight="6" colour="#909090"/>
    <onclick>
      <set object="[{scriptowner}]" &button="[owner]"/>
    </onclick>
  </render>
</graphics>

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

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


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

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

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


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

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