Skip to content

Commit

Permalink
Merge pull request #5618 from tstatler/TIDOC-1311-3_2_X
Browse files Browse the repository at this point in the history 
[TIDOC-1311] 3_2_X changes to font documentation
  • Loading branch information
bhatfield committed Apr 22, 2014
2 parents 4bc5d9f + a5c4d7d commit b958a70
Showing 1 changed file with 39 additions and 56 deletions.
95 changes: 39 additions & 56 deletions apidoc/Titanium/UI/Font.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,105 +7,88 @@ description: |
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, font: myFontName }
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.)
Custom fonts must be placed in the `Resources/fonts` directory. Note that the steps
for referring to the fonts are slightly different by platform.
* On Android, use the font file name, minus the `.otf` or `.ttf` extension.
For example, if you are using the Chantelli Antiqua font and the file is
named `Chantelli_Antiqua.ttf`, specify `fontFamily: 'Chantelli_Antiqua'`
on Android.
* On iOS, use the official font name--this name is embedded in the font file and
does not change if you rename the file. For example, for Chantelli Antiqua,
you'd specify: `fontFamily: 'Chantelli Antiqua'` (with a space).
On OS X, double-clicking on the font file will launch the Font Book application,
which shows the official font name.
In Alloy applications, custom fonts must be placed in a "fonts" folder in the platform-specific assets folder (<strong>app/assets/android/fonts</strong>, for example).
In classic Titanium applications, custom fonts must be placed in the **Resources/fonts** directory.
iOS requires one more step to embed a custom font in an application. The font must be
added to the application's `Info.plist` file:
For an example of using custom fonts, see [Custom Fonts](http://docs.appcelerator.com/titanium/#!/guide/Custom_Fonts).
1. Build the project at least once (the font won't work yet).
2. Copy *yourproject*`/build/iphone/Info.plist` to the *yourproject* folder.
3. Double-click `Info.plist` to open it in Xcode.
4. Right-click a blank area in the list of keys and choose **Add Row**.
From the resulting list, choose **Fonts provided by application**.
properties:
- name: fontFamily
summary: Specifies the font family or specific font to use.
description: |
5. Expand **Fonts provided by application** and click in the Value field.
Enter the full path of the font file, for example, `/fonts/Chantelli_Antiqua.ttf`.
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.
6. Save the file and close Xcode.
7. In Studio, clean the project then build it again. Your custom font should
show up.
* 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'`.
For more information on embedding custom fonts, see:
* On iOS you use the font's [PostScript name](http://docs.appcelerator.com/titanium/3.0/#!/guide/Custom_Fonts-section-29004935_CustomFonts-Findingafont%27sPostScriptname).
For example, the PostScript name for Burnstown Dam is "BurnstownDam-Regular so you'd specify: `fontFamily: 'BurnstownDam-Regular'`.
* [Custom Fonts in the Titanium Mobile Guides](http://docs.appcelerator.com/titanium/#!/guide/Custom_Fonts)
For an example of using a custom font, see [Custom Fonts](http://docs.appcelerator.com/titanium/#!/guide/Custom_Fonts).
Notes:
properties:
- name: fontFamily
summary: Name of a font family, for example, "Helvetica" or "DroidSans".
description: |
Note the the fonts available differ by platform.
If the requested family name does not match an existing font, the default font
family is used.
* 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.
On Android, the generic names "sans-serif," "serif," and "monospace" (or "monospaced") are
mapped to system fonts. On iOS, only "monospace" is supported.
type: String
default: Uses the default system font.
- name: fontSize
summary: Font size, in platform-dependent units.
description: |
On iOS and Mobile Web, font sizes are always specified in typographical points
(not to be confused with the Apple "points" used for other measurements on iOS).
On iOS and Mobile Web, 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
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.
* inches (in)
For example, "16dp" specifies a size of 16 density-independent pixels.
iOS ingores any unit specifier after the size value.
iOS ignores any unit specifier after the size value.
type: [ Number, String ]
default: 15px
- name: fontWeight
summary: Font weight. Valid values are "bold" or "normal".
summary: Font weight. Valid values are "bold" or "normal".
description: The "semibold" weight is recognized on iOS only.
type: String
default: normal
- name: fontStyle
summary: Font style. Valid values are "italic" or "normal".
summary: Font style. Valid values are "italic" or "normal".
type: String
platforms: [ iphone, ipad, blackberry ]
default: normal
- name: textStyle
summary: The text style for the font.
summary: The text style for the font.
description: |
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. Avaliable on iOS 7 and above.
Expand Down

0 comments on commit b958a70

Please sign in to comment.