Crazy Eddies GUI System: CEGUI::Font Class Reference

Crazy Eddies GUI System 0.7.6

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

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

Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Types | Protected Member Functions | Protected Attributes | Static Protected Attributes
CEGUI::Font Class Reference

Class that encapsulates a typeface. More...

Inheritance diagram for CEGUI::Font:
[legend]
Collaboration diagram for CEGUI::Font:
[legend]

List of all members.

## Public Member Functions
virtual | ~Font ()
| Destructor.
const String & | getName () const
| Return the string holding the font name.
const String & | getTypeName () const
| Return the type of the font.
bool | isCodepointAvailable (utf32 cp) const
| Return whether this Font can draw the specified code-point.
void | drawText (GeometryBuffer &buffer, const String &text, const Vector2 &position, const Rect *clip_rect, const ColourRect &colours, const float space_extra=0.0f, const float x_scale=1.0f, const float y_scale=1.0f)
| Draw text into a specified area of the display.
void | setNativeResolution (const Size &size)
| Set the native resolution for this Font.
Size | getNativeResolution () const
| Return the native display size for this Font. This is only relevant if the Font is being auto-scaled.
void | setAutoScaled (const bool auto_scaled)
| Enable or disable auto-scaling for this Font.
bool | isAutoScaled () const
| Return whether this Font is auto-scaled.
virtual void | notifyDisplaySizeChanged (const Size &size)
| Notify the Font that the display size may have changed.
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.
float | getTextExtent (const String &text, float x_scale=1.0f) const
| Return the pixel width of the specified text if rendered with this Font.
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.
void | writeXMLToStream (XMLSerializer &xml_stream) const
| Writes an xml representation of this Font to out_stream.
const FontGlyph * | getGlyphData (utf32 codepoint) const
| Return a pointer to the glyphDat struct for the given codepoint, or 0 if the codepoint does not have a glyph defined.
## Static Public Member Functions
static void | setDefaultResourceGroup (const String &resourceGroup)
| Sets the default resource group to be used when loading font data.
static const String & | getDefaultResourceGroup ()
| Returns the default resource group currently set for Fonts.
## Static Public Attributes
static const argb_t | DefaultColour
| Colour value used whenever a colour is not specified.
## Protected Types
typedef std::map< utf32, FontGlyph > | CodepointMap
| Definition of CodepointMap type.
## Protected Member Functions
| Font (const String &name, const String &type_name, const String &filename, const String &resource_group, const bool auto_scaled, const float native_horz_res, const float native_vert_res)
| Constructor.
virtual void | rasterise (utf32 start_codepoint, utf32 end_codepoint) const
| This function prepares a certain range of glyphs to be ready for displaying. This means that after returning from this function glyphs from d_cp_map[start_codepoint] to d_cp_map[end_codepoint] should have their d_image member set. If there is an error during rasterisation of some glyph, it's okay to leave the d_image field set to NULL, in which case such glyphs will be skipped from display.
virtual void | updateFont ()=0
| Update the font as needed, according to the current parameters.
virtual void | writeXMLToStream_impl (XMLSerializer &xml_stream) const =0
| implementaion version of writeXMLToStream.
void | addFontProperties ()
| Register all properties of this class.
void | setMaxCodepoint (utf32 codepoint)
| Set the maximal glyph index. This reserves the respective number of bits in the d_glyphPageLoaded array.
## Protected Attributes
String | d_name
| Name of this font.
String | d_type
| Type name string for this font (not used internally)
String | d_filename
| Name of the file used to create this font (font file or imagset)
String | d_resourceGroup
| Name of the font file's resource group.
float | d_ascender
| maximal font ascender (pixels above the baseline)
float | d_descender
| maximal font descender (negative pixels below the baseline)
float | d_height
| (ascender - descender) + linegap
bool | d_autoScale
| true when auto-scaling is enabled.
float | d_nativeHorzRes
| native horizontal resolution for this Imageset.
float | d_nativeVertRes
| native vertical resolution for this Imageset.
float | d_horzScaling
| current horizontal scaling factor.
float | d_vertScaling
| current vertical scaling factor.
utf32 | d_maxCodepoint
| Maximal codepoint for font glyphs.
uint * | d_glyphPageLoaded
| This bitmap holds information about loaded 'pages' of glyphs. A glyph page is a set of 256 codepoints, starting at 256-multiples. For example, the 1st glyph page is 0-255, fourth is 1024-1279 etc. When a specific glyph is required for painting, the corresponding bit is checked to see if the respective page has been rasterised. If not, the rasterise() method is invoked, which prepares the glyphs from the respective glyph page for being painted.
CodepointMap | d_cp_map
| Contains mappings from code points to Image objects.
## Static Protected Attributes
static String | d_defaultResourceGroup
| Holds default resource group for font loading.

