Struct Button

pub struct Button<Msg: Clone> {
    pub content: ButtonContent,
    pub on_press: Option<Msg>,
    pub on_long_press: Option<Msg>,
    pub on_drag_start: Option<Msg>,
    pub variant: ButtonVariant,
    pub icon_size: f32,
    pub id: Option<WidgetId>,
    pub focusable: bool,
    pub cursor: Option<CursorShape>,
    pub repeating: bool,
    pub tooltip: Option<String>,
}

A pressable button widget.

Create text buttons with button() and icon buttons with icon_button(). Buttons that step a value (date / time pickers, numeric spinners) can opt into press-and- hold repeat via Self::repeating — the runtime then re-fires on_press while the button is held, at the keyboard’s repeat cadence.

Fields

content: ButtonContent

The visual content of this button.

on_press: Option<Msg>

Message emitted when the button is pressed, or None if disabled.

on_long_press: Option<Msg>

Message emitted when the user holds the button for App::long_press_duration without moving past the tolerance, OR when the user right-clicks with the mouse. None leaves the button without a context-menu equivalent. The fire does NOT by itself put the gesture into drag mode — that is governed by Self::on_drag_start.

on_drag_start: Option<Msg>

Drag-arm message. Fires when the press transitions into a drag: touch on hold-timer expiry (in addition to on_long_press), mouse on motion past the drag-promotion threshold (without firing the menu). Independent of on_long_press so a button can open a menu without becoming draggable, or be draggable without showing a menu.

variant: ButtonVariant

Visual variant controlling colors and borders.

icon_size: f32

Width and height in pixels for icon buttons. Defaults to 48.0.

id: Option<WidgetId>

Optional stable identifier for focus management.

focusable: bool

Whether this button participates in keyboard focus (Tab). Default: true.

cursor: Option<CursorShape>

Override the pointer cursor shape on hover. None falls back to the Pointer (hand) default for clickable widgets.

repeating: bool

When true, holding the button down auto-fires the on_press message: one immediate fire on press, then an initial delay (≈ 500 ms — same as the keyboard) followed by repeats every ~120 ms (≈ 8 Hz, deliberately slower than the keyboard’s 30 Hz so a stepper does not whip past the target). The runtime cancels the timer on release, on touch cancel, and on long-press promotion. Default false — most buttons fire on tap only.

tooltip: Option<String>

Implementations

impl<Msg: Clone> Button<Msg>

pub fn new(label: String) -> Self

Create a text button with the given label.

pub fn tooltip(self, text: impl Into<String>) -> Self

Hint shown after a 600 ms pointer dwell. Pointer-only.

pub fn cursor(self, shape: CursorShape) -> Self

Override the pointer cursor shape shown on hover.

pub fn new_icon(rgba: Arc<Vec<u8>>, img_w: u32, img_h: u32) -> Self

Create an icon button from a shared RGBA buffer.

img_w and img_h must match the dimensions of rgba.

pub fn on_press(self, msg: Msg) -> Self

Set the message emitted when the button is pressed.

pub fn on_press_maybe(self, msg: Option<Msg>) -> Self

Optionally set the message — None leaves the button disabled.

pub fn repeating(self, on: bool) -> Self

Auto-fire on_press while the button is held down. The runtime fires once on press, then re-fires after the keyboard’s repeat delay (≈ 500 ms) and at a fixed ~120 ms (≈ 8 Hz) interval afterwards — slow enough to release on the value the user wants, fast enough to ramp. Each tick re-reads on_press from the live widget tree, so a stepper-style button whose message is "go to value + 1" keeps stepping correctly as the value updates.

Mutually compatible with on_long_press only in spirit — once the long-press message fires the gesture machine transitions to drag mode and the repeat timer is cancelled regardless of repeating. Default false.

pub fn on_long_press(self, msg: Msg) -> Self

Attach a long-press message. Fires when the press has been held stationary for App::long_press_duration, or when the user right-clicks with the mouse. By itself this does NOT put the gesture into drag mode — that is governed by Self::on_drag_start. The regular on_press is suppressed only when the press has been promoted to a drag (drag-arm fired).

pub fn on_drag_start(self, msg: Msg) -> Self

Attach a drag-arm message. Fires when the press transitions into drag mode — touch on hold-timer expiry (alongside on_long_press), mouse on motion past the drag-promotion threshold (without firing on_long_press). Independent of the menu so a button can be draggable without showing a menu, or open a menu without becoming draggable.

pub fn focusable(self, yes: bool) -> Self

Control whether this button receives keyboard focus (Tab navigation). Set to false for purely decorative or status-indicator buttons.

pub fn variant(self, v: ButtonVariant) -> Self

Set the visual variant.

pub fn icon_size(self, size: f32) -> Self

Set the display size (width = height) for icon buttons in pixels.

pub fn id(self, id: WidgetId) -> Self

Assign a stable identifier for focus management.

pub fn paint_bounds(&self, rect: Rect) -> Rect

Bounding box of everything the button can paint at rect, across every interaction state. This is the sum of: icon-button hover/press circle (radius rect.min_dim / 2 + 8), focus ring (grows FOCUS_W + 1 beyond that), stroke half-width (FOCUS_W / 2), plus ~1 px of antialiasing bleed. Text buttons only have the focus ring.

The partial-redraw path uses this to know how much canvas area to invalidate when the button transitions in/out of a state.

pub fn preferred_size(&self, max_width: f32, canvas: &Canvas) -> (f32, f32)

Return the preferred (width, height) given available max_width.

pub fn draw( &self, canvas: &mut Canvas, rect: Rect, focused: bool, hovered: bool, pressed: bool, )

Draw the button into canvas at rect.

focused draws a keyboard-focus ring; hovered and pressed apply pointer/touch state overlays (icon buttons only).

pub fn into_element(self) -> Element<Msg>

Wrap this button in an Element.

Trait Implementations

impl<Msg: Clone> From<Button<Msg>> for Element<Msg>

fn from(b: Button<Msg>) -> Self

Converts to this type from the input type.