XPComponents: class xp.controls.ComboBox

Main Page | Packages | Class Tree | Index | Help

Previous \| Next	Frames \| No Frames
Summary: Field \| Property \| Contructor \| Method	Detail: Field \| Property \| Contructor \| Method

xp.controls

class ComboBox

MovieClip
  |
  +--xp.system.UIControl
        |
        +--xp.controls.TextBase
              |
              +--xp.controls.Label
                    |
                    +--xp.controls.ComboBox

class ComboBox
extends Label

Allows users to select one option from a scrolling list of choices. This component can have an selectable text field at the top of the list that allows users to search the list

A combo box allows a user to make a single selection from a drop-down list. If the drop-down list hits the bottom of the document, it opens up instead of down. The combo box is composed of three subcomponents: a Button component, a Label component, and a ListBox component.

When a selection is made in the list, the label of the selection is copied to the text field at the top of the combo box. It doesn’t matter if the selection is made with the mouse or the keyboard.

A ComboBox component receives focus if you click the label or the button

Key	Description
Shift+Tab	Moves focus to the previous object.
Tab	Moves focus to the next object.
Control+Down Arrow	Opens the drop-down list and gives it focus
Control+Up Arrow	Closes the drop-down list
Down Arrow	Moves the selection down one item.
End	Selection moves to the bottom of the list.
Escape	Closes the drop-down list and returns focus to the combo box.
Enter	Closes the drop-down list and returns focus to the combo box.
Home	Moves the selection to the top of the list.
Page Down	Moves the selection down one page.
Page Up	Moves the selection up one page.
Shift+Tab	Moves focus to the previous object.
Tab	Moves focus to the next object.

Event summary for the ComboBox class
The following table lists events of the ComboBox class.

Event	Type	Description
xp.events.Event	change	Broadcast whenever user interaction causes the selection to change.
xp.events.ValueChangedEvent	valueChanged	Broadcast whenever user interaction causes the selection value to change.
xp.events.ItemRollOverEvent	itemRollOver	Broadcast when the pointer rolls over list items.
xp.events.ItemRollOutEvent	itemRollOut	Broadcast when the pointer rolls over and then off of list items.
xp.events.Event	close	Broadcast when the drop down closes.
xp.events.Event	open	Broadcast when the drop down open.

Author:: ProWin Computers Ltd. - Rob Edgar

Version:: 3.0.0.000

See also:: support@epresenterplus.com

Field Summary

public

autoSync: Boolean

Controls whether the selectedIndex of the control and the dataProvider are automatically kept in sync

public

canSelectWhileClosed: Boolean

Can items be selected while the dropdown is closed

public static

classInfo: Object

A static class information object

public

disableAcceptButton: Boolean

Disables the global accept button whilst this control has focus

public

disableCancelButton: Boolean

Disables the global cancel button whilst this control has focus

public

displayBindings: Object

A binding definition for the combobox display

public

displayIconFormatFunction: Object

The format function object for the display icon field

public

displayIconFormatter: Object

The formatter object for the display icon field

public

displayIconFormatterOptions: Object

The formatter options object for the display icon field

public

displayIconPath: String

The path or fieldName of the display icon field

public

displayLabelFormatFunction: Object

The format function object for the display label field

public

displayLabelFormatter: Object

The formatter object for the display label field

public

displayLabelFormatterOptions: Object

The formatter options object for the display label field

public

displayLabelPath: String

The path or fieldName of the display label field

public

iconFormatFunction: Object

The format function object for the icon field

public

iconFormatter: Object

The formatter object for the icon field

public

iconPath: String

The path or field of the icon field

public

initialMsg: String

Get or set the initial message displayed when there is no seleected item.

public

itemBindings: Object

The DataBinding for the listItems

public

keySearch: String

Controls the type of key search support enabled.

public

keySearchPath: String

The data path in the item to the search key value

public

labelFormatFunction: Object

The format function object for the label field

public

labelFormatter: Object

The formatter object for the label field

public

labelPath: String

The path or fieldName of the label field

public

listData: Array

Authoring Parameter - Data for List Items (optional)

public

listIcons: Array

Authoring Parameter - Icons for List Items (optional)

public

listLabels: Array

Authoring Parameter - Labels for List Items (optional)

public

raiseCommitOnClose: Boolean

Controls when the change event will be sent in response to selection changes

public

selectedValueBinding: Object

The DataBinding for the selected item

public

selectedValueFormatFunction: Object

The format function object for the value field

public

selectedValueFormatter: Object

The formatter object for the value field

public

selectedValuePath: String

The data path in the selected Item to the value

public

showSearchSelection: Boolean

Controls whether the current search is show by selecting the text in the control

public

styleClass: String

The name of the style class this instance will use.

public

tabStop: Boolean

