qnx.ui.buttons.SegmentedControl

SegmentedControl

Properties | Methods | Events | Examples


Packageqnx.ui.buttons
Classpublic class SegmentedControl
InheritanceSegmentedControl Inheritance UIComponent Inheritance flash.display.MovieClip
Implements ISizeable, 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
 Inheritedcontainment : String
Gets or sets a property that determines how a component is contained within a parent container.
UIComponent
  dataProvider : IDataProvider
Gets or sets the DataProvider object used by the segmented control.
SegmentedControl
  selectedIndex : int
Gets or sets the currently selected index.
SegmentedControl
  selectedItem : Object
Gets or sets the currently selected item.
SegmentedControl
 Inheritedsize : Number
Gets or sets the size for this component (as a percentage of the container's size, or in pixels).
UIComponent
 InheritedsizeMode : String
Gets or sets the size mode for this component.
UIComponent
 InheritedsizeUnit : String
Gets or sets the unit of measure for the size property.
UIComponent

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
destroy():void
Call this method when you want to have your object collected by the garbage collector.
UIComponent
 Inherited
drawNow():void
Calls the draw() method.
UIComponent
  
getItemAt(index:int):Object
Gets the data object from the DataProvider at a given index.
SegmentedControl
  
getTextFormatForState(state:String):TextFormat
Returns the TextFormat object for a specified state.
SegmentedControl
 Inherited
invalidate(property:String = all, invalidateNow:Boolean = false):void
Marks the property as invalid and the draw() method is called on the next frame or the next render, whichever comes first.
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
  
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
setPosition(x:Number, y:Number):void
Sets the x and y position of the component.
UIComponent
 Inherited
setSize(w:Number, h:Number):void
Sets the width and height of the component.
UIComponent
  
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

Protected Methods

 MethodDefined By
 Inherited
callLater(method:Function):void
Calls the specified method on the next frame or the next render, which ever happens first.
UIComponent
 Inherited
createInstance(linkage:Object):DisplayObject
Calling this method will attempt to create a DisplayObject instance based on the value of the linkage parameter.
UIComponent
 Inherited
draw():void
Called every time you set the width and height of the component.
UIComponent
 Inherited
isInvalid(property:String, ... properties):Boolean
Checks to see if the property is invalid and returns true if it is.
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
setEnabled(val:Boolean):void
Called when the enabled property changes.
UIComponent
 Inherited
validate(property:String = all):void
Lets the component know that the specified property has been validated.
UIComponent

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.

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()

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.


Throws

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

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.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;
            mySegment.height = 50;
            // 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 disply list
            this.addChild(mySegment);    
            
        }
        
    }
}