Trait piet_common::TextLayoutBuilder
source · 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 { ... }
}
Expand description
A trait for laying out text.
Required Associated Types§
sourcetype Out: TextLayout
type Out: TextLayout
The type of the generated TextLayout
.
Required Methods§
sourcefn max_width(self, width: f64) -> Self
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.
sourcefn alignment(self, alignment: TextAlignment) -> Self
fn alignment(self, alignment: TextAlignment) -> Self
Set the TextAlignment
to be used for this layout.
sourcefn default_attribute(self, attribute: impl Into<TextAttribute>) -> Self
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.
sourcefn range_attribute(
self,
range: impl RangeBounds<usize>,
attribute: impl Into<TextAttribute>
) -> Self
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();
Provided Methods§
sourcefn font(self, font: FontFamily, font_size: f64) -> Self
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();
sourcefn text_color(self, color: Color) -> Self
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.