ComboBox's are by default a tabStop

public

virtualMode: Boolean

Get or set the virtual mode

Fields inherited from class xp.controls.Label

classInfo, styleClass

Fields inherited from class xp.controls.TextBase

leading, leftMargin, rightMargin, textIndent

Fields inherited from class xp.system.UIControl

__layout, allowDrop, autoLayout, bindingDefaultValue, bindingFormatter, bindingPath, bindingSource, bindingType, bindingValidator, border, causesValidation, classInfo, clickOnENTER, clickOnSPACE, container, context, data, disableAcceptButton, disableCancelButton, enableBGMouseEvents, enableDblClickEvent, enableKeyDownEvents, enableKeyEvents, enableKeyUpEvents, enableMouseWheelEvents, formatterOptions, horizontalAlignment, index, isBinding, itemId, logEnabled, parent, parentContainer, parentForm, percentageHeight, percentageWidth, styleClass, tabIndex, tabStop, tooltip, tree, verticalAlignment

Property Summary

public

dataProvider: Object (read, write)

Gets or set the dataProvider

public

dropdownWidth: Number (read, write)

Gets or set the width of the drop down list

public

editable: Boolean (read, write)

Indicates whether the combo box is editable (true) or not (false).

public

itemsSource: ListDataSource (read, write)

Gets or set the ListDataSource

public

itemStyle (read, write)

The list item style

public

length: Number (read-only)

Number of items in the dataProvider.

public

restrict: String (read, write)

public

rowCount: Number (read, write)

Gets or set the number of visble rows in the drop down list

public

rowHeight: Number (read, write)

The default pixel height of rows in the list.

public

selectedIndex: Number (read, write)

The index of a selection in a single-selection list.

public

selectedItem: Object (read, write)

The selected item in a single-selection list.

public

selectedValue: Object (read, write)

The value from the currently selected item

public

value: Object (read, write)

If the combo box is editable, value returns the value of the text box.

Properties inherited from class xp.controls.Label

autoEllipsis, hAnchorPoint, html, icon, iconIndex, styleSheet, vAnchorPoint

Properties inherited from class xp.controls.TextBase

font, fontBold, fontColor, fontEmbed, fontFamily, fontItalic, fontName, fontSize, fontStyle, fontUnderline, fontWeight, text, textAlign, textDecoration, textWrap

Properties inherited from class xp.system.UIControl

alpha, autosize, background, backgroundVisible, bindings, borderBrush, borderRadius, borderShadow, borderStyle, borderThickness, bottom, dataSource, enableMouseEvents, focusManager, height, id, isEnabled, isFocused, isMouseOver, isPressed, isSelected, isValid, layout, left, margin, maxHeight, maxWidth, measuredHeight, measuredMinHeight, measuredMinWidth, measuredWidth, minHeight, minWidth, padding, readOnly, resources, right, styleName, top, triggers, visible, width, x, y

Constructor

public

ComboBox ( )

Constructor - This should not be called directly.

Method Summary

public

clearSelected ( ): Void

Clears all selected indices

public

close ( refocus: Boolean ): Void

Closes the drop down list

public

drawComponent ( ): Void

layout combo

public

getClass ( ): Function

Returns a reference to the components static class

public

getItemAt ( index )

given an index find the item from the source

public

getItemIndex ( item: Object )

given an item find its index

public

getItemsArray ( labels: Array, icons: Array, data: Array ): Array

Gets the items array from 3 native type arrays

public

getItemValue ( v ): Object

given an item find its value

public

getValueIndex ( value: Object )

given a value find its index

public static

newInstance ( owner, instanceId, depth, initObj )

Creates a new Instance of this class

public

onEnabledChanged ( state: Boolean ): Void

Override to sync the button and the internal textField enabled state

public

open ( ): Void

Open the drop down list

public

toggleList ( ): Void

Toggles the display of the drop down

Methods inherited from class xp.controls.Label

drawComponent, getClass, newInstance

Methods inherited from class xp.controls.TextBase

getTextEllipsis, getTextExtent

Methods inherited from class xp.system.UIControl

addBinding, addBindings, addEventListener, addPropertyTrigger, applyStyle, beginDeferUpdate, canUpdate, centerContent, checkState, containsFocus, destroy, destroyObject, drawFocus, endDeferUpdate, findFocusFromObject, findFocusInChildren, getBinding, getBounds, getCenter, getClass, getFocus, getFocusManager, getFocusRect, getLocation, getPropertyValue, getSize, getStateName, getTrigger, globalToLocalPoint, invalidate, invalidateLayout, invalidateSize, invalidateSizeAndLayout, invalidChild, isChild, isMouseDirectlyOver, isParent, localToGlobalPoint, localToLocalPoint, measure, mouseWheel, move, onChildFocus, onKillFocus, onSetFocus, processEnterKey, processEscapeKey, processTabKey, redraw, refresh, removeEventListener, routeEvent, setBounds, setFocus, setLocation, setPropertyValue, setSize, setValueChanged, update, validate

