# CEGUI::Font Class Reference

Class that encapsulates text rendering functionality for a typeface. More...

Collaboration diagram for CEGUI::Font:

[legend]
List of all members.

## Public Member Functions

size_t | drawText (const String &text, const Rect &draw_area, float z, const Rect &clip_rect, TextFormatting fmt, const ColourRect &colours, float x_scale=1.0f, float y_scale=1.0f) const
| Draw text into a specified area of the display.
size_t | drawText (const String &text, const Rect &draw_area, float z, const Rect &clip_rect, TextFormatting fmt, float x_scale=1.0f, float y_scale=1.0f) const
| Draw text into a specified area of the display using default colours.
void | drawText (const String &text, const Rect &draw_area, float z, const Rect &clip_rect, float x_scale=1.0f, float y_scale=1.0f) const
| Draw text into a specified area of the display with default colours and default formatting (LeftAligned).
size_t | drawText (const String &text, const Rect &draw_area, float z, TextFormatting fmt, const ColourRect &colours, float x_scale=1.0f, float y_scale=1.0f) const
| Draw text into a specified area of the display.
size_t | drawText (const String &text, const Rect &draw_area, float z, TextFormatting fmt, float x_scale=1.0f, float y_scale=1.0f) const
| Draw text into a specified area of the display with default colours.
void | drawText (const String &text, const Rect &draw_area, float z, float x_scale=1.0f, float y_scale=1.0f) const
| Draw text into a specified area of the display with default colours and default formatting (LeftAligned).
void | drawText (const String &text, const Vector3 &position, const Rect &clip_rect, const ColourRect &colours, float x_scale=1.0f, float y_scale=1.0f) const
| Draw text at the specified location.
void | drawText (const String &text, const Vector3 &position, const Rect &clip_rect, float x_scale=1.0f, float y_scale=1.0f) const
| Draw text at the specified location with default colours.
void | defineFontGlyphs (const String &glyph_set)
| Define the set of code points to be renderable by the font.
void | defineFontGlyphs (utf32 first_code_point, utf32 last_code_point)
| Define the range of code points to be renderable by the font.
void | setNativeResolution (const Size &size)
| Set the native resolution for this Font.
void | notifyScreenResolution (const Size &size)
| Notify the Font of the current (usually new) display resolution.
void | setAutoScalingEnabled (bool setting)
| Enable or disable auto-scaling for this Font.
void | setAntiAliased (bool setting)
| Set whether the font is anti-aliased or not. Only relevant for dynamic fonts, this setting is ignored for bitmapped fonts.
float | getTextExtent (const String &text, float x_scale=1.0f) const
| Return the pixel width of the specified text if rendered with this Font.
float | getLineSpacing (float y_scale=1.0f) const
| Return the pixel line spacing value for.
float | getFontHeight (float y_scale=1.0f) const
| return the exact pixel height of the font.
float | getBaseline (float y_scale=1.0f) const
| Return the number of pixels from the top of the highest glyph to the baseline.
size_t | getCharAtPixel (const String &text, float pixel, float x_scale=1.0f) const
| Return the index of the closest text character in String text that corresponds to pixel location pixel if the text were rendered.
size_t | getCharAtPixel (const String &text, size_t start_char, float pixel, float x_scale=1.0f) const
| Return the index of the closest text character in String text, starting at character index start_char, that corresponds to pixel location pixel if the text were to be rendered.
const String & | getName (void) const
| Return the name of this font.
Size | getNativeResolution (void) const
| Return the native display size for this Font. This is only relevant if the Font is being auto-scaled.
bool | isAutoScaled (void) const
| Return whether this Font is auto-scaled.
bool | isCodepointAvailable (utf32 cp) const
| Return whether this Font can currently draw the specified code-point.
size_t | getFormattedLineCount (const String &text, const Rect &format_area, TextFormatting fmt, float x_scale=1.0f) const
| Return the number of lines the given text would be formatted to.
float | getFormattedTextExtent (const String &text, const Rect &format_area, TextFormatting fmt, float x_scale=1.0f) const
| Return the horizontal pixel extent given text would be formatted to.
bool | isAntiAliased (void) const
| Return whether this font is anti-aliased or not. This is only relevant for dynamic fonts created from a TrueType font file.
const String & | getAvailableGlyphs (void) const
| Return a String object that contains the code-points that the font is currently configured to render.
uint | getPointSize (void) const
| Return the point size of a dynamic (ttf based) font.
| ~Font (void)
| Destroys a Font object.

