Titanium SDK

# Font

An abstract datatype for specifying a text font.

Availability
0.8
0.8
9.2.0
Extends
Object

NOTE

This is an abstract type. Any object of this structure can be used where this type is used.

# Overview

Available fonts vary by platform and device. On iOS, font support depends on the OS version. On Android, font support depends on the OS version and device manufacturer.

Note that to update the font used by a UI component, you must set the object's font property, like this:

myLabel.font = {
    fontSize: 24,
    fontFamily: myFontName
}

Changing the font object after assigning it does not reliably affect the underlying UI component:

// This may not work as expected
myLabel.font.fontSize = 24;

# Custom Fonts

Custom TrueType (.ttf) or OpenType (.otf) fonts may be embedded in an application on iOS and Android. (Note that you must have redistribution rights on the fonts you ship.)

In Alloy applications, custom fonts must be placed in a "fonts" folder in the platform-specific assets folder (app/assets/android/fonts, for example). In classic Titanium applications, custom fonts must be placed in the Resources/fonts directory.

For an example of using custom fonts, see Custom Fonts (opens new window).

# Properties

# fontFamily

Availability
0.8
0.8
9.2.0
fontFamily :String

Specifies the font family or specific font to use.

This can be the name of a font family (for example, "Helvetica" or "DroidSans") the base name of the font file (for example, "Droid_sans.ttf"), or the font's PostScript name. The value you specify also depends on the platform you are targeting.

  • On Android specify the font file name without its file extension (.otf or .ttf). For example, if you were using the "Burnstown Dam" font whose file name is named burnstown_dam.ttf, then you specify fontFamily: 'burnstown_dam'.

  • On iOS you use the font's PostScript name. For example, the PostScript name for Burnstown Dam is "BurnstownDam-Regular so you'd specify: fontFamily: 'BurnstownDam-Regular'.

For an example of using a custom font, see Custom Fonts.

Notes:

  • Available fonts differ by platform.
  • If the requested family name does not match an existing font, the default font family is used.
  • On Android, the generic names "sans-serif," "serif," and "monospace" (or "monospaced") are mapped to system fonts. On iOS, only "monospace" is supported.

Default: Uses the default system font.

# fontSize

Availability
0.8
0.8
9.2.0
fontSize :Number | String

Font size, in platform-dependent units.

On iOS, font sizes are always specified in typographical points (not to be confused with the Apple "points" used for other measurements on iOS).

On Android the default font sizing is in pixels, but the size can also include a unit specifier. Supported units and their specifiers are:

  • pixels (px)
  • typographical points (pt)
  • density-independent pixels (dp or dip)
  • millimeters (mm)
  • inches (in)

For example, "16dp" specifies a size of 16 density-independent pixels.

iOS ignores any unit specifier after the size value.

On Windows, font sizing is in effective pixels, not actual physical pixels so you don't have to alter font sizes for different screens sizes or resolutions. For more information about font sizing on Windows, see Typography Size and Scaling.

Default: 15px

# fontStyle

Availability
0.8
9.2.0
fontStyle :String

Font style. Valid values are "italic" or "normal".

Default: normal

# fontWeight

Availability
0.8
0.8
9.2.0
fontWeight :String

Font weight. Valid values are "bold", "semibold", "normal", "thin", "light" and "ultralight".

The "semibold", "thin", "light" and "ultralight" weights are recognized on iOS only. "thin", "light" and "ultralight" are only available on iOS 8.2 and later.

Default: normal

# textStyle

Availability
3.2.0
9.2.0
textStyle :String

The text style for the font.

Use one of the TEXT_STYLE constants from Titanium.UI to set the font to a predefined system font. When this property is set to a valid value, all other font properties are ignored.

Notes: Since SDK 9.0.0 property fontFamily will not be ignored for iOS 11+. Custom fonts can be used with this property for dynamic font management.

This API can be assigned the following constants:

Contents