sf::Font Class Reference

Class for loading and manipulating character fonts. More...

#include <SFML/Graphics/Font.hpp>

Classes
struct	Info
	Holds various information about a font. More...

Public Member Functions
	Font ()
	Default constructor.
	Font (const Font &copy)
	Copy constructor.
	~Font ()
	Destructor.
bool	loadFromFile (const std::string &filename)
	Load the font from a file.
bool	loadFromMemory (const void *data, std::size_t sizeInBytes)
	Load the font from a file in memory.
bool	loadFromStream (InputStream &stream)
	Load the font from a custom stream.
const Info &	getInfo () const
	Get the font information.
const Glyph &	getGlyph (Uint32 codePoint, unsigned int characterSize, bool bold, float outlineThickness=0) const
	Retrieve a glyph of the font.
bool	hasGlyph (Uint32 codePoint) const
	Determine if this font has a glyph representing the requested code point.
float	getKerning (Uint32 first, Uint32 second, unsigned int characterSize, bool bold=false) const
	Get the kerning offset of two glyphs.
float	getLineSpacing (unsigned int characterSize) const
	Get the line spacing.
float	getUnderlinePosition (unsigned int characterSize) const
	Get the position of the underline.
float	getUnderlineThickness (unsigned int characterSize) const
	Get the thickness of the underline.
const Texture &	getTexture (unsigned int characterSize) const
	Retrieve the texture containing the loaded glyphs of a certain size.
void	setSmooth (bool smooth)
	Enable or disable the smooth filter.
bool	isSmooth () const
	Tell whether the smooth filter is enabled or not.
Font &	operator= (const Font &right)
	Overload of assignment operator.

Detailed Description

Class for loading and manipulating character fonts.

Fonts can be loaded from a file, from memory or from a custom stream, and supports the most common types of fonts.

See the loadFromFile function for the complete list of supported formats.

Once it is loaded, a sf::Font instance provides three types of information about the font:

• Global metrics, such as the line spacing
• Per-glyph metrics, such as bounding box or kerning
• Pixel representation of glyphs

Fonts alone are not very useful: they hold the font data but cannot make anything useful of it. To do so you need to use the sf::Text class, which is able to properly output text with several options such as character size, style, color, position, rotation, etc. This separation allows more flexibility and better performances: indeed a sf::Font is a heavy resource, and any operation on it is slow (often too slow for real-time applications). On the other side, a sf::Text is a lightweight object which can combine the glyphs data and metrics of a sf::Font to display any text on a render target. Note that it is also possible to bind several sf::Text instances to the same sf::Font.

It is important to note that the sf::Text instance doesn't copy the font that it uses, it only keeps a reference to it. Thus, a sf::Font must not be destructed while it is used by a sf::Text (i.e. never write a function that uses a local sf::Font instance for creating a text).

Usage example:

// Declare a new font
sf::Font font;
 
// Load it from a file
if (!font.loadFromFile("arial.ttf"))
{
    // error...
}
 
// Create a text which uses our font
sf::Text text1;
text1.setFont(font);
text1.setCharacterSize(30);
text1.setStyle(sf::Text::Regular);
 
// Create another text using the same font, but with different parameters
sf::Text text2;
text2.setFont(font);
text2.setCharacterSize(50);
text2.setStyle(sf::Text::Italic);

Apart from loading font files, and passing them to instances of sf::Text, you should normally not have to deal directly with this class. However, it may be useful to access the font metrics or rasterized glyphs for advanced usage.

Note that if the font is a bitmap font, it is not scalable, thus not all requested sizes will be available to use. This needs to be taken into consideration when using sf::Text. If you need to display text of a certain size, make sure the corresponding bitmap font that supports that size is used.

See also

sf::Text

Definition at line 48 of file Font.hpp.

Constructor & Destructor Documentation

Font() [1/2]

sf::Font::Font

(

)

Default constructor.

This constructor defines an empty font

Font() [2/2]

sf::Font::Font

(

const Font &

copy

)

Copy constructor.

Parameters

copy	Instance to copy

~Font()

sf::Font::~Font

(

)

Destructor.

Cleans up all the internal resources used by the font

Member Function Documentation

getGlyph()

const Glyph & sf::Font::getGlyph	(	Uint32	codePoint,
		unsigned int	characterSize,
		bool	bold,
		float	outlineThickness = 0 ) const

Retrieve a glyph of the font.

If the font is a bitmap font, not all character sizes might be available. If the glyph is not available at the requested size, an empty glyph is returned.

You may want to use hasGlyph to determine if the glyph exists before requesting it. If the glyph does not exist, a font specific default is returned.

Be aware that using a negative value for the outline thickness will cause distorted rendering.

Parameters

codePoint	Unicode code point of the character to get
characterSize	Reference character size
bold	Retrieve the bold version or the regular one?
outlineThickness	Thickness of outline (when != 0 the glyph will not be filled)

