Struct druid::widget::Label

pub struct Label<T> { /* fields omitted */ }

A label that displays static or dynamic text.

This type manages an inner RawLabel, updating its text based on the current Data and Env as required.

If your Data is already text, you may use a RawLabel directly. As a convenience, you can create a RawLabel with the Label::raw constructor method.

A label is the easiest way to display text in Druid. A label is instantiated with some LabelText type, such as an ArcStr or a LocalizedString, and also has methods for setting the default font, font-size, text color, and other attributes.

In addition to being a Widget, Label is also regularly used as a component in other widgets that wish to display text; to facilitate this it has a draw_at method that allows the caller to easily draw the label's text at the desired position on screen.

Examples

Make a label to say something very important:

let font = FontDescriptor::new(FontFamily::SYSTEM_UI)
    .with_weight(FontWeight::BOLD)
    .with_size(48.0);

let important_label = Label::new("WATCH OUT!")
    .with_font(font)
    .with_text_color(Color::rgb(1.0, 0.2, 0.2));

Implementations

impl<T: TextStorage> Label<T>

pub fn raw() -> RawLabel<T>

Create a new RawLabel.

This can display text Data directly.

impl<T: Data> Label<T>

pub fn new(text: impl Into<LabelText<T>>) -> Self

Construct a new Label widget.

use druid::LocalizedString;
use druid::widget::Label;

// Construct a new Label using static string.
let _: Label<u32> = Label::new("Hello world");

// Construct a new Label using localized string.
let text = LocalizedString::new("hello-counter").with_arg("count", |data: &u32, _env| (*data).into());
let _: Label<u32> = Label::new(text);

// Construct a new dynamic Label. Text will be updated when data changes.
let _: Label<u32> = Label::new(|data: &u32, _env: &_| format!("Hello world: {}", data));

pub fn dynamic(text: impl Fn(&T, &Env) -> String + 'static) -> Self

Construct a new dynamic label.

The contents of this label are generated from the data using a closure.

This is provided as a convenience; a closure can also be passed to new, but due to limitations of the implementation of that method, the types in the closure need to be annotated, which is not true for this method.

Examples

The following are equivalent.

use druid::Env;
use druid::widget::Label;
let label1: Label<u32> = Label::new(|data: &u32, _: &Env| format!("total is {}", data));
let label2: Label<u32> = Label::dynamic(|data, _| format!("total is {}", data));

pub fn text(&self) -> ArcStr

Return the current value of the label's text.

pub fn set_text(&mut self, text: impl Into<LabelText<T>>)

Set the label's text.

Note

If you change this property, at runtime, you must ensure that update is called in order to correctly recompute the text. If you are unsure, call request_update explicitly.

pub fn with_text_color(self, color: impl Into<KeyOrValue<Color>>) -> Self

Builder-style method for setting the text color.

The argument can be either a Color or a Key<Color>.

pub fn with_text_size(self, size: impl Into<KeyOrValue<f64>>) -> Self

Builder-style method for setting the text size.

The argument can be either an f64 or a Key<f64>.

pub fn with_font(self, font: impl Into<KeyOrValue<FontDescriptor>>) -> Self

Builder-style method for setting the font.

The argument can be a FontDescriptor or a Key<FontDescriptor> that refers to a font defined in the Env.

pub fn with_line_break_mode(self, mode: LineBreaking) -> Self

Builder-style method to set the LineBreaking behaviour.

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

Builder-style method to set the TextAlignment.

pub fn draw_at(&self, ctx: &mut PaintCtx<'_, '_, '_>, origin: impl Into<Point>)

Draw this label's text at the provided Point, without internal padding.

This is a convenience for widgets that want to use Label as a way of managing a dynamic or localized string, but want finer control over where the text is drawn.

Methods from Deref<Target = RawLabel<ArcStr>>

pub fn set_text_color(&mut self, color: impl Into<KeyOrValue<Color>>)

Set the text color.

The argument can be either a Color or a Key<Color>.

If you change this property, you are responsible for calling request_layout to ensure the label is updated.

pub fn set_text_size(&mut self, size: impl Into<KeyOrValue<f64>>)

Set the text size.

The argument can be either an f64 or a Key<f64>.

If you change this property, you are responsible for calling request_layout to ensure the label is updated.

pub fn set_font(&mut self, font: impl Into<KeyOrValue<FontDescriptor>>)

Set the font.

The argument can be a FontDescriptor or a Key<FontDescriptor> that refers to a font defined in the Env.

If you change this property, you are responsible for calling request_layout to ensure the label is updated.

pub fn set_line_break_mode(&mut self, mode: LineBreaking)

Set the LineBreaking behaviour.

If you change this property, you are responsible for calling request_layout to ensure the label is updated.

pub fn set_text_alignment(&mut self, alignment: TextAlignment)

Set the TextAlignment for this layout.

pub fn draw_at(&self, ctx: &mut PaintCtx<'_, '_, '_>, origin: impl Into<Point>)

Draw this label's text at the provided Point, without internal padding.

This is a convenience for widgets that want to use Label as a way of managing a dynamic or localized string, but want finer control over where the text is drawn.

pub fn baseline_offset(&self) -> f64

Return the offset of the first baseline relative to the bottom of the widget.

Trait Implementations

impl<T> Deref for Label<T>

type Target = RawLabel<ArcStr>

The resulting type after dereferencing.

pub fn deref(&self) -> &Self::Target

Dereferences the value.

impl<T> DerefMut for Label<T>

pub fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl<T: Data> Widget<T> for Label<T>

pub fn event(
    &mut self,
    _ctx: &mut EventCtx<'_, '_>,
    _event: &Event,
    _data: &mut T,
    _env: &Env
)

Handle an event.

pub fn lifecycle(
    &mut self,
    ctx: &mut LifeCycleCtx<'_, '_>,
    event: &LifeCycle,
    data: &T,
    env: &Env
)

Handle a life cycle notification.

pub fn update(
    &mut self,
    ctx: &mut UpdateCtx<'_, '_>,
    _old_data: &T,
    data: &T,
    env: &Env
)

Update the widget's appearance in response to a change in the app's Data or Env.

pub fn layout(
    &mut self,
    ctx: &mut LayoutCtx<'_, '_>,
    bc: &BoxConstraints,
    _data: &T,
    env: &Env
) -> Size

Compute layout.

pub fn paint(&mut self, ctx: &mut PaintCtx<'_, '_, '_>, _data: &T, env: &Env)

Paint the widget appearance.