GG
Classes | Static Public Member Functions
GG::Font Class Reference

#include <Font.h>

List of all members.

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...
class  Substring
 A range of iterators into a std::string that defines a substring found in a string being rendered by Font. More...
struct  TextElement
 Used to encapsulate a token-like piece of text to be rendered using GG::Font. More...

Static Public Member Functions

static void RegisterKnownTag (const std::string &tag)
static void RemoveKnownTag (const std::string &tag)
static void ClearKnownTags ()
static void ThrowBadGlyph (const std::string &format_str, boost::uint32_t c)

Structors

 Font (const std::string &font_filename, unsigned int pts)
 Font (const std::string &font_filename, unsigned int pts, const std::vector< unsigned char > &file_contents)
template<class CharSetIter >
 Font (const std::string &font_filename, unsigned int pts, CharSetIter first, CharSetIter last)
template<class CharSetIter >
 Font (const std::string &font_filename, unsigned int pts, const std::vector< unsigned char > &file_contents, CharSetIter first, CharSetIter last)
 ~Font ()
 Font ()

Accessors

const std::string & FontName () const
unsigned int PointSize () const
const std::vector
< UnicodeCharset > & 
UnicodeCharsets () const
Y Ascent () const
Y Descent () const
Y Height () const
Y Lineskip () const
X SpaceWidth () const
X RenderGlyph (const Pt &pt, char c) const
X RenderGlyph (const Pt &pt, boost::uint32_t c) const
X RenderText (const Pt &pt, 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 (const Pt &pt1, const Pt &pt2, const std::string &text, Flags< TextFormat > &format, const std::vector< LineData > &line_data, RenderState &render_state, std::size_t begin_line, CPSize begin_char, std::size_t end_line, CPSize end_char) const
void ProcessTagsBefore (const std::vector< LineData > &line_data, RenderState &render_state, std::size_t begin_line, CPSize begin_char) const
Pt DetermineLines (const std::string &text, Flags< TextFormat > &format, X box_width, std::vector< LineData > &line_data) const
Pt DetermineLines (const std::string &text, Flags< TextFormat > &format, X box_width, std::vector< LineData > &line_data, std::vector< boost::shared_ptr< TextElement > > &text_elements) const
Pt DetermineLines (const std::string &text, Flags< TextFormat > &format, X box_width, const std::vector< boost::shared_ptr< TextElement > > &text_elements, std::vector< LineData > &line_data) const
Pt TextExtent (const std::string &text, Flags< TextFormat > format=FORMAT_NONE, X box_width=X0) const
Pt TextExtent (const std::string &text, const std::vector< LineData > &line_data) const

Exceptions

 GG_ABSTRACT_EXCEPTION (Exception)
 GG_CONCRETE_EXCEPTION (BadFile, GG::Font, Exception)
 GG_CONCRETE_EXCEPTION (InvalidPointSize, 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)

Detailed Description

A bitmapped font rendering class.

Font creates one or more 16-bits-per-pixel OpenGL textures that contain rendered glyphs from a requested font file at the requested point size, including only the requested ranges of code points. Once the textures have been created, text is rendered to the display by rendering quads textured with portions of the glyph textures. The glyphs 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(). See UnicodeCharsets.h for the ranges of code points available, including a function that allow one to determine which ranges are necessary for rendering a certain string. Point sizes above 250 are not supported. Note that users should not normally need to use Font directly. Users should instead use TextControl, Edit, or MultiEdit.

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. Tags can be nested. For instance, consider the use of the italics tag <i> here:

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

In this example, everything is italicized except for "text". Each <i> tag establishes that italics should be used for all further text until the next matching </i> tag. The first <i> tag matches the second </i> tag, and the two inner tags are matched. Note that unmatched close-tags (e.g. </i>) are ignored by the text parser Font uses to find tags – they will appear as regular text. The text justification tags are used on a per-line basis, since it makes no sense to, for instance, right-justify only a part of a line and center the rest. 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:

Users of Font may wish to create their own tags as well. Though Font will know nothing about the semantics of the new tags, it is possible to let Font know about them, 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 122 of file Font.h.


Constructor & Destructor Documentation

GG::Font::Font ( const std::string &  font_filename,
unsigned int  pts 
)

Ctor. Construct a font using only the printable ASCII characters.

Exceptions:
Font::ExceptionThrows a subclass of Font::Exception if the condition specified for the subclass is met.
GG::Font::Font ( const std::string &  font_filename,
unsigned int  pts,
const std::vector< unsigned char > &  file_contents 
)

Ctor. Construct a font using only the printable ASCII characters, from the in-memory contents file_contents.

Exceptions:
Font::ExceptionThrows a subclass of Font::Exception if the condition specified for the subclass is met.
template<class CharSetIter >
GG::Font::Font ( const std::string &  font_filename,
unsigned int  pts,
CharSetIter  first,
CharSetIter  last 
)

Ctor. Construct a font using all the code points in the UnicodeCharsets in the range [first, last).

Exceptions:
Font::ExceptionThrows a subclass of Font::Exception if the condition specified for the subclass is met.

Definition at line 708 of file Font.h.

template<class CharSetIter >
GG::Font::Font ( const std::string &  font_filename,
unsigned int  pts,
const std::vector< unsigned char > &  file_contents,
CharSetIter  first,
CharSetIter  last 
)

Ctor. Construct a font using all the code points in the UnicodeCharsets in the range [first, last), from the in-memory contents file_contents.

Exceptions:
Font::ExceptionThrows a subclass of Font::Exception if the condition specified for the subclass is met.

Definition at line 731 of file Font.h.


Member Function Documentation

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

Returns the name of the file from which this font was created.

unsigned int GG::Font::PointSize ( ) const

Returns the point size in which the characters in the font object are rendered.

const std::vector<UnicodeCharset>& GG::Font::UnicodeCharsets ( ) const

Returns the range(s) of code points rendered in the font

Y GG::Font::Ascent ( ) const

Returns the maximum amount above the baseline the text can go.

Y GG::Font::Descent ( ) const

Returns the maximum amount below the baseline the text can go.

Y GG::Font::Height ( ) const

Returns (Ascent() - Descent()).

Y GG::Font::Lineskip ( ) const

Returns the distance that should be placed between lines. This is usually not equal to Height().

X GG::Font::SpaceWidth ( ) const

Returns the width of the glyph for the space character.

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

Renders glyph for c and returns advance of glyph rendered.

Note:
Just as with most string parameters throughout GG, c must be a valid UTF-8 sequence.
X GG::Font::RenderGlyph ( const Pt pt,
boost::uint32_t  c 
) const

Renders glyph for c and returns advance of glyph rendered.

X GG::Font::RenderText ( const Pt pt,
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 ( const Pt pt1,
const Pt pt2,
const std::string &  text,
Flags< TextFormat > &  format,
const std::vector< LineData > &  line_data,
RenderState render_state,
std::size_t  begin_line,
CPSize  begin_char,
std::size_t  end_line,
CPSize  end_char 
) const

Formatted text rendering over a subset of lines and code points. The glyphs rendered are in the range [CodePointIndexOf(begin_line, begin_char, line_data), CodePointIndexOf(end_line - 1, end_char, line_data)).

void GG::Font::ProcessTagsBefore ( const std::vector< LineData > &  line_data,
RenderState render_state,
std::size_t  begin_line,
CPSize  begin_char 
) const

Sets render_state as if all the text before (begin_line, begin_char) had just been rendered.

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

Returns the maximum dimensions of the string in x and y, and populates line_data.

Pt GG::Font::DetermineLines ( const std::string &  text,
Flags< TextFormat > &  format,
X  box_width,
std::vector< LineData > &  line_data,
std::vector< boost::shared_ptr< TextElement > > &  text_elements 
) const

Returns the maximum dimensions of the string in x and y, and populates line_data and text_elements. Note that text_elements must be empty.

Pt GG::Font::DetermineLines ( const std::string &  text,
Flags< TextFormat > &  format,
X  box_width,
const std::vector< boost::shared_ptr< TextElement > > &  text_elements,
std::vector< LineData > &  line_data 
) const

Returns the maximum dimensions of the string in x and y, and populates line_data. The contents of text_elements will be used, and the equivalent work done by DetermineLines() will be skipped. Supplying a text and a text_elements that are incompatible will result in undefined behavior.

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

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

Pt GG::Font::TextExtent ( const std::string &  text,
const std::vector< LineData > &  line_data 
) const

Returns the maximum dimensions of the text in x and y.

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: <i>, <u>, <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: <i>, <u>, <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 0 font size is requested.

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.

static void GG::Font::ThrowBadGlyph ( const std::string &  format_str,
boost::uint32_t  c 
)
static

Throws a BadGlyph exception, with c converted to a printable ASCII character (if possible), or as a Unicode code point. format_str should contain the Boost.Format positional notation formatting tag "%1%" where the code point should appear.


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