## Detailed Description

Class that encapsulates 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.

This class is not specific to any font renderer, it just provides the basic interfaces needed to manage fonts.

## Member Function Documentation

void CEGUI::Font::drawText | ( | GeometryBuffer & | buffer,
|  | const String & | text,
|  | const Vector2 & | position,
|  | const Rect * | clip_rect,
|  | const ColourRect & | colours,
|  | const float | space_extra = `0.0f`,
|  | const float | x_scale = `1.0f`,
|  | const float | y_scale = `1.0f`
| ) |  |

Draw text into a specified area of the display.

Parameters:

  buffer | GeometryBuffer object where the geometry for the text be queued.
  text | String object containing the text to be drawn.
  position | Reference to a Vector2 object describing the location at which the text is to be drawn.
  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.
  space_extra | Number of additional pixels of spacing to be added to space characters.
  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.

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,
|  | 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.

References getCharAtPixel().

Referenced by getCharAtPixel().

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.

static const String& CEGUI::Font::getDefaultResourceGroup | ( |  | ) | `[inline, static]`

Returns the default resource group currently set for Fonts.

Returns:
  String describing the default resource group identifier that will be used when loading font data.

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.

const FontGlyph* CEGUI::Font::getGlyphData | ( | utf32 | codepoint | ) | const

Return a pointer to the glyphDat struct for the given codepoint, or 0 if the codepoint does not have a glyph defined.

Parameters:

  codepoint | utf32 codepoint to return the glyphDat structure for.

Returns:
  Pointer to the glyphDat struct for codepoint, or 0 if no glyph is defined for codepoint.

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.

Size CEGUI::Font::getNativeResolution | ( |  | ) | const

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.

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::isAutoScaled | ( |  | ) | const

Return whether this Font is auto-scaled.

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

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

Return whether this Font can 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.

virtual void CEGUI::Font::notifyDisplaySizeChanged | ( | const Size & | size | ) | `[virtual]`

Notify the Font that the display size may have changed.

Parameters:

  size | Size object describing the display resolution

virtual void CEGUI::Font::rasterise | ( | utf32 | start_codepoint,
|  | utf32 | end_codepoint
| ) |  | const`[protected, virtual]`

This function prepares a certain range of glyphs to be ready for displaying. This means that after returning from this function glyphs from d_cp_map[start_codepoint] to d_cp_map[end_codepoint] should have their d_image member set. If there is an error during rasterisation of some glyph, it's okay to leave the d_image field set to NULL, in which case such glyphs will be skipped from display.

Parameters:

  start_codepoint | The lowest codepoint that should be rasterised
  end_codepoint | The highest codepoint that should be rasterised

Reimplemented in CEGUI::FreeTypeFont.

void CEGUI::Font::setAutoScaled | ( | const bool | auto_scaled | ) |

Enable or disable auto-scaling for this Font.

Parameters:

  auto_scaled | true to enable auto-scaling. false to disable auto-scaling.

static void CEGUI::Font::setDefaultResourceGroup | ( | const String & | resourceGroup | ) | `[inline, static]`

Sets the default resource group to be used when loading font data.

Parameters:

  resourceGroup | String describing the default resource group identifier to be used.

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.

void CEGUI::Font::writeXMLToStream | ( | XMLSerializer & | xml_stream | ) | const

Writes an xml representation of this Font to out_stream.

Parameters:

  xml_stream | Stream where xml data should be output.

Returns:
  Nothing.

## Member Data Documentation

uint* CEGUI::Font::d_glyphPageLoaded`[protected]`

This bitmap holds information about loaded 'pages' of glyphs. A glyph page is a set of 256 codepoints, starting at 256-multiples. For example, the 1st glyph page is 0-255, fourth is 1024-1279 etc. When a specific glyph is required for painting, the corresponding bit is checked to see if the respective page has been rasterised. If not, the rasterise() method is invoked, which prepares the glyphs from the respective glyph page for being painted.

This array is big enough to hold at least max_codepoint bits. If this member is NULL, all glyphs are considered pre-rasterised.