Packageardisia.components.timePicker
Classpublic class TimePicker
InheritanceTimePicker Inheritance spark.components.ComboBox

Component designed to help users select a time, specific to the minute.

View the technical documentation on the Ardisia Labs website for more information.

Default MXML PropertydataProvider



Public Properties
 PropertyDefined By
  defaultDropDownTime : Number
When the user opens the drop down and the "selectedMinutes" property is not set, this is the default time to center in the drop down and hint too, but not select.
TimePicker
  openOnFocus : Boolean = true
Whether the drop down will open on focus.
TimePicker
  requireSelection : Boolean
[override] Whether the field must have a selectionMinutes value that is not -1; NO_SELECTION is not allowed.
TimePicker
  selectedMinutes : int
The user selected value in minutes.
TimePicker
  snapInterval : int
Sets the intervals, in minutes, displayed in the drop down.
TimePicker
  validationErrorMessage : String = Not a recognized time. Examples: 7p, 7pm, 7:00pm, 700p, 19:00p, 19PM etc.
The error message to display when the user entered string fails validation and could not be converted to a valid minutes value.
TimePicker
Public Methods
 MethodDefined By
  
dispose():void
Removes the control from the display list, removes event listeners, stops timers, and attempts to clear out references to ready the component for garbage collection.
TimePicker
  
setText(value:String):void
Update the text input skin part.
TimePicker
  
validate():Boolean
Determines if the selectedItem makes sense, E.G.
TimePicker
Protected Methods
 MethodDefined By
  
Initialize the collection.
TimePicker
  
convertMinutesToString(totalMinutes:Number):String
Converts passed minutes value into a human readable time string.
TimePicker
  
convertStringToMinutes(timeString:String):Number
Converts a user entered string to numerical value of minutes.
TimePicker
  
eventHandler(event:Event):void
Handles events on the TimePicker.
TimePicker
  
getClosestIndex(minutes:Number):int
Returns the index of the element in the collection with the closest minutes value relative to the passed value.
TimePicker
  
getMinutesIndex(minutes:Number):int
Returns the index of the element in the collection with a "minutes" property that is equal to the passed value.
TimePicker
  
handleKeyboardNavigation(event:KeyboardEvent):void
Handles the navigation cursor keys, and moves the proposed selected index to indices relative to the hinted index so behavior will match what users will expect from keyboard navigation.
TimePicker
  
Centers the provided index in the drop down and hints at it.
TimePicker
  
setCustomSelectedItem(minutes:int):void
Sets the "text" property on the textInput skin part.
TimePicker
  
Centers the defaultDropDownIndex in the dropDown and hints at it.
TimePicker
  
setHintedIndex(index:int):void
Sets the hinted index on the appropriate element.
TimePicker
  
setSelectedMinutes(value:Number):void
Updates the "selectedMinutes" property without invalidating properties.
TimePicker
  
setSelectedValueIndex(value:int):void
Sets the selectedIndex to the passed value.
TimePicker
  
textInput_changeHandler(event:TextOperationEvent):void
[override] Handles changes to the textInput skin part's text property.
TimePicker
  
textInputHandler(event:Event):void
Handles events on the text input skin part.
TimePicker
  
timePickerItemMatchingFunction(comboBox:ComboBox, inputText:String):Vector.<int>
Function used to match elements in the collection by examining the user entered string.
TimePicker
  
timePickerLabelFunction(item:Object):String
Function used to parse a label from the elements in the collection.
TimePicker
  
timePickerLabelToItemFunction(value:String):Object
Function used to parse a new custom TimePickerData object from a user entered string.
TimePicker
Property Detail
defaultDropDownTimeproperty
defaultDropDownTime:Number

When the user opens the drop down and the "selectedMinutes" property is not set, this is the default time to center in the drop down and hint too, but not select.

The default value is 480 (8 am).


Implementation
    public function get defaultDropDownTime():Number
    public function set defaultDropDownTime(value:Number):void
openOnFocusproperty 
public var openOnFocus:Boolean = true

Whether the drop down will open on focus.

The default value is true.

requireSelectionproperty 
requireSelection:Boolean[override]

Whether the field must have a selectionMinutes value that is not -1;

NO_SELECTION is not allowed. A value of 0 will be used instead.

The default value is false.


Implementation
    public function get requireSelection():Boolean
    public function set requireSelection(value:Boolean):void
selectedMinutesproperty 
selectedMinutes:int

The user selected value in minutes. A value of -1 means no selection.

This property is bindable and bound to 'valueCommit' events.

The default value is -1.

This property can be used as the source for data binding.


Implementation
    public function get selectedMinutes():int
    public function set selectedMinutes(value:int):void
snapIntervalproperty 
snapInterval:int

Sets the intervals, in minutes, displayed in the drop down. E.G. a value of 30 indicates that the drop down will display times each 30 minutes: 7:00am, 7:30am, 8:00am, 8:30am., etc.

The default value is 30.


Implementation
    public function get snapInterval():int
    public function set snapInterval(value:int):void
