CEGUI::Font Class Reference

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

Collaboration diagram for CEGUI::Font:

Collaboration graph
[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 StringgetName (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 StringgetAvailableGlyphs (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


Generated on Sat Nov 26 09:35:33 2005 for Crazy Eddies GUI System by  doxygen 1.4.5