Moai SDK  2.0
MOAIFont Class Reference
+ Inheritance diagram for MOAIFont:

Function List

getCache
 
getDefaultSize
 
getFilename
 
getFlags
 
getImage
 
getReader
 
load
 
loadFromBMFont
 
preloadGlyphs
 
rebuildKerningTables
 
setCache
 
setDefaultSize
 
setFilter
 
setFlags
 
setImage
 
setReader
 
setShader
 
loadFromTTF
 

Additional Inherited Members

- Function List inherited from MOAIInstanceEventSource
getListener
 
setListener
 

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 MOAIGlyphCache 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. MOAIDynamicGlyphCache is responsible for allocating textures to hold glyphs and for managing glyph placement within textures. For dynamic fonts, the typical setup uses MOAIFreeTypeFontReader and MOAIDynamicGlyphCache. 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

getCache

Returns glyph cache.


function getCache ( MOAIFont self )

Parameters
MOAIFontself
Returns
MOAILuaObject cache
getDefaultSize

Requests the font's default size.


function getDefaultSize ( MOAIFont self )

Parameters
MOAIFontself
Returns
number defaultSize
getFilename

Returns the filename of the font.


function getFilename ( MOAIFont self )

Parameters
MOAIFontself
Returns
string name
getFlags

Returns the current flags.


function getFlags ( MOAIFont self )

Parameters
MOAIFontself
Returns
number flags
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
MOAIFontself
Returns
MOAIImage image
getReader

Returns font reader.


function getCache ( MOAIFont self )

Parameters
MOAIFontself
Returns
MOAILuaObject reader
load

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


function load ( MOAIFont self, string filename )

Parameters
MOAIFontself
stringfilename 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
MOAIFontself
stringfilename The path to the BMFont file to load.
tabletextures 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
MOAIFontself
stringfilename
stringcharcodes
numberpoints The point size to be loaded from the TTF.
numberdpi 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
MOAIFontself
stringcharCodes A string which defines the characters found in the this->
numberpoints The point size to be rendered onto the internal texture.
numberdpi 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
MOAIFontself
Returns
nil
Note

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

Parameters
MOAIFontself
numberpoints The point size to be rendered onto the internal texture.
numberdpi 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 MOAIGlyphCache 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 [, MOAIGlyphCache cache ] )

Parameters
MOAIFontself
MOAIGlyphCachecache 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
MOAIFontself
numberpoints The point size to be rendered onto the internal texture.
numberdpi Optional. The device DPI (dots per inch of device screen). Default value is 72 (points same as pixels).
Returns
nil
setFilter

Sets the filtering mode for glyph textures.


function setFilter ( MOAIFont self [, number minFilter ] )

Parameters
MOAIFontself
numberminFilter Optional.
Returns
number magFilter, MOAILuaObject cache
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
MOAIFontself
numberflags 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
MOAIFontself
MOAIImageimage
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
MOAIFontself
MOAIFontReaderreader Optional. Default value is nil.
Returns
nil
setShader

Set the preferred shader for the font. (May be overridden by a prop.)


function setShader ( MOAIFont self, MOAIShader shader )

Parameters
MOAIFontself
MOAIShadershader
Returns
MOAIShader shader