qnx.fuse.ui.buttons.SegmentedControl

SegmentedControl

Properties | Methods | Events | Examples


Packageqnx.fuse.ui.buttons
Classpublic class SegmentedControl
InheritanceSegmentedControl Inheritance UIComponent Inheritance flash.display.MovieClip
Implements IDataViewer

A segmented control is a series of connected radio buttons that enable the user to select a single item from a list of multiple items. The following figure shows a SegmentedControl instance with three buttons:

A segmented control.

You can skin the SegmentedControl component by defining the background skin and the button skins for the segmented control.



Class information:
PlayBook Tablet OS Version:   1.0.6

View the examples

See also

Button
RadioButton



Public Properties

 PropertyDefined By
  dataProvider : IDataProvider
Gets or sets the DataProvider object used by the segmented control.
SegmentedControl
 InheritedexplicitHeight : Number
[read-only] Returns the explicit height (actual height, in pixels) of the UI component.
UIComponent
 InheritedexplicitWidth : Number
[read-only] Returns the explicit width (actual width, in pixels) of the UI component.
UIComponent
 InheritedincludeInLayout : Boolean
Specifies whether or not the component should be included in its parent container's layout.
UIComponent
 InheritedlayoutData : Object
Returns the layout data for the object.
UIComponent
 InheritedminHeight : Number
Gets or sets the minimum preferred height of the control.
UIComponent
 InheritedminWidth : Number
Gets or sets the minimum preferred width of the control.
UIComponent
  selectedIndex : int
Gets or sets the currently selected index.
SegmentedControl
  selectedItem : Object
Gets or sets the currently selected item.
SegmentedControl

Public Methods

 MethodDefined By
  
Creates a new SegmentedControl instance.
SegmentedControl
  
addItem(item:Object):void
Appends an item to the DataProvider.
SegmentedControl
  
addItemAt(item:Object, index:int):void
Adds an item to the DataProvider at a given index.
SegmentedControl
  
addItemsAt(items:Array, index:int):void
Adds items in the DataProvider at a given index, given an Array of items.
SegmentedControl
 Inherited
childChanged(resizedChild:DisplayObject = null):Boolean
Notifies the UIComponent that one or more of its children has changed in a manner that may affect this object's layout.
UIComponent
 Inherited
destroy():void
Call this method when you want to have your object collected by the garbage collector.
UIComponent
  
getItemAt(index:int):Object
Gets the data object from the DataProvider at a given index.
SegmentedControl
 Inherited
Returns the size options for the given control.
UIComponent
  
getTextFormatForState(state:String):TextFormat
Returns the TextFormat object for a specified state.
SegmentedControl
 Inherited
Calling this method results in a call to the components validateDisplayList() method before the display list is rendered.
UIComponent
 Inherited
Calling this method results in a call to the components validateProperties() method before the display list is rendered.
UIComponent
 Inherited
measure(availableWidth:Number, availableHeight:Number):LayoutMeasurement
This method calls doMeasure() in order to calculate the preferred size of the control.
UIComponent
  
removeAll():void
Removes all items from the DataProvider.
SegmentedControl
  
removeItem(item:Object):void
Removes an item from the DataProvider.
SegmentedControl
  
removeItemAt(index:int):void
Removes an item from the DataProvider at a given index.
SegmentedControl
  
replaceItem(newObject:Object, oldObject:Object):void
Replaces an item with a new item.
SegmentedControl
  
replaceItemAt(item:Object, index:int):void
Replaces the data at a given index.
SegmentedControl
 Inherited
setActualSize(w:Number, h:Number):void
Sets the width and height of the object without setting the explicitWidth and explicitHeight.
UIComponent
  
setBackgroundSkin(skin:Object):void
Sets the background skin for the segmented control, given a DisplayObject object to represent the background skin.
SegmentedControl
  
setButtonSkin(skin:Object):void
Sets the button skin for the buttons in the segmented control.
SegmentedControl
  
setButtonWidthAtIndex(buttonWidth:int = 100, index:int = 0):void
Sets the button width of an item at the specified index.
SegmentedControl
 Inherited
setLayoutBounds(bounds:Rectangle):void
Sets the receiver's size and location to the rectangular area specified by the arguments.
UIComponent
 Inherited
setPosition(x:Number, y:Number):void
Sets the x and y position of the component.
UIComponent
  
setSelectionSkin(skin:Object):void
Sets the selection indicator skin for the segmented control, given a DisplayObject object to represent the selection indicator skin.
SegmentedControl
  
setTextFormatForState(format:TextFormat, state:String):void
Sets the TextFormat object for the label for a given state.
SegmentedControl
  
updateItem(value:Object, oldObject:Object):void
Updates an item with a new item at the same position in the DataProvider.
SegmentedControl
  
updateItemAt(value:Object, index:int):void
Updates the item at the specified index with a new item.
SegmentedControl
  
