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

Inheritance diagram for CEGUI::Font:

Collaboration diagram for CEGUI::Font:

Public Member Functions
virtual void	load ()=0
	Complete font loading. If you create the font from an XML file, this method is invoked automatically after reading all the required data from the XMLAttributes object. If you create the font manually, it is your responsability to call this function as soon as you set up all the appropiate fields of the Font object.

bool	isCodepointAvailable (utf32 cp) const
	Return whether this Font can draw the specified code-point. More...

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)
	Draw text into a specified area of the display. More...

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)
	Draw text into a specified area of the display using default colours. More...

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)
	Draw text into a specified area of the display with default colours and default formatting (LeftAligned). More...

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)
	Draw text into a specified area of the display. More...

size_t	drawText (const String &text, const Rect &draw_area, float z, TextFormatting fmt, float x_scale=1.0f, float y_scale=1.0f)
	Draw text into a specified area of the display with default colours. More...

void	drawText (const String &text, const Rect &draw_area, float z, float x_scale=1.0f, float y_scale=1.0f)
	Draw text into a specified area of the display with default colours and default formatting (LeftAligned). More...

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)
	Draw text at the specified location. More...

void	drawText (const String &text, const Vector3 &position, const Rect &clip_rect, float x_scale=1.0f, float y_scale=1.0f)
	Draw text at the specified location with default colours. More...

virtual void	setNativeResolution (const Size &size)
	Set the native resolution for this Font. More...

virtual void	notifyScreenResolution (const Size &size)
	Notify the Font of the current (usually new) display resolution. More...

float	getLineSpacing (float y_scale=1.0f) const
	Return the pixel line spacing value for. More...

float	getFontHeight (float y_scale=1.0f) const
	return the exact pixel height of the font. More...

float	getBaseline (float y_scale=1.0f) const
	Return the number of pixels from the top of the highest glyph to the baseline. More...

float	getTextExtent (const String &text, float x_scale=1.0f)
	Return the pixel width of the specified text if rendered with this Font. More...

size_t	getCharAtPixel (const String &text, float pixel, float x_scale=1.0f)
	Return the index of the closest text character in String text that corresponds to pixel location pixel if the text were rendered. More...

size_t	getCharAtPixel (const String &text, size_t start_char, float pixel, float x_scale=1.0f)
	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. More...

size_t	getFormattedLineCount (const String &text, const Rect &format_area, TextFormatting fmt, float x_scale=1.0f)
	Return the number of lines the given text would be formatted to. More...

float	getFormattedTextExtent (const String &text, const Rect &format_area, TextFormatting fmt, float x_scale=1.0f)
	Return the horizontal pixel extent given text would be formatted to. More...

Public Member Functions inherited from CEGUI::PropertySet
	PropertySet (void)
	Constructs a new PropertySet object.

virtual	~PropertySet (void)
	Destructor for PropertySet objects.

void	addProperty (Property *property)
	Adds a new Property to the PropertySet. More...

void	removeProperty (const String &name)
	Removes a Property from the PropertySet. More...

void	clearProperties (void)
	Removes all Property objects from the PropertySet. More...

bool	isPropertyPresent (const String &name) const
	Checks to see if a Property with the given name is in the PropertySet. More...

const String &	getPropertyHelp (const String &name) const
	Return the help text for the specified Property. More...

String	getProperty (const String &name) const
	Gets the current value of the specified Property. More...

void	setProperty (const String &name, const String &value)
	Sets the current value of a Property. More...

bool	isPropertyDefault (const String &name) const
	Returns whether a Property is at it's default value. More...

String	getPropertyDefault (const String &name) const
	Returns the default value of a Property as a String. More...

Iterator	getIterator (void) const
	Return a PropertySet::Iterator object to iterate over the available Properties.

Static Public Member Functions
static void	setDefaultResourceGroup (const String &resourceGroup)
	Sets the default resource group to be used when loading font data. More...

static const String &	getDefaultResourceGroup ()
	Returns the default resource group currently set for Fonts. More...

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

Protected Types
typedef std::map< utf32, FontGlyph >	CodepointMap

