org.jrabbit.base.graphics.font
Class Font

java.lang.Object
  extended by org.jrabbit.base.graphics.font.Font
All Implemented Interfaces:
Createable, DataController, Destroyable, Referenced, FontRenderer

public class Font
extends java.lang.Object
implements Referenced, DataController, FontRenderer

A Font is an object that provides methods to render text. In addition to this basic functionality, it also provides some basic means to format the text it renders. Most of the methods a Font uses are fairly heavy-duty; this means it's a good idea to cache the results so that the Font does not need to do all the calculations every iteration. This class has been designed with that in mind, and various options are offered. From least advantageous to most: 1: When formatting text, store the results of the formatting calculations. 2: When rendering, store the rendering commands in a Display List. (Implemented elsewhere.) 3: Finally, the finished formatting and rendering can be stored on a texture and thereafter rendered as a textured quad. (Implemented elsewhere.) Unfortunately, none of these methods help deal with dynamic, rapidly changing text. So, if you're using dynamic text, it's advisable to use as little of it as possible. Finally, it should be noted that this class isn't intended to be used as an "object" - Fonts are most useful as resources on the side, accessed by other objects and utilized (via a Cache).

Author:
Chris Molini

Field Summary
protected  int indent
          When formatting, each new paragraph is indented by this many spaces.
protected  float lineSpacing
          How much of the standard line spacing (as specified by the renderer) that will divide each line of text.
protected  java.lang.String reference
          The name of this font.
protected  FontRenderer renderer
          The object that controls all rendering and measuring of text.
 
Constructor Summary
Font(java.lang.String reference, FontRenderer renderer)
          Creates a font with the indicated name and the supplied renderer.
 
Method Summary
 void create()
          Initializes the Font's renderer.
 void destroy()
          Destroys the renderer.
private  void ensureSize(java.lang.String word, java.util.LinkedList<java.lang.String> list, int width)
          Recursively breaks up a word into the smallest number of sections that fit within the supplied width, and adds them to the list.
 FontRenderer fontRenderer()
          Obtains a reference to this Font's renderer.
private  java.util.LinkedList<java.lang.String> forge(java.util.LinkedList<java.lang.String> words, int width, boolean indent)
          Strings together the LinkedList of correctly-sized words into a paragraph.
 float heightOf(int numLines)
          Calculates the height of a paragraph of the indicated number of lines.
 float heightOf(java.lang.String... text)
          Calculates the height of the supplied array of text.
 int indent()
          When formatting, every new paragraph has some indentation applied to its first line.
 float lineHeight()
          Obtains the vertical distance between two lines of text.
 java.lang.String reference()
          Accesses the name of the font.
 void render(float x, float y, java.lang.String text)
          Draws the indicated text at the indicated location relative to the Modelview Matrix.
 void render(java.lang.Iterable<java.lang.String> text)
          Draws the indicated text at the current location of the Modelview Matrix.
 void render(java.lang.String... text)
          Draws the indicated text at the current location of the Modelview Matrix.
 void render(java.lang.String text)
          Draws the indicated text at the current location of the Modelview Matrix.
 void setIndent(int indent)
          Defines the number of spaces used to indent each paragraph.
 void setSpacing(float spacing)
          Defines the proportional spacing this font will have between lines of text.
 float spacing()
          Gets the proportional spacing between lines of text.
 java.lang.String[] toLines(java.lang.String text)
          Breaks up the text by line breaks and carriage returns.
 java.lang.String[] toParagraph(java.lang.String text, int width, boolean indent)
          Breaks up the supplied String into a paragraph that cannot be wider than the indicated width.
 java.lang.String[] toParagraphs(java.lang.String text, int width)
          Formats the indicated String into a series of paragraphs, all fitting within the indicated width.
 java.lang.String[] toParagraphs(java.lang.String text, int width, boolean indent)
          Formats the indicated String into a series of paragraphs, all fitting within the indicated width.
 boolean valid()
          Checks if the renderer is still valid.
 float widthOf(java.lang.String text)
          Calculates the width of the supplied text.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

renderer

protected FontRenderer renderer
The object that controls all rendering and measuring of text.


reference

protected java.lang.String reference
The name of this font.


lineSpacing

protected float lineSpacing
How much of the standard line spacing (as specified by the renderer) that will divide each line of text. I.e., if you set this to 2, you get double-spaced fonts, and if you make it less than 1, the lines cluster together.


indent

protected int indent
When formatting, each new paragraph is indented by this many spaces. The default is 4.

Constructor Detail

Font

public Font(java.lang.String reference,
            FontRenderer renderer)
Creates a font with the indicated name and the supplied renderer.

Parameters:
reference - The identifier of the font.
renderer - The renderer that will draw the text.
Method Detail

reference

public java.lang.String reference()
Accesses the name of the font. This is used to identify the Font in a Cache.

Specified by:
reference in interface Referenced
Returns:
The name of this font.

create

public void create()
Initializes the Font's renderer.

Specified by:
create in interface Createable

valid

public boolean valid()
Checks if the renderer is still valid.

Specified by:
valid in interface DataController
Returns:
True if the object has been created and not destroyed.

destroy

public void destroy()
Destroys the renderer.

Specified by:
destroy in interface Destroyable

spacing

public float spacing()
Gets the proportional spacing between lines of text. The actual gap between lines is this value * the base line separation (as supplied by the renderer).

Returns:
The line spacing of this font.

setSpacing

public void setSpacing(float spacing)
Defines the proportional spacing this font will have between lines of text.

