GG::Font

GG::Font Class Reference

This class creates one or more 16-bpp OpenGL textures that contain rendered text from a requested font file at the requested point size, including only the requested ranges of characters. More...

#include <Font.h>

List of all members.

Structors

Font (const std::string &font_filename, int pts, unsigned int range=ALL_DEFINED_RANGES)

virtual ~Font ()

Accessors

const std::string & FontName () const

int PointSize () const

int GetGlyphRange () const

int Ascent () const

int Descent () const

int Height () const

int Lineskip () const

int SpaceWidth () const

int RenderGlyph (const Pt &pt, char c) const

int RenderGlyph (int x, int y, char c) const

int RenderText (const Pt &pt, const std::string &text) const

int RenderText (int x, int y, const std::string &text) const

void RenderText (const Pt &pt1, const Pt &pt2, const std::string &text, Flags< TextFormat > &format, const std::vector< LineData > *line_data=0, RenderState *render_state=0) const

void RenderText (int x1, int y1, int x2, int y2, const std::string &text, Flags< TextFormat > &format, const std::vector< LineData > *line_data=0, RenderState *render_state=0) const

void RenderText (const Pt &pt1, const Pt &pt2, const std::string &text, Flags< TextFormat > &format, const std::vector< LineData > &line_data, RenderState &render_state, int begin_line, int begin_char, int end_line, int end_char) const

void RenderText (int x1, int y1, int x2, int y2, const std::string &text, Flags< TextFormat > &format, const std::vector< LineData > &line_data, RenderState &render_state, int begin_line, int begin_char, int end_line, int end_char) const

Pt DetermineLines (const std::string &text, Flags< TextFormat > &format, int box_width, std::vector< LineData > &lines) const

Pt TextExtent (const std::string &text, Flags< TextFormat > format=FORMAT_NONE, int box_width=0) const

Exceptions

GG_ABSTRACT_EXCEPTION (Exception)

GG_CONCRETE_EXCEPTION (BadFile, GG::Font, Exception)

GG_CONCRETE_EXCEPTION (InvalidPointSize, GG::Font, Exception)

GG_CONCRETE_EXCEPTION (InvalidRangeFlags, GG::Font, Exception)

GG_CONCRETE_EXCEPTION (UnscalableFont, GG::Font, Exception)

GG_CONCRETE_EXCEPTION (BadFace, GG::Font, Exception)

GG_CONCRETE_EXCEPTION (BadPointSize, GG::Font, Exception)

GG_CONCRETE_EXCEPTION (BadGlyph, GG::Font, Exception)

Structors

Font ()

Public Types

enum GlyphRange {
 NUMBER = 1 << 0,
 ALPHA_UPPER = 1 << 1,
 ALPHA_LOWER = 1 << 2,
 SYMBOL = 1 << 3,
 ALL_DEFINED_RANGES = NUMBER | ALPHA_UPPER | ALPHA_LOWER | SYMBOL,
 ALL_CHARS = (1 << 5) - 1
}

Static Public Member Functions

static void RegisterKnownTag (const std::string &tag)

static void RemoveKnownTag (const std::string &tag)

static void ClearKnownTags ()

Friends

struct HandleTagFunctor

Classes

struct FormattingTag

The type of TextElement that represents a text formatting tag. More...

struct LineData

Holds the essential data on each line that a string occupies when rendered with given format flags. More...

struct RenderState

Holds the state of tags during rendering of text. More...

struct TextElement

Used to encapsulate a token-like piece of text to be rendered using GG::Font. More...

Detailed Description

This class creates one or more 16-bpp OpenGL textures that contain rendered text from a requested font file at the requested point size, including only the requested ranges of characters.

Once the textures have been created, text is rendered to the display by rendering polygons textured with portions of the rendered textures that contain individual character images. The characters are rendered to the textures in white, with alpha blending used for antialiasing. The user should set the desired text color with a call to glColor*() before any call to RenderText(). When text is rendered, DetermineLines() is called to determine where the line breaks are, so that text can be rendered centered, right-justified, or whatever. To cut down on this computation, when the text is not changing very rapidly (ie not every frame), DetermineLines() can be called by the user once, and the result supplied to RenderText() repeatedly. When this is done, the iteration through the text to determine line breaks is not necessary at render time. The user is responsible for ensuring that the line data applies to the text string supplied to RenderText(). The total range of characters covered by ALL_DEFINED_RANGES is 0x20 (' ') to 0x7E ('~'). SYMBOL covers everything in that range that isn't a letter or digit. ALL_CHARS covers all 256 ASCII character codes from 0x00 to 0xFF. The other ranges are self-explanatory. Point sizes above 250 are not supported.