Field Documentation

autoSync

public var autoSync: Boolean

Controls whether the selectedIndex of the control and the dataProvider are automatically kept in sync

canSelectWhileClosed

public var canSelectWhileClosed: Boolean

Can items be selected while the dropdown is closed

If true then whilst the combo has focus and is closed the keyboard can be used to navigate the items.

classInfo

public static var classInfo: Object

A static class information object

Every class has an associated classInfo object that holds the version and other static information. The classInfo can be accessed either directly by referencing the static class or by calling getClass() on any class instance.

disableAcceptButton

public var disableAcceptButton: Boolean

Disables the global accept button whilst this control has focus

disableCancelButton

public var disableCancelButton: Boolean

Disables the global cancel button whilst this control has focus

displayBindings

public var displayBindings: Object

A binding definition for the combobox display

displayIconFormatFunction

public var displayIconFormatFunction: Object

The format function object for the display icon field

displayIconFormatter

public var displayIconFormatter: Object

The formatter object for the display icon field

displayIconFormatterOptions

public var displayIconFormatterOptions: Object

The formatter options object for the display icon field

displayIconPath

public var displayIconPath: String

The path or fieldName of the display icon field

displayLabelFormatFunction

public var displayLabelFormatFunction: Object

The format function object for the display label field

displayLabelFormatter

public var displayLabelFormatter: Object

The formatter object for the display label field

displayLabelFormatterOptions

public var displayLabelFormatterOptions: Object

The formatter options object for the display label field

displayLabelPath

public var displayLabelPath: String

The path or fieldName of the display label field

iconFormatFunction

public var iconFormatFunction: Object

The format function object for the icon field

iconFormatter

public var iconFormatter: Object

The formatter object for the icon field

iconPath

public var iconPath: String

The path or field of the icon field

initialMsg

public var initialMsg: String

Get or set the initial message displayed when there is no seleected item.

itemBindings

public var itemBindings: Object

The DataBinding for the listItems

keySearch

public var keySearch: String

Controls the type of key search support enabled.

Controls whether items are searched for when keys are pressed.
When enabled search is based on a match between the search expression and the list items display label. Searching is case insensitive
Can be one of the following modes:
none: No key search support
first: Searching is based on a match of the last key pressed and the first letter of the list item display label incremental: Each character of the search expression that you enter causes the list to search for the first occurrence of the string that it has so far been given.
If there is no match the current search expression is cleared

keySearchPath

public var keySearchPath: String

The data path in the item to the search key value

If not specified defaults to the lable path

labelFormatFunction

public var labelFormatFunction: Object

The format function object for the label field

labelFormatter

public var labelFormatter: Object

The formatter object for the label field

labelPath

public var labelPath: String

The path or fieldName of the label field

listData

public var listData: Array

Authoring Parameter - Data for List Items (optional)

An array that specifies the data associated with the list items. The default value is [] (an empty array).

listIcons

public var listIcons: Array

Authoring Parameter - Icons for List Items (optional)

An array that specifies the linkage identifiers of the library symbols to be used as the icons in the list. The default value is [] (an empty array).

listLabels

public var listLabels: Array

Authoring Parameter - Labels for List Items (optional)

An array that specifies the text labels to use in the list. The default value is [] (an empty array).

raiseCommitOnClose

public var raiseCommitOnClose: Boolean

Controls when the change event will be sent in response to selection changes

If true then the change event will only fire when the dropdown close.

selectedValueBinding

public var selectedValueBinding: Object

The DataBinding for the selected item

selectedValueFormatFunction

public var selectedValueFormatFunction: Object

The format function object for the value field

selectedValueFormatter

public var selectedValueFormatter: Object

The formatter object for the value field

selectedValuePath

public var selectedValuePath: String

The data path in the selected Item to the value

showSearchSelection

public var showSearchSelection: Boolean

Controls whether the current search is show by selecting the text in the control

styleClass

public var styleClass: String

The name of the style class this instance will use.

tabStop

public var tabStop: Boolean

ComboBox's are by default a tabStop

virtualMode

public var virtualMode: Boolean

Get or set the virtual mode

When in virtualMode a small pool of virtual rows are reused as needed to fill the display area.

Property Documentation

dataProvider

public dataProvider

: Object (read, write)

Gets or set the dataProvider

An array of items, a reference or an itemsSource. When this property is set, if a reference it is resolved, if an array the array is wrapped in a ListDataSource

dropdownWidth

public dropdownWidth

: Number (read, write)