## Static Public Attributes

static const argb_t | DefaultColour = 0xFFFFFFFF
| Colour value used whenever a colour is not specified.

## Friends

class | Font_xmlHandler
class | FontManager

## Classes

struct | FontImplData
struct | glyphDat
| struct to hold extra details about a glyph (required for proper rendering)

## Detailed Description

Class that encapsulates text rendering functionality for a typeface.

A Font object is created for each unique typeface required. The Font class provides methods for loading typefaces from various sources, and then for outputting text via the Renderer object.

## Member Function Documentation

void CEGUI::Font::defineFontGlyphs | ( | utf32 | first_code_point,
|  | utf32 | last_code_point
| ) |

Define the range of code points to be renderable by the font.

Note:
  This function can take some time to execute depending upon the size of the code point set, and the size of the font being operated upon.

  The code point arguments must satisfy the following: first_code_point <= last_code_point, otherwise results are undefined

Parameters:

  | first_code_point | utf32 value describing the first code point that will be renderable by this font.
  | last_code_point | utf32 value describing the last code point that will be renderable by this font.

Returns:
  Nothing

Exceptions:

  | InvalidRequestException | thrown if the font is based on a bitmap rather than a true-type font.
  | RendererException | thrown if the Renderer can't support a texture large enough to hold the glyph imagery.
  | MemoryException | thrown if allocation of imagery construction buffer fails.

void CEGUI::Font::defineFontGlyphs | ( | const String & | glyph_set | ) |

Define the set of code points to be renderable by the font.

Note:
  This function can take some time to execute depending upon the size of the code point set, and the size of the font being operated upon.

Parameters:

  | glyph_set | String object describing all the code points that will be renderable by this font

Returns:
  Nothing

Exceptions:

  | InvalidRequestException | thrown if the font is based on a bitmap rather than a true-type font.
  | RendererException | thrown if the Renderer can't support a texture large enough to hold the glyph imagery.
  | MemoryException | thrown if allocation of imagery construction buffer fails.

void CEGUI::Font::drawText | ( | const String & | text,
|  | const Vector3 & | position,
|  | const Rect & | clip_rect,
|  | float | x_scale = `1.0f`,
|  | float | y_scale = `1.0f`
| ) | const`[inline]`

Draw text at the specified location with default colours.

Parameters:

  | text | String object containing the text to be drawn.
  | position | Vector3 object describing the location for the text. NB: The position specified here corresponds to the text baseline and not the top of any glyph. The baseline spacing required can be retrieved by calling getBaseline().
  | clip_rect | Rect object describing the clipping area for the drawing. No drawing will occur outside this Rect.
  | x_scale | Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  | y_scale | Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.

Returns:
  Nothing.

void CEGUI::Font::drawText | ( | const String & | text,
|  | const Vector3 & | position,
|  | const Rect & | clip_rect,
|  | const ColourRect & | colours,
|  | float | x_scale = `1.0f`,
|  | float | y_scale = `1.0f`
| ) | const`[inline]`

Draw text at the specified location.

Parameters:

  | text | String object containing the text to be drawn.
  | position | Vector3 object describing the location for the text. NB: The position specified here corresponds to the text baseline and not the top of any glyph. The baseline spacing required can be retrieved by calling getBaseline().
  | clip_rect | Rect object describing the clipping area for the drawing. No drawing will occur outside this Rect.
  | colours | ColourRect object describing the colours to be applied when drawing the text. NB: The colours specified in here are applied to each glyph, rather than the text as a whole.
  | x_scale | Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  | y_scale | Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.

Returns:
  Nothing.

void CEGUI::Font::drawText | ( | const String & | text,
|  | const Rect & | draw_area,
|  | float | z,
|  | float | x_scale = `1.0f`,
|  | float | y_scale = `1.0f`
| ) | const`[inline]`

Draw text into a specified area of the display with default colours and default formatting (LeftAligned).

