1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
//! Public builder, page binding and output of the carousel.
use super::{
options::{
CarouselIndicator, CarouselOrientation, CarouselVariant, IndicatorPosition, StackDirection,
},
style::CarouselStyle,
};
use crate::{components::sanitize, Id, Response, SpringOptions, Vec2};
use std::{hash::Hash, time::Duration};
/// The current page of a [`Carousel`]. Assigning it from outside moves the carousel with an
/// animation and reports no change; a user action writes the new page and reports one change.
pub enum CarouselPage<'a> {
/// The page index. With [`Carousel::keys`], content state follows the keys while the
/// index stays the source of truth: inserting a page before the current one changes
/// which page is shown unless you adjust the index too.
Index(&'a mut usize),
/// The key of the page (see [`Carousel::keys`]). Inserting or removing other pages keeps
/// this page and the motion going; removing the current page moves to its neighbour.
Key(&'a mut Id),
/// The carousel keeps the page itself, starting at [`Carousel::initial_page`].
Internal,
}
impl<'a> From<&'a mut usize> for CarouselPage<'a> {
fn from(page: &'a mut usize) -> Self {
Self::Index(page)
}
}
impl<'a> From<&'a mut Id> for CarouselPage<'a> {
fn from(key: &'a mut Id) -> Self {
Self::Key(key)
}
}
/// What happened during one pass of a [`Carousel`].
#[derive(Clone, Copy, Debug)]
pub struct CarouselOutput {
/// The paged area: hover, focus, `drag_*` of the swipe gesture.
pub response: Response,
/// Page shown or being moved to.
pub page: usize,
/// Key of that page.
pub key: Id,
/// The carousel itself changed the page this pass (swipe, key, wheel, click, button or
/// autoplay), once per action. Assigning the page from outside never sets it.
pub changed: bool,
/// `changed` came from autoplay, not from the user.
pub autoplayed: bool,
/// Closeness of the displayed position to the current page, 0..1 and 1 when settled.
/// It follows the pointer while dragging and dips while a transition runs.
pub progress: f32,
/// A swipe is in progress.
pub dragging: bool,
/// Enter, Space or a click activated this (front) page.
pub activated: Option<usize>,
}
/// A paged container with two looks: a stack of cards and a photo slider.
///
/// ```no_run
/// # fn demo(ui: &mut zaxis::Ui<'_>, page: &mut usize) {
/// use zaxis::Carousel;
/// let out = Carousel::new("steps").pages(3).show(ui, page, |ui, index| {
/// ui.label(format!("Step {index}"));
/// });
/// if out.changed { /* the user moved to `*page` */ }
/// # }
/// ```
///
/// Page content closures run once per visible layer in a pass and are never stored.
#[derive(Clone)]
pub struct Carousel {
pub(super) id: Id,
pub(super) variant: CarouselVariant,
pub(super) orientation: CarouselOrientation,
pub(super) count: usize,
pub(super) keys: Option<Vec<Id>>,
pub(super) width: Option<f32>,
pub(super) height: Option<f32>,
pub(super) wrap: bool,
pub(super) autoplay: Option<Duration>,
pub(super) arrows: bool,
pub(super) indicator: Option<CarouselIndicator>,
pub(super) position: Option<IndicatorPosition>,
pub(super) initial: usize,
pub(super) enabled: bool,
pub(super) wheel: bool,
pub(super) style: CarouselStyle,
pub(super) label: String,
}
impl Carousel {
pub fn new(source: impl Hash) -> Self {
Self {
id: Id::new(source),
variant: CarouselVariant::Stack,
orientation: CarouselOrientation::Horizontal,
count: 0,
keys: None,
width: None,
height: None,
wrap: false,
autoplay: None,
arrows: false,
indicator: None,
position: None,
initial: 0,
enabled: true,
wheel: true,
style: CarouselStyle::default(),
label: String::new(),
}
}
pub fn variant(mut self, variant: CarouselVariant) -> Self {
self.variant = variant;
self
}
/// A stack of cards (the default).
pub fn stack(self) -> Self {
self.variant(CarouselVariant::Stack)
}
/// A photo slider.
pub fn images(self) -> Self {
self.variant(CarouselVariant::Images)
}
pub fn orientation(mut self, orientation: CarouselOrientation) -> Self {
self.orientation = orientation;
self
}
/// Swipe, keys and wheel along the vertical axis; `Stack` only.
pub fn vertical(self) -> Self {
self.orientation(CarouselOrientation::Vertical)
}
/// Number of pages. Ignored when [`Self::keys`] is given.
pub fn pages(mut self, count: usize) -> Self {
self.count = count;
self
}
/// Stable keys of the pages, which also set their number. Content state, focus and the
/// motion follow a key when pages are inserted or removed. Equal keys are made unique
/// by their index and reported.
pub fn keys(mut self, keys: impl IntoIterator<Item = impl Hash>) -> Self {
self.keys = Some(keys.into_iter().map(Id::new).collect());
self
}
/// Outer width; the available width by default.
#[track_caller]
pub fn width(mut self, width: f32) -> Self {
self.width = sanitize::positive("Carousel::width", width).or(self.width);
self
}
/// Outer height including an indicator row outside the pages.
#[track_caller]
pub fn height(mut self, height: f32) -> Self {
self.height = sanitize::positive("Carousel::height", height).or(self.height);
self
}
#[track_caller]
pub fn size(self, size: Vec2) -> Self {
self.width(size.x).height(size.y)
}
/// Go from the last page to the first and back instead of stopping with a rubber band.
pub fn looping(mut self, looping: bool) -> Self {
self.wrap = looping;
self
}
/// Turn the page every `interval` while nothing holds it: it waits while the pointer is
/// over the carousel, while it has keyboard focus or is being dragged, while it is
/// hidden, and never runs with reduced motion. A non-looping carousel stops at the end.
#[track_caller]
pub fn autoplay(mut self, interval: Duration) -> Self {
if interval.is_zero() {
sanitize::positive("Carousel::autoplay", 0.0);
} else {
self.autoplay = Some(interval);
}
self
}
/// Previous and next buttons over the pages.
pub fn arrows(mut self, arrows: bool) -> Self {
self.arrows = arrows;
self
}
/// Default: a pill for `Stack`, strokes for `Images`.
pub fn indicator(mut self, indicator: CarouselIndicator) -> Self {
self.indicator = Some(indicator);
self
}
pub fn indicator_position(mut self, position: IndicatorPosition) -> Self {
self.position = Some(position);
self
}
/// First page of a carousel that keeps its own page ([`CarouselPage::Internal`]).
pub fn initial_page(mut self, page: usize) -> Self {
self.initial = page;
self
}
pub fn enabled(mut self, enabled: bool) -> Self {
self.enabled = enabled;
self
}
/// Turn pages with the wheel along the carousel axis (default on). Wheel movement
/// across the axis goes to the enclosing scroll area.
pub fn wheel(mut self, wheel: bool) -> Self {
self.wheel = wheel;
self
}
/// Merge `style` over the theme's [`Style::carousel`](crate::Style) and earlier calls.
pub fn style(mut self, style: CarouselStyle) -> Self {
self.style.merge(&style);
self
}
/// `Stack`: visible layers including the front card.
pub fn layers(mut self, layers: usize) -> Self {
self.style.layers = Some(layers);
self
}
/// `Stack`: how far each following sheet peeks out.
#[track_caller]
pub fn offset(mut self, offset: f32) -> Self {
self.style.offset =
sanitize::non_negative("Carousel::offset", offset).or(self.style.offset);
self
}
/// `Stack`: scale lost per layer.
#[track_caller]
pub fn scale_step(mut self, step: f32) -> Self {
self.style.scale_step =
sanitize::non_negative("Carousel::scale_step", step).or(self.style.scale_step);
self
}
/// `Stack`: the side the sheets show on.
pub fn direction(mut self, direction: StackDirection) -> Self {
self.style.direction = Some(direction);
self
}
/// `Stack`: where a leaving card goes, in card sizes (`(-1.0, 0.0)` is one width to the left).
#[track_caller]
pub fn exit(mut self, exit: Vec2) -> Self {
self.style.exit = sanitize::finite_vec2("Carousel::exit", exit).or(self.style.exit);
self
}
/// `Stack`: tilt of a leaving card in radians (0 by default).
#[track_caller]
pub fn exit_rotation(mut self, angle: f32) -> Self {
self.style.exit_rotation =
sanitize::finite("Carousel::exit_rotation", angle).or(self.style.exit_rotation);
self
}
/// `Images`: neighbours visible on each side.
pub fn neighbors(mut self, neighbors: usize) -> Self {
self.style.neighbors = Some(neighbors);
self
}
/// Spring of the transition; the theme's motion spring by default.
pub fn spring(mut self, spring: SpringOptions) -> Self {
self.style.spring = Some(spring);
self
}
}