Text Formatting Tags

GG::Font supports a few text formatting tags for convenience. These tags are similar to HTML or XML tags; there is an opening version "<tag>" and a closing version "</tag>" of each tag. It is important to note that GG::Font tags represent state change, and so cannot be meaningfully nested. For instance, consider the use of the italics tag here:

      <i>some text <i>and </i>some more text</i>

In this example, everything is italicized except for "some more text". Each tag establishes that italics should be used for all further text until the next tag. So the second tag is redundant, as is the second tag. Each respectively activates or deactivates italics when that is already the current state. The text justification tags are used on a per-line basis, since it makes no sense to right-justify only a part of a line and center the rest, for instance. When more than one justification tag appears on a line, the last one is used. A justification close-tag indicates that a line is to be the last one with that justification, and only applies if that justification is active.
The supported tags are:

```
 
```
Italics
```
 
```
Underline
```
<rgba r g b a></rgba> 
```
Color. Sets current rendering color to that specified by parameters. Parameters may be either floating point values between 0.0 and 1.0 inclusive, or 8-bit integer values between 0 and 255 inclusive. All parameters must be in one format or the other. The </rgba> tag does not restore the previously set <rgba> color, but instead restores the default color used to render the text. (Example tag: <rgba 0.4 0.5 0.6 0.7>)
```
<left></left> 
```
Left-justified text.
```
<center></center> 
```
Centered text.
```
<right></right> 
```
Right-justified text.
```
<pre></pre> 
```
Preformatted. Similar to HTML <pre> tag, except this one only causes all tags to be ignored until a subsequent </pre> tag is seen.

Users of Font may wish to create their own tags as well. Though Font will not be able to handle new tags without reworking the Font code, it is possible to let Font know about other tags, in order for Font to render them invisible as it does with the tags listed above. See the static methods RegisterKnownTag(), RemoveKnownTag(), and ClearKnownTags() for details. It is not possible to remove the built-in tags using these methods. If you wish not to use tags at all, call DetermineLines() and RenderText() with the format parameter containing FORMAT_IGNORETAGS, or include a <pre> tag at the beginning of the text to be rendered.

Definition at line 108 of file Font.h.

Member Enumeration Documentation

enum GG::Font::GlyphRange

the ranges of character glyphs to be rendered in this font

Enumerator:

NUMBER	only the numbers ('0' - '9')
ALPHA_UPPER	only the uppercase alphabet ('A' - 'Z')
ALPHA_LOWER	only the lowercase alphabet ('a' - 'z')
SYMBOL	everything printable not covered above
ALL_DEFINED_RANGES	everything above (all printable characters)
ALL_CHARS	all characters (0x00 - 0xFF)

Definition at line 214 of file Font.h.

Constructor & Destructor Documentation

GG::Font::Font	(	const std::string &	font_filename,
		int	pts,
		unsigned int	range = `ALL_DEFINED_RANGES`
	)

ctor.

Exceptions:

Font::Exception

Throws a subclass of Exception if one of the conditions specified for the subclasses is met.

virtual GG::Font::~Font ( ) [virtual]

virtual dtor

GG::Font::Font ( ) [protected]

default ctor

Member Function Documentation

const std::string& GG::Font::FontName ( ) const

returns the name of the file from which this font was created

int GG::Font::PointSize ( ) const

returns the point size in which the characters in the font object are rendered

int GG::Font::GetGlyphRange ( ) const

returns the range(s) of characters rendered in the font

See also:: GlyphRange

int GG::Font::Ascent ( ) const

returns the maximum amount above the baseline the text can go, in pixels

int GG::Font::Descent ( ) const

returns the maximum amount below the baseline the text can go, in pixels

int GG::Font::Height ( ) const

