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