Site under construction!

Text and fonts

Loading a font

Before drawing any text, you need to have an available font, just like any other program that prints text. Fonts are encapsulated in the Font class, which provides three main features: loading a font, getting glyphs (i.e. visual characters) from it, and reading its attributes. In a typical program, you'll only have to make use of the first feature, loading the font, so let's focus on that first.

The most common way of loading a font is from a file on disk, which is done with the loadFromFile function. 


Font font = new Font();
if (!font.loadFromFile("arial.ttf"))
{
    // error...
}

Note that DSFML won't load your system fonts automatically, i.e. font.loadFromFile("Courier New") won't work. Firstly, because DSFML requires file names, not font names, and secondly because DSFML doesn't have magical access to your system's font folder. If you want to load a font, you will need to include the font file with your application, just like every other resource (images, sounds, ...).

The loadFromFile function can sometimes fail with no obvious reason. First, check the error message that DSFML prints to the standard output (check the console). If the message is 'unable to open file', make sure that the working directory (which is the directory that any file path will be interpreted relative to) is what you think it is: When you run the application from your desktop environment, the working directory is the executable folder. However, when you launch your program from your IDE (Visual Studio, Code::Blocks, ...) the working directory might sometimes be set to the project directory instead. This can usually be changed quite easily in the project settings.

You can also load a font file from memory (loadFromMemory), or from a custom input stream (loadFromStream).

DSFML supports most common font formats. The full list is available in the API documentation.

That's all you need to do. Once your font is loaded, you can start drawing text.

Drawing text

To draw text, you will be using the Text class. It's very simple to use: 


auto text = new Text();

// select the font
text.font = myFont; // myFont is a Font

// set the string to display
text.string = "Hello world";

// set the character size
text.characterSize = 24; // in pixels, not points!

// set the color
text.color = Color.Red;

// set the text style
text.style = (Text.Bold | Text.Underlined);

...

// inside the main loop, between window.clear() and window.display()
window.draw(text);

Text can also be transformed: They have a position, an orientation and a scale. The functions involved are the same as for the Sprite class and other DSFML entities. They are explained in the Transforming entities tutorial.

Using non-ASCII characters

Handling non-ASCII characters (such as accented European, Arabic, or Chinese characters) is easy to do in DSFML. The string of text stored by the Text class uses utf-32, which will be able to handle any character set. Using non-ASCII characters is as simple as providing them to the Text's string property. 


text.string = "יטאח";

Making your own text class

If Text is too limited, or if you want to do something else with pre-rendered glyphs, Font provides everything that you need.

You can retrieve the texture which contains all the pre-rendered glyphs of a certain size: 


auto texture = font.getTexture(characterSize);

It is important to note that glyphs are added to the texture when they are requested. There are so many characters (remember, more than 100000) that they can't all be generated when you load the font. Instead, they are rendered on the fly when you call the getGlyph function (see below).

To do something meaningful with the font texture, you must get the texture coordinates of glyphs that are contained in it: 


auto glyph = font.getGlyph(character, characterSize, bold);

character is the UTF-32 code of the character whose glyph that you want to get. You must also specify the character size, and whether you want the bold or the regular version of the glyph.

The Glyph structure contains three members:

You can also get some of the font's other metrics, such as the kerning between two characters or the line spacing (always for a certain character size): 


int lineHeight = font.getLineHeight(characterSize);

int kerning = font.getKerning(character1, character2, characterSize);