Gets or set the width of the drop down list

If set to 0 the width is automatically calculated as the width of the widest item in the list.

editable

public editable

: Boolean (read, write)

Indicates whether the combo box is editable (true) or not (false).

In an editable combo box, a user can enter values into the text box that do not appear in the drop-down list. If a combo box is not editable, you cannot enter text into the text box. The text box displays the text of the item in the list. The default value is false.

itemsSource

public itemsSource

: ListDataSource (read, write)

Gets or set the ListDataSource

The itemsSource is the model for items viewed in a list. The data source wraps an array object. This can be an array of objects or XMLNodes.

itemStyle

public itemStyle

(read, write)

The list item style

The itemStyle controls all properties of an item both its visual properties and its data binding properties.

length

public length

: Number (read-only)

Number of items in the dataProvider.

restrict

public restrict

: String (read, write)

rowCount

public rowCount

: Number (read, write)

Gets or set the number of visble rows in the drop down list

rowHeight

public rowHeight

: Number (read, write)

The default pixel height of rows in the list.

The default height, in pixels, of rows in the list. The font settings do not make the rows grow to fit, so setting the rowHeight property is the best way to make sure items are fully displayed. The default value is 20.

selectedIndex

public selectedIndex

: Number (read, write)

The index of a selection in a single-selection list.

the selected index of a single-selection list. The value is undefined if nothing is selected; the value is equal to the last item selected if there are multiple selections. If you assign a value to selectedIndex, any current selection is cleared and the indicated item is selected

selectedItem

public selectedItem

: Object (read, write)

The selected item in a single-selection list.

An item object in a single-selection list. (In a multiple-selection list with multiple items selected, selectedItem returns the item that was most recently selected.) If there is no selection, the value is undefined.

selectedValue

public selectedValue

: Object (read, write)

The value from the currently selected item

An value object in a single-selection list. (In a multiple-selection list with multiple items selected, selectedValue returns the value that was most recently selected.) If there is no selection, the value is undefined.

value

public value

: Object (read, write)

If the combo box is editable, value returns the value of the text box.

If the combo box is static, value returns the value of the drop-down list. The value of the drop-down list is the selectedValue.

Constructor Documentation

ComboBox

public function ComboBox

()

Constructor - This should not be called directly.

If you want to dynamically create a new instance of a control use its static newInstance method

Method Documentation

clearSelected

public function clearSelected

(): Void

Clears all selected indices

close

public function close

(refocus: Boolean): Void

Closes the drop down list

Forces the drop down to close and become invisible.
Note: The drop down still exists and can be referenced.

drawComponent

public function drawComponent

(): Void

layout combo

Overrides:: Label.drawComponent in class Label

getClass

public function getClass

(): Function

Returns a reference to the components static class

Overrides:: Label.getClass in class Label

getItemAt

public function getItemAt

(index)

given an index find the item from the source

getItemIndex

public function getItemIndex

(item: Object)

given an item find its index

getItemsArray

public function getItemsArray

(labels: Array,
icons: Array,
data: Array): Array

Gets the items array from 3 native type arrays

Builds an object array from array of native types (string or number or boolean types)

getItemValue

public function getItemValue

(v): Object

given an item find its value

getValueIndex

public function getValueIndex

(value: Object)

given a value find its index

newInstance

public static function newInstance

(owner,
instanceId,
depth,
initObj)

Creates a new Instance of this class

Creates an instance of a component at runtime. You need to use the import statement and specify the class package name before calling this method. In addition, the component must be in the FLA file’s library.

Overrides:: Label.newInstance in class Label

Parameters:

owner		A reference to the movie clip or object that will contains the new Instance.
instanceId		A string indicating the instance name of the new instance.(optional)
depth		A number indicating the depth of the new instance.(optional)
initObj		An object containing initialization properties for the new instance.(optional)

Returns:: A object that is an instance of the specified class.

onEnabledChanged

public function onEnabledChanged

(state: Boolean): Void

Override to sync the button and the internal textField enabled state

Component developers should override this if they want to process a change to the enabled state instead of overriding the getter/setter

Overrides:: xp.system.UIControl.onEnabledChanged in class xp.system.UIControl

Parameters:

state

The new enabled state.

open

public function open

(): Void

Open the drop down list

Forces the drop down to open and become visible.
The position of the drop down will be automaticialy adjusted to take account of the stage size.

toggleList

public function toggleList

(): Void

Toggles the display of the drop down

If open when this method is called the drop down will close, if closed when this method is called then the drop down will open.

The documentation was generated from the following file:

ComboBox.as, Last Modified: 10/29/2005 10:49:26 PM

Previous \| Next	Frames \| No Frames
Summary: Field \| Property \| Contructor \| Method	Detail: Field \| Property \| Contructor \| Method