diff --git a/crates/kas-core/src/draw/draw.rs b/crates/kas-core/src/draw/draw.rs index dea0a8fe5..f73b31b3a 100644 --- a/crates/kas-core/src/draw/draw.rs +++ b/crates/kas-core/src/draw/draw.rs @@ -207,8 +207,8 @@ pub trait Draw { /// Text is drawn from `rect.pos` and clipped to `rect`. If the text /// scrolls, `rect` should be the size of the whole text, not the window. /// - /// It is required to call [`Text::prepare`] or equivalent - /// prior to this method to select a font, font size and perform layout. + /// The `text` object must be configured and prepared prior to calling this + /// method (see [`crate::theme::Text`] or [`crate::text::Text`]). fn text(&mut self, rect: Rect, text: &TextDisplay, col: Rgba); /// Draw text with a single color and effects @@ -219,8 +219,8 @@ pub trait Draw { /// The effects list does not contain colour information, but may contain /// underlining/strikethrough information. It may be empty. /// - /// It is required to call [`Text::prepare`] or equivalent - /// prior to this method to select a font, font size and perform layout. + /// The `text` object must be configured and prepared prior to calling this + /// method (see [`crate::theme::Text`] or [`crate::text::Text`]). fn text_effects(&mut self, rect: Rect, text: &TextDisplay, col: Rgba, effects: &[Effect<()>]); /// Draw text with effects (including [`Rgba`] color) @@ -232,8 +232,8 @@ pub trait Draw { /// If the `effects` list is empty or the first entry has `start > 0`, a /// default entity will be assumed. /// - /// It is required to call [`Text::prepare`] or equivalent - /// prior to this method to select a font, font size and perform layout. + /// The `text` object must be configured and prepared prior to calling this + /// method (see [`crate::theme::Text`] or [`crate::text::Text`]). fn text_effects_rgba(&mut self, rect: Rect, text: &TextDisplay, effects: &[Effect]); } diff --git a/crates/kas-core/src/event/cx/config.rs b/crates/kas-core/src/event/cx/config.rs index 42f1248c7..6c1255e5c 100644 --- a/crates/kas-core/src/event/cx/config.rs +++ b/crates/kas-core/src/event/cx/config.rs @@ -125,10 +125,7 @@ impl<'a> ConfigCx<'a> { /// Configure a text object /// - /// The [`TextClass`] should be set before calling this method (via - /// [`Text::new`] or [`Text::set_class`]). - /// - /// This selects a font given the [`TextClass`], + /// This selects a font given the [`TextClass`][crate::theme::TextClass], /// [theme configuration][crate::theme::Config] and /// the loaded [fonts][crate::text::fonts]. #[inline] diff --git a/crates/kas-core/src/text/mod.rs b/crates/kas-core/src/text/mod.rs index 5bf1f7af6..600d60797 100644 --- a/crates/kas-core/src/text/mod.rs +++ b/crates/kas-core/src/text/mod.rs @@ -8,11 +8,8 @@ //! Most of this module is simply a re-export of the [KAS Text] API, hence the //! lower level of integration than other parts of the library. //! -//! [`Text`] objects *must* be configured and prepared before usage, otherwise -//! they may appear empty. Call [`ConfigCx::text_config`] from -//! [`Events::configure`] and [`ConfigCx::text_set_size`] from -//! [`Layout::set_rect`] to set text position and prepare. -//! If text is adjusted, one may use e.g. [`Text::prepare`] to update. +//! See also [`crate::theme::Text`] which provides better integration with KAS +//! theming and widget sizing operations. //! //! [KAS Text]: https://github.com/kas-gui/kas-text/ diff --git a/crates/kas-core/src/theme/size.rs b/crates/kas-core/src/theme/size.rs index 592ef2f50..01b621359 100644 --- a/crates/kas-core/src/theme/size.rs +++ b/crates/kas-core/src/theme/size.rs @@ -230,7 +230,7 @@ pub trait ThemeSize { /// The height of a line of text by class /// - /// Prefer to use [`Self::text_line_height`] where possible. + /// Prefer to use [`SizeCx::text_line_height`] where possible. fn line_height(&self, class: TextClass) -> i32; /// Configure a text object, setting font properties diff --git a/crates/kas-core/src/theme/text.rs b/crates/kas-core/src/theme/text.rs index a3cc1d664..54e83062e 100644 --- a/crates/kas-core/src/theme/text.rs +++ b/crates/kas-core/src/theme/text.rs @@ -6,6 +6,7 @@ //! Theme-applied Text element use super::TextClass; +#[allow(unused)] use super::{DrawCx, SizeCx}; #[allow(unused)] use crate::event::ConfigCx; use crate::layout::AxisInfo; use crate::text::fonts::{FaceId, FontId, InvalidFontId}; @@ -16,18 +17,27 @@ use crate::Action; /// Text type-setting object (theme aware) /// /// This struct is a theme-aware variant of [`crate::text::Text`]. It contains: +/// - A [`TextClass`] /// - A [`FormattableText`] /// - A [`TextDisplay`] /// - Type-setting configuration. Values have reasonable defaults: -/// - The default font will be the first loaded font: see [fonts]. -/// - The default font size is 16px (the web default). +/// - The font is derived from the [`TextClass`] by +/// [`ConfigCx::text_configure`]. Otherwise, the default font will be +/// the first loaded font: see [`crate::text::fonts`]. +/// - The font size is derived from the [`TextClass`] by +/// [`ConfigCx::text_configure`]. Otherwise, the default font size is +/// 16px (the web default). /// - Default text direction and alignment is inferred from the text. -/// - Line-wrapping requires a call to [`Text::set_wrap_width`]. -/// - The bounds used for alignment [must be set][Text::set_bounds]. +/// - The bounds used for alignment and line-wrapping +/// must be set by calling [`Text::set_bounds`]. /// /// This struct tracks the [`TextDisplay`]'s /// [state of preparation][TextDisplay#status-of-preparation] and will perform -/// steps as required. +/// steps as required. Normal usage of this struct is as follows: +/// - Configure by calling [`ConfigCx::text_configure`] +/// - (Optionally) check size requirements by calling [`SizeCx::text_rules`] +/// - Set the size and prepare by calling [`ConfigCx::text_set_size`] +/// - Draw by calling [`DrawCx::text`] (and/or other text methods) #[derive(Clone, Debug)] pub struct Text { /// Bounds to use for alignment @@ -169,6 +179,8 @@ impl Text { /// Set text class /// + /// This controls line-wrapping, font and font size selection. + /// /// Default: `TextClass::Label(true)` #[inline] pub fn set_class(&mut self, class: TextClass) { @@ -209,7 +221,7 @@ impl Text { /// /// This is a scaling factor used to convert font sizes, with units /// `pixels/Em`. Equivalently, this is the line-height in pixels. - /// See [`crate::fonts`] documentation. + /// See [`crate::text::fonts`] documentation. /// /// To calculate this from text size in Points, use `dpem = dpp * pt_size` /// where the dots-per-point is usually `dpp = scale_factor * 96.0 / 72.0`