Class that encapsulates a typeface. More...

Inherits CEGUI::PropertySet, CEGUI::EventSet, and CEGUI::AllocatedObject< Font >.

Inherited by CEGUI::FreeTypeFont, and CEGUI::PixmapFont.

Collaboration diagram for CEGUI::Font:

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.

const String &	getFileName () const
	Return the filename of the used font.

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

float	drawText (GeometryBuffer &buffer, const String &text, const Vector2f &position, const Rectf *clip_rect, const ColourRect &colours, const float space_extra=0.0f, const float x_scale=1.0f, const float y_scale=1.0f) const
	Draw text into a specified area of the display. More...

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

const Sizef &	getNativeResolution () const
	Return the native display size for this Font. This is only relevant if the Font is being auto-scaled. More...

void	setAutoScaled (const AutoScaledMode auto_scaled)
	Enable or disable auto-scaling for this Font. More...

AutoScaledMode	getAutoScaled () const
	Checks whether this font is being auto-scaled and how. More...

virtual void	notifyDisplaySizeChanged (const Sizef &size)
	Notify the Font that the display size may have changed. 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) const
	Return the pixel width of the specified text if rendered with this Font. More...

float	getTextAdvance (const String &text, float x_scale=1.0f) const
	Return pixel advance of the specified text when rendered with this Font. More...

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

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

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

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

Property *	getPropertyInstance (const String &name) const
	Retrieves a property instance (that was previously added) 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...

template<typename T >
PropertyHelper< T >::return_type	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...