Returns

The glyph corresponding to codePoint and characterSize

getInfo()

const Info & sf::Font::getInfo

(

)

const

Get the font information.

Returns

A structure that holds the font information

getKerning()

float sf::Font::getKerning	(	Uint32	first,
		Uint32	second,
		unsigned int	characterSize,
		bool	bold = false ) const

Get the kerning offset of two glyphs.

The kerning is an extra offset (negative) to apply between two glyphs when rendering them, to make the pair look more "natural". For example, the pair "AV" have a special kerning to make them closer than other characters. Most of the glyphs pairs have a kerning offset of zero, though.

Parameters

first	Unicode code point of the first character
second	Unicode code point of the second character
characterSize	Reference character size

Returns

Kerning value for first and second, in pixels

getLineSpacing()

float sf::Font::getLineSpacing

(

unsigned int

characterSize

)

const

Get the line spacing.

Line spacing is the vertical offset to apply between two consecutive lines of text.

Parameters

characterSize

Reference character size

Returns

Line spacing, in pixels

getTexture()

const Texture & sf::Font::getTexture

(

unsigned int

characterSize

)

const

Retrieve the texture containing the loaded glyphs of a certain size.

The contents of the returned texture changes as more glyphs are requested, thus it is not very relevant. It is mainly used internally by sf::Text.

Parameters

characterSize

Reference character size

Returns

Texture containing the glyphs of the requested size

getUnderlinePosition()

float sf::Font::getUnderlinePosition

(

unsigned int

characterSize

)

const

Get the position of the underline.

Underline position is the vertical offset to apply between the baseline and the underline.

Parameters

characterSize

Reference character size

Returns

Underline position, in pixels

See also

getUnderlineThickness

getUnderlineThickness()

float sf::Font::getUnderlineThickness

(

unsigned int

characterSize

)

const

Get the thickness of the underline.

Underline thickness is the vertical size of the underline.

Parameters

characterSize

Reference character size

Returns

Underline thickness, in pixels

See also

getUnderlinePosition

hasGlyph()

bool sf::Font::hasGlyph

(

Uint32

codePoint

)

const

Determine if this font has a glyph representing the requested code point.

Most fonts only include a very limited selection of glyphs from specific Unicode subsets, like Latin, Cyrillic, or Asian characters.

While code points without representation will return a font specific default character, it might be useful to verify whether specific code points are included to determine whether a font is suited to display text in a specific language.

Parameters

codePoint

Unicode code point to check

Returns

True if the codepoint has a glyph representation, false otherwise

isSmooth()

bool sf::Font::isSmooth

(

)

const

Tell whether the smooth filter is enabled or not.

Returns

True if smoothing is enabled, false if it is disabled

See also

setSmooth

loadFromFile()

bool sf::Font::loadFromFile

(

const std::string &

filename

)

Load the font from a file.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42. Note that this function knows nothing about the standard fonts installed on the user's system, thus you can't load them directly.

Warning

SFML cannot preload all the font data in this function, so the file has to remain accessible until the sf::Font object loads a new font or is destroyed.

Parameters

filename

Path of the font file to load

Returns

True if loading succeeded, false if it failed

See also

loadFromMemory, loadFromStream

loadFromMemory()

bool sf::Font::loadFromMemory	(	const void *	data,
		std::size_t	sizeInBytes )

Load the font from a file in memory.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42.

Warning

SFML cannot preload all the font data in this function, so the buffer pointed by data has to remain valid until the sf::Font object loads a new font or is destroyed.

Parameters

data	Pointer to the file data in memory
sizeInBytes	Size of the data to load, in bytes

Returns

True if loading succeeded, false if it failed

See also

loadFromFile, loadFromStream

loadFromStream()

bool sf::Font::loadFromStream

(

InputStream &

stream

)

Load the font from a custom stream.

The supported font formats are: TrueType, Type 1, CFF, OpenType, SFNT, X11 PCF, Windows FNT, BDF, PFR and Type 42. Warning: SFML cannot preload all the font data in this function, so the contents of stream have to remain valid as long as the font is used.

Warning

SFML cannot preload all the font data in this function, so the stream has to remain accessible until the sf::Font object loads a new font or is destroyed.

Parameters

stream

Source stream to read from

Returns

True if loading succeeded, false if it failed

See also

loadFromFile, loadFromMemory

operator=()

Font & sf::Font::operator=

(

const Font &

right

)

Overload of assignment operator.

Parameters

right

Instance to assign

Returns

Reference to self

setSmooth()

void sf::Font::setSmooth

(

bool

smooth

)

Enable or disable the smooth filter.

When the filter is activated, the font appears smoother so that pixels are less noticeable. However if you want the font to look exactly the same as its source file, you should disable it. The smooth filter is enabled by default.

Parameters

smooth

True to enable smoothing, false to disable it

See also

isSmooth

---

The documentation for this class was generated from the following file:

• Font.hpp