Protected Member Functions
	Font (const String &name, const String &fontname, const String &resourceGroup="")
	Constructs a new semi-complete Font object. It is the responsability of the user to set up all remaining font parameters after constructing the Font object, and finally calling the load() method which will make font available for use. All font parameters that are not initialized are set to sensible default values. More...

	Font (const XMLAttributes &attributes)
	Constructs a new Font object and instantly loads it. The font is ready for use right after creation, there is no need to load() it. All data required by this font is loaded from the provided XMLAttributes object. More...

virtual	~Font ()
	Destroys a Font object.

virtual void	defineMapping (const XMLAttributes &attributes)
	Define a glyph mapping (handle a <Mapping> XML element)

virtual void	updateFont ()=0
	Update the font as required according to the current parameters.

size_t	drawWrappedText (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)
	draws wrapped text. returns number of lines output.

size_t	getNextWord (const String &in_string, size_t start_idx, String &out_string) const
	helper function for renderWrappedText to get next word of a string

void	drawTextLine (const String &text, const Vector3 &position, const Rect &clip_rect, const ColourRect &colours, float x_scale=1.0f, float y_scale=1.0f)
	Draw a line of text. No formatting is applied.

void	drawTextLineJustified (const String &text, const Rect &draw_area, const Vector3 &position, const Rect &clip_rect, const ColourRect &colours, float x_scale=1.0f, float y_scale=1.0f)
	Draw a justified line of text.

float	getWrappedTextExtent (const String &text, float wrapWidth, float x_scale=1.0f)
	returns extent of widest line of wrapped text.

const FontGlyph *	getGlyphData (utf32 codepoint)
	Return a pointer to the glyphDat struct for the given codepoint, or 0 if the codepoint does not have a glyph defined. More...

void	setMaxCodepoint (utf32 codepoint)
	Set the maximal glyph index. This reserves the respective number of bits in the d_glyphPageLoaded array.

virtual void	rasterize (utf32 start_codepoint, utf32 end_codepoint)
	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 rasterization 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. More...

void	writeXMLToStream (XMLSerializer &xml_stream) const
	Writes an xml representation of this Font to out_stream. More...

virtual void	writeXMLToStream_impl (XMLSerializer &xml_stream) const =0
	Same as writeXMLToStream() but called from inside writeXMLToStream() so that derived classes may add their own attributes to stream. More...

void	addFontProperties ()
	Register all properties of this class.

Protected Attributes
CodepointMap	d_cp_map
	Contains mappings from code points to Image objects.

String	d_name
	Name of this font.

String	d_fileName
	Holds the name of the file used to create this font (either font file or imagset)

String	d_resourceGroup
	Holds the 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_horzScaling
	current horizontal scaling factor.

float	d_vertScaling
	current vertical scaling factor.

float	d_nativeHorzRes
	native horizontal resolution for this Imageset.

float	d_nativeVertRes
	native vertical resolution for this Imageset.

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 rasterized. If not, the rasterize() method is invoked, which prepares the glyphs from the respective glyph page for being painted. More...

Static Protected Attributes
static String	d_defaultResourceGroup
	hold default resource group for font loading.

Friends
class	FontManager

class	Font_xmlHandler

class	FontProperties::NativeRes

class	FontProperties::Name

class	FontProperties::FileName

class	FontProperties::ResourceGroup

class	FontProperties::AutoScaled

Additional Inherited Members
Public Types inherited from CEGUI::PropertySet
typedef ConstBaseIterator < PropertyRegistry >	Iterator

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.

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

Constructor & Destructor Documentation

CEGUI::Font::Font	(	const String &	name,
		const String &	fontname,
		const String &	resourceGroup = `""`
	)

protected

Constructs a new semi-complete Font object. It is the responsability of the user to set up all remaining font parameters after constructing the Font object, and finally calling the load() method which will make font available for use. All font parameters that are not initialized are set to sensible default values.

Parameters

name	The unique name that will be used to identify this Font.
fontname	The filename of the font file, which contains the font data. This can be a TrueType, PostScript, bitmap font etc file.
resourceGroup	Resource group identifier to be passed to the resource provider to load the font definition file.

References addFontProperties().

CEGUI::Font::Font ( const XMLAttributes & attributes )

protected

Constructs a new Font object and instantly loads it. The font is ready for use right after creation, there is no need to load() it. All data required by this font is loaded from the provided XMLAttributes object.

Parameters

attributes The XML attributes attached to this Font.