template<typename T >
void	setProperty (const String &name, typename PropertyHelper< T >::pass_type 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...

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

Public Member Functions inherited from CEGUI::EventSet
	EventSet ()
	Constructor for EventSet objects.

virtual	~EventSet (void)
	Destructor for EventSet objects.

void	addEvent (const String &name)
	Creates a new Event object with the given name and adds it to the EventSet. More...

void	addEvent (Event &event)
	Adds the given Event object to the EventSet. Ownership of the object passes to EventSet and it will be deleted when it is removed from the EventSet - whether explicitly via removeEvent or when the EventSet is destroyed. More...

void	removeEvent (const String &name)
	Removes the Event with the given name. All connections to the event are disconnected, and the underlying Event object is destroyed. More...

void	removeEvent (Event &event)
	Removes the given event from the EventSet. All connections to the event are disconnected, and the event object is destroyed. More...

void	removeAllEvents (void)
	Remove all Event objects from the EventSet. Add connections will be disconnected, and all Event objects destroyed.

bool	isEventPresent (const String &name)
	Checks to see if an Event with the given name is present in this EventSet. More...

virtual Event::Connection	subscribeEvent (const String &name, Event::Subscriber subscriber)
	Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...

virtual Event::Connection	subscribeEvent (const String &name, Event::Group group, Event::Subscriber subscriber)
	Subscribes a handler to the specified group of the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...

template<typename Arg1 , typename Arg2 >
Event::Connection	subscribeEvent (const String &name, Arg1 arg1, Arg2 arg2)
	Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...

template<typename Arg1 , typename Arg2 >
Event::Connection	subscribeEvent (const String &name, Event::Group group, Arg1 arg1, Arg2 arg2)
	Subscribes a handler to the named Event. If the named Event is not yet present in the EventSet, it is created and added. More...

virtual Event::Connection	subscribeScriptedEvent (const String &name, const String &subscriber_name)
	Subscribes the named Event to a scripted funtion. More...

virtual Event::Connection	subscribeScriptedEvent (const String &name, Event::Group group, const String &subscriber_name)
	Subscribes the specified group of the named Event to a scripted funtion. More...

virtual void	fireEvent (const String &name, EventArgs &args, const String &eventNamespace="")
	Fires the named event passing the given EventArgs object. More...

bool	isMuted (void) const
	Return whether the EventSet is muted or not. More...

void	setMutedState (bool setting)
	Set the mute state for this EventSet. More...

Event *	getEventObject (const String &name, bool autoAdd=false)
	Return a pointer to the Event object with the given name, optionally adding such an Event object to the EventSet if it does not already exist. More...

EventIterator	getEventIterator (void) const
	Return a EventSet::EventIterator object to iterate over the events currently added to the EventSet.

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
	Colour value used whenever a colour is not specified.

static const String	EventNamespace
	Event namespace for font events.

static const String	EventRenderSizeChanged

Protected Types
typedef std::map< utf32, FontGlyph, std::less< utf32 > CEGUI_MAP_ALLOC(utf32, FontGlyph)>	CodepointMap
	Definition of CodepointMap type.

Protected Types inherited from CEGUI::EventSet
typedef std::map< String, Event , StringFastLessCompare CEGUI_MAP_ALLOC(String, Event )>	EventMap

Protected Member Functions
	Font (const String &name, const String &type_name, const String &filename, const String &resource_group, const AutoScaledMode auto_scaled, const Sizef &native_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. More...

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.

virtual void	onRenderSizeChanged (FontEventArgs &args)
	event trigger function for when the font rendering size changes.

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

virtual const FontGlyph *	findFontGlyph (const utf32 codepoint) const
	finds FontGlyph in map and returns it, or 0 if none.

Protected Member Functions inherited from CEGUI::EventSet
void	fireEvent_impl (const String &name, EventArgs &args)
	Implementation event firing member.

ScriptModule *	getScriptModule () const
	Helper to return the script module pointer or throw.

	EventSet (EventSet &)

EventSet &	operator= (EventSet &)

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

AutoScaledMode	d_autoScaled
	which mode should we use for auto-scaling

Sizef	d_nativeResolution
	native resolution for this Font.

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

CodepointMap	d_cp_map
	Contains mappings from code points to Image objects.

Protected Attributes inherited from CEGUI::EventSet
EventMap	d_events

bool	d_muted
	true if events for this EventSet have been muted.

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

Additional Inherited Members
Public Types inherited from CEGUI::PropertySet
typedef ConstMapIterator < PropertyRegistry >	PropertyIterator

Public Types inherited from CEGUI::EventSet
typedef ConstMapIterator < EventMap >	EventIterator

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

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

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: The x co-ord where subsequent text should be rendered to ensure correct positioning (which is not possible to determine accurately by using the extent measurement functions).

AutoScaledMode CEGUI::Font::getAutoScaled ( ) const

Checks whether this font is being auto-scaled and how.

Returns: AutoScaledMode describing how this font should be auto scaled

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

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.

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.

const Sizef& 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::getTextAdvance	(	const String &	text,
		float	x_scale = `1.0f`
	)		const

Return pixel advance of the specified text when rendered with this Font.

Parameters

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

Returns: pixel advance of text when rendered with this Font.

Note

The difference between the advance and the extent of a text string is important for numerous reasons. Picture some scenario where a glyph has a swash which extends way beyond the subsequent glyph - the text extent of those two glyphs is to the end of the swash on the first glyph whereas the advance of those two glyphs is to the start of a theoretical third glyph - still beneath the swash of the first glyph. The difference can basically be summarised as follows:

the extent is the total rendered width of all glyphs in the string.
the advance is the width to the point where the next character would have been drawn.

See Also: getTextExtent

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.

Note

The difference between the advance and the extent of a text string is important for numerous reasons. Picture some scenario where a glyph has a swash which extends way beyond the subsequent glyph - the text extent of those two glyphs is to the end of the swash on the first glyph whereas the advance of those two glyphs is to the start of a theoretical third glyph - still beneath the swash of the first glyph. The difference can basically be summarised as follows:

the extent is the total rendered width of all glyphs in the string.
the advance is the width to the point where the next character would have been drawn.

See Also: getTextAdvance

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 Sizef & 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

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 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 AutoScaledMode auto_scaled )

Enable or disable auto-scaling for this Font.

Parameters

auto_scaled AutoScaledMode describing how this font should be auto scaled

See Also: AutoScaledMode

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 Sizef & 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.

const String CEGUI::Font::EventRenderSizeChanged

static

Event fired when the font internal state has changed such that the rendered size of they glyphs is different. Handlers are passed a const FontEventArgs reference with FontEventArgs::font set to the Font whose rendered size has changed.

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Types

Protected Member Functions

Protected Attributes

Static Protected Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

Member Data Documentation