updateItemsAt(items:Array, index:int):void
Updates items in the DataProvider at a given index, given an Array of items.
SegmentedControl
 Inherited
Validates the display list of the component by calling the updateDisplayList().
UIComponent
 Inherited
Validates the component immediately by calling validateProperties(), validateSizes(), and validateDisplayList() if necessary.
UIComponent
 Inherited
Validates the properties of the component by calling the commitProperties() method.
UIComponent

Protected Methods

 MethodDefined By
 Inherited
Process properties of the component.
UIComponent
 Inherited
Process the state of the component.
UIComponent
 Inherited
doMeasure(availableWidth:Number, availableHeight:Number):LayoutMeasurement
Performs a measurement on the control, and returns a LayoutMeasurement instance containing the available width and height within the layout.
UIComponent
 Inherited
flushCache():void
Invoked as part of parentLayoutChanged.
UIComponent
 Inherited
onAdded():void
Called when the instance is added to the stage.
UIComponent
 Inherited
onRemoved():void
Called when the instance is removed from the stage.
UIComponent
 Inherited
Invalidates the parent's size and display list if includeInLayout property is set to true.
UIComponent
  
updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void
[override]
SegmentedControl

Events

 Event Summary Defined By
  Dispatches a change event when the selection of the control changes.SegmentedControl

Property Detail

dataProvider


dataProvider:IDataProvider

Gets or sets the DataProvider object used by the segmented control. The DataProvider must be of type IDataProvider.


Implementation

public function get dataProvider():IDataProvider
public function set dataProvider(value:IDataProvider):void

See also

DataProvider

selectedIndex


selectedIndex:int

Gets or sets the currently selected index.

         mySegment.selectedIndex = 2;
         

The default value is -1.


Implementation

public function get selectedIndex():int
public function set selectedIndex(value:int):void

selectedItem


selectedItem:Object

Gets or sets the currently selected item.


Implementation

public function get selectedItem():Object
public function set selectedItem(value:Object):void

Constructor Detail

SegmentedControl()


public function SegmentedControl()

Creates a new SegmentedControl instance.

Method Detail

addItem()


public function addItem(item:Object):void

Appends an item to the DataProvider.

The following example adds an object with the label Friday to the right-end of the SegmentedControl:

         mySegment.addItem({label: "Friday" })
         

Adding or removing an item fires a DataProvider event, which causes the columns to be cleared and redrawn.

Parameters

item:Object — The object to add to the DataProvider.

addItemAt()


public function addItemAt(item:Object, index:int):void

Adds an item to the DataProvider at a given index.

In the following example, an object with the label Thursday is added to the penultimate position in the SegmentedControl:

         mySegment.addItemAt({label: "Thursday" }, mySegment.dataProvider.length -1)
         

Adding or removing an item from the SegmentedControl dispatches a DataProvider event, which causes the columns to be cleared and redrawn.

Parameters

item:Object — The item to add.
index:int — The index at which to add the item.

addItemsAt()


public function addItemsAt(items:Array, index:int):void

Adds items in the DataProvider at a given index, given an Array of items.

Adding or removing an item fires a DataProvider event, which causes the columns to be cleared and redrawn.

Parameters

items:Array — The index at which to add the item.
index:int

getItemAt()


public function getItemAt(index:int):Object

Gets the data object from the DataProvider at a given index.

Adding or removing an item fires a DataProvider event, which causes the columns to be cleared and redrawn.

Parameters

index:int — The index at which to return the item.

Returns

Object

getTextFormatForState()


public function getTextFormatForState(state:String):TextFormat

Returns the TextFormat object for a specified state.

Parameters

state:String — The state for the TextFormat object to return.

Returns

TextFormat — The TextFormat object for the specified state.

See also

setTextFormatForState()
SkinStates

removeAll()


public function removeAll():void

Removes all items from the DataProvider.

Adding or removing an item fires a DataProvider event, which causes the columns to be cleared and redrawn.

removeItem()


public function removeItem(item:Object):void

Removes an item from the DataProvider.

Adding or removing an item fires a DataProvider event, which causes the columns to be cleared and redrawn.

Parameters

item:Object — The item to remove.


Throws

ArgumentError — Thrown if the item could not be found.

removeItemAt()


public function removeItemAt(index:int):void

Removes an item from the DataProvider at a given index.

Adding or removing an item fires a dDataProvider event, which causes the columns to be cleared and redrawn.

Parameters

index:int — The index location at which to remove the item.

replaceItem()


public function replaceItem(newObject:Object, oldObject:Object):void

Replaces an item with a new item.

Parameters

newObject:Object — The new item.
oldObject:Object — The current item to replace.


Throws

RangeError — Thrown if the specified index is less than 0, or greater than or equal to the length of the DataProvider.

See also

replaceItemAt()

replaceItemAt()


public function replaceItemAt(item:Object, index:int):void

Replaces the data at a given index.

Adding or removing an item fires a data provider event, which causes the columns to be cleared and redrawn.

Parameters

