class SF::Font

Overview

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 #load_from_file function for the complete list of supported formats.

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

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:

# Load a new font from file
font = SF::Font.from_file("arial.ttf")

# Create a text which uses our font
text1 = SF::Text.new("text", font, 30)

# Create another text using the same font, but with different parameters
text2 = SF::Text.new
text2.font = font
text2.character_size = 50
text2.style = 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

Defined in:

graphics/obj.cr

Constructors

Instance Method Summary

Constructor Detail

def self.from_file(*args, **kwargs) : self #

Shorthand for font = Font.new; font.load_from_file(...); font

Raises InitError on failure


[View source]
def self.from_memory(*args, **kwargs) : self #

Shorthand for font = Font.new; font.load_from_memory(...); font

Raises InitError on failure


[View source]
def self.from_stream(*args, **kwargs) : self #

Shorthand for font = Font.new; font.load_from_stream(...); font

Raises InitError on failure


[View source]
def self.new #

Default constructor

This constructor defines an empty font


[View source]

Instance Method Detail

def dup : Font #
Description copied from class Reference

Returns a shallow copy of this object.

This allocates a new object and copies the contents of self into it.


[View source]
def finalize #

Destructor

Cleans up all the internal resources used by the font


[View source]
def get_glyph(code_point : Int, character_size : Int, bold : Bool, outline_thickness : Number = 0) : Glyph #

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.

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

  • code_point - Unicode code point of the character to get
  • character_size - Reference character size
  • bold - Retrieve the bold version or the regular one?
  • outline_thickness - Thickness of outline (when != 0 the glyph will not be filled)

Returns: The glyph corresponding to code_point and character_size


[View source]
def get_kerning(first : Int, second : Int, character_size : Int) : Float32 #

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.

  • first - Unicode code point of the first character
  • second - Unicode code point of the second character
  • character_size - Reference character size

Returns: Kerning value for first and second, in pixels


[View source]
def get_line_spacing(character_size : Int) : Float32 #

Get the line spacing

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

  • character_size - Reference character size

Returns: Line spacing, in pixels


[View source]
def get_texture(character_size : Int) : Texture #

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.

  • character_size - Reference character size

Returns: Texture containing the glyphs of the requested size


[View source]
def get_underline_position(character_size : Int) : Float32 #

Get the position of the underline

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

  • character_size - Reference character size

Returns: Underline position, in pixels

See also: underline_thickness


[View source]
def get_underline_thickness(character_size : Int) : Float32 #

Get the thickness of the underline

Underline thickness is the vertical size of the underline.

  • character_size - Reference character size

Returns: Underline thickness, in pixels

See also: underline_position


[View source]
def info : Font::Info #

Get the font information

Returns: A structure that holds the font information


[View source]
def load_from_file(filename : String) : Bool #

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.

  • filename - Path of the font file to load

Returns: True if loading succeeded, false if it failed

See also: #load_from_memory, #load_from_stream


[View source]
def load_from_memory(data : Slice) : Bool #

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.

  • data - Slice containing the file data in memory

Returns: True if loading succeeded, false if it failed

See also: #load_from_file, #load_from_stream


[View source]
def load_from_stream(stream : InputStream) : Bool #

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.

  • stream - Source stream to read from

Returns: True if loading succeeded, false if it failed

See also: #load_from_file, #load_from_memory


[View source]