//! Buttons allow your users to perform actions by pressing them. //! //! # Example //! ```no_run //! # mod iced { pub mod widget { pub use iced_widget::*; } } //! # pub type State = (); //! # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>; //! use iced::widget::button; //! //! #[derive(Clone)] //! enum Message { //! ButtonPressed, //! } //! //! fn view(state: &State) -> Element<'_, Message> { //! button("Press me!").on_press(Message::ButtonPressed).into() //! } //! ``` //! Allow your users to perform actions by pressing a button. use iced_runtime::core::border::Radius; use iced_runtime::core::widget::Id; use iced_runtime::{Task, keyboard, task}; #[cfg(feature = "a11y")] use std::borrow::Cow; use crate::core::border::{self, Border}; use crate::core::layout; use crate::core::mouse; use crate::core::overlay; use crate::core::renderer; use crate::core::theme::palette; use crate::core::touch; use crate::core::widget::Operation; use crate::core::widget::tree::{self, Tree}; use crate::core::window; use crate::core::{ Background, Clipboard, Color, Element, Event, Layout, Length, Padding, Rectangle, Shadow, Shell, Size, Theme, Vector, Widget, }; use iced_renderer::core::widget::operation; /// A generic widget that produces a message when pressed. /// /// # Example /// ```no_run /// # mod iced { pub mod widget { pub use iced_widget::*; } } /// # pub type State = (); /// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>; /// use iced::widget::button; /// /// #[derive(Clone)] /// enum Message { /// ButtonPressed, /// } /// /// fn view(state: &State) -> Element<'_, Message> { /// button("Press me!").on_press(Message::ButtonPressed).into() /// } /// ``` /// /// If a [`Button::on_press`] handler is not set, the resulting [`Button`] will /// be disabled: /// /// ```no_run /// # mod iced { pub mod widget { pub use iced_widget::*; } } /// # pub type State = (); /// # pub type Element<'a, Message> = iced_widget::core::Element<'a, Message, iced_widget::Theme, iced_widget::Renderer>; /// use iced::widget::button; /// /// #[derive(Clone)] /// enum Message { /// ButtonPressed, /// } /// /// fn view(state: &State) -> Element<'_, Message> { /// button("I am disabled!").into() /// } /// ``` pub struct Button<'a, Message, Theme = crate::Theme, Renderer = crate::Renderer> where Renderer: crate::core::Renderer, Theme: Catalog, { content: Element<'a, Message, Theme, Renderer>, on_press: Option>, id: Id, #[cfg(feature = "a11y")] name: Option>, #[cfg(feature = "a11y")] description: Option>, #[cfg(feature = "a11y")] label: Option>, width: Length, height: Length, padding: Padding, clip: bool, class: Theme::Class<'a>, status: Option, } enum OnPress<'a, Message> { Direct(Message), Closure(Box Message + 'a>), } impl OnPress<'_, Message> { fn get(&self) -> Message { match self { OnPress::Direct(message) => message.clone(), OnPress::Closure(f) => f(), } } } impl<'a, Message, Theme, Renderer> Button<'a, Message, Theme, Renderer> where Renderer: crate::core::Renderer, Theme: Catalog, { /// Creates a new [`Button`] with the given content. pub fn new( content: impl Into>, ) -> Self { let content = content.into(); let size = content.as_widget().size_hint(); Button { content, id: Id::unique(), #[cfg(feature = "a11y")] name: None, #[cfg(feature = "a11y")] description: None, #[cfg(feature = "a11y")] label: None, on_press: None, width: size.width.fluid(), height: size.height.fluid(), padding: DEFAULT_PADDING, clip: false, class: Theme::default(), status: None, } } /// Sets the width of the [`Button`]. pub fn width(mut self, width: impl Into) -> Self { self.width = width.into(); self } /// Sets the height of the [`Button`]. pub fn height(mut self, height: impl Into) -> Self { self.height = height.into(); self } /// Sets the [`Padding`] of the [`Button`]. pub fn padding>(mut self, padding: P) -> Self { self.padding = padding.into(); self } /// Sets the message that will be produced when the [`Button`] is pressed. /// /// Unless `on_press` is called, the [`Button`] will be disabled. pub fn on_press(mut self, on_press: Message) -> Self { self.on_press = Some(OnPress::Direct(on_press)); self } /// Sets the message that will be produced when the [`Button`] is pressed. /// /// This is analogous to [`Button::on_press`], but using a closure to produce /// the message. /// /// This closure will only be called when the [`Button`] is actually pressed and, /// therefore, this method is useful to reduce overhead if creating the resulting /// message is slow. pub fn on_press_with( mut self, on_press: impl Fn() -> Message + 'a, ) -> Self { self.on_press = Some(OnPress::Closure(Box::new(on_press))); self } /// Sets the message that will be produced when the [`Button`] is pressed, /// if `Some`. /// /// If `None`, the [`Button`] will be disabled. pub fn on_press_maybe(mut self, on_press: Option) -> Self { self.on_press = on_press.map(OnPress::Direct); self } /// Sets whether the contents of the [`Button`] should be clipped on /// overflow. pub fn clip(mut self, clip: bool) -> Self { self.clip = clip; self } /// Sets the style of the [`Button`]. #[must_use] pub fn style(mut self, style: impl Fn(&Theme, Status) -> Style + 'a) -> Self where Theme::Class<'a>: From>, { self.class = (Box::new(style) as StyleFn<'a, Theme>).into(); self } /// Sets the style class of the [`Button`]. #[cfg(feature = "advanced")] #[must_use] pub fn class(mut self, class: impl Into>) -> Self { self.class = class.into(); self } /// Sets the [`Id`] of the [`Button`]. pub fn id(mut self, id: Id) -> Self { self.id = id; self } #[cfg(feature = "a11y")] /// Sets the name of the [`Button`]. pub fn name(mut self, name: impl Into>) -> Self { self.name = Some(name.into()); self } #[cfg(feature = "a11y")] /// Sets the description of the [`Button`]. pub fn description_widget( mut self, description: &T, ) -> Self { self.description = Some(iced_accessibility::Description::Id( description.description(), )); self } #[cfg(feature = "a11y")] /// Sets the description of the [`Button`]. pub fn description(mut self, description: impl Into>) -> Self { self.description = Some(iced_accessibility::Description::Text(description.into())); self } #[cfg(feature = "a11y")] /// Sets the label of the [`Button`]. pub fn label(mut self, label: &dyn iced_accessibility::Labels) -> Self { self.label = Some(label.label().into_iter().map(|l| l.into()).collect()); self } } #[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] struct State { is_hovered: bool, is_pressed: bool, is_focused: bool, } impl<'a, Message, Theme, Renderer> Widget for Button<'a, Message, Theme, Renderer> where Message: 'a + Clone, Renderer: 'a + crate::core::Renderer, Theme: Catalog, { fn tag(&self) -> tree::Tag { tree::Tag::of::() } fn state(&self) -> tree::State { tree::State::new(State::default()) } fn children(&self) -> Vec { vec![Tree::new(&self.content)] } fn diff(&mut self, tree: &mut Tree) { tree.diff_children(std::slice::from_mut(&mut self.content)); } fn size(&self) -> Size { Size { width: self.width, height: self.height, } } fn layout( &mut self, tree: &mut Tree, renderer: &Renderer, limits: &layout::Limits, ) -> layout::Node { layout::padded( limits, self.width, self.height, self.padding, |limits| { self.content.as_widget_mut().layout( &mut tree.children[0], renderer, limits, ) }, ) } fn operate( &mut self, tree: &mut Tree, layout: Layout<'_>, renderer: &Renderer, operation: &mut dyn Operation, ) { operation.container(None, layout.bounds()); operation.traverse(&mut |operation| { self.content.as_widget_mut().operate( &mut tree.children[0], layout.children().next().unwrap(), renderer, operation, ); }); } fn update( &mut self, tree: &mut Tree, event: &Event, layout: Layout<'_>, cursor: mouse::Cursor, renderer: &Renderer, clipboard: &mut dyn Clipboard, shell: &mut Shell<'_, Message>, viewport: &Rectangle, ) { self.content.as_widget_mut().update( &mut tree.children[0], event, layout.children().next().unwrap(), cursor, renderer, clipboard, shell, viewport, ); if shell.is_event_captured() { return; } match event { Event::Mouse(mouse::Event::ButtonPressed(mouse::Button::Left)) | Event::Touch(touch::Event::FingerPressed { .. }) => { if self.on_press.is_some() { let bounds = layout.bounds(); if cursor.is_over(bounds) { let state = tree.state.downcast_mut::(); state.is_pressed = true; shell.capture_event(); } } } Event::Mouse(mouse::Event::ButtonReleased(mouse::Button::Left)) | Event::Touch(touch::Event::FingerLifted { .. }) => { if let Some(on_press) = &self.on_press { let state = tree.state.downcast_mut::(); if state.is_pressed { state.is_pressed = false; let bounds = layout.bounds(); if cursor.is_over(bounds) { shell.publish(on_press.get()); } shell.capture_event(); } } } #[cfg(feature = "a11y")] Event::A11y( event_id, iced_accessibility::accesskit::ActionRequest { action, .. }, ) => { let state = tree.state.downcast_mut::(); if let Some(Some(on_press)) = (self.id == *event_id && matches!( action, iced_accessibility::accesskit::Action::Click )) .then(|| self.on_press.as_ref()) { state.is_pressed = false; shell.publish(on_press.get()); } return; } Event::Keyboard(keyboard::Event::KeyPressed { key, .. }) => { if let Some(on_press) = self.on_press.as_ref() { let state = tree.state.downcast_mut::(); if state.is_focused && matches!( key, keyboard::Key::Named(keyboard::key::Named::Enter) ) { state.is_pressed = true; shell.publish(on_press.get()); shell.capture_event(); return; } } } Event::Touch(touch::Event::FingerLost { .. }) | Event::Mouse(mouse::Event::CursorLeft) => { let state = tree.state.downcast_mut::(); state.is_hovered = false; state.is_pressed = false; } _ => {} } let current_status = if self.on_press.is_none() { Status::Disabled } else if cursor.is_over(layout.bounds()) { let state = tree.state.downcast_ref::(); if state.is_pressed { Status::Pressed } else { Status::Hovered } } else { Status::Active }; if let Event::Window(window::Event::RedrawRequested(_now)) = event { self.status = Some(current_status); } else if self.status.is_some_and(|status| status != current_status) { shell.request_redraw(); } } fn draw( &self, tree: &Tree, renderer: &mut Renderer, theme: &Theme, renderer_style: &renderer::Style, layout: Layout<'_>, cursor: mouse::Cursor, viewport: &Rectangle, ) { let bounds = layout.bounds(); let content_layout = layout.children().next().unwrap(); let style = theme.style(&self.class, self.status.unwrap_or(Status::Disabled)); if style.background.is_some() || style.border.width > 0.0 || style.shadow.color.a > 0.0 { renderer.fill_quad( renderer::Quad { bounds, border: style.border, shadow: style.shadow, snap: style.snap, }, style .background .unwrap_or(Background::Color(Color::TRANSPARENT)), ); } let viewport = if self.clip { bounds.intersection(viewport).unwrap_or(*viewport) } else { *viewport }; self.content.as_widget().draw( &tree.children[0], renderer, theme, &renderer::Style { text_color: style.text_color, icon_color: style .icon_color .unwrap_or(renderer_style.icon_color), scale_factor: renderer_style.scale_factor, }, content_layout, cursor, &viewport, ); } fn mouse_interaction( &self, _tree: &Tree, layout: Layout<'_>, cursor: mouse::Cursor, _viewport: &Rectangle, _renderer: &Renderer, ) -> mouse::Interaction { let is_mouse_over = cursor.is_over(layout.bounds()); if is_mouse_over && self.on_press.is_some() { mouse::Interaction::Pointer } else { mouse::Interaction::default() } } fn overlay<'b>( &'b mut self, tree: &'b mut Tree, layout: Layout<'b>, renderer: &Renderer, viewport: &Rectangle, translation: Vector, ) -> Option> { self.content.as_widget_mut().overlay( &mut tree.children[0], layout.children().next().unwrap(), renderer, viewport, translation, ) } #[cfg(feature = "a11y")] /// get the a11y nodes for the widget fn a11y_nodes( &self, layout: Layout<'_>, state: &Tree, p: mouse::Cursor, ) -> iced_accessibility::A11yTree { use iced_accessibility::{ A11yNode, A11yTree, accesskit::{Action, Node, NodeId, Rect, Role}, }; let child_layout = layout.children().next().unwrap(); let child_tree = &state.children[0]; let child_tree = self.content .as_widget() .a11y_nodes(child_layout, child_tree, p); let Rectangle { x, y, width, height, } = layout.bounds(); let bounds = Rect::new( x as f64, y as f64, (x + width) as f64, (y + height) as f64, ); let is_hovered = state.state.downcast_ref::().is_hovered; let mut node = Node::new(Role::Button); node.add_action(Action::Focus); node.add_action(Action::Click); node.set_bounds(bounds); if let Some(name) = self.name.as_ref() && self.label.as_ref().is_none_or(|l| l.is_empty()) { node.set_label(name.clone()); } match self.description.as_ref() { Some(iced_accessibility::Description::Id(id)) => { node.set_described_by( id.iter() .cloned() .map(|id| NodeId::from(id)) .collect::>(), ); } Some(iced_accessibility::Description::Text(text)) => { node.set_description(text.clone()); } None => {} } if let Some(label) = self.label.as_ref() { node.set_labelled_by(label.clone()); } if self.on_press.is_none() { node.set_disabled() } // TODO hover // if is_hovered { // node.set_busy() // } A11yTree::node_with_child_tree( A11yNode::new(node, self.id.clone()), child_tree, ) } fn id(&self) -> Option { Some(self.id.clone()) } fn set_id(&mut self, id: Id) { self.id = id; } } impl<'a, Message, Theme, Renderer> From> for Element<'a, Message, Theme, Renderer> where Message: Clone + 'a, Theme: Catalog + 'a, Renderer: crate::core::Renderer + 'a, { fn from(button: Button<'a, Message, Theme, Renderer>) -> Self { Self::new(button) } } /// The default [`Padding`] of a [`Button`]. pub const DEFAULT_PADDING: Padding = Padding { top: 5.0, bottom: 5.0, right: 10.0, left: 10.0, }; /// The possible status of a [`Button`]. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Status { /// The [`Button`] can be pressed. Active, /// The [`Button`] can be pressed and it is being hovered. Hovered, /// The [`Button`] is being pressed. Pressed, /// The [`Button`] cannot be pressed. Disabled, } /// The style of a button. /// /// If not specified with [`Button::style`] /// the theme will provide the style. #[derive(Debug, Clone, Copy, PartialEq)] pub struct Style { /// The [`Background`] of the button. pub background: Option, /// The border radius of the button. pub border_radius: Radius, /// The border width of the button. pub border_width: f32, /// The border [`Color`] of the button. pub border_color: Color, /// The icon [`Color`] of the button. pub icon_color: Option, /// The text [`Color`] of the button. pub text_color: Color, /// The [`Border`] of the button. pub border: Border, /// The [`Shadow`] of the button. pub shadow: Shadow, /// Whether the button should be snapped to the pixel grid. pub snap: bool, } impl Style { /// Updates the [`Style`] with the given [`Background`]. pub fn with_background(self, background: impl Into) -> Self { Self { background: Some(background.into()), ..self } } // /// Returns whether the [`Button`] is currently focused or not. // pub fn is_focused(&self) -> bool { // self.is_focused // } // /// Returns whether the [`Button`] is currently hovered or not. // pub fn is_hovered(&self) -> bool { // self.is_hovered // } // /// Focuses the [`Button`]. // pub fn focus(&mut self) { // self.is_focused = true; // } // /// Unfocuses the [`Button`]. // pub fn unfocus(&mut self) { // self.is_focused = false; // } } impl Default for Style { fn default() -> Self { Self { background: None, border_radius: 0.0.into(), border_width: 0.0, border_color: Color::TRANSPARENT, icon_color: None, text_color: Color::BLACK, border: Border::default(), shadow: Shadow::default(), snap: cfg!(feature = "crisp"), } } } /// The theme catalog of a [`Button`]. /// /// All themes that can be used with [`Button`] /// must implement this trait. /// /// # Example /// ```no_run /// # use iced_widget::core::{Color, Background}; /// # use iced_widget::button::{Catalog, Status, Style}; /// # struct MyTheme; /// #[derive(Debug, Default)] /// pub enum ButtonClass { /// #[default] /// Primary, /// Secondary, /// Danger /// } /// /// impl Catalog for MyTheme { /// type Class<'a> = ButtonClass; /// /// fn default<'a>() -> Self::Class<'a> { /// ButtonClass::default() /// } /// /// /// fn style(&self, class: &Self::Class<'_>, status: Status) -> Style { /// let mut style = Style::default(); /// /// match class { /// ButtonClass::Primary => { /// style.background = Some(Background::Color(Color::from_rgb(0.529, 0.808, 0.921))); /// }, /// ButtonClass::Secondary => { /// style.background = Some(Background::Color(Color::WHITE)); /// }, /// ButtonClass::Danger => { /// style.background = Some(Background::Color(Color::from_rgb(0.941, 0.502, 0.502))); /// }, /// } /// /// style /// } /// } /// ``` /// /// Although, in order to use [`Button::style`] /// with `MyTheme`, [`Catalog::Class`] must implement /// `From>`. pub trait Catalog { /// The item class of the [`Catalog`]. type Class<'a>; /// The default class produced by the [`Catalog`]. fn default<'a>() -> Self::Class<'a>; /// The [`Style`] of a class with the given status. fn style(&self, class: &Self::Class<'_>, status: Status) -> Style; } /// A styling function for a [`Button`]. pub type StyleFn<'a, Theme> = Box Style + 'a>; impl Catalog for Theme { type Class<'a> = StyleFn<'a, Self>; fn default<'a>() -> Self::Class<'a> { Box::new(primary) } fn style(&self, class: &Self::Class<'_>, status: Status) -> Style { class(self, status) } } /// A primary button; denoting a main action. pub fn primary(theme: &Theme, status: Status) -> Style { let palette = theme.extended_palette(); let base = styled(palette.primary.base); match status { Status::Active | Status::Pressed => base, Status::Hovered => Style { background: Some(Background::Color(palette.primary.strong.color)), ..base }, Status::Disabled => disabled(base), } } /// A secondary button; denoting a complementary action. pub fn secondary(theme: &Theme, status: Status) -> Style { let palette = theme.extended_palette(); let base = styled(palette.secondary.base); match status { Status::Active | Status::Pressed => base, Status::Hovered => Style { background: Some(Background::Color(palette.secondary.strong.color)), ..base }, Status::Disabled => disabled(base), } } /// A success button; denoting a good outcome. pub fn success(theme: &Theme, status: Status) -> Style { let palette = theme.extended_palette(); let base = styled(palette.success.base); match status { Status::Active | Status::Pressed => base, Status::Hovered => Style { background: Some(Background::Color(palette.success.strong.color)), ..base }, Status::Disabled => disabled(base), } } /// A warning button; denoting a risky action. pub fn warning(theme: &Theme, status: Status) -> Style { let palette = theme.extended_palette(); let base = styled(palette.warning.base); match status { Status::Active | Status::Pressed => base, Status::Hovered => Style { background: Some(Background::Color(palette.warning.strong.color)), ..base }, Status::Disabled => disabled(base), } } /// A danger button; denoting a destructive action. pub fn danger(theme: &Theme, status: Status) -> Style { let palette = theme.extended_palette(); let base = styled(palette.danger.base); match status { Status::Active | Status::Pressed => base, Status::Hovered => Style { background: Some(Background::Color(palette.danger.strong.color)), ..base }, Status::Disabled => disabled(base), } } /// A text button; useful for links. pub fn text(theme: &Theme, status: Status) -> Style { let palette = theme.extended_palette(); let base = Style { text_color: palette.background.base.text, ..Style::default() }; match status { Status::Active | Status::Pressed => base, Status::Hovered => Style { text_color: palette.background.base.text.scale_alpha(0.8), ..base }, Status::Disabled => disabled(base), } } /// A button using background shades. pub fn background(theme: &Theme, status: Status) -> Style { let palette = theme.extended_palette(); let base = styled(palette.background.base); match status { Status::Active => base, Status::Pressed => Style { background: Some(Background::Color( palette.background.strong.color, )), ..base }, Status::Hovered => Style { background: Some(Background::Color(palette.background.weak.color)), ..base }, Status::Disabled => disabled(base), } } /// A subtle button using weak background shades. pub fn subtle(theme: &Theme, status: Status) -> Style { let palette = theme.extended_palette(); let base = styled(palette.background.weakest); match status { Status::Active => base, Status::Pressed => Style { background: Some(Background::Color( palette.background.strong.color, )), ..base }, Status::Hovered => Style { background: Some(Background::Color( palette.background.weaker.color, )), ..base }, Status::Disabled => disabled(base), } } fn styled(pair: palette::Pair) -> Style { Style { background: Some(Background::Color(pair.color)), text_color: pair.text, border: border::rounded(2), ..Style::default() } } fn disabled(style: Style) -> Style { Style { background: style .background .map(|background| background.scale_alpha(0.5)), text_color: style.text_color.scale_alpha(0.5), ..style } } /// Produces a [`Task`] that focuses the [`Button`] with the given [`Id`]. pub fn focus(id: Id) -> Task { task::widget(operation::focusable::focus(id)) } impl operation::Focusable for State { fn is_focused(&self) -> bool { self.is_focused } fn focus(&mut self) { self.is_focused = true; } fn unfocus(&mut self) { self.is_focused = false; } }