validationErrorMessageproperty 
public var validationErrorMessage:String = Not a recognized time. Examples: 7p, 7pm, 7:00pm, 700p, 19:00p, 19PM etc.

The error message to display when the user entered string fails validation and could not be converted to a valid minutes value.

The default value is "Not a recognized time. Examples: 7p, 7pm, 7:00pm, 700p, 19p, etc.".

Method Detail
buildCollection()method
protected function buildCollection():void

Initialize the collection. Rebuilds each time the snapInterval is changed.

convertMinutesToString()method 
protected function convertMinutesToString(totalMinutes:Number):String

Converts passed minutes value into a human readable time string.

Parameters

totalMinutes:Number — the Number of minutes to parse into a string

Returns
String — parsed String
convertStringToMinutes()method 
protected function convertStringToMinutes(timeString:String):Number

Converts a user entered string to numerical value of minutes. Override this method to change the format of the time string.

Parameters

timeString:String — the user entered string

Returns
Number — a Number representing the number of minutes parsed from the string
dispose()method 
public function dispose():void

Removes the control from the display list, removes event listeners, stops timers, and attempts to clear out references to ready the component for garbage collection.

Call when you no longer want to simply hide the component and want it removed and eligible for GC.

eventHandler()method 
protected function eventHandler(event:Event):void

Handles events on the TimePicker. When the opening the drop down, center and hint the selectedIndex or the defaultDropDown index. Param event the Event that triggered the handler

Parameters

event:Event

getClosestIndex()method 
protected function getClosestIndex(minutes:Number):int

Returns the index of the element in the collection with the closest minutes value relative to the passed value.

Parameters

minutes:Number — the value to find the closest index for

Returns
int — the index of the closest value in the collection, may be an exact match
getMinutesIndex()method 
protected function getMinutesIndex(minutes:Number):int

Returns the index of the element in the collection with a "minutes" property that is equal to the passed value. Returns -1 if not found.

Parameters

minutes:Number — the value to find the closest index for

Returns
int — the index of the matched value in the collection
handleKeyboardNavigation()method 
protected function handleKeyboardNavigation(event:KeyboardEvent):void

Handles the navigation cursor keys, and moves the proposed selected index to indices relative to the hinted index so behavior will match what users will expect from keyboard navigation.

Parameters

event:KeyboardEvent — the KeyboardEvent passed from the event handler

setCenteredVerticalScrollPosition()method 
protected function setCenteredVerticalScrollPosition(index:int):void

Centers the provided index in the drop down and hints at it. Only works for VerticalLayout.

Parameters

index:int — the int of the index to center

setCustomSelectedItem()method 
protected function setCustomSelectedItem(minutes:int):void

Sets the "text" property on the textInput skin part.

Parameters

minutes:int

setDefaultDropDownIndex()method 
protected function setDefaultDropDownIndex():void

Centers the defaultDropDownIndex in the dropDown and hints at it.

setHintedIndex()method 
protected function setHintedIndex(index:int):void

Sets the hinted index on the appropriate element.

Parameters

index:int — the int index of the renderer to set isHinted to true

setSelectedMinutes()method 
protected function setSelectedMinutes(value:Number):void

Updates the "selectedMinutes" property without invalidating properties.

Parameters

value:Number — the number to update the "selectedMinutes" property to

setSelectedValueIndex()method 
protected function setSelectedValueIndex(value:int):void

Sets the selectedIndex to the passed value.

Parameters

value:int — the int to set the selectedIndex to.

setText()method 
public function setText(value:String):void

Update the text input skin part.

Parameters

value:String — String

textInput_changeHandler()method 
override protected function textInput_changeHandler(event:TextOperationEvent):void

Handles changes to the textInput skin part's text property.

Overridden to detect when the string is null, to reset the hintedIndex.

Parameters

event:TextOperationEvent — the TextOperationEvent that triggered the handler

textInputHandler()method 
protected function textInputHandler(event:Event):void

Handles events on the text input skin part.

Parameters

event:Event — the Event that triggered the handler

timePickerItemMatchingFunction()method 
protected function timePickerItemMatchingFunction(comboBox:ComboBox, inputText:String):Vector.<int>

Function used to match elements in the collection by examining the user entered string.

The TimePicker never selects matched elements. Instead, this class will hint the closest marched index and center it in the drop down. This matches user expected behaviour.

Parameters

comboBox:ComboBox — the ComboBox to match
 
inputText:String — the String to match with elements in the collection

Returns
Vector.<int> — a vector of indexes
timePickerLabelFunction()method 
protected function timePickerLabelFunction(item:Object):String

Function used to parse a label from the elements in the collection.

The renderer in the default skin, doesn't use this method.

Parameters

item:Object — the Object to parse

Returns
String
timePickerLabelToItemFunction()method 
protected function timePickerLabelToItemFunction(value:String):Object

Function used to parse a new custom TimePickerData object from a user entered string.

Parameters

value:String — the String to use to create a new TimePickerData object

Returns
Object
validate()method 
public function validate():Boolean

Determines if the selectedItem makes sense, E.G. can be converted to a valid minutes quantity, and clears the error string..

Returns
Boolean — a Boolean of success or failure