GG: GG::Font Class Reference

GG

- Main Page
- Related Pages
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Classes | Static Public Member Functions | List of all members
GG::Font Class Reference

`#include <Font.h>`

## Classes
struct | FormattingTag
struct | LineData
struct | RenderState
class | Substring
struct | TextElement

## 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:

-     <i></i>

  Italics

-     <u></u>

  Underline

-     <rgba r g b a></rgba>

  Color. Sets current rendering color to that specified by parameters. Parameters may be either floating point values in the range [0.0, 1.0], or integer values in the range [0, 255]. All parameters must be in one format or the other. The </rgba> tag restores the previously set <rgba> color, or restores the default color used to render the text when there are no other <rgba> tags in effect. 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. Note that due to their semantics, <pre> tags cannot be nested.

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::Exception | Throws 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::Exception | Throws 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::Exception | Throws a subclass of Font::Exception if the condition specified for the subclass is met.

Definition at line 709 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::Exception | Throws a subclass of Font::Exception if the condition specified for the subclass is met.

Definition at line 732 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:

- Font.h