fontmachine.bitmapfont

This module contains the BitmapFont class.
This class is the most important class in the FontMachine library as this class is, itself, a font.
All FontMachine bitmap fonts are instances od a BitmapFont class.

Table of contents:

Classes:
Class BitmapFont implements Font
Description:This class represents a BitmapFont.
Details: A BitmapFont is a font used to draw text on the graphics canvas.
Usually, to load a FontMachine font in your game or application, all you have to do is:
Global myFont:BitmapFont = BitmapFont.Load("myfont.txt")
myFont.DrawText("Hello world!",10,10)
(Obviously, you better see the complete source code samples)
Table of contents:Functions:
  • Load ( Function Load:BitmapFont(fontName:String, dynamicLoad:bool) )
Methods:
Method CharCount:Int()
Description:This function return the number of chars that have been created in the given bitmapfont.
Returns:Int
Details: Important:Notice that some chars can have null characters due them being just part of scape sequences, so be sure to check for <> null before accesing any character info by index.
Method DrawBorder:Bool() property
Description:Set this property to True or False to enable the font border.
Returns:Bool
Details: If the font has been rendered without a border, this property has no effect.
Load an example in Jungle Ide.
Method DrawShadow:Bool() property
Description:Set this property to True or False to enable the font shadow.
Returns:Bool
Details: If the font has been rendered without a shadow, this property has no effect.
Load an example in Jungle Ide.
Method DrawText(text:String, x#, y#, align:Int)
Description:This method allows you to draw a string on the graphics canvas.
Returns:Int
Details: The first parameter is the string to be drawn
The second and third parameters are the X and Y coordinates.
The third parameter is a member of eDrawAlign and determines the aligment of the text to be drawn on the graphics canvas.
This is a detailed example:
'We import the required modules:
Import mojo
Import fontmachine

'Start the program:
Function Main()
New Tutorial
End


Class Tutorial extends App

'We create a BitmapFont variable called font. Our font will be loaded here:
Field font:BitmapFont

Method OnCreate()

SetUpdateRate(60)

'We load the sample font (called bluesky) into our variable called font.
'The first parameter is the name (and path) of the font description file (txt file generated on the FontMachine editor)
'The second parameter indicates if the font glipths will be loaded dynamically (true) or statically (false).
'If the font characters are loaded dynamically, the application will load (and download on HTML5) only required characters.
'Otherwise, the full font will be required. For more information about dynamic or static fonts, see the documentation.

font = New BitmapFont("bluesky/bluesky.txt", False)

Print "Font loaded!"

End
Method OnRender()
Cls(255,255,255)

'We just draw some text:
font.DrawText("Hello world",210,10, eDrawAlign.CENTER)
End

Method OnUpdate()
If KeyDown(KEY_A) Then font.Kerning.x-=.4
If KeyDown(KEY_D) Then font.Kerning.x+=.4
If KeyDown(KEY_W) Then font.Kerning.y-=.4
If KeyDown(KEY_S) Then font.Kerning.y+=.4
End
End
Load this example in Jungle Ide.
Method DrawText(text:String, x#, y#)
Description:This method allows you to draw a string on the graphics canvas.
Returns:Int
Details: This method is a simplified version of the DrawText command that asumes left aligment of text.
Method GetBorderImage:Image(char:Int)
Description:this method will return the image associated to a given char border on dynamic fonts.
Returns:Image
Details: If the character border image has not been loaded yet, this function will load it.
Method GetBorderInfo:BitMapCharMetrics(char:Int)
Description:This method returns the drawing char info of the given border character.
Returns:BitMapCharMetrics
Method GetFaceImage:Image(char:Int)
Description:this method will return the image associated to a given char on dynamic fonts.
Returns:Image
Details: If the character image has not been loaded yet, this function will load it.
Method GetFaceInfo:BitMapCharMetrics(char:Int)
Description:This method returns the drawing char info of the given face character.
Returns:BitMapCharMetrics
Method GetFontHeight:Int()
Description:This method returns the height in pixels of the font.
Returns:Int
Method GetPackedBorderRectangle:DrawingRectangle(char:Int)
Description:This method returns the rectangle coordinates of the given char border into the packed texture.
Returns:DrawingRectangle
Details: This method returns phisical coordinates in the texture, in pixels.
Method GetPackedFaceRectangle:DrawingRectangle(char:Int)
Description:This method returns the rectangle coordinates of the given char into the packed texture.
Returns:DrawingRectangle
Details: This method returns phisical coordinates in the texture, in pixels.
Method GetPackedShadowRectangle:DrawingRectangle(char:Int)
Description:This method returns the rectangle coordinates of the given char shadow into the packed texture.
Returns:DrawingRectangle
Details: This method returns phisical coordinates in the texture, in pixels.
Method GetShadowImage:Image(char:Int)
Description:this method will return the image associated to a given char shadow on dynamic fonts.
Returns:Image
Details: If the character shadow image has not been loaded yet, this function will load it.
Method GetShadowInfo:BitMapCharMetrics(char:Int)
Description:This method returns the drawing char info of the given shadow character.
Returns:BitMapCharMetrics
Method GetTxtHeight:Float(Text:String)
Description:This method returns the height in graphic units of the given string.
Returns:Float
Method GetTxtWidth:Float(text:String)
Description:This method returns the width in graphic units of the given string.
Returns:Float
Details: You can see a sample application that uses the GetTxtWidth function here.
Method GetTxtWidth:Float(text:String, fromChar:Int, toChar:Int)
Description:This method returns the width in graphic units of the given substring.
Returns:Float
Details: This function will take fromChar and toChar parameters to calculate the substring metrics
Method IsPacked:Bool()
Description:This method returns True if the current font is a packed font. Otherwise it returns false.
Returns:Bool
Function Load:BitmapFont(fontName:String, dynamicLoad:bool)
Description:This function creates an instance of a BitmapFont class.
Returns:BitmapFont
Details: The fontName parameter indicates the name of the txt file containing the font description (generated by the FontMachine editor).
The second parameter indicates if the font should be loaded dynamically (only valid for non packed fonts).
Method LoadCharsForText(text:String)
Description:This method will force a dynamic font to load all the characters required to draw the given string on the graphics canvas.
Returns:Int
Method LoadFullFont()
Description:This method will force a dynamic font to load all the available characters.
Returns:Int
Method New(fontDescriptionFilePath:String, dynamicLoad:bool)
Description:This is a BitmapFont class constructor.
Details: The fontDescriptionFilePath parameter indicates the name of the txt file containing the font description (generated by the FontMachine editor).
The second parameter (dynamicLoad) indicates if the font should be loaded dynamically (only valid for non packed fonts).
Method New(fontDescriptionFilePath:String)
Description:This is a BitmapFont class constructor.
Details: The fontDescriptionFilePath parameter indicates the name of the txt file containing the font description (generated by the FontMachine editor).
Method UnloadCharsForText(text:String)
Description:This method will force a dynamic font to unload all the characters in the given string.
Returns:Int
Method UnloadFullFont()
Description:This method will force a dynamic font to unload all its characters.
Returns:Int
Method Kerning:drawingpoint.DrawingPoint() property
Description:This property allows you to define additional kerning on a given bitmap font.
Returns:DrawingPoint
Details: By using this property, you set the horizonal and vertical kerning that has to be added on any draw operation.
This information will be expressed in the form of a DrawingPoint instance.


This FontMachine library is released under the MIT license:
Copyright (c) 2011 Manel Ibáñez

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

This document was generated using the Jungle IDE document generator version 12.02.13-A