MOAIFont Class Reference

Inherits MOAILuaObject.

List of all members.

Function List
	getDefaultSize
	getFilename
	getFlags
	getImage
	load
	loadFromBMFont
	preloadGlyphs
	rebuildKerningTables
	setCache
	setDefaultSize
	setFlags
	setImage
	setReader
	loadFromTTF

---

Detailed Description

MOAIFont is the top level object for managing sets of glyphs associated with a single font face. An instance of MOAIFont may contain glyph sets for multiple sizes of the font. Alternatively, a separate instance of MOAIFont may be used for each font size. Using a single font object for each size of a font face can make it easier to unload font sizes that are no longer needed.

An instance of MOAIFont may represent a dynamic or static font. Dynamic fonts are used to retrieve glyphs from a font file format on an as-needed basis. Static fonts have no associated font file format and therefore contain a fixed set of glyphs at runtime. For languages demanding very large character sets (such as Chinese), dynamic fonts are typically used. For languages where it is feasible to pre-render a full set of glyphs to texture (or bitmap fonts), static fonts may be used.

MOAIFont orchestrates objects derived from MOAIFontReader and MOAIGlyphCacheBase to render glyphs into glyph sets. MOAIFontReader is responsible for interpreting the font file format (if any), retrieving glyph metrics (including kerning) and rendering glyphs to texture. MOAIGlyphCache is responsible for allocating textures to hold glyphs and for managing glyph placement within textures. For dynamic fonts, the typical setup uses MOAIFreeTypeFontReader and MOAIGlyphCache. For static fonts, there is usually no font reader; MOAIStaticGlyphCache is loaded directly from a serialized file and its texture memory is initialized with MOAIFont's setImage () command.

As mentioned, a single MOAIFont may be used to render multiple sizes of a font face. When glyphs need to be laid out or rendered, the font object will return a set of glyphs matching whatever size was requested. It is also possible to specify a default size that will be used if no size is requested for rendering or if no matching size is found. If no default size is set by the user, it will be set automatically the first time a specific size is requested.

MOAIFont can also control how or if kerning tables are loaded when glyphs are being rendered. The default behavior is to load kerning information automatically. It is possible to prevent kerning information from being loaded. In this case, kerning tables may be loaded manually if so desired.

Constants MOAIFont.FONT_AUTOLOAD_KERNING MOAIFont.DEFAULT_FLAGS

---

Function Documentation

getDefaultSize

Requests the font's default size.

---

function getDefaultSize ( MOAIFont self )

Parameters:

self	( MOAIFont )

Returns:

defaultSize ( number )

getFilename

Returns the filename of the font.

---

function getFilename ( MOAIFont self )

Parameters:

self	( MOAIFont )

Returns:

name ( string )

getFlags

Returns the current flags.

---

function getFlags ( MOAIFont self )

Parameters:

self	( MOAIFont )

Returns:

flags ( number )

getImage

Requests a 'glyph map image' from the glyph cache currently attached to the font. The glyph map image stitches together the texture pages used by the glyph cache to produce a single image that represents a snapshot of all of the texture memory being used by the font.

---

function getImage ( MOAIFont self )

Parameters:

self	( MOAIFont )

Returns:

image ( MOAIImage )

load

Sets the filename of the font for use when loading glyphs.

---

function load ( MOAIFont self, string filename )

Parameters:

self	( MOAIFont )
filename	( string ) The path to the font file to load.

Returns:

nil

loadFromBMFont

Sets the filename of the font for use when loading a BMFont.

---

function loadFromBMFont ( MOAIFont self, string filename [, table textures ] )

Parameters:

self	( MOAIFont )
filename	( string ) The path to the BMFont file to load.
textures	( table ) Optional. Table of preloaded textures.

Returns:

nil

loadFromTTF

Preloads a set of glyphs from a TTF or OTF. Included for backward compatibility. May be removed in a future release.

---

function loadFromTTF ( MOAIFont self, string filename, string charcodes, number points [, number dpi ] )

Parameters:

self	( MOAIFont )
filename	( string )
charcodes	( string )
points	( number ) The point size to be loaded from the TTF.
dpi	( number ) Optional. The device DPI (dots per inch of device screen). Default value is 72 (points same as pixels).

Returns:

nil

preloadGlyphs

Loads and caches glyphs for quick access later.

---

function preloadGlyphs ( MOAIFont self, string charCodes, number points [, number dpi ] )

Parameters:

self	( MOAIFont )
charCodes	( string ) A string which defines the characters found in the this->
points	( number ) The point size to be rendered onto the internal texture.
dpi	( number ) Optional. The device DPI (dots per inch of device screen). Default value is 72 (points same as pixels).

Returns:

nil

rebuildKerningTables

Forces a full reload of the kerning tables for either a single glyph set within the font (if a size is specified) or for all glyph sets in the font.

---

function rebuildKerningTables ( MOAIFont self )

Parameters:

self	( MOAIFont )

Returns:

nil

Note:

---

function rebuildKerningTables ( MOAIFont self, number points [, number dpi ] )

Parameters:

self	( MOAIFont )
points	( number ) The point size to be rendered onto the internal texture.
dpi	( number ) Optional. The device DPI (dots per inch of device screen). Default value is 72 (points same as pixels).

Returns:

nil

Note:

setCache

Attaches or clears the glyph cache associated with the font. The cache is an object derived from MOAIGlyphCacheBase and may be a dynamic cache that can allocate space for new glyphs on an as-needed basis or a static cache that only supports direct loading of glyphs and glyph textures through MOAIFont's setImage () command.

---

function setCache ( MOAIFont self [, MOAIGlyphCacheBase cache ] )

Parameters:

self	( MOAIFont )
cache	( MOAIGlyphCacheBase ) Optional. Default value is nil.

Returns:

nil

setDefaultSize

Selects a glyph set size to use as the default size when no other size is specified by objects wishing to use MOAIFont to render text.

---

function setDefaultSize ( MOAIFont self, number points [, number dpi ] )

Parameters:

self	( MOAIFont )
points	( number ) The point size to be rendered onto the internal texture.
dpi	( number ) Optional. The device DPI (dots per inch of device screen). Default value is 72 (points same as pixels).

Returns:

nil

setFlags

Set flags to control font loading behavior. Right now the only supported flag is FONT_AUTOLOAD_KERNING which may be used to enable automatic loading of kern tables. This flag is initially true by default.

---

function setFlags ( MOAIFont self [, number flags ] )

Parameters:

self	( MOAIFont )
flags	( number ) Optional. Flags are FONT_AUTOLOAD_KERNING or DEFAULT_FLAGS. DEFAULT_FLAGS is the same as FONT_AUTOLOAD_KERNING. Alternatively, pass '0' to clear the flags.

Returns:

nil

setImage

Passes an image to the glyph cache currently attached to the font. The image will be used to recreate and initialize the texture memory managed by the glyph cache and used by the font. It will not affect any glyph entires that have already been laid out and stored in the glyph cache. If no cache is attached to the font, an instance of MOAIStaticGlyphCache will automatically be allocated.

---

function setImage ( MOAIFont self, MOAIImage image )

Parameters:

self	( MOAIFont )
image	( MOAIImage )

Returns:

nil

setReader

Attaches or clears the MOAIFontReader associated with the font. MOAIFontReader is responsible for loading and rendering glyphs from a font file on demand. If you are using a static font and do not need a reader, set this field to nil.

---

function setReader ( MOAIFont self [, MOAIFontReader reader ] )

Parameters:

self	( MOAIFont )
reader	( MOAIFontReader ) Optional. Default value is nil.

Returns:

nil