Exceptions

FileIOException	thrown if there was some problem accessing or parsing the file filename
InvalidRequestException	thrown if an invalid filename was provided.
AlreadyExistsException	thrown if a Font Imageset clashes with one already defined in the system.
GenericException	thrown if something goes wrong while accessing a true-type font referenced in file filename.
RendererException	thrown if the Renderer can't support a texture large enough to hold the requested glyph imagery.
MemoryException	thrown if allocation of imagery construction buffer fails.

References addFontProperties(), d_horzScaling, d_nativeHorzRes, d_nativeVertRes, d_vertScaling, CEGUI::System::getRenderer(), CEGUI::System::getSingleton(), and CEGUI::Renderer::getSize().

Member Function Documentation

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`
	)

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.

References CEGUI::Centred, drawTextLine(), drawTextLineJustified(), drawWrappedText(), CEGUI::String::find_first_of(), getBaseline(), getLineSpacing(), getTextExtent(), CEGUI::Rect::getWidth(), CEGUI::Justified, CEGUI::LeftAligned, CEGUI::String::length(), CEGUI::String::npos, CEGUI::RightAligned, CEGUI::String::substr(), CEGUI::WordWrapCentred, CEGUI::WordWrapJustified, CEGUI::WordWrapLeftAligned, and CEGUI::WordWrapRightAligned.

Referenced by CEGUI::ListboxTextItem::draw(), CEGUI::TreeItem::draw(), and drawWrappedText().

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`
	)

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.

References drawText().

Referenced by drawText().

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`
	)

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.

References drawText(), and CEGUI::LeftAligned.

Referenced by drawText().

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`
	)

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.

References drawText().

Referenced by drawText().

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`
	)

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.

References drawText().

Referenced by drawText().

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

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.

References drawText(), and CEGUI::LeftAligned.

Referenced by drawText().

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`
	)

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.

References drawText(), and CEGUI::LeftAligned.

Referenced by drawText().

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

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.

References drawText(), and CEGUI::LeftAligned.

Referenced by drawText().

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

Referenced by CEGUI::TreeItem::draw(), drawText(), and CEGUI::FontDim::getValue_impl().

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

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 CEGUI::MultiLineEditbox::formatText(), getCharAtPixel(), CEGUI::FalagardEditbox::getTextIndexFromPosition(), CEGUI::MultiLineEditbox::getTextIndexFromPosition(), CEGUI::MultiLineEditbox::handleLineDown(), and CEGUI::MultiLineEditbox::handleLineUp().

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

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.

References CEGUI::FontGlyph::getAdvance(), getGlyphData(), and CEGUI::String::length().

static const String& CEGUI::Font::getDefaultResourceGroup ( void )

inlinestatic

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.

Referenced by CEGUI::FontManager::createFont(), and CEGUI::FreeTypeFont::updateFont().

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.

Referenced by CEGUI::TabControl::addTab(), CEGUI::FalagardMultiLineEditbox::cacheTextLines(), CEGUI::ListboxTextItem::draw(), and CEGUI::TextComponent::render_impl().

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

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

References CEGUI::String::begin(), CEGUI::Centred, CEGUI::String::clear(), CEGUI::TextUtils::DefaultWhitespace, CEGUI::String::end(), CEGUI::String::find_first_not_of(), CEGUI::String::find_first_of(), getNextWord(), getTextExtent(), CEGUI::Rect::getWidth(), CEGUI::Justified, CEGUI::LeftAligned, CEGUI::String::length(), CEGUI::String::npos, CEGUI::RightAligned, and CEGUI::String::substr().

Referenced by CEGUI::Tooltip::getTextSize_impl(), and CEGUI::TextComponent::render_impl().

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

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.

References CEGUI::Centred, CEGUI::String::find_first_of(), getTextExtent(), CEGUI::Rect::getWidth(), getWrappedTextExtent(), CEGUI::Justified, CEGUI::LeftAligned, CEGUI::String::length(), CEGUI::String::npos, CEGUI::RightAligned, CEGUI::String::substr(), CEGUI::WordWrapCentred, CEGUI::WordWrapJustified, CEGUI::WordWrapLeftAligned, and CEGUI::WordWrapRightAligned.

Referenced by drawTextLineJustified(), and CEGUI::Tooltip::getTextSize_impl().

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