returns (Ascent() - Descent()), in pixels

int GG::Font::Lineskip ( ) const

returns the distance that should be placed between lines, in pixels. This is usually not equal to Height().

int GG::Font::SpaceWidth ( ) const

returns the width in pixels of the glyph for the space character

int GG::Font::RenderGlyph	(	const Pt &	pt,
		char	c
	)			const

renders glyph for c and returns advance of glyph rendered

int GG::Font::RenderGlyph	(	int	x,
		int	y,
		char	c
	)			const

renders glyph for c and returns advance of glyph rendered

int GG::Font::RenderText	(	const Pt &	pt,
		const std::string &	text
	)			const

unformatted text rendering; repeatedly calls RenderGlyph, then returns advance of entire string

int GG::Font::RenderText	(	int	x,
		int	y,
		const std::string &	text
	)			const

unformatted text rendering; repeatedly calls RenderGlyph, then returns advance of entire string

void GG::Font::RenderText	(	const Pt &	pt1,
		const Pt &	pt2,
		const std::string &	text,
		Flags< TextFormat > &	format,
		const std::vector< LineData > *	line_data = `0`,
		RenderState *	render_state = `0`
	)			const

formatted text rendering

void GG::Font::RenderText	(	int	x1,
		int	y1,
		int	x2,
		int	y2,
		const std::string &	text,
		Flags< TextFormat > &	format,
		const std::vector< LineData > *	line_data = `0`,
		RenderState *	render_state = `0`
	)			const

formatted text rendering

void GG::Font::RenderText	(	const Pt &	pt1,
		const Pt &	pt2,
		const std::string &	text,
		Flags< TextFormat > &	format,
		const std::vector< LineData > &	line_data,
		RenderState &	render_state,
		int	begin_line,
		int	begin_char,
		int	end_line,
		int	end_char
	)			const

formatted text rendering over a subset of lines and characters

void GG::Font::RenderText	(	int	x1,
		int	y1,
		int	x2,
		int	y2,
		const std::string &	text,
		Flags< TextFormat > &	format,
		const std::vector< LineData > &	line_data,
		RenderState &	render_state,
		int	begin_line,
		int	begin_char,
		int	end_line,
		int	end_char
	)			const

formatted text rendering over a subset of lines and characters

Pt GG::Font::DetermineLines	(	const std::string &	text,
		Flags< TextFormat > &	format,
		int	box_width,
		std::vector< LineData > &	lines
	)			const

returns the maximum dimensions of the string in x and y

Pt GG::Font::TextExtent	(	const std::string &	text,
		Flags< TextFormat >	format = `FORMAT_NONE`,
		int	box_width = `0`
	)			const

returns the maximum dimensions of the string in x and y. Provided as a convenience; it just calls DetermineLines with the given parameters.

static void GG::Font::RegisterKnownTag ( const std::string & tag ) [static]

adds tag to the list of embedded tags that Font should not print when rendering text. Passing "foo" will cause Font to treat "<foo>", <foo [arg1 [arg2 ...]]>, and "</foo>" as tags.

static void GG::Font::RemoveKnownTag ( const std::string & tag ) [static]

removes tag from the known tag list. Does not remove the built in tags: , , <rgba r g b a>, and <pre>.

static void GG::Font::ClearKnownTags ( ) [static]

removes all tags from the known tag list. Does not remove the built in tags: , , <rgba r g b a>, and <pre>.

GG::Font::GG_ABSTRACT_EXCEPTION ( Exception )

The base class for Font exceptions.

GG::Font::GG_CONCRETE_EXCEPTION	(	BadFile	,
		GG::Font	,
		Exception
	)

Thrown when valid font data cannot be read from a file.

GG::Font::GG_CONCRETE_EXCEPTION	(	InvalidPointSize	,
		GG::Font	,
		Exception
	)

Thrown when a nonpositive font size is requested.

GG::Font::GG_CONCRETE_EXCEPTION	(	InvalidRangeFlags	,
		GG::Font	,
		Exception
	)

Thrown when an invalid glyph range flag is specified when creating a Font.

GG::Font::GG_CONCRETE_EXCEPTION	(	UnscalableFont	,
		GG::Font	,
		Exception
	)

