From f2d52071849d2b78b9f9560ea701b0d07a6fdbdb Mon Sep 17 00:00:00 2001 From: Marijn Suijten Date: Tue, 7 May 2024 21:38:42 +0200 Subject: [PATCH] cursor: Rename `set_callback()` to `set_fallback()` to match intent 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. --- wayland-cursor/src/lib.rs | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/wayland-cursor/src/lib.rs b/wayland-cursor/src/lib.rs index 280328bb998..99aedb347f7 100644 --- a/wayland-cursor/src/lib.rs +++ b/wayland-cursor/src/lib.rs @@ -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]), @@ -211,10 +213,10 @@ 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 @@ -222,13 +224,13 @@ impl CursorTheme { /// use wayland_client::{Connection, backend::InvalidId, protocol::wl_shm}; /// fn example(conn: &Connection, shm: wl_shm::WlShm, size: u32) -> Result { /// 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(&mut self, fallback: F) + pub fn set_fallback(&mut self, fallback: F) where F: Fn(&str, u32) -> Option> + 'static, {