1use crate::component_prelude::*;
2use gpui::{AnyElement, AnyView, DefiniteLength};
3use ui_macros::RegisterComponent;
4
5use crate::{ButtonCommon, ButtonLike, ButtonSize, ButtonStyle, IconName, IconSize, Label};
6use crate::{
7 Color, DynamicSpacing, ElevationIndex, IconPosition, KeyBinding, KeybindingPosition, TintColor,
8 prelude::*,
9};
10
11use super::button_icon::ButtonIcon;
12
13/// An element that creates a button with a label and an optional icon.
14///
15/// Common buttons:
16/// - Label, Icon + Label: [`Button`] (this component)
17/// - Icon only: [`IconButton`]
18/// - Custom: [`ButtonLike`]
19///
20/// To create a more complex button than what the [`Button`] or [`IconButton`] components provide, use
21/// [`ButtonLike`] directly.
22///
23/// # Examples
24///
25/// **A button with a label**, is typically used in scenarios such as a form, where the button's label
26/// indicates what action will be performed when the button is clicked.
27///
28/// ```
29/// use ui::prelude::*;
30///
31/// Button::new("button_id", "Click me!")
32/// .on_click(|event, window, cx| {
33/// // Handle click event
34/// });
35/// ```
36///
37/// **A toggleable button**, is typically used in scenarios such as a toolbar,
38/// where the button's state indicates whether a feature is enabled or not, or
39/// a trigger for a popover menu, where clicking the button toggles the visibility of the menu.
40///
41/// ```
42/// use ui::prelude::*;
43///
44/// Button::new("button_id", "Click me!")
45/// .icon(IconName::Check)
46/// .toggle_state(true)
47/// .on_click(|event, window, cx| {
48/// // Handle click event
49/// });
50/// ```
51///
52/// To change the style of the button when it is selected use the [`selected_style`][Button::selected_style] method.
53///
54/// ```
55/// use ui::prelude::*;
56/// use ui::TintColor;
57///
58/// Button::new("button_id", "Click me!")
59/// .toggle_state(true)
60/// .selected_style(ButtonStyle::Tinted(TintColor::Accent))
61/// .on_click(|event, window, cx| {
62/// // Handle click event
63/// });
64/// ```
65/// This will create a button with a blue tinted background when selected.
66///
67/// **A full-width button**, is typically used in scenarios such as the bottom of a modal or form, where it occupies the entire width of its container.
68/// The button's content, including text and icons, is centered by default.
69///
70/// ```
71/// use ui::prelude::*;
72///
73/// let button = Button::new("button_id", "Click me!")
74/// .full_width()
75/// .on_click(|event, window, cx| {
76/// // Handle click event
77/// });
78/// ```
79///
80#[derive(IntoElement, Documented, RegisterComponent)]
81pub struct Button {
82 base: ButtonLike,
83 label: SharedString,
84 label_color: Option<Color>,
85 label_size: Option<LabelSize>,
86 selected_label: Option<SharedString>,
87 selected_label_color: Option<Color>,
88 icon: Option<IconName>,
89 icon_position: Option<IconPosition>,
90 icon_size: Option<IconSize>,
91 icon_color: Option<Color>,
92 selected_icon: Option<IconName>,
93 selected_icon_color: Option<Color>,
94 key_binding: Option<KeyBinding>,
95 key_binding_position: KeybindingPosition,
96 alpha: Option<f32>,
97 truncate: bool,
98}
99
100impl Button {
101 /// Creates a new [`Button`] with a specified identifier and label.
102 ///
103 /// This is the primary constructor for a [`Button`] component. It initializes
104 /// the button with the provided identifier and label text, setting all other
105 /// properties to their default values, which can be customized using the
106 /// builder pattern methods provided by this struct.
107 pub fn new(id: impl Into<ElementId>, label: impl Into<SharedString>) -> Self {
108 Self {
109 base: ButtonLike::new(id),
110 label: label.into(),
111 label_color: None,
112 label_size: None,
113 selected_label: None,
114 selected_label_color: None,
115 icon: None,
116 icon_position: None,
117 icon_size: None,
118 icon_color: None,
119 selected_icon: None,
120 selected_icon_color: None,
121 key_binding: None,
122 key_binding_position: KeybindingPosition::default(),
123 alpha: None,
124 truncate: false,
125 }
126 }
127
128 /// Sets the color of the button's label.
129 pub fn color(mut self, label_color: impl Into<Option<Color>>) -> Self {
130 self.label_color = label_color.into();
131 self
132 }
133
134 /// Defines the size of the button's label.
135 pub fn label_size(mut self, label_size: impl Into<Option<LabelSize>>) -> Self {
136 self.label_size = label_size.into();
137 self
138 }
139
140 /// Sets the label used when the button is in a selected state.
141 pub fn selected_label<L: Into<SharedString>>(mut self, label: impl Into<Option<L>>) -> Self {
142 self.selected_label = label.into().map(Into::into);
143 self
144 }
145
146 /// Sets the label color used when the button is in a selected state.
147 pub fn selected_label_color(mut self, color: impl Into<Option<Color>>) -> Self {
148 self.selected_label_color = color.into();
149 self
150 }
151
152 /// Assigns an icon to the button.
153 pub fn icon(mut self, icon: impl Into<Option<IconName>>) -> Self {
154 self.icon = icon.into();
155 self
156 }
157
158 /// Sets the position of the icon relative to the label.
159 pub fn icon_position(mut self, icon_position: impl Into<Option<IconPosition>>) -> Self {
160 self.icon_position = icon_position.into();
161 self
162 }
163
164 /// Specifies the size of the button's icon.
165 pub fn icon_size(mut self, icon_size: impl Into<Option<IconSize>>) -> Self {
166 self.icon_size = icon_size.into();
167 self
168 }
169
170 /// Sets the color of the button's icon.
171 pub fn icon_color(mut self, icon_color: impl Into<Option<Color>>) -> Self {
172 self.icon_color = icon_color.into();
173 self
174 }
175
176 /// Chooses an icon to display when the button is in a selected state.
177 pub fn selected_icon(mut self, icon: impl Into<Option<IconName>>) -> Self {
178 self.selected_icon = icon.into();
179 self
180 }
181
182 /// Sets the icon color used when the button is in a selected state.
183 pub fn selected_icon_color(mut self, color: impl Into<Option<Color>>) -> Self {
184 self.selected_icon_color = color.into();
185 self
186 }
187
188 /// Display the keybinding that triggers the button action.
189 pub fn key_binding(mut self, key_binding: impl Into<Option<KeyBinding>>) -> Self {
190 self.key_binding = key_binding.into();
191 self
192 }
193
194 /// Sets the position of the keybinding relative to the button label.
195 ///
196 /// This method allows you to specify where the keybinding should be displayed
197 /// in relation to the button's label.
198 pub fn key_binding_position(mut self, position: KeybindingPosition) -> Self {
199 self.key_binding_position = position;
200 self
201 }
202
203 /// Sets the alpha property of the color of label.
204 pub fn alpha(mut self, alpha: f32) -> Self {
205 self.alpha = Some(alpha);
206 self
207 }
208
209 /// Truncates overflowing labels with an ellipsis (`…`) if needed.
210 ///
211 /// Buttons with static labels should _never_ be truncated, ensure
212 /// this is only used when the label is dynamic and may overflow.
213 pub fn truncate(mut self, truncate: bool) -> Self {
214 self.truncate = truncate;
215 self
216 }
217}
218
219impl Toggleable for Button {
220 /// Sets the selected state of the button.
221 ///
222 /// This method allows the selection state of the button to be specified.
223 /// It modifies the button's appearance to reflect its selected state.
224 ///
225 /// # Examples
226 ///
227 /// ```
228 /// use ui::prelude::*;
229 ///
230 /// Button::new("button_id", "Click me!")
231 /// .toggle_state(true)
232 /// .on_click(|event, window, cx| {
233 /// // Handle click event
234 /// });
235 /// ```
236 ///
237 /// Use [`selected_style`](Button::selected_style) to change the style of the button when it is selected.
238 fn toggle_state(mut self, selected: bool) -> Self {
239 self.base = self.base.toggle_state(selected);
240 self
241 }
242}
243
244impl SelectableButton for Button {
245 /// Sets the style for the button when selected.
246 ///
247 /// # Examples
248 ///
249 /// ```
250 /// use ui::prelude::*;
251 /// use ui::TintColor;
252 ///
253 /// Button::new("button_id", "Click me!")
254 /// .toggle_state(true)
255 /// .selected_style(ButtonStyle::Tinted(TintColor::Accent))
256 /// .on_click(|event, window, cx| {
257 /// // Handle click event
258 /// });
259 /// ```
260 /// This results in a button with a blue tinted background when selected.
261 fn selected_style(mut self, style: ButtonStyle) -> Self {
262 self.base = self.base.selected_style(style);
263 self
264 }
265}
266
267impl Disableable for Button {
268 /// Disables the button.
269 ///
270 /// This method allows the button to be disabled. When a button is disabled,
271 /// it doesn't react to user interactions and its appearance is updated to reflect this.
272 ///
273 /// # Examples
274 ///
275 /// ```
276 /// use ui::prelude::*;
277 ///
278 /// Button::new("button_id", "Click me!")
279 /// .disabled(true)
280 /// .on_click(|event, window, cx| {
281 /// // Handle click event
282 /// });
283 /// ```
284 ///
285 /// This results in a button that is disabled and does not respond to click events.
286 fn disabled(mut self, disabled: bool) -> Self {
287 self.base = self.base.disabled(disabled);
288 self
289 }
290}
291
292impl Clickable for Button {
293 /// Sets the click event handler for the button.
294 fn on_click(
295 mut self,
296 handler: impl Fn(&gpui::ClickEvent, &mut Window, &mut App) + 'static,
297 ) -> Self {
298 self.base = self.base.on_click(handler);
299 self
300 }
301
302 fn cursor_style(mut self, cursor_style: gpui::CursorStyle) -> Self {
303 self.base = self.base.cursor_style(cursor_style);
304 self
305 }
306}
307
308impl FixedWidth for Button {
309 /// Sets a fixed width for the button.
310 ///
311 /// This function allows a button to have a fixed width instead of automatically growing or shrinking.
312 /// Sets a fixed width for the button.
313 ///
314 /// # Examples
315 ///
316 /// ```
317 /// use ui::prelude::*;
318 ///
319 /// Button::new("button_id", "Click me!")
320 /// .width(px(100.))
321 /// .on_click(|event, window, cx| {
322 /// // Handle click event
323 /// });
324 /// ```
325 ///
326 /// This sets the button's width to be exactly 100 pixels.
327 fn width(mut self, width: impl Into<DefiniteLength>) -> Self {
328 self.base = self.base.width(width);
329 self
330 }
331
332 /// Sets the button to occupy the full width of its container.
333 ///
334 /// # Examples
335 ///
336 /// ```
337 /// use ui::prelude::*;
338 ///
339 /// Button::new("button_id", "Click me!")
340 /// .full_width()
341 /// .on_click(|event, window, cx| {
342 /// // Handle click event
343 /// });
344 /// ```
345 ///
346 /// This stretches the button to the full width of its container.
347 fn full_width(mut self) -> Self {
348 self.base = self.base.full_width();
349 self
350 }
351}
352
353impl ButtonCommon for Button {
354 /// Sets the button's id.
355 fn id(&self) -> &ElementId {
356 self.base.id()
357 }
358
359 /// Sets the visual style of the button using a [`ButtonStyle`].
360 fn style(mut self, style: ButtonStyle) -> Self {
361 self.base = self.base.style(style);
362 self
363 }
364
365 /// Sets the button's size using a [`ButtonSize`].
366 fn size(mut self, size: ButtonSize) -> Self {
367 self.base = self.base.size(size);
368 self
369 }
370
371 /// Sets a tooltip for the button.
372 ///
373 /// This method allows a tooltip to be set for the button. The tooltip is a function that
374 /// takes a mutable references to [`Window`] and [`App`], and returns an [`AnyView`]. The
375 /// tooltip is displayed when the user hovers over the button.
376 ///
377 /// # Examples
378 ///
379 /// ```
380 /// use ui::prelude::*;
381 /// use ui::Tooltip;
382 ///
383 /// Button::new("button_id", "Click me!")
384 /// .tooltip(Tooltip::text("This is a tooltip"))
385 /// .on_click(|event, window, cx| {
386 /// // Handle click event
387 /// });
388 /// ```
389 ///
390 /// This will create a button with a tooltip that displays "This is a tooltip" when hovered over.
391 fn tooltip(mut self, tooltip: impl Fn(&mut Window, &mut App) -> AnyView + 'static) -> Self {
392 self.base = self.base.tooltip(tooltip);
393 self
394 }
395
396 fn tab_index(mut self, tab_index: impl Into<isize>) -> Self {
397 self.base = self.base.tab_index(tab_index);
398 self
399 }
400
401 fn layer(mut self, elevation: ElevationIndex) -> Self {
402 self.base = self.base.layer(elevation);
403 self
404 }
405}
406
407impl RenderOnce for Button {
408 #[allow(refining_impl_trait)]
409 fn render(self, _window: &mut Window, cx: &mut App) -> ButtonLike {
410 let is_disabled = self.base.disabled;
411 let is_selected = self.base.selected;
412
413 let label = self
414 .selected_label
415 .filter(|_| is_selected)
416 .unwrap_or(self.label);
417
418 let label_color = if is_disabled {
419 Color::Disabled
420 } else if is_selected {
421 self.selected_label_color.unwrap_or(Color::Selected)
422 } else {
423 self.label_color.unwrap_or_default()
424 };
425
426 self.base.child(
427 h_flex()
428 .gap(DynamicSpacing::Base04.rems(cx))
429 .when(self.icon_position == Some(IconPosition::Start), |this| {
430 this.children(self.icon.map(|icon| {
431 ButtonIcon::new(icon)
432 .disabled(is_disabled)
433 .toggle_state(is_selected)
434 .selected_icon(self.selected_icon)
435 .selected_icon_color(self.selected_icon_color)
436 .size(self.icon_size)
437 .color(self.icon_color)
438 }))
439 })
440 .child(
441 h_flex()
442 .when(
443 self.key_binding_position == KeybindingPosition::Start,
444 |this| this.flex_row_reverse(),
445 )
446 .gap(DynamicSpacing::Base06.rems(cx))
447 .justify_between()
448 .child(
449 Label::new(label)
450 .color(label_color)
451 .size(self.label_size.unwrap_or_default())
452 .when_some(self.alpha, |this, alpha| this.alpha(alpha))
453 .when(self.truncate, |this| this.truncate()),
454 )
455 .children(self.key_binding),
456 )
457 .when(self.icon_position != Some(IconPosition::Start), |this| {
458 this.children(self.icon.map(|icon| {
459 ButtonIcon::new(icon)
460 .disabled(is_disabled)
461 .toggle_state(is_selected)
462 .selected_icon(self.selected_icon)
463 .selected_icon_color(self.selected_icon_color)
464 .size(self.icon_size)
465 .color(self.icon_color)
466 }))
467 }),
468 )
469 }
470}
471
472// View this component preview using `workspace: open component-preview`
473impl Component for Button {
474 fn scope() -> ComponentScope {
475 ComponentScope::Input
476 }
477
478 fn sort_name() -> &'static str {
479 "ButtonA"
480 }
481
482 fn description() -> Option<&'static str> {
483 Some("A button triggers an event or action.")
484 }
485
486 fn preview(_window: &mut Window, _cx: &mut App) -> Option<AnyElement> {
487 Some(
488 v_flex()
489 .gap_6()
490 .children(vec![
491 example_group_with_title(
492 "Button Styles",
493 vec![
494 single_example(
495 "Default",
496 Button::new("default", "Default").into_any_element(),
497 ),
498 single_example(
499 "Filled",
500 Button::new("filled", "Filled")
501 .style(ButtonStyle::Filled)
502 .into_any_element(),
503 ),
504 single_example(
505 "Subtle",
506 Button::new("outline", "Subtle")
507 .style(ButtonStyle::Subtle)
508 .into_any_element(),
509 ),
510 single_example(
511 "Tinted",
512 Button::new("tinted_accent_style", "Accent")
513 .style(ButtonStyle::Tinted(TintColor::Accent))
514 .into_any_element(),
515 ),
516 single_example(
517 "Transparent",
518 Button::new("transparent", "Transparent")
519 .style(ButtonStyle::Transparent)
520 .into_any_element(),
521 ),
522 ],
523 ),
524 example_group_with_title(
525 "Tint Styles",
526 vec![
527 single_example(
528 "Accent",
529 Button::new("tinted_accent", "Accent")
530 .style(ButtonStyle::Tinted(TintColor::Accent))
531 .into_any_element(),
532 ),
533 single_example(
534 "Error",
535 Button::new("tinted_negative", "Error")
536 .style(ButtonStyle::Tinted(TintColor::Error))
537 .into_any_element(),
538 ),
539 single_example(
540 "Warning",
541 Button::new("tinted_warning", "Warning")
542 .style(ButtonStyle::Tinted(TintColor::Warning))
543 .into_any_element(),
544 ),
545 single_example(
546 "Success",
547 Button::new("tinted_positive", "Success")
548 .style(ButtonStyle::Tinted(TintColor::Success))
549 .into_any_element(),
550 ),
551 ],
552 ),
553 example_group_with_title(
554 "Special States",
555 vec![
556 single_example(
557 "Default",
558 Button::new("default_state", "Default").into_any_element(),
559 ),
560 single_example(
561 "Disabled",
562 Button::new("disabled", "Disabled")
563 .disabled(true)
564 .into_any_element(),
565 ),
566 single_example(
567 "Selected",
568 Button::new("selected", "Selected")
569 .toggle_state(true)
570 .into_any_element(),
571 ),
572 ],
573 ),
574 example_group_with_title(
575 "Buttons with Icons",
576 vec![
577 single_example(
578 "Icon Start",
579 Button::new("icon_start", "Icon Start")
580 .icon(IconName::Check)
581 .icon_position(IconPosition::Start)
582 .into_any_element(),
583 ),
584 single_example(
585 "Icon End",
586 Button::new("icon_end", "Icon End")
587 .icon(IconName::Check)
588 .icon_position(IconPosition::End)
589 .into_any_element(),
590 ),
591 single_example(
592 "Icon Color",
593 Button::new("icon_color", "Icon Color")
594 .icon(IconName::Check)
595 .icon_color(Color::Accent)
596 .into_any_element(),
597 ),
598 ],
599 ),
600 ])
601 .into_any_element(),
602 )
603 }
604}