Parameters:
spacing - How much to multiply the default line spacing.

indent

public int indent()
When formatting, every new paragraph has some indentation applied to its first line. For simplicity, this indentation is simply a number of space characters inserted at the beginning of the text. The number of spaces inserted is given by this number.

Returns:
The number of spaces added to the first line of every paragraph.

setIndent

public void setIndent(int indent)
Defines the number of spaces used to indent each paragraph. To get rid of indenting, set this to 0. The default value is 4.

Parameters:
indent - The number of spaces to indent paragraphs formatted by this font.

fontRenderer

public FontRenderer fontRenderer()
Obtains a reference to this Font's renderer.

Returns:
The FontRenderer this font is using.

lineHeight

public float lineHeight()
Obtains the vertical distance between two lines of text. This is not the same as the value returned by the renderer, but is instead multiplied by the current line spacing.

Specified by:
lineHeight in interface FontRenderer
Returns:
The spacing between two lines of text.

widthOf

public float widthOf(java.lang.String text)
Calculates the width of the supplied text.

Specified by:
widthOf in interface FontRenderer
Parameters:
text - The text to measure.
Returns:
The width of the indicated text when rendered by this font.

heightOf

public float heightOf(java.lang.String... text)
Calculates the height of the supplied array of text. The font considers each entry in the array as a separate line.

Parameters:
text - The group of text to measure.
Returns:
The total height of the indicated text when rendered.

heightOf

public float heightOf(int numLines)
Calculates the height of a paragraph of the indicated number of lines.

Parameters:
numeLines - The number of lines in the considered paragraph.
Returns:
The total height of the indicated text when rendered.

render

public void render(java.lang.String text)
Draws the indicated text at the current location of the Modelview Matrix.

Parameters:
text - The String to draw.

render

public void render(float x,
                   float y,
                   java.lang.String text)
Draws the indicated text at the indicated location relative to the Modelview Matrix.

Specified by:
render in interface FontRenderer
Parameters:
x - The x coordinate to draw at.
y - The y coordinate to draw at.
text - The String to draw.

render

public void render(java.lang.String... text)
Draws the indicated text at the current location of the Modelview Matrix. Each String in the supplied array is treated as a separate line of text.

Parameters:
text - The list of Strings to render.

render

public void render(java.lang.Iterable<java.lang.String> text)
Draws the indicated text at the current location of the Modelview Matrix. Each String in the supplied Iterable is treated as a separate line.

Parameters:
text - The Strings to render.

toParagraphs

public java.lang.String[] toParagraphs(java.lang.String text,
                                       int width)
Formats the indicated String into a series of paragraphs, all fitting within the indicated width. This caches the results as an array of lines of text. This method is very expensive, as it has to do a lot of string splitting and width calculations. Ideally, one should run the desired text through this method in an editor and save the results, and not ever have to call this in-game. NOTE: This method simply delegates to toParagraphs(String, int, boolean), where indentation is allowed.

Parameters:
text - The text to format.
width - The width to keep each paragraph in.
Returns:
An array of Strings where each String is a separate line of text.

toParagraphs

public java.lang.String[] toParagraphs(java.lang.String text,
                                       int width,
                                       boolean indent)
Formats the indicated String into a series of paragraphs, all fitting within the indicated width. This caches the results as an array of lines of text. This method is very expensive, as it has to do a lot of string splitting and width calculations. Ideally, one should run the desired text through this method in an editor and save the results, and not ever have to call this in-game.

Parameters:
text - The text to format.
width - The width to keep each paragraph in.
indent - Whether or not to append indentation to the beginning of each paragraph.
Returns:
An array of Strings where each String is a separate line of text.

toLines

public java.lang.String[] toLines(java.lang.String text)
Breaks up the text by line breaks and carriage returns.

Parameters:
text - The text to split.
Returns:
The text, separated by line.

toParagraph

public java.lang.String[] toParagraph(java.lang.String text,
                                      int width,
                                      boolean indent)
Breaks up the supplied String into a paragraph that cannot be wider than the indicated width. The supplied String should NOT include newline characters, the method toParagraphs() will handle text that requires line breaks. The formatting process takes several passes. First, the supplied string is broken up by spaces. Then, each "word" is checked to see if it is wider than the supplied width. If so, it is split up into the minimum of sections that will fit in the width. Finally, all of these individual words and word sections are arranged in an optimal paragraph. This method will take time, especially for long text with many long words. It's recommended to call this once for static text and reuse the result. Formatting text that changes rapidly is not recommended if performance is important.

Parameters:
text - The text we wish to format.
width - The maximum number of pixels the resulting rendered paragraph can have.
indent - Whether or not to indent the paragraph.
Returns:
A formatted paragraph, complete with indenting. Each entry in the returned array is a separate line.

ensureSize

private void ensureSize(java.lang.String word,
                        java.util.LinkedList<java.lang.String> list,
                        int width)
Recursively breaks up a word into the smallest number of sections that fit within the supplied width, and adds them to the list. If the indicated word is not wider than the limit, no cropping occurs.

Parameters:
word - The word to crop.
list - The list to add words to.
width - The width to keep the word within.

forge

private java.util.LinkedList<java.lang.String> forge(java.util.LinkedList<java.lang.String> words,
                                                     int width,
                                                     boolean indent)
Strings together the LinkedList of correctly-sized words into a paragraph.

Parameters:
words - The list of words to put together.
width - The maximum width of the paragraph.
indent - Whether or not to indent the beginning of the paragraph.
Returns:
A LinkedList where every entry is a line in the paragraph.