Struct Checkbox 

pub struct Checkbox<M> { /* private fields */ }

A checkbox with an optional label beside it.

The message is a function of the new value rather than a fixed value, so an application matches on what the checkbox became rather than looking the widget up afterwards. An enum’s tuple variant already is such a function:

enum Message { Muted(bool) }
Checkbox::new("Mute", Message::Muted);

A plain fn pointer rather than a closure, so this needs no allocation, no M: Clone, and works in no_std.

Why there is no indeterminate state

The third state only means anything for a checkbox that summarises other checkboxes — a parent over a list of children — and neither the list nor the hierarchy exists here yet. It is also additive when it does: HTML keeps indeterminate as a property separate from checked precisely because it is a way of drawing a checkbox rather than a third value it can hold. So this stays a bool and gains a flag later, rather than becoming an enum everybody has to match on for a case nothing can currently produce.

Implementations

impl<M> Checkbox<M>

pub fn new(label: impl Into<String>, message: fn(bool) -> M) -> Self

An unchecked box whose message is built from the value it changes to.

pub fn inert(label: impl Into<String>) -> Self

A checkbox that emits nothing, for a value the application reads rather than reacts to.

pub fn with_checked(self, checked: bool) -> Self

Sets the initial value.

pub fn with_role(self, role: Role) -> Self

Sets the colour role of the filled box. The tick comes from the theme’s pairing, so it stays readable whichever role and theme are chosen.

pub fn with_style(self, style: TextStyle) -> Self

Sets the label’s font and size.

pub fn with_size(self, size_px: u16) -> Self

Sets the label’s size, keeping the font.

pub const fn checked(&self) -> bool

Whether the box is ticked.

pub fn set_checked(&mut self, checked: bool)

Sets the value without emitting anything.

The message reports what a person did. An application that assigns here and then receives its own message back would either loop or have to guard against itself, which is the bug this rule exists to prevent.

pub fn label(&self) -> &str

The current label.

pub fn set_label(&mut self, label: impl Into<String>)

Replaces the label.

pub fn set_role(&mut self, role: Role)

Replaces the colour role.

pub fn set_style(&mut self, style: TextStyle)

Replaces the label’s font and size.

For an application that registers a font after building its tree, which is the ordinary case: the tree has to exist before anyone knows whether the font file was there.

pub fn preferred_width(&self, theme: &Theme, engine: &mut TextEngine) -> i32

Width this checkbox needs for its box, its gap and its label.

Takes the theme because the box is a theme metric — a touch theme’s box is 28 logical pixels where a mouse theme’s is 20 — and the engine because with a proportional font the label’s width is not the character count times anything.

Trait Implementations

impl<M: Clone> Clone for Checkbox<M>

fn clone(&self) -> Checkbox<M>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<M: Debug> Debug for Checkbox<M>

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

Formats the value using the given formatter.

impl<M> Describe for Checkbox<M>

const KIND: &'static str = "checkbox"

The name a form file uses for this widget. Kebab-case.

const DOC: &'static str = "A box and a tick: one thing that is either on or off."

One line saying what this widget is, for somebody choosing one.

const GROUP: Group = Group::Input

Which shelf of the catalogue this belongs on.

const ICON: &'static Icon

The widget’s glyph: a small portrait of the thing, for a palette to draw beside — or instead of — its name.

const PROPERTIES: &'static [Property]

Every property, in the order an inspector should show them.

fn get(&self, name: &str) -> Option<Value>

The current value.

fn apply(&mut self, name: &str, value: Value) -> Result<(), Mismatch>

Applies a value, reporting only what went wrong.

fn set(&mut self, name: &str, value: Value) -> Result<(), PropertyError>

Applies a value, reporting what went wrong and where.

impl<M: 'static> Widget<M> for Checkbox<M>

fn describe(&self) -> Option<&dyn DynDescribe>

This widget’s property description, if it has one.

fn describe_mut(&mut self) -> Option<&mut dyn DynDescribe>

The mutable half of describe.

fn measure(&self, ctx: &mut MeasureCtx<'_>, _offered: Offer) -> Measured

How big this widget would like to be, given what the caller can promise.

fn paint(&self, ctx: &mut PaintCtx<'_>, canvas: &mut Pen<'_>)

Draws into canvas, which is already clipped to this widget’s bounds intersected with the damage region being repainted.

fn on_event(&mut self, event: &Event<'_>, ctx: &mut EventCtx<'_, M>) -> Handled

Reacts to an event routed to this widget.

fn accepts_pointer(&self) -> bool

Returns true if the pointer can hit this widget.

fn focusable(&self) -> bool

Returns true if this widget can take keyboard focus.

fn preserves_focus(&self) -> bool

Returns true if a press on this widget should leave focus exactly where it is.

fn animate(&mut self, now_ms: u64) -> Animation

Advances time-based state. Called only while this widget has asked to animate — see EventCtx::request_animation — and stops being called the moment it answers Wake::Never.

fn snap(&mut self, now_ms: u64) -> Animation

Lands whatever is in flight at its end state, without animating it.