Skip to content

Commit

Permalink
cursor: Rename set_callback() to set_fallback() to match intent
Browse files Browse the repository at this point in the history
The intent of this function is to set a _fallback_ that `get_cursor()`
uses when no cursor can be loaded.  This fallback _is_ a _callback_
(or _closure_ / `Fn` in Rust terms) that calculates an optional fallback
value based on the given name and size of the requested cursor.

Also make sure this "fallback" setter is properly linked from
`get_cursor()`, making it easier to find when users attempt to
understand the docs.
  • Loading branch information
MarijnS95 committed May 7, 2024
1 parent 1f6f4f5 commit f2d5207
Showing 1 changed file with 8 additions and 6 deletions.
14 changes: 8 additions & 6 deletions wayland-cursor/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -190,7 +190,9 @@ impl CursorTheme {
///
/// This method returns [`None`] if this cursor is not provided either by the theme, or by one of its parents.
///
/// If a fallback is set, it will use the data from fallback
/// If a [fallback is set], it will use the data from fallback.
///
/// [fallback is set]: Self::set_fallback()
pub fn get_cursor(&mut self, name: &str) -> Option<&Cursor> {
match self.cursors.iter().position(|cursor| cursor.name == name) {
Some(i) => Some(&self.cursors[i]),
Expand All @@ -211,24 +213,24 @@ impl CursorTheme {
}
}

/// Set a callback to load the cursor data, in case the system theme is missing a cursor that you need.
/// Set a fallback to load the cursor data, in case the system theme is missing a cursor that you need.
///
/// Your callback will be invoked with he name and size of the requested cursor and should return a byte
/// array with the contents of an `xcursor` file, or `None` if you don't provide a fallback for this cursor.
/// Your fallback will be invoked with the name and size of the requested cursor and should return a byte
/// array with the contents of an `xcursor` file, or [`None`] if you don't provide a fallback for this cursor.
///
/// For example, this defines a generic fallback cursor image and uses it for all missing cursors:
/// ```ignore
/// use wayland_cursor::CursorTheme;
/// use wayland_client::{Connection, backend::InvalidId, protocol::wl_shm};
/// fn example(conn: &Connection, shm: wl_shm::WlShm, size: u32) -> Result<CursorTheme, InvalidId> {
/// let mut theme = CursorTheme::load_or(conn, shm, "default", size)?;
/// theme.set_callback(|name, size| {
/// theme.set_fallback(|name, size| {
/// include_bytes!("./icons/default")
/// });
/// Ok(theme)
/// }
/// ```
pub fn set_callback<F>(&mut self, fallback: F)
pub fn set_fallback<F>(&mut self, fallback: F)
where
F: Fn(&str, u32) -> Option<Cow<'static, [u8]>> + 'static,
{
Expand Down

0 comments on commit f2d5207

Please sign in to comment.