Trait piet::TextLayoutBuilder

pub trait TextLayoutBuilder: Sized {
    type Out: TextLayout;

    fn max_width(self, width: f64) -> Self;
    fn alignment(self, alignment: TextAlignment) -> Self;
    fn default_attribute(self, attribute: impl Into<TextAttribute>) -> Self;
    fn range_attribute(
        self,
        range: impl RangeBounds<usize>,
        attribute: impl Into<TextAttribute>
    ) -> Self;
    fn build(self) -> Result<Self::Out, Error>;

    fn font(self, font: FontFamily, font_size: f64) -> Self { ... }
    fn text_color(self, color: Color) -> Self { ... }
}

A trait for laying out text.

Required Associated Types

type Out: TextLayout

The type of the generated TextLayout.

Required Methods

fn max_width(self, width: f64) -> Self

Set a max width for this layout.

You may pass an f64 to this method to indicate a width (in display points) that will be used for word-wrapping.

If you pass f64::INFINITY, words will not be wrapped; this is the default behaviour.

fn alignment(self, alignment: TextAlignment) -> Self

Set the TextAlignment to be used for this layout.

fn default_attribute(self, attribute: impl Into<TextAttribute>) -> Self

Add a default TextAttribute for this layout.

Default attributes will be used for regions of the layout that do not have explicit attributes added via range_attribute.

You must set default attributes before setting range attributes, or the implementation is free to ignore them.

fn range_attribute(
    self,
    range: impl RangeBounds<usize>,
    attribute: impl Into<TextAttribute>
) -> Self

Add a TextAttribute to a range of this layout.

The range argument is can be any of the range forms accepted by slice indexing, such as .., ..n, n.., n..m, etcetera.

The attribute argument is a TextAttribute or any type that can be converted to such an attribute; for instance you may pass a FontWeight directly.

Notes

This is a low-level API; what this means in particular is that it is designed to be efficiently implemented, not necessarily ergonomic to use, and there may be a few gotchas.

ranges of added attributes should be added in non-decreasing start order. This is to say that attributes should be added in the order of the start of their ranges. Attributes added out of order may be skipped.

attributes do not stack. Setting the range 0..100 to FontWeight::BOLD and then setting the range 20..50 to FontWeight::THIN will result in the range 50..100 being reset to the default font weight; we will not remember that you had earlier set it to BOLD.

Examples

let times = text.font_family("Times New Roman").unwrap();
let layout = text.new_text_layout("This API is okay, I guess?")
    .font(FontFamily::MONOSPACE, 12.0)
    .default_attribute(FontStyle::Italic)
    .range_attribute(..5, FontWeight::BOLD)
    .range_attribute(5..14, times)
    .range_attribute(20.., TextAttribute::TextColor(Color::rgb(1.0, 0., 0.,)))
    .build();

fn build(self) -> Result<Self::Out, Error>

Attempt to build the TextLayout.

This should only fail in exceptional circumstances.

Provided Methods

fn font(self, font: FontFamily, font_size: f64) -> Self

A convenience method for setting the default font family and size.

Examples

let times = text.font_family("Times New Roman").unwrap();

// the following are equivalent
let layout_one = text.new_text_layout("hello everyone!")
    .font(times.clone(), 12.0)
    .build();

let layout_two = text.new_text_layout("hello everyone!")
    .default_attribute(TextAttribute::FontFamily(times.clone()))
    .default_attribute(TextAttribute::FontSize(12.0))
    .build();

fn text_color(self, color: Color) -> Self

A convenience method for setting the default text color.

This is equivalent to passing TextAttribute::TextColor to the default_attribute method.

Implementors