Titanium Mobile

# Titanium.UI.Label

A text label, with an optional background image.

Availability
0.8
0.8
9.2.0
Extends
Titanium.UI.View

# Overview

Use the Titanium.UI.createLabel method or <Label> Alloy element to create a label.

# Examples

# Basic Label

Create a center-aligned label with a text shadow and specified-size font, and another containing forced line breaks and Unicode symbols.

var win = Ti.UI.createWindow({
  backgroundColor: 'white',
  exitOnClose: true,
  fullscreen: false,
  layout: 'vertical',
  title: 'Label Demo'
});

var label1 = Ti.UI.createLabel({
  color: '#900',
  font: { fontSize:48 },
  shadowColor: '#aaa',
  shadowOffset: {x:5, y:5},
  shadowRadius: 3,
  text: 'A simple label',
  textAlign: Ti.UI.TEXT_ALIGNMENT_CENTER,
  top: 30,
  width: Ti.UI.SIZE, height: Ti.UI.SIZE
});

var label2 = Ti.UI.createLabel({
  color:'blue',
  text: 'A long label with\na few line breaks\nand Unicode (UTF8)\nsymbols such as\na white chess piece \u2655\nand the euro symbol \u20ac\nlooks like this!\n',
  textAlign: Ti.UI.TEXT_ALIGNMENT_LEFT,
  top: 30,
  width: 300, height: 200
});

win.add(label1);
win.add(label2);
win.open();

# Alloy XML Markup

Previous example as an Alloy view.

The font and shadowOffset properties need to be defined in the TSS or controller file. These property values are dictionaries, rather than single values, so they cannot be included in the markup.

<Alloy>
    <Window id="win" backgroundColor="white" exitOnClose="true" fullscreen="false" layout="vertical" title="Label Demo">

        <!-- The text property can either be defined as an attribute or as node text. -->
        <Label id="label1" color="#900" shadowColor="#aaa" text="A simple label" textAlign="Ti.UI.TEXT_ALIGNMENT_CENTER"
            top="30" width="Ti.UI.SIZE" height="Ti.UI.SIZE" />
        <Label id="label2" color="blue" textAlign="Ti.UI.TEXT_ALIGNMENT_LEFT" top="30" width="300" height="200">
            A long label with\na few line breaks\nand Unicode (UTF8)\nsymbols such as\na white chess piece \u2655\nand the euro symbol \u20ac\nlooks like this!\n
        </Label>
    </Window>
</Alloy>

# Properties

# attributedString

Availability
3.6.0
3.2.0
9.2.0
attributedString :Titanium.UI.AttributedString

Specify an attributed string for the label.

The underlying attributed string drawn by the label. If set, avoid setting common attributes in the label, such as color and font, as unexpected behaviors may result.

Prior to Release 3.6.0, assign this property an object from the <Titanium.UI.iOS.AttributedString> class.

Since Appcelerator CLI 4.1.0 (Alloy 1.7.0), for Alloy, you can use an <AttributedString> element inside a <Label> element and set the text property as node text:

<Alloy>
  <Window>
      <Label>
        <AttributedString>
            Alloy is great!
        </AttributedString>
      </Label>
  </Window>
</Alloy>

Then set attributes in the TSS file:

"AttributedString" : {
  attributes: [
    {
      type: Ti.UI.ATTRIBUTE_FOREGROUND_COLOR,
      value: 'red',
      range: [0, 5]
    },
    {
      type: Ti.UI.ATTRIBUTE_UNDERLINES_STYLE,
      value: Ti.UI.ATTRIBUTE_UNDERLINE_STYLE_SINGLE,
      range: [9, 5]
    }
  ]
}
Availability
0.8
autoLink :Number

Automatically convert certain text items in the label to clickable links.

Multiple autolink values can be combined with a bitwise OR. For example:

label.autoLink = Ti.UI.AUTOLINK_MAP_ADDRESSES|Ti.UI.AUTOLINK_PHONE_NUMBERS;

Prior to Release 3.0, this field used platform-specific constants. These are now deprecated in favor of the AUTOLINK constants.

The Android-specific LINKIFY legacy constants are defined in Titanium.UI.Android.

This API can be assigned the following constants:

# backgroundPaddingBottom

Availability
0.8
9.2.0
backgroundPaddingBottom :Number

Number of pixels to extend the background image past the label on the bottom.

# backgroundPaddingLeft

Availability
0.8
9.2.0
backgroundPaddingLeft :Number

Number of pixels to extend the background image past the label on the left.

# backgroundPaddingRight

Availability
0.8
9.2.0
backgroundPaddingRight :Number

Number of pixels to extend the background image past the label on the right.