Parameters:

  | text | String object containing the text to be drawn.
  | draw_area | Rect object describing the area of the display where the text is to be rendered. The text is formatted using this Rect depending upon the option specified in fmt. Additionally, the drawn text is clipped to be within this Rect (applies to non-word wrapped formatting where the text may otherwise have fallen outside this Rect).
  | z | flat value specifying the z co-ordinate for the drawn text.
  | x_scale | Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  | y_scale | Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.

Returns:
  Nothing.

size_t CEGUI::Font::drawText | ( | const String & | text,
|  | const Rect & | draw_area,
|  | float | z,
|  | TextFormatting | fmt,
|  | float | x_scale = `1.0f`,
|  | float | y_scale = `1.0f`
| ) | const`[inline]`

Draw text into a specified area of the display with default colours.

Parameters:

  | text | String object containing the text to be drawn.
  | draw_area | Rect object describing the area of the display where the text is to be rendered. The text is formatted using this Rect depending upon the option specified in fmt. Additionally, the drawn text is clipped to be within this Rect (applies to non-word wrapped formatting where the text may otherwise have fallen outside this Rect).
  | z | flat value specifying the z co-ordinate for the drawn text.
  | fmt | One of the TextFormatting values specifying the text formatting required.
  | x_scale | Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  | y_scale | Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.

Returns:
  The number of lines output. NB: This does not consider clipping, so if all text was clipped, this would still return >=1.

size_t CEGUI::Font::drawText | ( | const String & | text,
|  | const Rect & | draw_area,
|  | float | z,
|  | TextFormatting | fmt,
|  | const ColourRect & | colours,
|  | float | x_scale = `1.0f`,
|  | float | y_scale = `1.0f`
| ) | const`[inline]`

Draw text into a specified area of the display.

Parameters:

  | text | String object containing the text to be drawn.
  | draw_area | Rect object describing the area of the display where the text is to be rendered. The text is formatted using this Rect depending upon the option specified in fmt. Additionally, the drawn text is clipped to be within this Rect (applies to non-word wrapped formatting where the text may otherwise have fallen outside this Rect).
  | z | flat value specifying the z co-ordinate for the drawn text.
  | fmt | One of the TextFormatting values specifying the text formatting required.
  | colours | ColourRect object describing the colours to be applied when drawing the text. NB: The colours specified in here are applied to each glyph, rather than the text as a whole.
  | x_scale | Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  | y_scale | Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.

Returns:
  The number of lines output. NB: This does not consider clipping, so if all text was clipped, this would still return >=1.

void CEGUI::Font::drawText | ( | const String & | text,
|  | const Rect & | draw_area,
|  | float | z,
|  | const Rect & | clip_rect,
|  | float | x_scale = `1.0f`,
|  | float | y_scale = `1.0f`
| ) | const`[inline]`

Draw text into a specified area of the display with default colours and default formatting (LeftAligned).

Parameters:

  | text | String object containing the text to be drawn.
  | draw_area | Rect object describing the area of the display where the text is to be rendered. The text is not clipped to this Rect, but is formatted using this Rect depending upon the option specified in fmt.
  | z | flat value specifying the z co-ordinate for the drawn text.
  | clip_rect | Rect object describing the clipping area for the drawing. No drawing will occur outside this Rect.
  | x_scale | Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  | y_scale | Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.

Returns:
  Nothing.

size_t CEGUI::Font::drawText | ( | const String & | text,
|  | const Rect & | draw_area,
|  | float | z,
|  | const Rect & | clip_rect,
|  | TextFormatting | fmt,
|  | float | x_scale = `1.0f`,
|  | float | y_scale = `1.0f`
| ) | const`[inline]`

Draw text into a specified area of the display using default colours.

Parameters:

  | text | String object containing the text to be drawn.
  | draw_area | Rect object describing the area of the display where the text is to be rendered. The text is not clipped to this Rect, but is formatted using this Rect depending upon the option specified in fmt.
  | z | flat value specifying the z co-ordinate for the drawn text.
  | clip_rect | Rect object describing the clipping area for the drawing. No drawing will occur outside this Rect.
  | fmt | One of the TextFormatting values specifying the text formatting required.
  | x_scale | Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  | y_scale | Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.

Returns:
  The number of lines output. NB: This does not consider clipping, so if all text was clipped, this would still return >=1.

