fix: update documentation, add some customization

TextPlugin now includes general family face overrides

Author: dsgallups

crates/bevy_text/src/lib.rs

@@ -79,13 +79,33 @@ pub const DEFAULT_FONT_DATA: &[u8] = include_bytes!("FiraMono-subset.ttf");
 /// When the `bevy_text` feature is enabled with the `bevy` crate, this
 /// plugin is included by default in the `DefaultPlugins`.
 pub struct TextPlugin {
-    /// If true, the [`CosmicFontSystem`] will load system fonts.
+    /// If `true`, the [`CosmicFontSystem`] will load system fonts.
+    ///
+    /// Supports Windows, Linux, and MacOS.
+    ///
+    /// See [`cosmic_text::fontdb::Database::load_system_fonts`] for details.
     pub load_system_fonts: bool,
+
+    /// Override the family identifier for the system general Serif font
+    pub family_serif: Option<String>,
+    /// Override the default identifier for the general Sans-Serif font
+    pub family_sans_serif: Option<String>,
+    /// Override the default identifier for the general Cursive font
+    pub family_cursive: Option<String>,
+    /// Override the default identifier for the general Fantasy font
+    pub family_fantasy: Option<String>,
+    /// Override the default identifier for the general Monospace font
+    pub family_monospace: Option<String>,
 }
 impl Default for TextPlugin {
     fn default() -> Self {
         Self {
             load_system_fonts: true,
+            family_serif: None,
+            family_sans_serif: None,
+            family_cursive: None,
+            family_fantasy: None,
+            family_monospace: None,
         }
     }
 }
@@ -104,7 +124,7 @@ impl Plugin for TextPlugin {
             .init_asset_loader::<FontLoader>()
             .init_resource::<FontAtlasSets>()
             .init_resource::<TextPipeline>()
-            .insert_resource(CosmicFontSystem::new(self.load_system_fonts))
+            .insert_resource(CosmicFontSystem::new_with_settings(self))
             .init_resource::<SwashCache>()
             .init_resource::<TextIterScratch>()
             .add_systems(

crates/bevy_text/src/pipeline.rs

@@ -17,7 +17,7 @@ use cosmic_text::{Attrs, Buffer, Metrics, Shaping, Wrap};
 
 use crate::{
     error::TextError, ComputedTextBlock, Font, FontAtlasSets, FontSmoothing, Justify, LineBreak,
-    PositionedGlyph, TextBounds, TextEntity, TextFont, TextLayout,
+    PositionedGlyph, TextBounds, TextEntity, TextFont, TextLayout, TextPlugin,
 };
 
 /// A wrapper resource around a [`cosmic_text::FontSystem`]
@@ -30,20 +30,39 @@ pub struct CosmicFontSystem(pub cosmic_text::FontSystem);
 
 impl Default for CosmicFontSystem {
     fn default() -> Self {
-        Self::new(true)
+        Self::new_with_settings(&TextPlugin::default())
     }
 }
 
 impl CosmicFontSystem {
     /// Creates a new, wrapped [`cosmic_text::FontSystem`].
     ///
-    /// The option to load system fonts is typically provided via [`TextPlugin`](super::TextPlugin).
-    pub fn new(load_system_fonts: bool) -> Self {
+    /// The option to load system fonts is typically provided via the values in [`TextPlugin`].
+    pub fn new_with_settings(plugin_settings: &TextPlugin) -> Self {
         let locale = sys_locale::get_locale().unwrap_or_else(|| String::from("en-US"));
         let mut db = cosmic_text::fontdb::Database::new();
-        if load_system_fonts {
+        if plugin_settings.load_system_fonts {
             db.load_system_fonts();
         }
+        if let Some(family_serif) = &plugin_settings.family_serif {
+            db.set_serif_family(family_serif.to_string());
+        }
+
+        if let Some(family_sans_serif) = &plugin_settings.family_sans_serif {
+            db.set_serif_family(family_sans_serif.to_string());
+        }
+
+        if let Some(family_cursive) = &plugin_settings.family_cursive {
+            db.set_serif_family(family_cursive.to_string());
+        }
+
+        if let Some(family_fantasy) = &plugin_settings.family_fantasy {
+            db.set_serif_family(family_fantasy.to_string());
+        }
+
+        if let Some(family_monospace) = &plugin_settings.family_monospace {
+            db.set_serif_family(family_monospace.to_string());
+        }
 
         Self(cosmic_text::FontSystem::new_with_locale_and_db(locale, db))
     }