Thrown when a FreeType font could be loaded, but the resulting font is not scalable, making it unusable by GG.

GG::Font::GG_CONCRETE_EXCEPTION	(	BadFace	,
		GG::Font	,
		Exception
	)

Thrown when an attempt is made to create a glyph from null font face object.

GG::Font::GG_CONCRETE_EXCEPTION	(	BadPointSize	,
		GG::Font	,
		Exception
	)

Thrown when an attempt to set the size of a FreeType font face fails.

GG::Font::GG_CONCRETE_EXCEPTION	(	BadGlyph	,
		GG::Font	,
		Exception
	)

Thrown when FreeType is unable to fulfill a request to load or render a glpyh.

The documentation for this class was generated from the following file:

Font.h

Generated on Wed Mar 26 14:35:42 2008 for GG by

1.5.2


Structors
	Font (const std::string &font_filename, int pts, unsigned int range=ALL_DEFINED_RANGES)
virtual	~Font ()
Accessors
const std::string &	FontName () const
int	PointSize () const
int	GetGlyphRange () const
int	Ascent () const
int	Descent () const
int	Height () const
int	Lineskip () const
int	SpaceWidth () const
int	RenderGlyph (const Pt &pt, char c) const
int	RenderGlyph (int x, int y, char c) const
int	RenderText (const Pt &pt, const std::string &text) const
int	RenderText (int x, int y, const std::string &text) const
void	RenderText (const Pt &pt1, const Pt &pt2, const std::string &text, Flags< TextFormat > &format, const std::vector< LineData > line_data=0, RenderState render_state=0) const
void	RenderText (int x1, int y1, int x2, int y2, const std::string &text, Flags< TextFormat > &format, const std::vector< LineData > line_data=0, RenderState render_state=0) const
void	RenderText (const Pt &pt1, const Pt &pt2, const std::string &text, Flags< TextFormat > &format, const std::vector< LineData > &line_data, RenderState &render_state, int begin_line, int begin_char, int end_line, int end_char) const
void	RenderText (int x1, int y1, int x2, int y2, const std::string &text, Flags< TextFormat > &format, const std::vector< LineData > &line_data, RenderState &render_state, int begin_line, int begin_char, int end_line, int end_char) const
Pt	DetermineLines (const std::string &text, Flags< TextFormat > &format, int box_width, std::vector< LineData > &lines) const
Pt	TextExtent (const std::string &text, Flags< TextFormat > format=FORMAT_NONE, int box_width=0) const
Exceptions
	GG_ABSTRACT_EXCEPTION (Exception)
	GG_CONCRETE_EXCEPTION (BadFile, GG::Font, Exception)
	GG_CONCRETE_EXCEPTION (InvalidPointSize, GG::Font, Exception)
	GG_CONCRETE_EXCEPTION (InvalidRangeFlags, GG::Font, Exception)
	GG_CONCRETE_EXCEPTION (UnscalableFont, GG::Font, Exception)
	GG_CONCRETE_EXCEPTION (BadFace, GG::Font, Exception)
	GG_CONCRETE_EXCEPTION (BadPointSize, GG::Font, Exception)
	GG_CONCRETE_EXCEPTION (BadGlyph, GG::Font, Exception)
Structors
	Font ()
Public Types
enum	GlyphRange { NUMBER = 1 << 0, ALPHA_UPPER = 1 << 1, ALPHA_LOWER = 1 << 2, SYMBOL = 1 << 3, ALL_DEFINED_RANGES = NUMBER \| ALPHA_UPPER \| ALPHA_LOWER \| SYMBOL, ALL_CHARS = (1 << 5) - 1 }
Static Public Member Functions
static void	RegisterKnownTag (const std::string &tag)
static void	RemoveKnownTag (const std::string &tag)
static void	ClearKnownTags ()
Friends
struct	HandleTagFunctor
Classes
struct	FormattingTag
	The type of TextElement that represents a text formatting tag. More...
struct	LineData
	Holds the essential data on each line that a string occupies when rendered with given format flags. More...
struct	RenderState
	Holds the state of tags during rendering of text. More...
struct	TextElement
	Used to encapsulate a token-like piece of text to be rendered using GG::Font. More...