gloo_history/
history.rs

1use std::borrow::Cow;
2
3use crate::listener::HistoryListener;
4use crate::location::Location;
5#[cfg(feature = "query")]
6use crate::{error::HistoryResult, query::ToQuery};
7
8/// A trait to provide [`History`] access.
9///
10/// # Warning
11///
12/// The behaviour of this trait is not well-defined when you mix multiple history kinds in the same application
13/// or use `window().history()` to update session history.
14pub trait History: Clone + PartialEq {
15    /// Returns the number of elements in [`History`].
16    fn len(&self) -> usize;
17
18    /// Returns true if the current [`History`] is empty.
19    fn is_empty(&self) -> bool {
20        self.len() == 0
21    }
22
23    /// Moves back 1 page in [`History`].
24    fn back(&self) {
25        self.go(-1);
26    }
27
28    /// Moves forward 1 page in [`History`].
29    fn forward(&self) {
30        self.go(1);
31    }
32
33    /// Loads a specific page in [`History`] with a `delta` relative to current page.
34    ///
35    /// See: <https://developer.mozilla.org/en-US/docs/Web/API/History/go>
36    fn go(&self, delta: isize);
37
38    /// Pushes a route entry with [`None`] being the state.
39    fn push<'a>(&self, route: impl Into<Cow<'a, str>>);
40
41    /// Replaces the current history entry with provided route and [`None`] state.
42    fn replace<'a>(&self, route: impl Into<Cow<'a, str>>);
43
44    /// Pushes a route entry with state.
45    fn push_with_state<'a, T>(&self, route: impl Into<Cow<'a, str>>, state: T)
46    where
47        T: 'static;
48
49    /// Replaces the current history entry with provided route and state.
50    fn replace_with_state<'a, T>(&self, route: impl Into<Cow<'a, str>>, state: T)
51    where
52        T: 'static;
53
54    /// Same as `.push()` but affix the queries to the end of the route.
55    #[cfg(feature = "query")]
56    fn push_with_query<'a, Q>(
57        &self,
58        route: impl Into<Cow<'a, str>>,
59        query: Q,
60    ) -> HistoryResult<(), Q::Error>
61    where
62        Q: ToQuery;
63
64    /// Same as `.replace()` but affix the queries to the end of the route.
65    #[cfg(feature = "query")]
66    fn replace_with_query<'a, Q>(
67        &self,
68        route: impl Into<Cow<'a, str>>,
69        query: Q,
70    ) -> HistoryResult<(), Q::Error>
71    where
72        Q: ToQuery;
73
74    /// Same as `.push_with_state()` but affix the queries to the end of the route.
75    #[cfg(feature = "query")]
76    fn push_with_query_and_state<'a, Q, T>(
77        &self,
78        route: impl Into<Cow<'a, str>>,
79        query: Q,
80        state: T,
81    ) -> HistoryResult<(), Q::Error>
82    where
83        Q: ToQuery,
84        T: 'static;
85
86    /// Same as `.replace_with_state()` but affix the queries to the end of the route.
87    #[cfg(feature = "query")]
88    fn replace_with_query_and_state<'a, Q, T>(
89        &self,
90        route: impl Into<Cow<'a, str>>,
91        query: Q,
92        state: T,
93    ) -> HistoryResult<(), Q::Error>
94    where
95        Q: ToQuery,
96        T: 'static;
97
98    /// Creates a Listener that will be notified when current state changes.
99    ///
100    /// This method returns a [`HistoryListener`] that will automatically unregister the callback
101    /// when dropped.
102    fn listen<CB>(&self, callback: CB) -> HistoryListener
103    where
104        CB: Fn() + 'static;
105
106    /// Returns current [`Location`].
107    fn location(&self) -> Location;
108}
gloo_history/history.rs

gloo_history/
history.rs
