Skip to main content

sui_widgets/
selection.rs

1use std::{any::Any, cell::RefCell, collections::BTreeMap, fmt, ops::Range, rc::Rc, sync::Arc};
2
3use sui_core::{ImageHandle, Rect, WidgetId};
4
5#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
6pub struct SelectionOwnerId(u64);
7
8impl SelectionOwnerId {
9    pub const fn new(raw: u64) -> Self {
10        Self(raw)
11    }
12
13    pub const fn get(self) -> u64 {
14        self.0
15    }
16}
17
18impl From<WidgetId> for SelectionOwnerId {
19    fn from(value: WidgetId) -> Self {
20        Self(value.get())
21    }
22}
23
24impl From<u64> for SelectionOwnerId {
25    fn from(value: u64) -> Self {
26        Self(value)
27    }
28}
29
30#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
31pub struct SelectionOrder(u64);
32
33impl SelectionOrder {
34    pub const fn new(raw: u64) -> Self {
35        Self(raw)
36    }
37
38    pub const fn get(self) -> u64 {
39        self.0
40    }
41}
42
43impl From<SelectionOwnerId> for SelectionOrder {
44    fn from(value: SelectionOwnerId) -> Self {
45        Self(value.get())
46    }
47}
48
49impl From<WidgetId> for SelectionOrder {
50    fn from(value: WidgetId) -> Self {
51        Self(value.get())
52    }
53}
54
55impl From<u64> for SelectionOrder {
56    fn from(value: u64) -> Self {
57        Self(value)
58    }
59}
60
61#[derive(Debug, Clone, Copy, PartialEq, Eq)]
62pub enum SelectionIntent {
63    Replace,
64    Extend,
65    Toggle,
66}
67
68/// Controls whether a selectable widget writes its selection to the clipboard
69/// from implicit widget-owned routes such as Ctrl+C and accessibility Copy.
70///
71/// `AppManaged` is the default for shared selection scopes: widgets publish
72/// selection state and the application decides how to expose copy commands.
73#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
74pub enum SelectionClipboardBehavior {
75    #[default]
76    AppManaged,
77    WidgetManaged,
78}
79
80impl SelectionClipboardBehavior {
81    pub const fn is_widget_managed(self) -> bool {
82        matches!(self, Self::WidgetManaged)
83    }
84}
85
86#[derive(Clone)]
87pub enum SelectionPayload {
88    Text(String),
89    Image {
90        handle: ImageHandle,
91        region: Option<Rect>,
92    },
93    Custom {
94        kind: Arc<str>,
95        data: Arc<dyn Any + Send + Sync>,
96    },
97}
98
99impl SelectionPayload {
100    pub fn text(text: impl Into<String>) -> Self {
101        Self::Text(text.into())
102    }
103
104    pub fn image(handle: ImageHandle) -> Self {
105        Self::Image {
106            handle,
107            region: None,
108        }
109    }
110
111    pub fn image_region(handle: ImageHandle, region: Rect) -> Self {
112        Self::Image {
113            handle,
114            region: Some(region),
115        }
116    }
117
118    pub fn custom<T>(kind: impl Into<Arc<str>>, data: T) -> Self
119    where
120        T: Any + Send + Sync + 'static,
121    {
122        Self::Custom {
123            kind: kind.into(),
124            data: Arc::new(data),
125        }
126    }
127
128    pub fn as_text(&self) -> Option<&str> {
129        match self {
130            Self::Text(text) => Some(text),
131            Self::Image { .. } | Self::Custom { .. } => None,
132        }
133    }
134
135    pub fn custom_kind(&self) -> Option<&str> {
136        match self {
137            Self::Custom { kind, .. } => Some(kind.as_ref()),
138            Self::Text(_) | Self::Image { .. } => None,
139        }
140    }
141
142    pub fn custom_data<T>(&self) -> Option<&T>
143    where
144        T: Any + Send + Sync + 'static,
145    {
146        match self {
147            Self::Custom { data, .. } => data.downcast_ref(),
148            Self::Text(_) | Self::Image { .. } => None,
149        }
150    }
151}
152
153impl fmt::Debug for SelectionPayload {
154    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
155        match self {
156            Self::Text(text) => f.debug_tuple("Text").field(text).finish(),
157            Self::Image { handle, region } => f
158                .debug_struct("Image")
159                .field("handle", handle)
160                .field("region", region)
161                .finish(),
162            Self::Custom { kind, .. } => f
163                .debug_struct("Custom")
164                .field("kind", kind)
165                .finish_non_exhaustive(),
166        }
167    }
168}
169
170#[derive(Debug, Clone)]
171pub struct SelectionEntry {
172    pub owner: SelectionOwnerId,
173    pub order: SelectionOrder,
174    pub payload: SelectionPayload,
175}
176
177#[derive(Debug, Clone, PartialEq, Eq, Default)]
178pub struct SelectionChange {
179    affected_owners: Vec<SelectionOwnerId>,
180}
181
182impl SelectionChange {
183    pub fn new(affected_owners: Vec<SelectionOwnerId>) -> Self {
184        Self { affected_owners }
185    }
186
187    pub fn is_empty(&self) -> bool {
188        self.affected_owners.is_empty()
189    }
190
191    pub fn affected_owners(&self) -> &[SelectionOwnerId] {
192        &self.affected_owners
193    }
194}
195
196impl SelectionEntry {
197    pub fn new(
198        owner: impl Into<SelectionOwnerId>,
199        order: impl Into<SelectionOrder>,
200        payload: SelectionPayload,
201    ) -> Self {
202        Self {
203            owner: owner.into(),
204            order: order.into(),
205            payload,
206        }
207    }
208}
209
210#[derive(Debug, Clone, Copy, PartialEq, Eq)]
211pub struct SelectionPoint {
212    pub owner: SelectionOwnerId,
213    pub offset: usize,
214    pub order: SelectionOrder,
215}
216
217impl SelectionPoint {
218    pub fn new(
219        owner: impl Into<SelectionOwnerId>,
220        offset: usize,
221        order: impl Into<SelectionOrder>,
222    ) -> Self {
223        Self {
224            owner: owner.into(),
225            offset,
226            order: order.into(),
227        }
228    }
229}
230
231#[derive(Debug, Clone, PartialEq, Eq)]
232pub struct TextSelectionInfo {
233    pub owner: SelectionOwnerId,
234    pub range: Range<usize>,
235    pub text_len: usize,
236}
237
238#[derive(Debug, Clone)]
239struct OwnerSelection {
240    entries: Vec<SelectionEntry>,
241    text: Option<TextSelectionInfo>,
242}
243
244#[derive(Debug, Default)]
245struct SelectionState {
246    revision: u64,
247    active_owner: Option<SelectionOwnerId>,
248    anchor: Option<SelectionPoint>,
249    focus: Option<SelectionPoint>,
250    owners: BTreeMap<SelectionOwnerId, OwnerSelection>,
251}
252
253#[derive(Clone, Debug, Default)]
254pub struct SelectionScope {
255    inner: Rc<RefCell<SelectionState>>,
256}
257
258impl SelectionScope {
259    pub fn new() -> Self {
260        Self::default()
261    }
262
263    pub fn revision(&self) -> u64 {
264        self.inner.borrow().revision
265    }
266
267    pub fn active_owner(&self) -> Option<SelectionOwnerId> {
268        self.inner.borrow().active_owner
269    }
270
271    pub fn anchor(&self) -> Option<SelectionPoint> {
272        self.inner.borrow().anchor
273    }
274
275    pub fn focus(&self) -> Option<SelectionPoint> {
276        self.inner.borrow().focus
277    }
278
279    pub fn set_points(
280        &self,
281        anchor: Option<SelectionPoint>,
282        focus: Option<SelectionPoint>,
283    ) -> SelectionChange {
284        let mut affected = Vec::new();
285        if let Some(point) = anchor {
286            affected.push(point.owner);
287        }
288        if let Some(point) = focus {
289            affected.push(point.owner);
290        }
291        affected.sort();
292        affected.dedup();
293
294        let mut state = self.inner.borrow_mut();
295        state.anchor = anchor;
296        state.focus = focus;
297        state.revision = state.revision.saturating_add(1);
298        SelectionChange::new(affected)
299    }
300
301    pub fn selected_items(&self) -> Vec<SelectionEntry> {
302        let mut entries = self
303            .inner
304            .borrow()
305            .owners
306            .values()
307            .flat_map(|owner| owner.entries.iter().cloned())
308            .collect::<Vec<_>>();
309        entries.sort_by_key(|entry| (entry.order, entry.owner));
310        entries
311    }
312
313    pub fn selected_items_for_owner(
314        &self,
315        owner: impl Into<SelectionOwnerId>,
316    ) -> Vec<SelectionEntry> {
317        let owner = owner.into();
318        self.inner
319            .borrow()
320            .owners
321            .get(&owner)
322            .map(|selection| selection.entries.clone())
323            .unwrap_or_default()
324    }
325
326    pub fn selected_text(&self) -> Option<String> {
327        let text = self
328            .selected_items()
329            .into_iter()
330            .filter_map(|entry| match entry.payload {
331                SelectionPayload::Text(text) => Some(text),
332                SelectionPayload::Image { .. } | SelectionPayload::Custom { .. } => None,
333            })
334            .collect::<String>();
335        (!text.is_empty()).then_some(text)
336    }
337
338    pub fn text_selection_for_owner(
339        &self,
340        owner: impl Into<SelectionOwnerId>,
341    ) -> Option<TextSelectionInfo> {
342        let owner = owner.into();
343        self.inner
344            .borrow()
345            .owners
346            .get(&owner)
347            .and_then(|selection| selection.text.clone())
348    }
349
350    pub fn has_owner_selection(&self, owner: impl Into<SelectionOwnerId>) -> bool {
351        let owner = owner.into();
352        self.inner.borrow().owners.contains_key(&owner)
353    }
354
355    pub fn replace(
356        &self,
357        owner: impl Into<SelectionOwnerId>,
358        entries: Vec<SelectionEntry>,
359    ) -> SelectionChange {
360        self.select(owner, SelectionIntent::Replace, entries, None)
361    }
362
363    pub fn replace_text(
364        &self,
365        owner: impl Into<SelectionOwnerId>,
366        order: impl Into<SelectionOrder>,
367        range: Range<usize>,
368        text_len: usize,
369        text: impl Into<String>,
370    ) -> SelectionChange {
371        let owner = owner.into();
372        let order = order.into();
373        let selected_text = text.into();
374        let entries = (!selected_text.is_empty()).then(|| {
375            vec![SelectionEntry::new(
376                owner,
377                order,
378                SelectionPayload::Text(selected_text),
379            )]
380        });
381        self.select(
382            owner,
383            SelectionIntent::Replace,
384            entries.unwrap_or_default(),
385            Some(TextSelectionInfo {
386                owner,
387                range,
388                text_len,
389            }),
390        )
391    }
392
393    pub fn extend(
394        &self,
395        owner: impl Into<SelectionOwnerId>,
396        entries: Vec<SelectionEntry>,
397    ) -> SelectionChange {
398        self.select(owner, SelectionIntent::Extend, entries, None)
399    }
400
401    pub fn toggle(
402        &self,
403        owner: impl Into<SelectionOwnerId>,
404        entries: Vec<SelectionEntry>,
405    ) -> SelectionChange {
406        self.select(owner, SelectionIntent::Toggle, entries, None)
407    }
408
409    pub fn clear_owner(&self, owner: impl Into<SelectionOwnerId>) -> SelectionChange {
410        let owner = owner.into();
411        let mut state = self.inner.borrow_mut();
412        let had_owner = state.owners.remove(&owner).is_some();
413        let had_active_owner = state.active_owner == Some(owner);
414        let had_anchor = state.anchor.is_some_and(|point| point.owner == owner);
415        let had_focus = state.focus.is_some_and(|point| point.owner == owner);
416        if had_owner || had_active_owner || had_anchor || had_focus {
417            if had_active_owner {
418                state.active_owner = None;
419            }
420            if had_anchor {
421                state.anchor = None;
422            }
423            if had_focus {
424                state.focus = None;
425            }
426            state.revision = state.revision.saturating_add(1);
427            SelectionChange::new(vec![owner])
428        } else {
429            SelectionChange::default()
430        }
431    }
432
433    pub fn clear(&self) -> SelectionChange {
434        let mut state = self.inner.borrow_mut();
435        let affected = state.owners.keys().copied().collect::<Vec<_>>();
436        if !state.owners.is_empty()
437            || state.active_owner.is_some()
438            || state.anchor.is_some()
439            || state.focus.is_some()
440        {
441            state.owners.clear();
442            state.active_owner = None;
443            state.anchor = None;
444            state.focus = None;
445            state.revision = state.revision.saturating_add(1);
446            SelectionChange::new(affected)
447        } else {
448            SelectionChange::default()
449        }
450    }
451
452    fn select(
453        &self,
454        owner: impl Into<SelectionOwnerId>,
455        intent: SelectionIntent,
456        entries: Vec<SelectionEntry>,
457        text: Option<TextSelectionInfo>,
458    ) -> SelectionChange {
459        let owner = owner.into();
460        let mut state = self.inner.borrow_mut();
461        let affected = match intent {
462            SelectionIntent::Replace => state
463                .owners
464                .keys()
465                .copied()
466                .chain(std::iter::once(owner))
467                .collect::<Vec<_>>(),
468            SelectionIntent::Extend | SelectionIntent::Toggle => vec![owner],
469        };
470        match intent {
471            SelectionIntent::Replace => {
472                state.owners.clear();
473                insert_owner_selection(&mut state, owner, entries, text);
474            }
475            SelectionIntent::Extend => {
476                insert_owner_selection(&mut state, owner, entries, text);
477            }
478            SelectionIntent::Toggle => {
479                if state.owners.contains_key(&owner) {
480                    state.owners.remove(&owner);
481                    if state.active_owner == Some(owner) {
482                        state.active_owner = None;
483                    }
484                } else {
485                    insert_owner_selection(&mut state, owner, entries, text);
486                }
487            }
488        }
489        state.revision = state.revision.saturating_add(1);
490        let mut affected = affected;
491        affected.sort();
492        affected.dedup();
493        SelectionChange::new(affected)
494    }
495}
496
497fn insert_owner_selection(
498    state: &mut SelectionState,
499    owner: SelectionOwnerId,
500    entries: Vec<SelectionEntry>,
501    text: Option<TextSelectionInfo>,
502) {
503    state.active_owner = Some(owner);
504    if entries.is_empty() && text.as_ref().is_none_or(|text| text.range.is_empty()) {
505        state.owners.remove(&owner);
506    } else {
507        state.owners.insert(owner, OwnerSelection { entries, text });
508    }
509}
510
511#[cfg(test)]
512mod tests {
513    use super::*;
514
515    #[test]
516    fn replace_text_updates_selected_text_and_clears_previous_owner() {
517        let scope = SelectionScope::new();
518        let first = SelectionOwnerId::new(1);
519        let second = SelectionOwnerId::new(2);
520
521        let change = scope.replace_text(first, first, 0..5, 5, "hello");
522        assert_eq!(change.affected_owners(), &[first]);
523        assert_eq!(scope.selected_text().as_deref(), Some("hello"));
524        assert!(scope.has_owner_selection(first));
525
526        let change = scope.replace_text(second, second, 0..5, 5, "world");
527        assert_eq!(change.affected_owners(), &[first, second]);
528        assert_eq!(scope.selected_text().as_deref(), Some("world"));
529        assert!(!scope.has_owner_selection(first));
530        assert!(scope.has_owner_selection(second));
531    }
532
533    #[test]
534    fn extend_keeps_multiple_payload_kinds_in_order() {
535        let scope = SelectionScope::new();
536        let first = SelectionOwnerId::new(10);
537        let second = SelectionOwnerId::new(20);
538
539        scope.extend(
540            second,
541            vec![SelectionEntry::new(
542                second,
543                SelectionOrder::new(2),
544                SelectionPayload::text("B"),
545            )],
546        );
547        scope.extend(
548            first,
549            vec![SelectionEntry::new(
550                first,
551                SelectionOrder::new(1),
552                SelectionPayload::text("A"),
553            )],
554        );
555
556        assert_eq!(scope.selected_text().as_deref(), Some("AB"));
557        assert_eq!(
558            scope
559                .selected_items()
560                .iter()
561                .map(|entry| entry.owner)
562                .collect::<Vec<_>>(),
563            vec![first, second]
564        );
565    }
566}