protected

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.

References d_cp_map, d_glyphPageLoaded, d_maxCodepoint, and rasterize().

Referenced by drawTextLine(), drawTextLineJustified(), getCharAtPixel(), and getTextExtent().

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.

Referenced by CEGUI::FalagardMultiLineEditbox::cacheCaratImagery(), CEGUI::FalagardMultiLineEditbox::cacheTextLines(), CEGUI::MultiLineEditbox::configureScrollbars(), CEGUI::ListboxTextItem::draw(), CEGUI::TreeItem::draw(), drawText(), drawWrappedText(), CEGUI::MultiLineEditbox::ensureCaratIsVisible(), CEGUI::ListboxTextItem::getPixelSize(), CEGUI::TreeItem::getPixelSize(), CEGUI::MultiLineEditbox::getTextIndexFromPosition(), CEGUI::Tooltip::getTextSize_impl(), CEGUI::FontDim::getValue_impl(), CEGUI::MultiLineEditbox::handlePageDown(), CEGUI::MultiLineEditbox::handlePageUp(), and CEGUI::TextComponent::render_impl().

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

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.

References CEGUI::FontGlyph::getAdvance(), getGlyphData(), CEGUI::FontGlyph::getRenderedAdvance(), and CEGUI::String::length().

Referenced by CEGUI::FalagardMultiLineEditbox::cacheCaratImagery(), CEGUI::FalagardMultiLineEditbox::cacheTextLines(), CEGUI::TabControl::calculateTabButtonSizePosition(), drawText(), drawTextLineJustified(), drawWrappedText(), CEGUI::MultiLineEditbox::ensureCaratIsVisible(), CEGUI::MultiLineEditbox::formatText(), getFormattedLineCount(), getFormattedTextExtent(), CEGUI::ListboxTextItem::getPixelSize(), CEGUI::TreeItem::getPixelSize(), CEGUI::FontDim::getValue_impl(), getWrappedTextExtent(), CEGUI::MultiLineEditbox::handleLineDown(), and CEGUI::MultiLineEditbox::handleLineUp().

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.

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

virtual

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

Parameters

size	Size object describing the display resolution

Returns: Nothing

References d_autoScale, d_horzScaling, d_nativeHorzRes, d_nativeVertRes, d_vertScaling, and updateFont().

Referenced by setNativeResolution().

void CEGUI::Font::rasterize	(	utf32	start_codepoint,
		utf32	end_codepoint
	)

protectedvirtual

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 rasterization 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 rasterized
end_codepoint	The highest codepoint that should be rasterized

Reimplemented in CEGUI::FreeTypeFont.

Referenced by getGlyphData().

static void CEGUI::Font::setDefaultResourceGroup ( const String & resourceGroup )

inlinestatic

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 )

virtual

Set the native resolution for this Font.

Parameters

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

Returns: Nothing

References d_nativeHorzRes, d_nativeVertRes, CEGUI::System::getSingleton(), and notifyScreenResolution().

Referenced by CEGUI::FontProperties::NativeRes::set().

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

protected

Writes an xml representation of this Font to out_stream.

Parameters

xml_stream Stream where xml data should be output.

Returns: Nothing.

References CEGUI::XMLSerializer::attribute(), CEGUI::XMLSerializer::closeTag(), d_autoScale, d_fileName, d_name, d_nativeHorzRes, d_nativeVertRes, d_resourceGroup, CEGUI::DefaultNativeHorzRes, CEGUI::DefaultNativeVertRes, CEGUI::String::empty(), CEGUI::XMLSerializer::openTag(), and writeXMLToStream_impl().

Referenced by CEGUI::FontManager::writeFontToStream().

virtual void CEGUI::Font::writeXMLToStream_impl ( XMLSerializer & xml_stream ) const

protectedpure virtual

Same as writeXMLToStream() but called from inside writeXMLToStream() so that derived classes may add their own attributes to stream.

Parameters

xml_stream Stream where xml data should be output.

Implemented in CEGUI::FreeTypeFont, and CEGUI::PixmapFont.

Referenced by writeXMLToStream().

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 rasterized. If not, the rasterize() 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-rasterized.

Referenced by getGlyphData(), setMaxCodepoint(), and ~Font().

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Static Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation