Polish slint::register_font_from_memory

 - Make `FontHandle` opaque.
 - Avoid memory allocations
 - Reword documentation
 - Avoid indirection to i_slint_core (prevent documentation to be
   repeated)

ammends for #9762

Author: ogoffart

api/rs/slint/Cargo.toml

@@ -259,6 +259,7 @@ i-slint-core = { workspace = true }
 slint-macros = { workspace = true }
 i-slint-backend-selector = { workspace = true }
 i-slint-core-macros = { workspace = true }
+i-slint-common = { workspace = true }
 slint-interpreter = { workspace = true, optional = true, default-features = false, features = ["display-diagnostics", "compat-1-2", "internal-live-preview"] }
 
 const-field-offset = { version = "0.1.2", path = "../../../helper_crates/const-field-offset" }

api/rs/slint/lib.rs

@@ -218,6 +218,10 @@ pub use i_slint_core::component_factory::ComponentFactory;
 #[cfg(not(target_arch = "wasm32"))]
 pub use i_slint_core::graphics::{BorrowedOpenGLTextureBuilder, BorrowedOpenGLTextureOrigin};
 // keep in sync with internal/interpreter/api.rs
+#[cfg(feature = "std")]
+pub use i_slint_common::sharedfontique::{
+    register_font_from_memory, FontHandle, RegisterFontError,
+};
 pub use i_slint_core::graphics::{
     Brush, Color, Image, LoadImageError, Rgb8Pixel, Rgba8Pixel, RgbaColor, SharedPixelBuffer,
 };
@@ -233,39 +237,6 @@ pub use i_slint_core::{
     string::{SharedString, ToSharedString},
 };
 
-/// Register a custom font from byte data at runtime.
-///
-/// **This is an experimental API.** The API may change in future versions.
-///
-/// Returns a [`FontHandle`] on success, or a [`RegisterFontError`] on failure.
-///
-/// This API is available when the `std` feature is enabled.
-///
-/// # Example
-///
-/// ```ignore
-/// # use slint::*;
-/// let font_data = include_bytes!("path/to/font.ttf");
-/// match register_font_from_memory(font_data.to_vec()) {
-///     Ok(handle) => println!("Registered {} font families", handle.family_ids.len()),
-///     Err(e) => eprintln!("Failed to register font: {}", e),
-/// }
-/// ```
-#[cfg(feature = "std")]
-pub use i_slint_core::register_font_from_memory;
-
-/// Handle to a registered font that can be used for future operations.
-///
-/// **This is an experimental API.** The API may change in future versions.
-#[cfg(feature = "std")]
-pub use i_slint_core::FontHandle;
-
-/// Error type for font registration failures.
-///
-/// **This is an experimental API.** The API may change in future versions.
-#[cfg(feature = "std")]
-pub use i_slint_core::RegisterFontError;
-
 pub mod private_unstable_api;
 
 /// Enters the main event loop. This is necessary in order to receive

internal/common/sharedfontique.rs

@@ -132,14 +132,17 @@ impl std::ops::DerefMut for Collection {
 }
 
 /// Handle to a registered font that can be used for future operations.
+///
+/// Returned by [`register_font_from_memory()`].
 #[derive(Debug, Clone)]
-pub struct FontHandle {
-    /// Family IDs of the registered fonts
-    pub family_ids: Vec<fontique::FamilyId>,
-}
+#[non_exhaustive]
+pub struct FontHandle {}
 
 /// Error type for font registration failures.
+///
+/// Returned by [`register_font_from_memory()`].
 #[derive(Debug, Clone)]
+#[non_exhaustive]
 pub enum RegisterFontError {
     /// The provided font data was empty
     EmptyData,
@@ -165,22 +168,18 @@ impl std::error::Error for RegisterFontError {}
 
 /// Register a font from byte data dynamically.
 ///
-/// # Arguments
-///
-/// * `font_data` - Font data as bytes (supports any type that can be converted to a byte slice)
+/// The argument is the owner of a slice of byte that contains the data of the font.
+/// It can for example be a `&'static [u8]` obtained from [`include_bytes!()`] or a `Vec<u8>`
+/// obtained from [`std::fs::read()`].
 ///
-/// # Returns
-///
-/// Returns a `FontHandle` on success, or a `RegisterFontError` on failure.
+/// The data must be in the [TrueType (TTF) format](https://en.wikipedia.org/wiki/TrueType).
 ///
 /// # Example
 ///
-/// ```ignore
-/// let font_bytes = include_bytes!("my_font.ttf");
-/// match register_font_from_memory(font_bytes.to_vec()) {
-///     Ok(handle) => println!("Registered {} font families", handle.family_ids.len()),
-///     Err(e) => eprintln!("Failed to register font: {}", e),
-/// }
+/// ```
+/// # use i_slint_common::sharedfontique as slint;
+/// let font_bytes = include_bytes!("sharedfontique/DejaVuSans.ttf");
+/// slint::register_font_from_memory(font_bytes).expect("Failed to register font");
 /// ```
 pub fn register_font_from_memory(
     font_data: impl AsRef<[u8]> + Send + Sync + 'static,
@@ -191,9 +190,7 @@ pub fn register_font_from_memory(
         return Err(RegisterFontError::EmptyData);
     }
 
-    // Convert to owned data for Arc
-    let owned_data: Vec<u8> = data.to_vec();
-    let blob = fontique::Blob::new(Arc::new(owned_data));
+    let blob = fontique::Blob::new(Arc::new(font_data));
 
     let mut collection = get_collection();
     let fonts = collection.register_fonts(blob, None);
@@ -202,15 +199,13 @@ pub fn register_font_from_memory(
         return Err(RegisterFontError::NoFontsFound);
     }
 
-    let family_ids: Vec<_> = fonts.iter().map(|(family_id, _)| *family_id).collect();
-
     // Set up fallbacks for all scripts
     for script in fontique::Script::all_samples().iter().map(|(script, _)| *script) {
         collection
-            .append_fallbacks(fontique::FallbackKey::new(script, None), family_ids.iter().copied());
+            .append_fallbacks(fontique::FallbackKey::new(script, None), fonts.iter().map(|x| x.0));
     }
 
-    Ok(FontHandle { family_ids })
+    Ok(FontHandle {})
 }
 
 /// Font metrics in design space. Scale with desired pixel size and divided by units_per_em

internal/core/lib.rs

@@ -62,18 +62,6 @@ pub mod window;
 #[doc(inline)]
 pub use string::SharedString;
 
-/// Register a font from memory.
-#[cfg(feature = "std")]
-pub use i_slint_common::sharedfontique::register_font_from_memory;
-
-/// Handle to a registered font.
-#[cfg(feature = "std")]
-pub use i_slint_common::sharedfontique::FontHandle;
-
-/// Error type for font registration failures.
-#[cfg(feature = "std")]
-pub use i_slint_common::sharedfontique::RegisterFontError;
-
 #[doc(inline)]
 pub use sharedvector::SharedVector;