Struct harfbuzz_rs::Font

pub struct Font<'a> { /* fields omitted */ }

A type representing a single font (i.e. a specific combination of typeface and typesize).

It safely wraps hb_font_t.

Font Funcs

A font is one of the most important structures in harfbuzz. It coordinates how glyph information is accessed during shaping. This is done through so-called font funcs.

You can manually define new font funcs according to your needs, in most cases though the default font funcs provided by HarfBuzz will suffice. In that case the creation of a usable font amounts to calling the Font::new constructor with the desired Face.

Parents and Children

Every font except the empty font has a parent font. If a font does not have some font func set, it will automatically use the parent's implementation of that font func. This behavior is useful to effectively "subclass" font objects to use different font function implementations for some font funcs while reusing the parent's implementation for the remaining funcs.

Since every font created by Font::new by default uses HarfBuzz's internal font funcs they can be used as a fallback mechanism by only customizing the font funcs of a sub-font.

Examples

Create a simple font from a Face using the default font funcs:

use harfbuzz_rs::*;
let face = Face::from_file(path, 0).expect("Error reading font file.");
let font = Font::new(face);

Methods

impl<'a> Font<'a>

pub fn new<T: Into<Shared<Face<'a>>>>(face: T) -> Owned<Self>

Create a new font from the specified Face.

This is the default constructor of Font. In many cases it is the best choice if you simply want to shape some text.

The default parent of a font created by this function is the empty font.

Font Functions

The font returned by this function uses the font funcs that come with HarfBuzz for OpenType Fonts. The font funcs can be overwritten using Font::set_font_funcs.

Errors

If for some reason no valid font can be constructed this function will return the empty font.

pub fn empty() -> Owned<Self>

Returns an empty font.

This can be useful when you need a dummy font for whatever reason. Any function you call on the empty font will return some reasonable default value. An empty font is the only font whose .parent() method returns None.

pub fn create_sub_font<T: Into<Shared<Self>>>(font: T) -> Owned<Self>

Create a new sub font from the current font that by default inherits its parent font's face, scale, ppem and font funcs.

The sub-font's parent will be the font on which this method is called.

Creating sub-fonts is especially useful if you want to overwrite some of the font funcs of an already existing font.

Examples

use harfbuzz_rs::*;
let face = Face::from_file(path, 0).expect("Error reading font file.");
let font = Font::new(face).to_shared();

let sub_font = Font::create_sub_font(font.clone());
// we know that sub_font has a parent
assert_eq!(sub_font.parent().unwrap(), font);

pub fn parent(&self) -> Option<Shared<Self>>

Returns a shared pointer to the parent font.

If self is the empty font it returns None.

See also

create_sub_font

Examples

The empty font (and only it) has no parent:

use harfbuzz_rs::Font;

let font = Font::empty();
assert_eq!(font.parent(), None);

pub fn face(&self) -> Shared<Face<'a>>

Returns a shared pointer to the face from which this font was created.

pub fn scale(&self) -> (i32, i32)

Returns the EM scale of the font.

pub fn set_scale(&mut self, x: i32, y: i32)

Sets the EM scale of the font.

pub fn ppem(&self) -> (u32, u32)

pub fn set_ppem(&mut self, x: u32, y: u32)

pub fn set_font_funcs<FuncsType>(&mut self, funcs: FuncsType) where
    FuncsType: 'a + Send + Sync + FontFuncs, 

Sets the font functions that this font will have from a value that implements FontFuncs.

pub fn get_font_h_extents(&self) -> Option<FontExtents>

pub fn get_font_v_extents(&self) -> Option<FontExtents>

pub fn get_nominal_glyph(&self, c: char) -> Option<Glyph>

pub fn get_variation_glyph(&self, c: char, v: char) -> Option<Glyph>

pub fn get_glyph_h_advance(&self, glyph: Glyph) -> Position

Get the horizontal advance width of a glyph.

pub fn get_glyph_v_advance(&self, glyph: Glyph) -> Position

Get the vertical advance width of a glyph.

pub fn get_glyph_h_origin(&self, glyph: Glyph) -> Option<(Position, Position)>

pub fn get_glyph_v_origin(&self, glyph: Glyph) -> Option<(Position, Position)>

pub fn get_glyph_extents(&self, glyph: Glyph) -> Option<GlyphExtents>

pub fn get_glyph_contour_point(
    &self,
    glyph: Glyph,
    point_index: u32
) -> Option<(Position, Position)>

pub fn get_glyph_name(&self, glyph: Glyph) -> Option<String>

pub fn get_glyph_from_name(&self, name: &str) -> Option<Glyph>

Trait Implementations

impl<'a> HarfbuzzObject for Font<'a>

type Raw = hb_font_t

Type of the raw harfbuzz object.

unsafe fn from_raw(raw: *const Self::Raw) -> Self

Creates a reference from a harfbuzz object pointer.

fn as_raw(&self) -> *mut Self::Raw

Returns the underlying harfbuzz object pointer.

unsafe fn reference(&self)

Increases the reference count of the HarfBuzz object.

unsafe fn dereference(&self)

Decreases the reference count of the HarfBuzz object and destroys it if the reference count reaches zero.

impl<'a> Eq for Font<'a>

impl<'a> Send for Font<'a>

impl<'a> PartialEq<Font<'a>> for Font<'a>

fn eq(&self, other: &Font<'a>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Font<'a>) -> bool

This method tests for !=.

impl<'a> Sync for Font<'a>

impl<'a> Debug for Font<'a>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.