size_t CEGUI::Font::drawText | ( | const String & | text,
|  | const Rect & | draw_area,
|  | float | z,
|  | const Rect & | clip_rect,
|  | TextFormatting | fmt,
|  | const ColourRect & | colours,
|  | float | x_scale = `1.0f`,
|  | float | y_scale = `1.0f`
| ) | const

Draw text into a specified area of the display.

Parameters:

  | text | String object containing the text to be drawn.
  | draw_area | Rect object describing the area of the display where the text is to be rendered. The text is not clipped to this Rect, but is formatted using this Rect depending upon the option specified in fmt.
  | z | flat value specifying the z co-ordinate for the drawn text.
  | clip_rect | Rect object describing the clipping area for the drawing. No drawing will occur outside this Rect.
  | fmt | One of the TextFormatting values specifying the text formatting required.
  | colours | ColourRect object describing the colours to be applied when drawing the text. NB: The colours specified in here are applied to each glyph, rather than the text as a whole.
  | x_scale | Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.
  | y_scale | Scaling factor to be applied to each glyph's y axis, where 1.0f is considered to be 'normal'.

Returns:
  The number of lines output. NB: This does not consider clipping, so if all text was clipped, this would still return >=1.

const String & CEGUI::Font::getAvailableGlyphs | ( | void |  | ) | const

Return a String object that contains the code-points that the font is currently configured to render.

Returns:
  Reference to a String object.

float CEGUI::Font::getBaseline | ( | float | y_scale = `1.0f` | ) | const`[inline]`

Return the number of pixels from the top of the highest glyph to the baseline.

Parameters:

  | y_scale | Scaling factor to be applied to the baseline distance, where 1.0f is considered to be 'normal'.

Returns:
  pixel spacing from top of front glyphs to baseline

size_t CEGUI::Font::getCharAtPixel | ( | const String & | text,
|  | size_t | start_char,
|  | float | pixel,
|  | float | x_scale = `1.0f`
| ) | const

Return the index of the closest text character in String text, starting at character index start_char, that corresponds to pixel location pixel if the text were to be rendered.

Parameters:

  | text | String object containing the text.
  | start_char | index of the first character to consider. This is the lowest value that will be returned from the call.
  | pixel | Specifies the (horizontal) pixel offset to return the character index for.
  | x_scale | Scaling factor to be applied to each glyph's x axis when measuring the text extent, where 1.0f is considered to be 'normal'.

Returns:
  Returns a character index into String text for the character that would be rendered closest to horizontal pixel offset pixel if the text were to be rendered via this Font. Range of the return is from 0 to text.length(), so may actually return an index past the end of the string, which indicates pixel was beyond the last character.

size_t CEGUI::Font::getCharAtPixel | ( | const String & | text,
|  | float | pixel,
|  | float | x_scale = `1.0f`
| ) | const`[inline]`

Return the index of the closest text character in String text that corresponds to pixel location pixel if the text were rendered.

Parameters:

  | text | String object containing the text.
  | pixel | Specifies the (horizontal) pixel offset to return the character index for.
  | x_scale | Scaling factor to be applied to each glyph's x axis when measuring the text extent, where 1.0f is considered to be 'normal'.

Returns:
  Returns a character index into String text for the character that would be rendered closest to horizontal pixel offset pixel if the text were to be rendered via this Font. Range of the return is from 0 to text.length(), so may actually return an index past the end of the string, which indicates pixel was beyond the last character.

float CEGUI::Font::getFontHeight | ( | float | y_scale = `1.0f` | ) | const`[inline]`

return the exact pixel height of the font.

Parameters:

  | y_scale | Scaling factor to be applied to the height, where 1.0f is considered to be 'normal'.

Returns:
  float value describing the pixel height of the font without any additional padding.

size_t CEGUI::Font::getFormattedLineCount | ( | const String & | text,
|  | const Rect & | format_area,
|  | TextFormatting | fmt,
|  | float | x_scale = `1.0f`
| ) | const

Return the number of lines the given text would be formatted to.

Since text formatting can result in multiple lines of text being output, it can be useful to know how many lines would be output without actually rendering the text.