item:Object — The new item to add.
index:int — The index at which to add the itemm.

setBackgroundSkin()


public function setBackgroundSkin(skin:Object):void

Sets the background skin for the segmented control, given a DisplayObject object to represent the background skin.

The following code listing sets the background skin to the default skin for the dark color scheme:

         mySegment.setBackgroundSkin(SegmentedControlSkinBlack);
         

Parameters

skin:Object — The skin to use for the background of the segmented control.

See also

SkinAssets

setButtonSkin()


public function setButtonSkin(skin:Object):void

Sets the button skin for the buttons in the segmented control.

You can pass in a qualified class name String, or the actual class. In either instance the class that is used must implement the ISkin interface.

Note: Do not pass in an instance of a skin class. This may cause unexpected behavior.

The following code listing sets the button skin to the default skin for the dark color scheme:

         mySegment.setButtonSkin(RoundedButtonSkinBlack);
         

Parameters

skin:Object — The button skin.

See also

SkinAssets

setButtonWidthAtIndex()


public function setButtonWidthAtIndex(buttonWidth:int = 100, index:int = 0):void

Sets the button width of an item at the specified index.

The following listing sets the width of the second button to 200 pixels.

         mySegment.setButtonWidthAtIndex(200, 1);
         

This operation will override the current width and height of this control, other button widths will not be changed.

Parameters

buttonWidth:int (default = 100) — The new width to set. The default is 100 (pixels).
index:int (default = 0) — The index of the button to set. The default is 0.

setSelectionSkin()


public function setSelectionSkin(skin:Object):void

Sets the selection indicator skin for the segmented control, given a DisplayObject object to represent the selection indicator skin.

The following code listing sets the selection indicator skin to the default skin for the dark color scheme:

         mySegment.setBackgroundSkin(SegmentedControlButtonSkinBlack);
         

Parameters

skin:Object — The skin to use for the selection indicator of the segmented control.

See also

SkinAssets

setTextFormatForState()


public function setTextFormatForState(format:TextFormat, state:String):void

Sets the TextFormat object for the label for a given state.

Valid state parameter values are:

  • selected
  • default

In the following example, the a TextFormat object is applied to the selected state label:

         var myFormat:TextFormat = new TextFormat();
         myFormat.font = "Myriad Pro";
         myFormat.size = 22;
         myFormat.color = 0xFFFFFF;

         var segmentedControl:SegmentedControl = new SegmentedControl();
         segmentedControl.setTextFormatForState(myFormat, SkinStates.UP);

         

Parameters

format:TextFormat — The TextFormat object to apply to the label.
state:String — The state for which to apply the TextFormat object.

See also

SkinStates
getTextFormatForState()

updateDisplayList()


override protected function updateDisplayList(unscaledWidth:Number, unscaledHeight:Number):void

Parameters

unscaledWidth:Number
unscaledHeight:Number

updateItem()


public function updateItem(value:Object, oldObject:Object):void

Updates an item with a new item at the same position in the DataProvider.

Parameters

value:Object — The new item.
oldObject:Object — The current item to replace.

See also

updateItemAt()

updateItemAt()


public function updateItemAt(value:Object, index:int):void

Updates the item at the specified index with a new item.

Parameters

value:Object — The new item.
index:int — The index of the item to replace.


Throws

RangeError — Thrown if the specified index is less than 0, or greater than or equal to the length of the DataProvider.

See also

updateItem()

updateItemsAt()


public function updateItemsAt(items:Array, index:int):void

Updates items in the DataProvider at a given index, given an Array of items.

Updating an item fires a DataProvider event, which causes the columns to be cleared and redrawn.

Parameters

items:Array — The index at which to update the items.
index:int

Event Detail

change


Event Object Type: flash.events.Event
Event.type property = flash.events.Event.CHANGE

Dispatches a change event when the selection of the control changes.

Examples

The following example creates a SegmentedControl instance.

package
{
    import flash.display.Sprite;

    import qnx.fuse.ui.buttons.SegmentedControl;
    import qnx.ui.data.DataProvider;

    [SWF(height="600", width="1024",
    frameRate="30", backgroundColor="#FFFFFF")]
    public class SegmentedControlExample extends Sprite
    {
        public function SegmentedControlExample()
        {
            initializeUI();
        }

        private function initializeUI():void
        {
            // create an array for the segmented control with objects
            // that have label properties
            var buttonArray:Array=[];
            buttonArray.push({label:"AM"});
            buttonArray.push({label:"FM"});
            buttonArray.push({label:"HD"});

            // create a segemented control
            var mySegment:SegmentedControl = new SegmentedControl();
            mySegment.x = 200;
            mySegment.y = 200;
            mySegment.width = 200;
            // set the data provider
            mySegment.dataProvider = new DataProvider(buttonArray);
            // set the selected index to be the 3rd item in the dataProvider
            mySegment.selectedIndex = 2;
            // add the control to the display list
            this.addChild(mySegment);

        }

    }
}