# backgroundPaddingTop

Availability
0.8
9.2.0
backgroundPaddingTop :Number

Number of pixels to extend the background image past the label on the top.

# color

Availability
0.8
0.8
9.2.0
color :String | Titanium.UI.Color

Color of the label text, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

# font

Availability
0.8
0.8
9.2.0
font :Font

Font to use for the label text.

# highlightedColor

Availability
0.8
0.8
9.2.0
highlightedColor :String | Titanium.UI.Color

Color of the label when in the highlighted state, as a color name or hex triplet.

For information about color values, see the "Colors" section of Titanium.UI.

Used when the label is part of a view that can be highlighted, such as a Titanium.UI.TableViewRow.

# html

Availability
0.8
html :String

Simple HTML formatting.

# includeFontPadding

Availability
3.3.0
includeFontPadding :Boolean

Includes extra top and bottom padding to make room for accents that go above normal ascent and descent.

Default: undefined but behaves as true

# lines

Availability
4.1.0
lines :Number

Makes the label be exactly this many lines tall.

# lineSpacing

Availability
5.4.0
lineSpacing :LabelLineSpacing

Line spacing of the text, as a dictionary with the properties add and multiply.

# maxLines

Availability
4.1.0
6.1.0
9.2.0
maxLines :Number

Makes the label at most this many lines tall.

# minimumFontSize

Availability
6.1.0
0.8
9.2.0
minimumFontSize :Number

Minimum font size when the font is sized based on the contents.

When set to a valid font size, this property enables single-line mode and the font will be auto-downscaled so that its text will fit the label's width if necessary. Will not downscale the font lower than the assigned minimum font size.

When set to less than or equal to zero, the font auto-downscaling feature will be disabled.

# shadowColor

Availability
3.2.0
0.8
9.2.0
shadowColor :String | Titanium.UI.Color

Shadow color of the text, as a color name or hex triplet.

Use in conjunction with shadowOffset and shadowRadius. For information about color values, see the "Colors" section of Titanium.UI.

# shadowOffset

Availability
3.2.0
0.8
9.2.0
shadowOffset :Point

Shadow offset of the text, as a dictionary with the properties x and y.

Use in conjunction with shadowColor and shadowRadius.

# shadowRadius

Availability
3.2.0
shadowRadius :Number

Shadow radius of the text.

Use in conjunction with shadowColor and shadowOffset.

# text

Availability
0.8
0.8
9.2.0
text :String

Label text.

Use the backslash and letter n line feed character combination, ie \n, to force a new line.

Use Unicode characters, such as those included in (but not limited to) the Unicode List of Useful Symbols section of wikipedia, to insert special characters and symbols.

See the example in Titanium.UI.Label for a demonstration.

# textAlign

Availability
0.8
0.8
9.2.0
textAlign :String | Number

Text alignment.

This API can be assigned the following constants:

# textid

Availability
0.8
0.8
9.2.0
textid :String

Key identifying a string from the locale file to use for the label text.

Only one of text or textid should be specified.

# verticalAlign

Availability
3.0.0
3.0.0
9.2.0
verticalAlign :Number | String

Vertical text alignment, specified using one of the vertical alignment constants from Titanium.UI.

On iPhone and iPad the default value of the property is undefined. The behavior of the label depends on the actual content height. If the actual content height is larger than the available height the text is truncated at the end and the content is center aligned.

On Android, the default value of the property is undefined, and the default behavior when the property is undefined is to center the text vertically.

This API can be assigned the following constants:

Default: undefined

# wordWrap DEPRECATED

Availability
0.8
wordWrap :Boolean

DEPRECATED SINCE 8.0.0

If you want to disable wrapping, then set maxLines to 1 instead.

Enable or disable word wrapping in the label.

Default: true

# Events

Availability
4.0.0
3.2.0
9.2.0

Fired when user interacts with a URL in the Label.

The URL is set using the ATTRIBUTE_LINK property on the attributedString.

On Android, this event also fires if the html property is used instead of the attributedString property. This event will also override the default behavior of openning the link in its default application.

On iOS, this is only valid on version 7 and above. In previous versions of the the Titanium SDK this event required a longpress gesture to be performed. Beginning with Titanium SDK 4.0.0, only a singletap gesture is required to invoke this event.

Properties

Name Type Description
url String

The URL that is associated with this event.

range Array

An array of two numbers [location, length] describing the character range of the text associated with this URL.

bubbles Boolean

This is false. This event does not bubble

source Object

Source object that fired the event.

type String

Name of the event fired.

bubbles Boolean

True if the event will try to bubble up if possible.

cancelBubble Boolean

Set to true to stop the event from bubbling.

Contents