Skip to main content

crabshell_ui/
widgets.rs

1//! The widgets, and the [`Widget`] trait they share.
2//!
3//! A widget value is only a description. Nothing happens until its window is
4//! created: then each description becomes a node in the window's tree, and
5//! each closure property becomes an effect that updates that node.
6
7use std::hash::Hash;
8use std::path::PathBuf;
9use std::rc::Rc;
10use std::time::Duration;
11
12use crabshell_reactive::{Memo, Signal};
13
14use crate::cx::Cx;
15use crate::dnd::DragContent;
16use crate::geometry::{Point, Rect, Size};
17use crate::image::ImageTransition;
18use crate::input::{
19  CursorShape, Drag, DragValue, DropTarget, Handler, Handlers, LinkHandler, Wheel,
20};
21use crate::keyboard::KeyEvent;
22use crate::keyed::{self, KeyedList, KeyedMount};
23use crate::prop::{IntoProp, Prop};
24use crate::rich::Span;
25use crate::screencopy::ScreencopyProps;
26use crate::scroll::ScrollProps;
27use crate::style::{Color, Style};
28use crate::text_input::InputProps;
29
30/// Something that can be placed in a window: one of this crate's widgets, or
31/// a type of your own that is made of them.
32///
33/// To make your own, return another widget's element. Calling
34/// `into_element` on a container describes everything inside it too, so the
35/// result is plain data:
36///
37/// ```
38/// use crabshell_ui::{Element, Row, Text, Widget};
39///
40/// struct Greeting;
41///
42/// impl Widget for Greeting {
43///     fn into_element(self: Box<Self>) -> Element {
44///         Box::new(Row::new().gap(4).child(Text::new("hello")).child(Text::new("world")))
45///             .into_element()
46///     }
47/// }
48/// ```
49pub trait Widget: 'static {
50  /// Turns the description, and everything inside it, into the element
51  /// the window builds nodes from. It runs when the window is created or a
52  /// list item first appears, before the window's tree is touched and
53  /// without recording what it reads, so it only describes.
54  fn into_element(self: Box<Self>) -> Element;
55}
56
57/// What a [`Widget`] turns into: plain data, with every child already turned
58/// into its element. Only this crate's widgets create one.
59pub struct Element {
60  pub(crate) name: &'static str,
61  pub(crate) common: Common,
62  pub(crate) kind: ElementKind,
63  pub(crate) children: Vec<ElementChild>,
64}
65
66pub(crate) enum ElementKind {
67  Flex(FlexProps),
68  Grid(GridProps),
69  Stack,
70  Spacer,
71  Text(TextProps),
72  Icon(IconProps),
73  Image(ImageProps),
74  Capture(ScreencopyProps),
75  Canvas(Box<dyn FnMut(&mut crate::canvas::Pen)>),
76  // Boxed: a button's handlers make it the largest by far.
77  Button(Box<ButtonProps>),
78  // Boxed: its scroll bar's style makes it large.
79  Scroll(Box<ScrollProps>),
80  Input(Box<InputProps>),
81}
82
83/// What every widget takes besides its own properties.
84#[derive(Default)]
85pub(crate) struct Common {
86  pub(crate) style: Option<Prop<Style>>,
87  pub(crate) visible: Option<Prop<bool>>,
88  pub(crate) geometry: Option<Signal<Rect>>,
89  pub(crate) mapped_geometry: Option<Signal<Rect>>,
90  pub(crate) accessible_name: Option<Prop<String>>,
91  /// Told the widget's size after each layout that changes it, with the
92  /// tree released. Lists measure their rows with it; configs have
93  /// `geometry`.
94  pub(crate) measure: Option<Measure>,
95}
96
97/// What a list runs with a row's size after a layout changes it.
98pub(crate) type Measure = Rc<dyn Fn(Size)>;
99
100/// One entry of a container's child list: a single widget, or a keyed list
101/// that grows and shrinks.
102pub(crate) enum Child {
103  One(Box<dyn Widget>),
104  Keyed(KeyedList),
105}
106
107/// A [`Child`] with its widget turned into an element.
108pub(crate) enum ElementChild {
109  One(Box<Element>),
110  Keyed(KeyedMount),
111}
112
113/// Turns every child widget into its element, which does the same for its
114/// own children.
115fn describe(children: Vec<Child>) -> Vec<ElementChild> {
116  children
117    .into_iter()
118    .map(|child| match child {
119      Child::One(widget) => ElementChild::One(Box::new(widget.into_element())),
120      Child::Keyed(list) => ElementChild::Keyed(list.into_mount()),
121    })
122    .collect()
123}
124
125pub(crate) struct FlexProps {
126  pub(crate) column: bool,
127  /// Takes the room left in its parent, like a spacer. Only `Menu` sets
128  /// it, so an entry's row fills its button.
129  pub(crate) grow: bool,
130  pub(crate) gap: Option<Prop<u32>>,
131  pub(crate) padding_vertical: Option<Prop<u32>>,
132  pub(crate) padding_horizontal: Option<Prop<u32>>,
133  pub(crate) align: Option<Prop<Align>>,
134  pub(crate) justify: Option<Prop<Justify>>,
135  pub(crate) wrap: Option<Prop<bool>>,
136  pub(crate) reverse: Option<Prop<bool>>,
137  /// Overrides `column` with a binding, for a list that turns.
138  pub(crate) column_binding: Option<Prop<bool>>,
139}
140
141pub(crate) struct GridProps {
142  pub(crate) columns: Option<Prop<u32>>,
143  pub(crate) gap: Option<Prop<u32>>,
144  pub(crate) row_gap: Option<Prop<u32>>,
145  pub(crate) column_gap: Option<Prop<u32>>,
146  pub(crate) padding_vertical: Option<Prop<u32>>,
147  pub(crate) padding_horizontal: Option<Prop<u32>>,
148}
149
150pub(crate) struct TextProps {
151  /// The plain text, or for a rich text `None` and its spans.
152  pub(crate) text: Option<Prop<String>>,
153  pub(crate) spans: Option<Prop<Vec<Span>>>,
154  pub(crate) elide: Option<Prop<Elide>>,
155  pub(crate) max_lines: Option<Prop<u32>>,
156  pub(crate) selectable: Option<Prop<bool>>,
157  pub(crate) on_link: Option<LinkHandler>,
158  pub(crate) link_hover_color: Option<Prop<Option<Color>>>,
159}
160
161pub(crate) struct IconProps {
162  pub(crate) source: Prop<IconSource>,
163  pub(crate) fallback: Option<Prop<IconSource>>,
164  pub(crate) size: Option<Prop<u32>>,
165  pub(crate) tint: Option<Prop<Option<Color>>>,
166}
167
168pub(crate) struct ImageProps {
169  pub(crate) source: Prop<PathBuf>,
170  pub(crate) width: Option<Prop<u32>>,
171  pub(crate) height: Option<Prop<u32>>,
172  pub(crate) fit: Option<Prop<Fit>>,
173  pub(crate) tint: Option<Prop<Option<Color>>>,
174  pub(crate) brightness: Option<Prop<f32>>,
175  pub(crate) contrast: Option<Prop<f32>>,
176  pub(crate) saturation: Option<Prop<f32>>,
177  pub(crate) blur: Option<Prop<f32>>,
178  pub(crate) playing: Option<Prop<bool>>,
179  pub(crate) transition: Option<Prop<ImageTransition>>,
180}
181
182/// The filters an [`Image`] is drawn through, for the renderer. Each
183/// number is finite and at least 0, and the default changes nothing.
184#[derive(Clone, Copy, Debug, PartialEq)]
185pub struct ImageFilters {
186  /// The color every pixel is painted in, keeping its alpha.
187  pub tint: Option<Color>,
188  /// Scales each color channel, as CSS's `brightness()`.
189  pub brightness: f32,
190  /// Moves each channel from or toward the middle gray, as CSS's
191  /// `contrast()`.
192  pub contrast: f32,
193  /// Moves each color from or toward its gray, as CSS's `saturate()`.
194  pub saturation: f32,
195  /// A Gaussian blur's standard deviation in logical pixels, as CSS's
196  /// `blur()`.
197  pub blur: f32,
198}
199
200impl Default for ImageFilters {
201  fn default() -> ImageFilters {
202    ImageFilters {
203      tint: None,
204      brightness: 1.0,
205      contrast: 1.0,
206      saturation: 1.0,
207      blur: 0.0,
208    }
209  }
210}
211
212/// How an [`Image`] fills its box when their shapes differ, as CSS's
213/// `object-fit`.
214#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
215pub enum Fit {
216  /// Stretched to the box. The default.
217  #[default]
218  Fill,
219  /// As large as fits whole, centered, keeping its shape.
220  Contain,
221  /// Covering the whole box, centered, keeping its shape; what sticks out
222  /// is cut off.
223  Cover,
224}
225
226pub(crate) struct ButtonProps {
227  pub(crate) hover_style: Option<Prop<Style>>,
228  pub(crate) pressed_style: Option<Prop<Style>>,
229  pub(crate) focus_style: Option<Prop<Style>>,
230  pub(crate) hovered: Option<Signal<bool>>,
231  pub(crate) position: Option<Signal<Option<Point>>>,
232  pub(crate) enabled: Option<Prop<bool>>,
233  pub(crate) focus: Option<Prop<bool>>,
234  pub(crate) cursor: Option<Prop<CursorShape>>,
235  pub(crate) drag_data: Option<Prop<Option<DragValue>>>,
236  pub(crate) drop_hovered: Option<Signal<bool>>,
237  pub(crate) handlers: Handlers,
238}
239
240/// How a [`Row`] or [`Column`] places children across its direction: up and
241/// down in a row, left and right in a column. As a child's own
242/// [`Style::align_self`] and [`Style::justify_self`], it also places the
243/// child in a [`Stack`]'s or grid's cell: start is the top or the left.
244#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
245pub enum Align {
246  /// At the start: the top of a row, the left of a column.
247  Start,
248  /// In the middle.
249  Center,
250  /// At the end: the bottom of a row, the right of a column.
251  End,
252  /// Stretched to fill. The default, as in CSS.
253  #[default]
254  Stretch,
255}
256
257/// How a [`Row`] or [`Column`] places children along its direction when
258/// they don't fill it.
259#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
260pub enum Justify {
261  /// Packed at the start. The default.
262  #[default]
263  Start,
264  /// Packed in the middle.
265  Center,
266  /// Packed at the end.
267  End,
268  /// The first child at the start, the last at the end, equal space between.
269  SpaceBetween,
270  /// Equal space around each child.
271  SpaceAround,
272  /// Equal space between children and at both ends.
273  SpaceEvenly,
274}
275
276/// What an [`Icon`] shows.
277#[derive(Clone, Debug, PartialEq)]
278pub enum IconSource {
279  /// A freedesktop icon name such as `"audio-volume-high"`, looked up in
280  /// the icon theme.
281  Name(String),
282  /// An SVG or PNG file.
283  File(PathBuf),
284  /// Raw pixels, as a tray item sends them.
285  Pixels(IconPixels),
286}
287
288/// Raw icon pixels: ARGB32 in network byte order (A, R, G, B bytes), row
289/// by row, as the StatusNotifierItem spec sends them.
290#[derive(Clone, Debug, PartialEq)]
291pub struct IconPixels {
292  /// Width in pixels.
293  pub width: u32,
294  /// Height in pixels.
295  pub height: u32,
296  /// `width * height * 4` bytes. Shared, so the same icon isn't copied.
297  pub data: Rc<[u8]>,
298}
299
300/// The methods every container has: `child`, `children_keyed`, `exit`
301/// and `displaced`.
302macro_rules! container_methods {
303  () => {
304    /// Adds `child` after the children added so far.
305    pub fn child(mut self, child: impl Widget) -> Self {
306      self.children.push(Child::One(Box::new(child)));
307      self
308    }
309
310    /// Adds one child per item, after the children added so far.
311    ///
312    /// `items` runs in an effect, so the list updates when a signal it
313    /// read changes. `key` names each item. `view` builds the child for
314    /// a key the first time it appears, and that child is kept while
315    /// its key stays in the list, even if it moves. `view` receives the
316    /// item's [`Cx`] and a [`Memo`] that updates when that item's value
317    /// changes. When a key leaves the list, its child and everything
318    /// created in `view` are freed, at once or after an
319    /// [`exit`](Self::exit). If two items share a key, only the first is
320    /// shown and the duplicate is logged.
321    pub fn children_keyed<T, K, W>(
322      mut self,
323      items: impl FnMut() -> Vec<T> + 'static,
324      key: impl FnMut(&T) -> K + 'static,
325      view: impl FnMut(&Cx, Memo<T>) -> W + 'static,
326    ) -> Self
327    where
328      T: Clone + PartialEq + 'static,
329      K: Eq + Hash + 'static,
330      W: Widget,
331    {
332      self
333        .children
334        .push(Child::Keyed(keyed::mount(items, key, view)));
335      self
336    }
337
338    /// Lets the children of the last [`children_keyed`](Self::children_keyed)
339    /// list added leave over `exit` instead of at once. A child whose key
340    /// leaves stays mounted and painted right after the child that was
341    /// before it, and its context's [`leaving`](Cx::leaving) turns `true`,
342    /// so its own `cx.animate` can fade or shrink it out. It is freed at
343    /// the first tick of the animation clock that finds nothing moving in
344    /// it, or after `exit` at the latest; motion the clock doesn't run in
345    /// the item, such as one stepped by `cx.interval`, doesn't hold it.
346    /// If its key comes back first, the same child, with its
347    /// state, takes the key's new place. A closure is read as each key
348    /// leaves, and an exit of 0 removes at once. Leaving children still
349    /// take pointer and keyboard input; a handler can check
350    /// [`cx.leaving()`](Cx::leaving) to ignore clicks during the exit.
351    pub fn exit(mut self, exit: impl IntoProp<Duration>) -> Self {
352      let last = self
353        .children
354        .iter_mut()
355        .rev()
356        .find_map(|child| match child {
357          Child::Keyed(list) => Some(list),
358          Child::One(_) => None,
359        });
360      match last {
361        Some(list) => list.exit = Some(exit.into_prop()),
362        None => tracing::warn!("`exit` was called before any `children_keyed`; it does nothing"),
363      }
364      self
365    }
366
367    /// Slides the children that a change of the last
368    /// [`children_keyed`](Self::children_keyed) list moves, instead of
369    /// jumping: when its keys are added, leave (once their
370    /// [`exit`](Self::exit) ends) or move, each child of this container
371    /// whose place changes goes from where it was drawn to its new place
372    /// over `transition`. It moves where it is drawn and hit, as
373    /// [`Style::translate`](crate::Style::translate) does, so a slide never
374    /// lays the window out again. A child moved again mid-slide starts from
375    /// where it is drawn. Other layout changes, such as a resize or text
376    /// growing, still move children at once, and a new child shows in its
377    /// place. A closure is read at each change of the list, and a
378    /// transition of 0 jumps.
379    pub fn displaced(mut self, transition: impl IntoProp<crate::Transition>) -> Self {
380      let last = self
381        .children
382        .iter_mut()
383        .rev()
384        .find_map(|child| match child {
385          Child::Keyed(list) => Some(list),
386          Child::One(_) => None,
387        });
388      match last {
389        Some(list) => list.displaced = Some(transition.into_prop()),
390        None => {
391          tracing::warn!("`displaced` was called before any `children_keyed`; it does nothing")
392        }
393      }
394      self
395    }
396  };
397}
398
399/// The `visible`, `geometry`, `mapped_geometry` and `accessible_name`
400/// methods every widget has.
401macro_rules! visibility_methods {
402  () => {
403    /// Shows or hides the widget. Hidden, it is taken out of the layout,
404    /// so its space goes to the others, and it isn't drawn, hit or
405    /// reached by Tab; it drops the keyboard focus and the pointer. Its
406    /// bindings and state stay, so it shows again as it was. Shown by
407    /// default.
408    pub fn visible(mut self, visible: impl $crate::IntoProp<bool>) -> Self {
409      self.common.visible = Some(visible.into_prop());
410      self
411    }
412
413    /// Shares where the widget is: after each layout that moves or
414    /// resizes it, its laid-out rectangle in the window's logical
415    /// pixels, scrolled with any scroll view around it but not moved by
416    /// a style's translate, scale or rotate, is written to `geometry`. A
417    /// hidden widget writes nothing. An effect that reads it may change
418    /// the layout: the window is laid out again at once, until nothing
419    /// moves.
420    pub fn geometry(mut self, geometry: ::crabshell_reactive::Signal<$crate::Rect>) -> Self {
421      self.common.geometry = Some(geometry);
422      self
423    }
424
425    /// Shares where the widget is drawn: the box around it once its own
426    /// and its ancestors' translate, scale and rotate have moved it, in
427    /// the window's logical pixels, scrolled with any scroll view around
428    /// it. It is written after each layout that moves it and after each
429    /// change of a transform or an offset that does, every frame of an
430    /// animated one. A hidden widget writes nothing. Where the window
431    /// itself is on its output is unknown: Wayland doesn't tell a client.
432    pub fn mapped_geometry(mut self, geometry: ::crabshell_reactive::Signal<$crate::Rect>) -> Self {
433      self.common.mapped_geometry = Some(geometry);
434      self
435    }
436
437    /// What a screen reader calls the widget, instead of what it shows:
438    /// a button's text, a text's own, or a field's placeholder. An icon
439    /// button needs one to be read at all.
440    pub fn accessible_name(mut self, name: impl $crate::IntoProp<String>) -> Self {
441      self.common.accessible_name = Some(name.into_prop());
442      self
443    }
444  };
445}
446
447/// The `style` method every widget has, with `visible` and `geometry`.
448macro_rules! style_method {
449  () => {
450    /// Sets the widget's [`Style`](crate::Style).
451    pub fn style(mut self, style: impl $crate::IntoProp<$crate::Style>) -> Self {
452      self.common.style = Some(style.into_prop());
453      self
454    }
455
456    $crate::widgets::visibility_methods!();
457  };
458}
459
460pub(crate) use visibility_methods;
461
462/// Defines `Row` and `Column`, which differ only in direction.
463macro_rules! flex_widget {
464  ($name:ident, $column:literal, $doc:literal) => {
465    #[doc = $doc]
466    ///
467    /// `gap`, `padding`, `align`, `justify`, `wrap` and `reverse` change
468    /// the layout. Each takes a value or a closure.
469    pub struct $name {
470      flex: FlexProps,
471      common: Common,
472      children: Vec<Child>,
473    }
474
475    impl $name {
476      /// An empty container.
477      pub fn new() -> Self {
478        $name {
479          flex: FlexProps {
480            column: $column,
481            grow: false,
482            gap: None,
483            padding_vertical: None,
484            padding_horizontal: None,
485            align: None,
486            justify: None,
487            wrap: None,
488            reverse: None,
489            column_binding: None,
490          },
491          common: Common::default(),
492          children: Vec::new(),
493        }
494      }
495
496      /// Sets the space between children in logical pixels.
497      pub fn gap(mut self, gap: impl IntoProp<u32>) -> Self {
498        self.flex.gap = Some(gap.into_prop());
499        self
500      }
501
502      /// Sets the padding: `vertical` above and below, `horizontal`
503      /// left and right, in logical pixels. It wins over the padding
504      /// of the container's [`Style`].
505      pub fn padding(
506        mut self,
507        vertical: impl IntoProp<u32>,
508        horizontal: impl IntoProp<u32>,
509      ) -> Self {
510        self.flex.padding_vertical = Some(vertical.into_prop());
511        self.flex.padding_horizontal = Some(horizontal.into_prop());
512        self
513      }
514
515      /// Sets how children are placed across the direction.
516      pub fn align(mut self, align: impl IntoProp<Align>) -> Self {
517        self.flex.align = Some(align.into_prop());
518        self
519      }
520
521      /// Sets how children are placed along the direction.
522      pub fn justify(mut self, justify: impl IntoProp<Justify>) -> Self {
523        self.flex.justify = Some(justify.into_prop());
524        self
525      }
526
527      /// When on, children that don't fit start a new line, `gap` apart
528      /// like the children, and the lines pack at the start. Off by
529      /// default.
530      pub fn wrap(mut self, wrap: impl IntoProp<bool>) -> Self {
531        self.flex.wrap = Some(wrap.into_prop());
532        self
533      }
534
535      /// When on, a row runs right to left and a column bottom to top, so
536      /// [`Justify::Start`] packs children at the right or the bottom.
537      /// Tab still moves through them in child order. Off by default.
538      pub fn reverse(mut self, reverse: impl IntoProp<bool>) -> Self {
539        self.flex.reverse = Some(reverse.into_prop());
540        self
541      }
542
543      container_methods!();
544      style_method!();
545    }
546
547    impl Default for $name {
548      fn default() -> Self {
549        Self::new()
550      }
551    }
552
553    impl Widget for $name {
554      fn into_element(self: Box<Self>) -> Element {
555        Element {
556          name: stringify!($name),
557          common: self.common,
558          kind: ElementKind::Flex(self.flex),
559          children: describe(self.children),
560        }
561      }
562    }
563  };
564}
565
566flex_widget!(
567  Row,
568  false,
569  "Lays its children out left to right, like a CSS flexbox row."
570);
571flex_widget!(
572  Column,
573  true,
574  "Lays its children out top to bottom, like a CSS flexbox column."
575);
576
577/// Places its children row by row into equal-width columns, each row as
578/// tall as its tallest child. A child takes several cells with
579/// [`Style::span`], and places itself in its cell with
580/// [`Style::align_self`] and [`Style::justify_self`]; it fills the cell by
581/// default.
582///
583/// `columns`, `gap`, `row_gap`, `column_gap` and `padding` change the
584/// layout. Each takes a value or a closure.
585///
586/// ```
587/// use crabshell_ui::{Grid, Style, Text};
588///
589/// let days = (1..=31).fold(Grid::new().columns(7).gap(4), |grid, day| {
590///     grid.child(Text::new(day.to_string()))
591/// });
592/// let wide = Grid::new()
593///     .columns(2)
594///     .child(Text::new("title").style(Style::new().span(2, 1)));
595/// ```
596pub struct Grid {
597  grid: GridProps,
598  common: Common,
599  children: Vec<Child>,
600}
601
602impl Grid {
603  /// An empty grid of one column.
604  pub fn new() -> Grid {
605    Grid {
606      grid: GridProps {
607        columns: None,
608        gap: None,
609        row_gap: None,
610        column_gap: None,
611        padding_vertical: None,
612        padding_horizontal: None,
613      },
614      common: Common::default(),
615      children: Vec::new(),
616    }
617  }
618
619  /// Sets the number of columns, all as wide. 1 by default, and 0
620  /// counts as 1.
621  pub fn columns(mut self, columns: impl IntoProp<u32>) -> Grid {
622    self.grid.columns = Some(columns.into_prop());
623    self
624  }
625
626  /// Sets the space between rows and between columns in logical pixels.
627  /// `row_gap` and `column_gap` win over it.
628  pub fn gap(mut self, gap: impl IntoProp<u32>) -> Grid {
629    self.grid.gap = Some(gap.into_prop());
630    self
631  }
632
633  /// Sets the space between rows in logical pixels.
634  pub fn row_gap(mut self, gap: impl IntoProp<u32>) -> Grid {
635    self.grid.row_gap = Some(gap.into_prop());
636    self
637  }
638
639  /// Sets the space between columns in logical pixels.
640  pub fn column_gap(mut self, gap: impl IntoProp<u32>) -> Grid {
641    self.grid.column_gap = Some(gap.into_prop());
642    self
643  }
644
645  /// Sets the padding: `vertical` above and below, `horizontal` left and
646  /// right, in logical pixels. It wins over the padding of the grid's
647  /// [`Style`], as a [`Row`]'s does.
648  pub fn padding(mut self, vertical: impl IntoProp<u32>, horizontal: impl IntoProp<u32>) -> Grid {
649    self.grid.padding_vertical = Some(vertical.into_prop());
650    self.grid.padding_horizontal = Some(horizontal.into_prop());
651    self
652  }
653
654  container_methods!();
655  style_method!();
656}
657
658impl Default for Grid {
659  fn default() -> Self {
660    Self::new()
661  }
662}
663
664impl Widget for Grid {
665  fn into_element(self: Box<Self>) -> Element {
666    Element {
667      name: "Grid",
668      common: self.common,
669      kind: ElementKind::Grid(self.grid),
670      children: describe(self.children),
671    }
672  }
673}
674
675/// Draws its children on top of each other in one cell, each stretched to
676/// the size of the largest. Later children are on top.
677pub struct Stack {
678  common: Common,
679  children: Vec<Child>,
680}
681
682impl Stack {
683  /// An empty stack.
684  pub fn new() -> Stack {
685    Stack {
686      common: Common::default(),
687      children: Vec::new(),
688    }
689  }
690
691  container_methods!();
692  style_method!();
693}
694
695impl Default for Stack {
696  fn default() -> Self {
697    Self::new()
698  }
699}
700
701impl Widget for Stack {
702  fn into_element(self: Box<Self>) -> Element {
703    Element {
704      name: "Stack",
705      common: self.common,
706      kind: ElementKind::Stack,
707      children: describe(self.children),
708    }
709  }
710}
711
712/// Takes the space left over in a [`Row`] or [`Column`]. Several spacers
713/// share it equally, or by their styles' [`grow`](Style::grow).
714pub struct Spacer {
715  common: Common,
716}
717
718impl Spacer {
719  /// A spacer.
720  pub fn new() -> Spacer {
721    Spacer {
722      common: Common::default(),
723    }
724  }
725
726  style_method!();
727}
728
729impl Default for Spacer {
730  fn default() -> Self {
731    Self::new()
732  }
733}
734
735impl Widget for Spacer {
736  fn into_element(self: Box<Self>) -> Element {
737    Element {
738      name: "Spacer",
739      common: self.common,
740      kind: ElementKind::Spacer,
741      children: Vec::new(),
742    }
743  }
744}
745
746/// Where text that doesn't fit is cut, with "…" in its place.
747#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
748pub enum Elide {
749  /// Not cut: the text keeps its width and overflows. The default.
750  #[default]
751  None,
752  /// The start of the last line shown.
753  Start,
754  /// The middle of the last line shown.
755  Middle,
756  /// The end of the last line shown.
757  End,
758}
759
760/// A line of text.
761///
762/// The text, `elide` and `max_lines` change the layout. Color, font,
763/// alignment, line height and decorations come from the nearest widget
764/// whose [`Style`] sets each, starting with the text's own.
765pub struct Text {
766  text: TextProps,
767  common: Common,
768}
769
770impl Text {
771  /// Text showing `text`: a string, or a closure that returns a `String`.
772  pub fn new(text: impl IntoProp<String>) -> Text {
773    Text {
774      text: TextProps {
775        text: Some(text.into_prop()),
776        spans: None,
777        elide: None,
778        max_lines: None,
779        selectable: None,
780        on_link: None,
781        link_hover_color: None,
782      },
783      common: Common::default(),
784    }
785  }
786
787  /// Text made of styled spans: a `Vec<Span>`, or a closure that returns
788  /// one. Each span takes what it doesn't set from the text, and
789  /// everything else a `Text` takes works the same.
790  pub fn rich(spans: impl IntoProp<Vec<Span>>) -> Text {
791    Text {
792      text: TextProps {
793        text: None,
794        spans: Some(spans.into_prop()),
795        elide: None,
796        max_lines: None,
797        selectable: None,
798        on_link: None,
799        link_hover_color: None,
800      },
801      common: Common::default(),
802    }
803  }
804
805  /// Runs `handler` with a link span's URL when a left click lands on
806  /// the span's glyphs. Over a link the cursor is the pointing hand and
807  /// the click goes to nothing else, not even a button around the text;
808  /// elsewhere the text lets the pointer through as before. In a
809  /// [`selectable`](Self::selectable) text, a press and release on one
810  /// link that selected nothing opens it, and a drag selects. Tab stops
811  /// on each link shown, in text order, and Enter or Space opens the one
812  /// focused. A link under the pointer or the focus draws underlined, in
813  /// [`link_hover_color`](Self::link_hover_color) if set. A handler that
814  /// panics is logged and disabled, and its links are plain text.
815  pub fn on_link(mut self, handler: impl Fn(&Cx, &str) + 'static) -> Text {
816    self.text.on_link = Some(Rc::new(Handler::new(handler)));
817    self
818  }
819
820  /// The color a link is drawn in while the pointer is over it or the
821  /// keyboard focus is on it: a color, `None`, or a closure returning
822  /// either. Either way the link is underlined; with `None`, the default,
823  /// it keeps its own color.
824  pub fn link_hover_color(mut self, color: impl IntoProp<Option<Color>>) -> Text {
825    self.text.link_hover_color = Some(color.into_prop());
826    self
827  }
828
829  /// When on, the text takes the pointer with an I-beam: a press, a drag,
830  /// a double click on a word, a triple click on a line and Shift+click
831  /// select it, as in a text field, and a
832  /// press takes the keyboard focus, so Ctrl+C copies the selection.
833  /// Inside a [`Button`], it takes the press, so the button doesn't
834  /// click. Tab doesn't stop on it. Off by default.
835  pub fn selectable(mut self, selectable: impl IntoProp<bool>) -> Text {
836    self.text.selectable = Some(selectable.into_prop());
837    self
838  }
839
840  /// When on, text that doesn't fit ends in "…" instead of being cut off.
841  /// Off by default. The same as [`elide`](Self::elide) with
842  /// [`Elide::End`] or [`Elide::None`]; whichever is called last wins.
843  pub fn ellipsis(mut self, ellipsis: impl IntoProp<bool>) -> Text {
844    let elide = ellipsis
845      .into_prop()
846      .map(|on| if on { Elide::End } else { Elide::None });
847    self.text.elide = Some(elide);
848    self
849  }
850
851  /// Where text that doesn't fit is cut, with "…" in its place:
852  /// [`Elide::None`] by default. With `max_lines` above 1, the last line
853  /// shown is cut.
854  pub fn elide(mut self, elide: impl IntoProp<Elide>) -> Text {
855    self.text.elide = Some(elide.into_prop());
856    self
857  }
858
859  /// Lets the text wrap onto at most this many lines, at word boundaries,
860  /// or inside a word too long for a line. The default is 1, which never
861  /// wraps. 0 counts as 1.
862  pub fn max_lines(mut self, max_lines: impl IntoProp<u32>) -> Text {
863    self.text.max_lines = Some(max_lines.into_prop());
864    self
865  }
866
867  style_method!();
868}
869
870impl Widget for Text {
871  fn into_element(self: Box<Self>) -> Element {
872    Element {
873      name: "Text",
874      common: self.common,
875      kind: ElementKind::Text(self.text),
876      children: Vec::new(),
877    }
878  }
879}
880
881/// An icon, drawn as a square.
882pub struct Icon {
883  icon: IconProps,
884  common: Common,
885}
886
887impl Icon {
888  /// The default size in logical pixels.
889  pub const DEFAULT_SIZE: u32 = 16;
890
891  /// An icon showing `source`: an icon name (`&str`), a file (`&Path` or
892  /// `PathBuf`), an [`IconSource`], or a closure that returns one.
893  pub fn new(source: impl IntoProp<IconSource>) -> Icon {
894    Icon {
895      icon: IconProps {
896        source: source.into_prop(),
897        fallback: None,
898        size: None,
899        tint: None,
900      },
901      common: Common::default(),
902    }
903  }
904
905  /// Sets the width and height in logical pixels.
906  pub fn size(mut self, size: impl IntoProp<u32>) -> Icon {
907    self.icon.size = Some(size.into_prop());
908    self
909  }
910
911  /// Paints the icon's pixels in `tint`, keeping their alpha, as a
912  /// symbolic icon's color follows the theme. `None`, the default, draws
913  /// it as it is.
914  pub fn tint(mut self, tint: impl IntoProp<Option<Color>>) -> Icon {
915    self.icon.tint = Some(tint.into_prop());
916    self
917  }
918
919  /// What to draw when the icon's own source isn't in the theme or its
920  /// file can't be loaded, taking what [`Icon::new`] takes. A chain of
921  /// fallbacks picks one with `cx.icon_path`.
922  pub fn fallback(mut self, fallback: impl IntoProp<IconSource>) -> Icon {
923    self.icon.fallback = Some(fallback.into_prop());
924    self
925  }
926
927  style_method!();
928}
929
930/// A picture from a PNG, JPEG, GIF, WebP or SVG file, drawn at a fixed
931/// size.
932///
933/// A GIF of more than one frame plays while it is drawn, at its own
934/// delays, looping as the file says. The filters run once on the picture
935/// at the size drawn, and the result is cached, so a filtered image costs
936/// what a plain one does to draw.
937pub struct Image {
938  image: ImageProps,
939  common: Common,
940}
941
942impl Image {
943  /// The default width and height in logical pixels.
944  pub const DEFAULT_SIZE: u32 = 64;
945
946  /// An image of the file at `source`: a path (`&str`, `String`, `&Path`
947  /// or `PathBuf`) or a closure that returns one.
948  pub fn new(source: impl IntoProp<PathBuf>) -> Image {
949    Image {
950      image: ImageProps {
951        source: source.into_prop(),
952        width: None,
953        height: None,
954        fit: None,
955        tint: None,
956        brightness: None,
957        contrast: None,
958        saturation: None,
959        blur: None,
960        playing: None,
961        transition: None,
962      },
963      common: Common::default(),
964    }
965  }
966
967  /// Sets the width in logical pixels.
968  pub fn width(mut self, width: impl IntoProp<u32>) -> Image {
969    self.image.width = Some(width.into_prop());
970    self
971  }
972
973  /// Sets the height in logical pixels.
974  pub fn height(mut self, height: impl IntoProp<u32>) -> Image {
975    self.image.height = Some(height.into_prop());
976    self
977  }
978
979  /// Sets how the picture fills the image's box when their shapes differ.
980  pub fn fit(mut self, fit: impl IntoProp<Fit>) -> Image {
981    self.image.fit = Some(fit.into_prop());
982    self
983  }
984
985  /// Paints the picture's pixels in `tint`, keeping their alpha, as
986  /// [`Icon::tint`] does. `None`, the default, draws it as it is.
987  pub fn tint(mut self, tint: impl IntoProp<Option<Color>>) -> Image {
988    self.image.tint = Some(tint.into_prop());
989    self
990  }
991
992  /// Scales the colors, as CSS's `brightness()`: 1, the default, leaves
993  /// them, 0 is black and 2 twice as bright. A number that isn't finite
994  /// counts as 1, and one below 0 as 0.
995  pub fn brightness(mut self, brightness: impl IntoProp<f32>) -> Image {
996    self.image.brightness = Some(brightness.into_prop());
997    self
998  }
999
1000  /// Sets the contrast, as CSS's `contrast()`: 1, the default, leaves the
1001  /// colors, 0 is middle gray and more than 1 is stronger. A number that
1002  /// isn't finite counts as 1, and one below 0 as 0.
1003  pub fn contrast(mut self, contrast: impl IntoProp<f32>) -> Image {
1004    self.image.contrast = Some(contrast.into_prop());
1005    self
1006  }
1007
1008  /// Sets the saturation, as CSS's `saturate()`: 1, the default, leaves
1009  /// the colors, 0 is gray and more than 1 is more vivid. A number that
1010  /// isn't finite counts as 1, and one below 0 as 0.
1011  pub fn saturation(mut self, saturation: impl IntoProp<f32>) -> Image {
1012    self.image.saturation = Some(saturation.into_prop());
1013    self
1014  }
1015
1016  /// Blurs the picture, as CSS's `blur()`: the Gaussian's standard
1017  /// deviation in logical pixels, 0 by default. Pixels past the picture's
1018  /// edge count as its edge pixels, so a blurred picture keeps its edges
1019  /// opaque. A number that isn't finite or is below 0 counts as 0. The
1020  /// blur is for still pictures, such as album art and wallpapers: a
1021  /// blurred GIF shows its first frame, still.
1022  pub fn blur(mut self, blur: impl IntoProp<f32>) -> Image {
1023    self.image.blur = Some(blur.into_prop());
1024    self
1025  }
1026
1027  /// Whether an animated GIF plays, true by default. False pauses it on
1028  /// the frame it shows.
1029  pub fn playing(mut self, playing: impl IntoProp<bool>) -> Image {
1030    self.image.playing = Some(playing.into_prop());
1031    self
1032  }
1033
1034  /// How a new source comes in: [`ImageTransition::None`], the default,
1035  /// shows it at once; the others bring it in over the old picture on the
1036  /// animation clock, repainting only the image's box. A new source
1037  /// mid-transition starts again from the picture most of the box shows:
1038  /// the one leaving before halfway, the one coming in from halfway on.
1039  /// A new source that can't be loaded keeps the old picture; the clock
1040  /// still runs and repaints the box for the transition's length, since
1041  /// only the renderer learns the file is bad.
1042  pub fn transition(mut self, transition: impl IntoProp<ImageTransition>) -> Image {
1043    self.image.transition = Some(transition.into_prop());
1044    self
1045  }
1046
1047  style_method!();
1048}
1049
1050impl Widget for Image {
1051  fn into_element(self: Box<Self>) -> Element {
1052    Element {
1053      name: "Image",
1054      common: self.common,
1055      kind: ElementKind::Image(self.image),
1056      children: Vec::new(),
1057    }
1058  }
1059}
1060
1061impl Widget for Icon {
1062  fn into_element(self: Box<Self>) -> Element {
1063    Element {
1064      name: "Icon",
1065      common: self.common,
1066      kind: ElementKind::Icon(self.icon),
1067      children: Vec::new(),
1068    }
1069  }
1070}
1071
1072/// A clickable box around one child, which it centers.
1073///
1074/// While the pointer is over it, `hover_style` is laid over its style, and
1075/// while it is also held down, `pressed_style` on top of that. Handlers run
1076/// on the main thread and receive the button's [`Cx`]. A handler that panics
1077/// is logged and never called again.
1078pub struct Button {
1079  button: ButtonProps,
1080  common: Common,
1081  child: Box<dyn Widget>,
1082}
1083
1084impl Button {
1085  /// A button around `child`.
1086  pub fn new(child: impl Widget) -> Button {
1087    Button {
1088      child: Box::new(child),
1089      button: ButtonProps {
1090        hover_style: None,
1091        pressed_style: None,
1092        focus_style: None,
1093        hovered: None,
1094        position: None,
1095        enabled: None,
1096        focus: None,
1097        cursor: None,
1098        drag_data: None,
1099        drop_hovered: None,
1100        handlers: Handlers::default(),
1101      },
1102      common: Common::default(),
1103    }
1104  }
1105
1106  /// Sets the style laid over the normal one while the pointer is over the
1107  /// button.
1108  pub fn hover_style(mut self, style: impl IntoProp<Style>) -> Button {
1109    self.button.hover_style = Some(style.into_prop());
1110    self
1111  }
1112
1113  /// Shares whether the pointer is over the button: the button sets
1114  /// `hovered` to `true` while the pointer is over it or anything inside
1115  /// it, buttons too, and back to `false` when it leaves, the window loses
1116  /// it, or the button goes. Unlike `hover_style`, which only the deepest
1117  /// button under the pointer shows, an outer button stays hovered while
1118  /// the pointer is over one inside it, so it can show controls on hover.
1119  /// A drag of this button or one inside it keeps it hovered until the
1120  /// release.
1121  pub fn hovered(mut self, hovered: Signal<bool>) -> Button {
1122    self.button.hovered = Some(hovered);
1123    self
1124  }
1125
1126  /// Sets the style laid over the hover style while the button is held
1127  /// down.
1128  pub fn pressed_style(mut self, style: impl IntoProp<Style>) -> Button {
1129    self.button.pressed_style = Some(style.into_prop());
1130    self
1131  }
1132
1133  /// Sets the style laid over the normal one while the button has the
1134  /// keyboard focus, which Tab moves between buttons.
1135  pub fn focus_style(mut self, style: impl IntoProp<Style>) -> Button {
1136    self.button.focus_style = Some(style.into_prop());
1137    self
1138  }
1139
1140  /// Runs `handler` for each key pressed while the button has the
1141  /// keyboard focus. It returns `true` when it used the key; otherwise the
1142  /// window's `on_key` gets it, and then Tab, Enter and Space do what
1143  /// they do by default.
1144  pub fn on_key(mut self, handler: impl Fn(&Cx, &KeyEvent) -> bool + 'static) -> Button {
1145    self.button.handlers.key = Some(Rc::new(Handler::new(handler)));
1146    self
1147  }
1148
1149  /// Runs `handler` as soon as the left button goes down over this
1150  /// button, while it is held: the time to call
1151  /// [`Cx::start_move`](crate::Cx::start_move), as a title bar does.
1152  pub fn on_press(mut self, handler: impl Fn(&Cx) + 'static) -> Button {
1153    self.button.handlers.press = Some(Rc::new(Handler::new(handler)));
1154    self
1155  }
1156
1157  /// Runs `handler` when the left button comes up after going down on
1158  /// this button, wherever the pointer is by then, before `on_click`.
1159  pub fn on_release(mut self, handler: impl Fn(&Cx) + 'static) -> Button {
1160    self.button.handlers.release = Some(Rc::new(Handler::new(handler)));
1161    self
1162  }
1163
1164  /// Runs `handler` when the left button is pressed and released over this
1165  /// button, unless that ended a drag or a long press, or made a double
1166  /// click.
1167  pub fn on_click(mut self, handler: impl Fn(&Cx) + 'static) -> Button {
1168    self.button.handlers.click = Some(Rc::new(Handler::new(handler)));
1169    self
1170  }
1171
1172  /// Runs `handler` instead of a second `on_click` when a click comes
1173  /// within 400 ms and 5 logical pixels of the one before, as Qt's
1174  /// defaults say. A third click starts over. Without it, every click
1175  /// runs `on_click`.
1176  pub fn on_double_click(mut self, handler: impl Fn(&Cx) + 'static) -> Button {
1177    self.button.handlers.double_click = Some(Rc::new(Handler::new(handler)));
1178    self
1179  }
1180
1181  /// Runs `handler` once the left button has been held on this button for
1182  /// 800 ms without moving 10 logical pixels, as Qt's press and hold. The
1183  /// release after it doesn't click, though moving on can still drag.
1184  pub fn on_long_press(mut self, handler: impl Fn(&Cx) + 'static) -> Button {
1185    self.button.handlers.long_press = Some(Rc::new(Handler::new(handler)));
1186    self
1187  }
1188
1189  /// Runs `handler` as the left button drags this button: a
1190  /// [`DragPhase::Start`](crate::DragPhase::Start) once it moves 10
1191  /// logical pixels from where it went down, a `Move` for each motion
1192  /// after, and an `End` when it comes up, the pointer leaves the window,
1193  /// or the button is disabled. A button with no `on_click`,
1194  /// `on_double_click` or `on_long_press` starts at the press instead, so
1195  /// a slider moves from the first touch.
1196  ///
1197  /// While it drags, the button gets every motion, even outside itself or
1198  /// the window, stays hovered, and doesn't click.
1199  pub fn on_drag(mut self, handler: impl Fn(&Cx, Drag) + 'static) -> Button {
1200    self.button.handlers.drag = Some(Rc::new(Handler::new(handler)));
1201    self
1202  }
1203
1204  /// Runs `handler` when the right button is pressed and released over this
1205  /// button.
1206  pub fn on_right_click(mut self, handler: impl Fn(&Cx) + 'static) -> Button {
1207    self.button.handlers.right_click = Some(Rc::new(Handler::new(handler)));
1208    self
1209  }
1210
1211  /// Runs `handler` when the middle button is pressed and released over
1212  /// this button.
1213  pub fn on_middle_click(mut self, handler: impl Fn(&Cx) + 'static) -> Button {
1214    self.button.handlers.middle_click = Some(Rc::new(Handler::new(handler)));
1215    self
1216  }
1217
1218  /// Runs `handler` when the mouse's back side button is pressed and
1219  /// released over this button.
1220  pub fn on_back(mut self, handler: impl Fn(&Cx) + 'static) -> Button {
1221    self.button.handlers.back = Some(Rc::new(Handler::new(handler)));
1222    self
1223  }
1224
1225  /// Runs `handler` when the mouse's forward side button is pressed and
1226  /// released over this button.
1227  pub fn on_forward(mut self, handler: impl Fn(&Cx) + 'static) -> Button {
1228    self.button.handlers.forward = Some(Rc::new(Handler::new(handler)));
1229    self
1230  }
1231
1232  /// Runs `handler` with whole scroll steps while the pointer is over this
1233  /// button: positive for up, negative for down. A mouse wheel gives one
1234  /// step per notch; touchpad scrolling gives one step per 15 logical
1235  /// pixels. Sideways scrolling gives none.
1236  pub fn on_scroll(mut self, handler: impl Fn(&Cx, i32) + 'static) -> Button {
1237    self.button.handlers.scroll = Some(Rc::new(Handler::new(handler)));
1238    self
1239  }
1240
1241  /// Runs `handler` with every scroll event while the pointer is over
1242  /// this button, on both axes: a wheel's notches, a touchpad's pixels,
1243  /// where it came from, and the `stop` when the fingers lift. Positive
1244  /// is down and right. With `on_scroll` too, both run.
1245  pub fn on_wheel(mut self, handler: impl Fn(&Cx, Wheel) + 'static) -> Button {
1246    self.button.handlers.wheel = Some(Rc::new(Handler::new(handler)));
1247    self
1248  }
1249
1250  /// Shares where the pointer is: the button writes `position`, in its
1251  /// own coordinates with (0, 0) at its top-left, while the pointer is
1252  /// over it or anything inside it, and `None` when it leaves. While a
1253  /// button inside it, or this one, is dragged, it follows the pointer
1254  /// wherever it goes, even outside the button. It is written only on a
1255  /// change.
1256  pub fn pointer_position(mut self, position: Signal<Option<Point>>) -> Button {
1257    self.button.position = Some(position);
1258    self
1259  }
1260
1261  /// Turns the button on or off; it is on by default. Off, none of its
1262  /// handlers run, it shows no hover, pressed or focus style and the
1263  /// default cursor, and Tab skips it. The pointer passes through it to
1264  /// the button around it, as through a disabled Qt `MouseArea`. Turning
1265  /// it off while it is held lets go, ending a drag with its `End`, and
1266  /// drops its focus.
1267  pub fn enabled(mut self, enabled: impl IntoProp<bool>) -> Button {
1268    self.button.enabled = Some(enabled.into_prop());
1269    self
1270  }
1271
1272  /// Takes the keyboard focus whenever this turns true, as
1273  /// [`TextInput::focus`](crate::TextInput::focus) does. Tab and a field
1274  /// may take it away again.
1275  pub fn focus(mut self, focus: impl IntoProp<bool>) -> Button {
1276    self.button.focus = Some(focus.into_prop());
1277    self
1278  }
1279
1280  /// Makes a drag of this button carry `data`, which a button whose
1281  /// [`on_drop`](Self::on_drop) takes a `T` is given when the drag is
1282  /// released over it. A closure is read as it changes, and a drop gets
1283  /// the value it holds at the release. While it holds a value, the button
1284  /// drags as one with [`on_drag`](Self::on_drag) does, and its `on_drag`
1285  /// still runs, so it can follow the pointer with a translate; its `End`
1286  /// says whether it was dropped. While it holds `None`, the button acts as
1287  /// if it had no data: it clicks, and drags only with its own `on_drag`,
1288  /// so `editing.get().then_some(id)` drags only in an edit mode. Once
1289  /// the pointer leaves the window, the drag reaches buttons in the
1290  /// shell's other windows too, and other programs see one they can't
1291  /// take.
1292  pub fn drag_data<T: Clone + 'static>(mut self, data: impl IntoProp<Option<T>>) -> Button {
1293    let data = data
1294      .into_prop()
1295      .map(|data| data.map(|value| Rc::new(value) as DragValue));
1296    self.button.drag_data = Some(data);
1297    self
1298  }
1299
1300  /// Runs `handler` with a copy of the [`drag_data`](Self::drag_data) of a
1301  /// drag released over this button, or over anything inside it, when
1302  /// that data is a `T`. Data of any other type passes over it, as if it
1303  /// weren't there. The deepest button under the pointer that takes it is
1304  /// the one dropped on, and the dragged button never takes its own.
1305  pub fn on_drop<T: Clone + 'static>(mut self, handler: impl Fn(&Cx, T) + 'static) -> Button {
1306    let take = move |cx: &Cx, value: &dyn std::any::Any| {
1307      if let Some(value) = value.downcast_ref::<T>() {
1308        handler(cx, value.clone());
1309      }
1310    };
1311    self.button.handlers.drop = Some(DropTarget {
1312      accepts: std::any::TypeId::of::<T>(),
1313      handler: Rc::new(Handler::new(take)),
1314      name: "on_drop",
1315    });
1316    self
1317  }
1318
1319  /// Makes a drag of this button carry `content`, as
1320  /// [`drag_data`](Self::drag_data) does, to buttons in any of the
1321  /// shell's windows and, once the pointer leaves the window, to other
1322  /// programs, as text or a URI list. It replaces any `drag_data`.
1323  pub fn drag_content(self, content: impl IntoProp<Option<DragContent>>) -> Button {
1324    self.drag_data(content)
1325  }
1326
1327  /// Runs `handler` with what a drag from another program, or a
1328  /// [`drag_content`](Self::drag_content) of the shell's, carries when it
1329  /// is released over this button: URIs when the program offers them,
1330  /// else text. It replaces any [`on_drop`](Self::on_drop).
1331  pub fn on_drop_content(mut self, handler: impl Fn(&Cx, DragContent) + 'static) -> Button {
1332    self = self.on_drop(handler);
1333    if let Some(target) = &mut self.button.handlers.drop {
1334      target.name = "on_drop_content";
1335    }
1336    self
1337  }
1338
1339  /// Shares whether a drop is waiting: the button writes `hovered` true
1340  /// while a drag whose data its [`on_drop`](Self::on_drop) would take is
1341  /// over it, as Qt's `DropArea.containsDrag`, and false when the drag
1342  /// leaves, ends, or either button goes, is hidden or is turned off.
1343  pub fn drop_hovered(mut self, hovered: Signal<bool>) -> Button {
1344    self.button.drop_hovered = Some(hovered);
1345    self
1346  }
1347
1348  /// Sets the cursor shown over the button, instead of the pointing hand.
1349  /// While the button drags, the pointing hand and the open hand show as
1350  /// the grabbing hand until the release; any other shape stays.
1351  pub fn cursor(mut self, cursor: impl IntoProp<CursorShape>) -> Button {
1352    self.button.cursor = Some(cursor.into_prop());
1353    self
1354  }
1355
1356  style_method!();
1357}
1358
1359impl Widget for Button {
1360  fn into_element(self: Box<Self>) -> Element {
1361    Element {
1362      name: "Button",
1363      common: self.common,
1364      kind: ElementKind::Button(Box::new(self.button)),
1365      children: vec![ElementChild::One(Box::new(self.child.into_element()))],
1366    }
1367  }
1368}