dioxus_html/events/
mounted.rs

1//! Handles querying data from the renderer
2
3use std::{
4    fmt::{Debug, Display, Formatter},
5    future::Future,
6    pin::Pin,
7};
8
9/// An Element that has been rendered and allows reading and modifying information about it.
10///
11/// Different platforms will have different implementations and different levels of support for this trait. Renderers that do not support specific features will return `None` for those queries.
12// we can not use async_trait here because it does not create a trait that is object safe
13pub trait RenderedElementBacking: std::any::Any {
14    /// return self as Any
15    fn as_any(&self) -> &dyn std::any::Any;
16
17    /// Get the number of pixels that an element's content is scrolled
18    fn get_scroll_offset(&self) -> Pin<Box<dyn Future<Output = MountedResult<PixelsVector2D>>>> {
19        Box::pin(async { Err(MountedError::NotSupported) })
20    }
21
22    /// Get the size of an element's content, including content not visible on the screen due to overflow
23    #[allow(clippy::type_complexity)]
24    fn get_scroll_size(&self) -> Pin<Box<dyn Future<Output = MountedResult<PixelsSize>>>> {
25        Box::pin(async { Err(MountedError::NotSupported) })
26    }
27
28    /// Get the bounding rectangle of the element relative to the viewport (this does not include the scroll position)
29    #[allow(clippy::type_complexity)]
30    fn get_client_rect(&self) -> Pin<Box<dyn Future<Output = MountedResult<PixelsRect>>>> {
31        Box::pin(async { Err(MountedError::NotSupported) })
32    }
33
34    /// Scroll to make the element visible
35    fn scroll_to(
36        &self,
37        _options: ScrollToOptions,
38    ) -> Pin<Box<dyn Future<Output = MountedResult<()>>>> {
39        Box::pin(async { Err(MountedError::NotSupported) })
40    }
41
42    /// Scroll to the given element offsets
43    fn scroll(
44        &self,
45        _coordinates: PixelsVector2D,
46        _behavior: ScrollBehavior,
47    ) -> Pin<Box<dyn Future<Output = MountedResult<()>>>> {
48        Box::pin(async { Err(MountedError::NotSupported) })
49    }
50
51    /// Set the focus on the element
52    fn set_focus(&self, _focus: bool) -> Pin<Box<dyn Future<Output = MountedResult<()>>>> {
53        Box::pin(async { Err(MountedError::NotSupported) })
54    }
55}
56
57impl RenderedElementBacking for () {
58    fn as_any(&self) -> &dyn std::any::Any {
59        self
60    }
61}
62
63/// The way that scrolling should be performed
64#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
65#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
66#[doc(alias = "ScrollIntoViewOptions")]
67pub enum ScrollBehavior {
68    /// Scroll to the element immediately
69    #[cfg_attr(feature = "serialize", serde(rename = "instant"))]
70    Instant,
71
72    /// Scroll to the element smoothly
73    #[default]
74    #[cfg_attr(feature = "serialize", serde(rename = "smooth"))]
75    Smooth,
76}
77
78/// The desired final position within the scrollable ancestor container for a given axis.
79#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
80#[doc(alias = "ScrollIntoViewOptions")]
81pub enum ScrollLogicalPosition {
82    /// Aligns the element's start edge (top or left) with the start of the scrollable container,
83    /// making the element appear at the start of the visible area.
84    #[cfg_attr(feature = "serialize", serde(rename = "start"))]
85    Start,
86    /// Aligns the element at the center of the scrollable container,
87    /// positioning it in the middle of the visible area.
88    #[cfg_attr(feature = "serialize", serde(rename = "center"))]
89    Center,
90    /// Aligns the element's end edge (bottom or right) with the end of the scrollable container,
91    /// making the element appear at the end of the visible area
92    #[cfg_attr(feature = "serialize", serde(rename = "end"))]
93    End,
94    /// Scrolls the element to the nearest edge in the given axis.
95    /// This minimizes the scrolling distance.
96    #[cfg_attr(feature = "serialize", serde(rename = "nearest"))]
97    Nearest,
98}
99
100/// The way that scrolling should be performed
101#[cfg_attr(feature = "serialize", derive(serde::Serialize, serde::Deserialize))]
102#[doc(alias = "ScrollIntoViewOptions")]
103pub struct ScrollToOptions {
104    pub behavior: ScrollBehavior,
105    pub vertical: ScrollLogicalPosition,
106    pub horizontal: ScrollLogicalPosition,
107}
108impl Default for ScrollToOptions {
109    fn default() -> Self {
110        Self {
111            behavior: ScrollBehavior::Smooth,
112            vertical: ScrollLogicalPosition::Start,
113            horizontal: ScrollLogicalPosition::Center,
114        }
115    }
116}
117
118/// An Element that has been rendered and allows reading and modifying information about it.
119///
120/// Different platforms will have different implementations and different levels of support for this trait. Renderers that do not support specific features will return `None` for those queries.
121pub struct MountedData {
122    inner: Box<dyn RenderedElementBacking>,
123}
124
125impl Debug for MountedData {
126    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
127        f.debug_struct("MountedData").finish()
128    }
129}
130
131impl<E: RenderedElementBacking> From<E> for MountedData {
132    fn from(e: E) -> Self {
133        Self { inner: Box::new(e) }
134    }
135}
136
137impl MountedData {
138    /// Create a new MountedData
139    pub fn new(registry: impl RenderedElementBacking + 'static) -> Self {
140        Self {
141            inner: Box::new(registry),
142        }
143    }
144
145    /// Get the number of pixels that an element's content is scrolled
146    #[doc(alias = "scrollTop")]
147    #[doc(alias = "scrollLeft")]
148    pub async fn get_scroll_offset(&self) -> MountedResult<PixelsVector2D> {
149        self.inner.get_scroll_offset().await
150    }
151
152    /// Get the size of an element's content, including content not visible on the screen due to overflow
153    #[doc(alias = "scrollWidth")]
154    #[doc(alias = "scrollHeight")]
155    pub async fn get_scroll_size(&self) -> MountedResult<PixelsSize> {
156        self.inner.get_scroll_size().await
157    }
158
159    /// Get the bounding rectangle of the element relative to the viewport (this does not include the scroll position)
160    #[doc(alias = "getBoundingClientRect")]
161    pub async fn get_client_rect(&self) -> MountedResult<PixelsRect> {
162        self.inner.get_client_rect().await
163    }
164
165    /// Scroll to make the element visible
166    #[doc(alias = "scrollIntoView")]
167    pub fn scroll_to(
168        &self,
169        behavior: ScrollBehavior,
170    ) -> Pin<Box<dyn Future<Output = MountedResult<()>>>> {
171        self.inner.scroll_to(ScrollToOptions {
172            behavior,
173            ..ScrollToOptions::default()
174        })
175    }
176
177    /// Scroll to make the element visible
178    #[doc(alias = "scrollIntoView")]
179    pub fn scroll_to_with_options(
180        &self,
181        options: ScrollToOptions,
182    ) -> Pin<Box<dyn Future<Output = MountedResult<()>>>> {
183        self.inner.scroll_to(options)
184    }
185
186    /// Scroll to the given element offsets
187    #[doc(alias = "scrollTo")]
188    pub fn scroll(
189        &self,
190        coordinates: PixelsVector2D,
191        behavior: ScrollBehavior,
192    ) -> Pin<Box<dyn Future<Output = MountedResult<()>>>> {
193        self.inner.scroll(coordinates, behavior)
194    }
195
196    /// Set the focus on the element
197    #[doc(alias = "focus")]
198    #[doc(alias = "blur")]
199    pub fn set_focus(&self, focus: bool) -> Pin<Box<dyn Future<Output = MountedResult<()>>>> {
200        self.inner.set_focus(focus)
201    }
202
203    /// Downcast this event to a concrete event type
204    #[inline(always)]
205    pub fn downcast<T: 'static>(&self) -> Option<&T> {
206        self.inner.as_any().downcast_ref::<T>()
207    }
208}
209
210use dioxus_core::Event;
211
212use crate::geometry::{PixelsRect, PixelsSize, PixelsVector2D};
213
214pub type MountedEvent = Event<MountedData>;
215
216pub use super::onmounted as onmount;
217
218/// The MountedResult type for the MountedData
219pub type MountedResult<T> = Result<T, MountedError>;
220
221#[derive(Debug)]
222/// The error type for the MountedData
223#[non_exhaustive]
224pub enum MountedError {
225    /// The renderer does not support the requested operation
226    NotSupported,
227    /// The element was not found
228    OperationFailed(Box<dyn std::error::Error>),
229}
230
231impl Display for MountedError {
232    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
233        match self {
234            MountedError::NotSupported => {
235                write!(f, "The renderer does not support the requested operation")
236            }
237            MountedError::OperationFailed(e) => {
238                write!(f, "The operation failed: {}", e)
239            }
240        }
241    }
242}
243
244impl std::error::Error for MountedError {}
dioxus_html/events/mounted.rs

dioxus_html/events/
mounted.rs
