Struct LayoutJob 

pub struct LayoutJob {
    pub text: String,
    pub sections: Vec<LayoutSection>,
    pub wrap: TextWrapping,
    pub first_row_min_height: f32,
    pub break_on_newline: bool,
    pub halign: Align,
    pub justify: bool,
    pub round_output_to_gui: bool,
    pub keep_trailing_whitespace: bool,
}

Describes the task of laying out text.

This supports mixing different fonts, color and formats (underline etc).

Pass this to crate::FontsView::layout_job or crate::text::layout.

Example:

use epaint::{Color32, text::{LayoutJob, TextFormat}, FontFamily, FontId};

let mut job = LayoutJob::default();
job.append(
    "Hello ",
    0.0,
    TextFormat {
        font_id: FontId::new(14.0, FontFamily::Proportional),
        color: Color32::WHITE,
        ..Default::default()
    },
);
job.append(
    "World!",
    0.0,
    TextFormat {
        font_id: FontId::new(14.0, FontFamily::Monospace),
        color: Color32::BLACK,
        ..Default::default()
    },
);

As you can see, constructing a LayoutJob is currently a lot of work. It would be nice to have a helper macro for it!

Fields

text: String

The complete text of this job, referenced by LayoutSection.

sections: Vec<LayoutSection>

The different section, which can have different fonts, colors, etc.

Invariant: the sections are ordered by their byte_range, and together cover the whole of Self::text with no gaps and no overlaps. That is: the first section starts at byte 0, the last section ends at text.len(), and each section starts exactly where the previous one ended. This is checked by Self::debug_sanity_check.

wrap: TextWrapping

Controls the text wrapping and elision.

first_row_min_height: f32

The first row must be at least this high. This is in case we lay out text that is the continuation of some earlier text (sharing the same row), in which case this will be the height of the earlier text. In other cases, set this to 0.0.

break_on_newline: bool

If true, all \n characters will result in a new paragraph, starting on a new row.

If false, all \n characters will be ignored and show up as the replacement character.

Default: true.

halign: Align

How to horizontally align the text (Align::LEFT, Align::Center, Align::RIGHT).

justify: bool

Justify text so that word-wrapped rows fill the whole TextWrapping::max_width.

round_output_to_gui: bool

Round output sizes using emath::GuiRounding, to avoid rounding errors in layout code.

keep_trailing_whitespace: bool

If false (default), trailing whitespace is ignored when computing horizontal alignment (Self::halign). This is desirable for labels so that e.g. “Hello “ centers the same as “Hello”.

If true, trailing whitespace is included in the row width used for alignment. This is desirable for text editors where the user expects to see their spaces.

Implementations

impl LayoutJob

pub fn clear(&mut self)

Clear the text and sections while preserving the layout settings.

pub fn simple( text: String, font_id: FontId, color: Color32, wrap_width: f32, ) -> LayoutJob

Break on \n and at the given wrap width.

pub fn simple_format(text: String, format: TextFormat) -> LayoutJob

Break on \n

pub fn simple_singleline( text: String, font_id: FontId, color: Color32, ) -> LayoutJob

Does not break on \n, but shows the replacement character instead.

pub fn single_section(text: String, format: TextFormat) -> LayoutJob

pub fn is_empty(&self) -> bool

pub fn append(&mut self, text: &str, leading_space: f32, format: TextFormat)

Helper for adding a new section when building a LayoutJob.

If the appended text has the same TextFormat as the last section and no leading_space, it is merged into that section instead of adding a new one. This keeps the section count down and lets text shaping (e.g. kerning) work across the appended text, since shaping is done per LayoutSection.

pub fn format_at_byte(&self, byte_idx: ByteIndex) -> &TextFormat

The TextFormat of the section containing the character starting at the given byte index.

If the index is past the end, the format of the last section is returned.

Panics if the job has no sections. Assumes LayoutJob::sections are ordered by increasing byte_range (as produced by Self::append).

pub fn debug_sanity_check(&self)

Check the Self::sections invariant: the sections are ordered and together cover the whole of Self::text with no gaps and no overlaps.

Only does anything in debug builds.

pub fn font_height(&self, fonts: &mut FontsView<'_>) -> f32

The height of the tallest font used in the job.

Returns a value rounded to emath::GUI_ROUNDING.

pub fn effective_wrap_width(&self) -> f32

The wrap with, with a small margin in some cases.

Trait Implementations

impl Clone for LayoutJob

fn clone(&self) -> LayoutJob

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for LayoutJob

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for LayoutJob

fn default() -> LayoutJob

Returns the “default value” for a type.

impl From<LayoutJob> for WidgetText

fn from(layout_job: LayoutJob) -> Self

Converts to this type from the input type.

impl Hash for LayoutJob

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl PartialEq for LayoutJob

fn eq(&self, other: &LayoutJob) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for LayoutJob