Trait piet::Text

pub trait Text: Clone {
    type TextLayoutBuilder: TextLayoutBuilder<Out = Self::TextLayout>;
    type TextLayout: TextLayout;

    fn font_family(&mut self, family_name: &str) -> Option<FontFamily>;
    fn load_font(&mut self, data: &[u8]) -> Result<FontFamily, Error>;
    fn new_text_layout(
        &mut self,
        text: impl TextStorage
    ) -> Self::TextLayoutBuilder;
}

The Piet text API.

This trait is the interface for text-related functionality, such as font management and text layout.

Required Associated Types

type TextLayoutBuilder: TextLayoutBuilder<Out = Self::TextLayout>

A concrete type that implements the TextLayoutBuilder trait.

type TextLayout: TextLayout

A concrete type that implements the TextLayout trait.

Required Methods

fn font_family(&mut self, family_name: &str) -> Option<FontFamily>

Query the platform for a font with a given name, and return a FontFamily object corresponding to that font, if it is found.

Examples

Trying a preferred font, falling back if it isn’t found.

let text_font = text.font_family("Charter")
    .or_else(|| text.font_family("Garamond"))
    .unwrap_or(FontFamily::SERIF);

fn load_font(&mut self, data: &[u8]) -> Result<FontFamily, Error>

Load the provided font data and make it available for use.

This method takes font data (such as the contents of a file on disk) and attempts to load it, making it subsequently available for use.

If loading is successful, this method will return a FontFamily handle that can be used to select this font when constructing a TextLayout.

Notes

font families and styles:

If you wish to use multiple fonts in a given family, you will need to load them individually. This method will return the same handle for each font in the same family; the handle does not refer to a specific font. This means that if you load bold and regular fonts from the same family, to use the bold version you must, when constructing your TextLayout, pass the family as well as the correct weight.

If you wish to use custom fonts, load each concrete instance of the font-family that you wish to use; that is, if you are using regular, bold, italic, and bold-italic, you should be loading four distinct fonts.

family name masking

If you load a custom font, the family name of your custom font will take precedence over system families of the same name; so your ‘Helvetica’ will potentially interfere with the use of the platform ‘Helvetica’.

Examples

let helvetica_regular = get_font_data("Helvetica-Regular");
let helvetica_bold = get_font_data("Helvetica-Bold");

let regular = text.load_font(&helvetica_regular).unwrap();
let bold = text.load_font(&helvetica_bold).unwrap();
assert_eq!(regular, bold);

let layout = text.new_text_layout("Custom Fonts")
    .font(regular, 12.0)
    .range_attribute(6.., FontWeight::BOLD);

fn new_text_layout(&mut self, text: impl TextStorage) -> Self::TextLayoutBuilder

Create a new layout object to display the provided text.

The returned object is a TextLayoutBuilder; methods on that type can be used to customize the layout.

Internally, the text argument will be stored in an Rc or Arc, so that the layout can be cheaply cloned. To avoid duplicating the storage of text (which is likely also owned elsewhere in your application) you can pass a type such as Rc<str> or Rc<String>; alternatively you can just use String or &static str.

Implementors