Parameters:

  | text | String object containing the text to be measured.
  | format_area | Rect object describing the area to be used when formatting the text depending upon the option specified in fmt.
  | fmt | One of the TextFormatting values specifying the text formatting required.
  | x_scale | Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.

Returns:
  The number of lines produced from the specified formatting

float CEGUI::Font::getFormattedTextExtent | ( | const String & | text,
|  | const Rect & | format_area,
|  | TextFormatting | fmt,
|  | float | x_scale = `1.0f`
| ) | const

Return the horizontal pixel extent given text would be formatted to.

The value return by this method is basically the extent of the widest line within the formatted text.

Parameters:

  | text | String object containing the text to be measured.
  | format_area | Rect object describing the area to be used when formatting the text depending upon the option specified in fmt.
  | fmt | One of the TextFormatting values specifying the text formatting required.
  | x_scale | Scaling factor to be applied to each glyph's x axis, where 1.0f is considered to be 'normal'.

Returns:
  The widest pixel extent of the lines produced from the specified formatting.

float CEGUI::Font::getLineSpacing | ( | float | y_scale = `1.0f` | ) | const`[inline]`

Return the pixel line spacing value for.

Parameters:

  | y_scale | Scaling factor to be applied to the line spacing, where 1.0f is considered to be 'normal'.

Returns:
  Number of pixels between vertical base lines, i.e. The minimum pixel space between two lines of text.

const String& CEGUI::Font::getName | ( | void |  | ) | const`[inline]`

Return the name of this font.

Returns:
  String object holding the name of this font.

Size CEGUI::Font::getNativeResolution | ( | void |  | ) | const`[inline]`

Return the native display size for this Font. This is only relevant if the Font is being auto-scaled.

Returns:
  Size object describing the native display size for this Font.

uint CEGUI::Font::getPointSize | ( | void |  | ) | const

Return the point size of a dynamic (ttf based) font.

Returns:
  uint value indicating the point size specified when the dynamic font was created.

Exceptions:

  | InvalidRequestException | thrown if the font is a static (bitmap based) font which do not support point sizes.

float CEGUI::Font::getTextExtent | ( | const String & | text,
|  | float | x_scale = `1.0f`
| ) | const

Return the pixel width of the specified text if rendered with this Font.

Parameters:

  | text | String object containing the text to return the rendered pixel width for.
  | x_scale | Scaling factor to be applied to each glyph's x axis when measuring the extent, where 1.0f is considered to be 'normal'.

Returns:
  Number of pixels that text will occupy when rendered with this Font.

bool CEGUI::Font::isAntiAliased | ( | void |  | ) | const

Return whether this font is anti-aliased or not. This is only relevant for dynamic fonts created from a TrueType font file.

Returns:
  - true if the font is anti-aliased.
  - false if the font is not anti-aliased.

bool CEGUI::Font::isAutoScaled | ( | void |  | ) | const`[inline]`

Return whether this Font is auto-scaled.

Returns:
  true if the Font is auto-scaled, false if not.

bool CEGUI::Font::isCodepointAvailable | ( | utf32 | cp | ) | const`[inline]`

Return whether this Font can currently draw the specified code-point.

Parameters:

  | cp | utf32 code point that is the subject of the query.

Returns:
  true if the font contains a mapping for code point cp, false if it does not contain a mapping for cp.

void CEGUI::Font::notifyScreenResolution | ( | const Size & | size | ) |

Notify the Font of the current (usually new) display resolution.

Parameters:

  | size | Size object describing the display resolution

Returns:
  Nothing

void CEGUI::Font::setAntiAliased | ( | bool | setting | ) |

Set whether the font is anti-aliased or not. Only relevant for dynamic fonts, this setting is ignored for bitmapped fonts.

Parameters:

  setting

  - true if the font should be anti-aliased.
  - false if the font should not be anti-aliased.

Returns:
  Nothing.

void CEGUI::Font::setAutoScalingEnabled | ( | bool | setting | ) |

Enable or disable auto-scaling for this Font.

Parameters:

  | setting | true to enable auto-scaling, false to disable auto-scaling.

Returns:
  Nothing.

void CEGUI::Font::setNativeResolution | ( | const Size & | size | ) |

Set the native resolution for this Font.

Parameters:

  | size | Size object describing the new native screen resolution for this Font.

Returns:
  Nothing