#include <Font.h>
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 () | |
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 | 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) | |
Structors | |
Font () |
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.
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>
<u></u>
<rgba r g b a></rgba>
<left></left>
<center></center>
<right></right>
<pre></pre>
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 123 of file Font.h.
GG::Font::Font | ( | const std::string & | font_filename, | |
unsigned int | pts | |||
) |
Ctor. Construct a font using only the printable ASCII characters.
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.
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, | |||
CharSetIter | first, | |||
CharSetIter | last | |||
) | [inline] |
GG::Font::Font | ( | const std::string & | font_filename, | |
unsigned int | pts, | |||
const std::vector< unsigned char > & | file_contents, | |||
CharSetIter | first, | |||
CharSetIter | last | |||
) | [inline] |
GG::Font::~Font | ( | ) |
Dtor.
GG::Font::Font | ( | ) | [protected] |
Default ctor.
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::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.
Renders glyph for c and returns advance of glyph rendered.
Renders glyph for c and returns advance of glyph rendered.
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::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] |
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.