Titanium SDK

# Titanium.UI.PickerColumn

A picker column, representing a selectable group of items in a Titanium.UI.Picker.

Availability
0.9
0.9
9.2.0
Extends
Titanium.UI.View

# Overview

Use the Titanium.UI.createPickerColumn method to create a picker column control. In an Alloy application, you can use a <PickerColumn> element inside a <Picker> element. You can also use <Column> as a shorthand for <PickerColumn> (see Examples).

On Android, the useSpinner property must be enabled to support multiple columns.

See Titanium.UI.Picker for further examples of usage.

# Examples

# Multi-Column Picker

Create a two-column, platform-specific style, picker and automatically select a row in each column.

var win = Ti.UI.createWindow({
  backgroundColor: 'white',
  exitOnClose: true,
  fullscreen: false,
  title: 'Use picker to make selection'
});

var fruit = [ 'Bananas', 'Grapes', 'Blueberries', 'Strawberries' ];
var color = [ 'blue', 'red', 'yellow', 'white' ];

var column1 = Ti.UI.createPickerColumn();

for(var i=0, ilen=fruit.length; i<ilen; i++){
  var row = Ti.UI.createPickerRow({
    title: fruit[i]
  });
  column1.addRow(row);
}

var column2 = Ti.UI.createPickerColumn();

for(var i=0, ilen=color.length; i<ilen; i++){
  var row = Ti.UI.createPickerRow({
    title: color[i]
  });
  column2.addRow(row);
}

var picker = Ti.UI.createPicker({
  columns: [column1, column2],
  selectionIndicator: true,
  useSpinner: true, // required in order to use multi-column pickers with Android
  top:50
});

function pickerDefaults(obj){
  // on iOS, must be after picker has been rendered
  picker.setSelectedRow(0, 2, false);
  picker.setSelectedRow(1, 3, false);
}

win.add(picker);

var isAndroid = Ti.Platform.osname === 'android';

if(isAndroid){
  pickerDefaults(picker);
}

win.open();

if(!isAndroid){
  setTimeout(function(){
    pickerDefaults(picker);
  }, 1500);
}

# Alloy XML Markup

Previous example as an Alloy view.

multicolumnpicker.xml

<Alloy>
    <Window id="win" backgroundColor="white" exitOnClose="true" fullscreen="false"
        title="Use picker to make selection">

        <Picker id="picker" top="50" selectionIndicator="true" useSpinner="true">
            <PickerColumn id="column1">
                <PickerRow title="Bananas"/>
                <PickerRow title="Grapes"/>
                <PickerRow title="Blueberries"/>
                <PickerRow title="Strawberries"/>
            </PickerColumn>
            <!-- Picker shorthand notation -->
            <Column id="column2">
                <Row title="blue"/>
                <Row title="red"/>
                <Row title="yellow"/>
                <Row title="white"/>
            </Column>
        </Picker>
    </Window>
</Alloy>

multicolumnpicker.js:

$.picker.setSelectedRow(0, 2, false);
$.picker.setSelectedRow(1, 3, false);

# Properties

# apiName READONLY

Availability
3.2.0
3.2.0
9.2.0
apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.

# bubbleParent

Availability
3.0.0
3.0.0
9.2.0
bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

# filterTouchesWhenObscured

Availability
9.3.0
filterTouchesWhenObscured :Boolean

Discards touch related events if another app's system overlay covers the view.

This is a security feature to protect an app from "tapjacking", where a malicious app can use a system overlay to intercept touch events in your app or to trick the end-user to tap on UI in your app intended for the overlay.

Setting this property to true causes touch related events (including "click") to not be fired if a system overlay overlaps the view.

Default: false

# font

Availability
0.9
font :Font

Font to use for text.

# id

Availability
0.9
0.9
9.2.0
id :String

View's identifier.

The id property of the Ti.UI.View represents the view's identifier. The identifier string does not have to be unique. You can use this property with getViewById method.

# lifecycleContainer

Availability
3.6.0
lifecycleContainer :Titanium.UI.Window | Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.

# rowCount READONLY

Availability
0.9
0.9
9.2.0
rowCount :Number

Number of rows in this column.

# rows READONLY

Availability
0.9
0.9
9.2.0
rows :Array<Titanium.UI.PickerRow>

Rows of this column.

While this property is currently writable on Android, changing its value is strongly discouraged.

# tooltip

Availability
12.1.0
12.1.0
12.1.0
tooltip :String

The default text to display in the control's tooltip.

Assigning a value to this property causes the tool tip to be displayed for the view. Setting the property to null cancels the display of the tool tip for the view. Note: This property is only used for apps targeting macOS Catalyst.

# Methods

# addEventListener

Availability
0.9
0.9
9.2.0
addEventListener(name, callback) → void

Adds the specified callback as an event listener for the named event.

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to invoke when the event is fired.

Returns

Type
void

# addRow

Availability
0.9
0.9
9.2.0
addRow(row) → void

Adds a row to this column.

In an Alloy application you can use one or more <PickerRow> (or <Row>) elements inside a <PickerColumn> (or <Column>) element.

<Alloy>
    <PickerColumn id="hour">
        <PickerRow title="10"/>
        <PickerRow title="11"/>
        <PickerRow title="12"/>
    </PickerColumn>
    <!-- Picker shorthand notation -->
    <Column id="minutes">
        <Row title="15"/>
        <Row title="30"/>
        <Row title="45"/>
        <Row title="00"/>
    </Column>
</Alloy>

Parameters

Name Type Description
row Titanium.UI.PickerRow

A row to add.

Returns

Type
void

# applyProperties

Availability
3.0.0
3.0.0
9.2.0
applyProperties(props) → void

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

Parameters

Name Type Description
props Dictionary

A dictionary of properties to apply.

Returns

Type
void

# fireEvent

Availability
0.9
0.9
9.2.0
fireEvent(name[, event]) → void

Fires a synthesized event to any registered listeners.

Parameters

Name Type Description
name String

Name of the event.

event Dictionary

A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type
void

# removeEventListener

Availability
0.9
0.9
9.2.0
removeEventListener(name, callback) → void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

Returns

Type
void

# removeRow

Availability
0.9
0.9
9.2.0
removeRow(row) → void

Removes a row from this column.

Parameters

Name Type Description
row Titanium.UI.PickerRow

A row to remove.

Returns

Type
void

# stopAnimation

Availability
12.1.0
stopAnimation() → void

Stops a running animation.

Stops a running view Titanium.UI.Animation.

Returns

Type
void

# Events

# focus

Availability
0.9

Fired when the view element gains focus.

This event only fires when using the trackball to navigate.

# longclick

Availability
0.9

Fired when the device detects a long click.

A long click is generated by touching and holding on the touchscreen or holding down the trackball button.

The event occurs before the finger/button is lifted.

A longpress and a longclick can occur together.

As the trackball can fire this event, it is not intended to return the x and y coordinates of the touch, even when it is generated by the touchscreen.

A longclick blocks a click, meaning that a click event will not fire when a longclick listener exists.

# postlayout

Availability
2.0.0
2.0.0
9.2.0

Fired when a layout cycle is finished.

This event is fired when the view and its ancestors have been laid out. The rect and size values should be usable when this event is fired.

This event is typically triggered by either changing layout properties or by changing the orientation of the device. Note that changing the layout of child views or ancestors can also trigger a relayout of this view.

Note that altering any properties that affect layout from the postlayout callback may result in an endless loop.

Contents