Struct Button 

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

A button that emits a message when it is activated.

Activation is a release inside the button, or Enter/Space while it holds focus. A press that is dragged off and released elsewhere is cancelled, which is what makes a touchscreen usable — a finger that lands on the wrong control can be slid away rather than committing.

Implementations

impl<M> Button<M>

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

A primary button carrying message.

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

A button that emits nothing. Useful as a disabled affordance, or when the application only cares about focus.

pub fn no_focus(self) -> Self

Presses without touching focus: the button takes none, and costs none.

An ordinary button takes focus when pressed, which is right for a button somebody tabs to and wrong for a key on an on-screen keyboard — that key is pressed while a field is being typed into, and the field has to keep the caret. Making the key merely unfocusable is not enough either, since pressing an unfocusable node is what drops focus and commits a field.

So this asks for neither. The button still presses, still paints pressed, still emits its message; Tab skips it, and the focus ring never moves.

ui.add(root, Button::new("q", Msg::Key('q')).no_focus(), Rect::new(0, 100, 40, 40));
assert_eq!(ui.focused(), Some(field));

pub fn with_repeat(self, delay_ms: u64, interval_ms: u64) -> Self

Emits again, and again, while a finger stays on it.

A repeating button acts on press rather than on release, which is the only way it could work: repeats have to start while the finger is still down. That is a real change in feel and the reason this is opt-in — an ordinary button emits on release precisely so that sliding off it before letting go cancels the press, and a repeating one gives that up.

Reach for it where holding means more of the same: Backspace on an on-screen keyboard, a stepper’s arrows, a scrollbar’s ends. Not for anything whose second press means something different from its first.

delay_ms is the pause before the first repeat — long enough that an ordinary tap never triggers one — and interval_ms the gap between the rest. The repeats are counted, not emitted: the button has no message channel while it is animating, so whoever owns it collects them with take_repeats once a frame.

Costs nothing when nothing is held. The button asks the tree to wake it only between a press and its release, and answers Wake::Never the moment the finger goes.

pub fn with_icon(self, icon: &'static Icon) -> Self

A shape drawn in place of the label.

For the button whose meaning is a picture — a Backspace key, a scrollbar’s arrow — and specifically for the case where that picture is not reliably in the font. An Icon is filled polygons this crate draws itself, so it is the same on a machine with no fonts installed at all as it is on one with DejaVu.

It takes the label’s place rather than sitting beside it, and it is drawn in the same content colour the label would have used, so it follows the theme and the button’s state without being told. Keep the label anyway: it is what label still reports, which is what a test and an accessibility pass read.

Sized from the button rather than fixed, and kept square — the shortest side decides, so a wide key gets a centred square icon rather than a stretched one.

pub fn set_icon(&mut self, icon: Option<&'static Icon>)

Removes or replaces the icon.

pub const fn icon(&self) -> Option<&'static Icon>

The shape drawn in place of the label, if any.

pub fn with_corner(self, corner: impl Into<String>) -> Self

A small second label in the top-right corner.

What a key on a real keyboard has printed above the character it types: the ! over the 1, the ? over the +. It says what the other state of this button would give, which is the whole reason a keyboard prints it — you cannot discover Shift by pressing Shift if pressing it is what changes the legend.

Drawn at two thirds the label’s size in the same content colour, so it reads as an annotation rather than as a second button. Empty is the normal case and costs nothing.

pub fn set_corner(&mut self, corner: impl Into<String>)

Replaces the corner label.

pub fn corner(&self) -> &str

What is printed in the corner, if anything.

pub fn take_repeats(&mut self) -> u32

Repeats owed since this was last called, and clears the tally.

Zero unless with_repeat was asked for and a finger has been resting on the button for longer than its delay.

Reach for repeats_pending first when polling several buttons: taking needs &mut, and getting one out of the tree costs a repaint of the node whether or not anything had changed.

pub const fn watching_hold(self) -> Self

Reports how long a finger has been resting on it.

The other half of press-and-hold. with_repeat answers “again, and again”; this answers “how long”, which is what a gesture that fires once after a delay needs — a key offering its alternates, a button revealing a menu.

Costs the same as repeating and no more: the button asks the tree to wake it only between a press and its release, so a screen nobody is touching schedules nothing. Read it with held_ms.

pub const fn held_ms(&self) -> Option<u64>

How long the current press has lasted, in milliseconds.

None when nothing is on it. Updated on each tick while held, so it is as fresh as the last one — which for a wake-driven tree means as fresh as whatever asked to be woken.

A free read: unlike Ui::widget_mut, looking does not repaint.

pub const fn repeats_pending(&self) -> u32

Repeats owed, without taking them.

The read that costs nothing. Ui::widget_mut damages the node it hands out — it cannot know whether the caller changed anything — so polling a keyboard’s sixty keys through it repaints the whole keyboard on every frame. This is how a caller finds the one key that owes something before asking for it mutably.

pub const fn is_held(&self) -> bool

Whether a finger is on it now.

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

Sets the colour role. The content colour comes from the theme’s pairing, so the label stays readable whichever role and theme are chosen.

pub fn with_radius(self, radius: Radius) -> Self

Sets the corner rounding token.

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

Sets the font and size.

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

Sets the size, keeping the font.

pub const fn style(&self) -> TextStyle

The font and size the label draws in.

pub fn label(&self) -> &str

The current label.

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

Replaces the label.

pub fn set_message(&mut self, message: Option<M>)

Replaces the message emitted on activation.

pub const fn role(&self) -> Role

The colour role it is drawn in.

Worth reading before writing: Ui::widget_mut repaints whatever it hands out, so a caller restyling a row of buttons at once should skip the ones already right.

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

Replaces the colour role.

What a list of buttons uses to show which one is selected, since a role survives a theme change and a colour does not.

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

Replaces the 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, engine: &mut TextEngine) -> i32

Width this button needs for its label plus comfortable padding.

Takes the engine because with a proportional font the answer is not the character count times anything, and guessing is how a button ends up one letter too narrow in the language it was not tested in.

Trait Implementations

impl<M: Clone> Clone for Button<M>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<M: Debug> Debug for Button<M>

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

Formats the value using the given formatter.

impl<M> Describe for Button<M>

const KIND: &'static str = "button"

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

const DOC: &'static str = "A rectangle somebody presses to make something happen."

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: Clone + 'static> Widget<M> for Button<M>

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

Counts the repeats a held finger has earned, and asks for the next wake.

Counted from the press rather than accumulated from the last tick, so a clock that jumped — a loop that blocked, a snapshot ticking straight past a second — yields the repeats that time actually covered and no more.

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

A held key under reduced motion still repeats.

Motion::None is about movement, not about clocks — the same rule the carousel’s auto-advance follows. Backspace that stopped deleting because somebody turned animations off would be a bug wearing a setting’s clothes.

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.