Label.yml

---
name: Titanium.UI.Label
summary: A text label, with an optional background image.
description: |
    | Android | iOS |
    | ------- | --- |
    | ![Android](./label_android.png) |  |

    Use the <Titanium.UI.createLabel> method or **`<Label>`** Alloy element to create a label.
extends: Titanium.UI.View
since: "0.8"
excludes:
    properties: [children]
    methods: [add, remove, removeAllChildren, replaceAt]

properties:
  - name: attributedString
    summary: Specify an attributed string for the label.
    description: |
        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:

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

        Then set attributes in the TSS file:

        ``` js
        "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]
            }
          ]
        }
        ```
    type: Titanium.UI.AttributedString
    platforms: [android, iphone, ipad, macos]
    since:
        android: 3.6.0
        iphone: 3.2.0
        ipad: 3.2.0

  - name: autoLink
    summary: Automatically convert certain text items in the label to clickable links.
    description: |
        Multiple autolink values can be combined with a bitwise OR. For example:

        ``` js
        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>.
    type: Number
    constants: Titanium.UI.AUTOLINK_*
    platforms: [android]

  - name: autoSize
    summary: Automatically scales the label into its size.
    description: |
        To use `autoSize` you have to set a `width` and `height` to the label and it will
        automatically increase the font size to fill up the space. The actual `fontSize`
        value stays the same.
    type: Boolean
    default: false,
    platforms: [android]
    since: "11.1.0"

  - name: backgroundPaddingBottom
    summary: Number of pixels to extend the background image past the label on the bottom.
    type: Number
    platforms: [iphone, ipad, macos]

  - name: backgroundPaddingLeft
    summary: Number of pixels to extend the background image past the label on the left.
    type: Number
    platforms: [iphone, ipad, macos]

  - name: backgroundPaddingRight
    summary: Number of pixels to extend the background image past the label on the right.
    type: Number
    platforms: [iphone, ipad, macos]

  - name: backgroundPaddingTop
    summary: Number of pixels to extend the background image past the label on the top.
    type: Number
    platforms: [iphone, ipad, macos]

  - name: color
    summary: Color of the label text, as a color name or hex triplet.
    description: |
        For information about color values, see the "Colors" section of <Titanium.UI>.
    type: [String, Titanium.UI.Color]

  - name: ellipsize
    summary: |
        Causes words in the text that are longer than the view is wide to be ellipsized instead of broken in the middle.
    constants: Titanium.UI.TEXT_ELLIPSIZE_TRUNCATE_*
    type: Number
    default: Titanium.UI.TEXT_ELLIPSIZE_TRUNCATE_END
    platforms: [android, iphone, ipad, macos]

  - name: font
    summary: Font to use for the label text.
    type: Font

  - name: highlightedColor
    summary: Color of the label when in the highlighted state, as a color name or hex triplet.
    description: |
        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>.
    type: [String, Titanium.UI.Color]
    platforms: [android, iphone, ipad, macos]

  - name: html
    summary: Pass a HTML-based string and it will be formatted accordingly.
    description: |
        Note that complex html structures like images are not supported.
        Use a <Titanium.UI.WebView> for those cases.
    platforms: [android, iphone, ipad, macos]
    since: { android: "0.8.0", iphone: "12.3.0", ipad: "12.3.0", macos: "12.3.0" }
    type: String

  - name: breakStrategy
    summary: Break strategy (control over paragraph layout). Check [Android breakStrategy](https://developer.android.com/reference/android/widget/TextView#attr_android:breakStrategy) for more infos.
    platforms: [android]
    type: Number
    constants: Titanium.UI.BREAK_*
    since: "12.3.0"

  - name: hyphenationFrequency
    summary: Frequency of automatic hyphenation. Check [Android hyphenationFrequency](https://developer.android.com/reference/android/widget/TextView#attr_android:hyphenationFrequency) for more infos.
    platforms: [android]
    type: Number
    constants: Titanium.UI.HYPHEN_*
    since: "12.3.0"

  - name: includeFontPadding
    summary: Includes extra top and bottom padding to make room for accents that go above normal ascent and descent.
    platforms: [android]
    type: Boolean
    default: undefined but behaves as true
    since: "3.3.0"

  - name: lines
    summary: Makes the label be exactly this many lines tall.
    platforms: [android]
    type: Number
    since: "4.1.0"

  - name: lineCount
    summary: Returns the amount of lines the content is acually using. Is equal or lower than `maxLines`.
    type: Number
    permission: read-only
    since: "12.3.0"

  - name: lineSpacing
    summary: Line spacing of the [text](Titanium.UI.Label.text), as a dictionary with the properties `add` and `multiply`.
    platforms: [android]
    type: LabelLineSpacing
    since: "5.4.0"

  - name: maxLines
    summary: Makes the label at most this many lines tall.
    platforms: [android, iphone, ipad, macos]
    type: Number
    since: {android: "4.1.0", iphone: "6.1.0", ipad: "6.1.0"}

  - name: minimumFontSize
    summary: Minimum font size when the font is sized based on the contents.
    description: |
        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.
    type: Number
    since: {iphone: "0.8.0", ipad: "0.8.0", android: "6.1.0"}
    platforms: [android, iphone, ipad, macos]

  - name: shadowColor
    summary: Shadow color of the [text](Titanium.UI.Label.text), as a color name or hex triplet.
    description: |
        Use in conjunction with [shadowOffset](Titanium.UI.Label.shadowOffset) and [shadowRadius](Titanium.UI.Label.shadowRadius).
        For information about color values, see the "Colors" section of <Titanium.UI>.
    type: [String, Titanium.UI.Color]
    platforms: [android, iphone, ipad, macos]
    since: {android: "3.2.0"}

  - name: shadowOffset
    summary: Shadow offset of the [text](Titanium.UI.Label.text), as a dictionary with the properties `x` and `y`.
    description: |
        Use in conjunction with [shadowColor](Titanium.UI.Label.shadowColor) and [shadowRadius](Titanium.UI.Label.shadowRadius).
    type: Point
    platforms: [android, iphone, ipad, macos]
    since: {android: "3.2.0"}

  - name: shadowRadius
    summary: Shadow radius of the [text](Titanium.UI.Label.text).
    description: |
        Use in conjunction with [shadowColor](Titanium.UI.Label.shadowColor) and [shadowOffset](Titanium.UI.Label.shadowOffset).
    type: Number
    platforms: [android]
    since: "3.2.0"

  - name: text
    summary: Label text.
    description: |
        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](http://en.wikibooks.org/w/index.php?title=Unicode/List_of_useful_symbols)
        section of wikipedia, to insert special characters and symbols.

        See the example in [label](Titanium.UI.Label) for a demonstration.
    type: String

  - name: textAlign
    summary: Text alignment.
    type: [String, Number]
    constants: Titanium.UI.TEXT_ALIGNMENT_*

  - name: textid
    summary: Key identifying a string from the locale file to use for the label text.
    description: Only one of `text` or `textid` should be specified.
    type: String

  - name: visibleText
    summary: Returns the actual text seen on the screen. If the text is ellipsized it will be different to the normal `text`.
    platforms: [android]
    type: String
    permission: read-only
    since: {android: "12.3.0"}

  - name: wordWrap
    summary: Enable or disable word wrapping in the label.
    type: Boolean
    default: true
    platforms: [android]
    deprecated:
        since: "8.0.0"
        notes: If you want to disable wrapping, then set [Titanium.UI.Label.maxLines](Titanium.UI.Label.maxLines) to 1 instead.

  - name: verticalAlign
    summary: |
        Vertical text alignment, specified using one of the  vertical alignment constants
        from <Titanium.UI>.
    description: |
        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.
    type: [Number,String]
    constants: Titanium.UI.TEXT_VERTICAL_ALIGNMENT_*
    default: undefined
    since: { iphone: "3.0.0", ipad: "3.0.0", android: "3.0.0" }

events:
  - name: link
    summary: Fired when user interacts with a URL in the Label.
    description: |
        The URL is set using the [ATTRIBUTE_LINK](Titanium.UI.ATTRIBUTE_LINK) property on the [attributedString](Titanium.UI.Label.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: url
        summary: The URL that is associated with this event.
        type: String
      - name: range
        summary: An array of two numbers [location, length] describing the character range of the text associated with this URL.
        type: Array
      - name: bubbles
        summary: This is false. This event does not bubble
        type: Boolean
    platforms: [iphone,ipad, android, macos]
    since: {iphone: "3.2.0", ipad: "3.2.0", android: "4.0.0"}

examples:
  - title: Simple Alloy XML Example
    example: |
        Simple label in a Window

        ``` xml
        <Alloy>
            <Window>
                <Label text="Just a label with text"/>
            </Window>
        </Alloy>
        ```

  - title: Basic Label
    example: |
        Create a center-aligned label with a text shadow and specified-size font, and another
        containing forced line breaks and Unicode symbols.

        ``` js
        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();
        ```

  - title: Alloy XML Markup
    example: |
        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.

        ``` xml
        <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>
        ```

---
name: LabelLineSpacing
summary: See [TextView.setLineSpacing](https://developer.android.com/reference/android/widget/TextView#setLineSpacing(float,%20float))
platforms: [android]
properties:
  - name: add
    summary: The value in pixels that should be added to each line other than the last line. This will be applied after the multiplier
    type: Number
  - name: multiply
    summary: The value by which each line height other than the last line will be multiplied by
    type: Number