diff --git a/TODO/_current.md b/TODO/_current.md index 72622bec2..116a63651 100644 --- a/TODO/_current.md +++ b/TODO/_current.md @@ -8,7 +8,7 @@ - Review badges. * Review docs. - Do a full read, look for typos or failed links. - - Last reviewed `zero_ui::clipboard`. + - Last reviewed `zero_ui::color`. # Publish diff --git a/zero-ui-color/src/filter.rs b/zero-ui-color/src/filter.rs index 6d9a3c099..ecf4f1b50 100644 --- a/zero-ui-color/src/filter.rs +++ b/zero-ui-color/src/filter.rs @@ -17,9 +17,6 @@ use crate::{RenderColor, Rgba}; /// A color filter or combination of filters. /// -/// You can start a filter from one of the standalone filter functions, and then combine more filters using -/// the builder call style. -/// /// # Examples /// /// ``` @@ -35,65 +32,8 @@ pub struct Filter { filters: Vec, needs_layout: bool, } + impl Filter { - fn op(mut self, op: FilterOp) -> Self { - self.filters.push(FilterData::Op(op)); - self - } - - /// Compute a [`RenderFilter`] in the current [`LAYOUT`] context. - /// - /// Most filters convert one-to-one, effects that have a [`Length`] value use the - /// layout context to calculate relative values. - /// - /// Relative blur radius lengths are calculated using the `constraints().fill_size().width` value. - /// - /// [`LAYOUT`]: zero_ui_layout::context::LAYOUT - pub fn layout(&self) -> RenderFilter { - self.filters - .iter() - .map(|f| match f { - FilterData::Op(op) => *op, - FilterData::Blur(l) => { - let l = l.layout_f32_x(); - FilterOp::Blur(l, l) - } - FilterData::DropShadow { - offset, - blur_radius, - color, - } => FilterOp::DropShadow(Shadow { - offset: offset.layout().to_wr().to_vector(), - color: RenderColor::from(*color), - blur_radius: blur_radius.layout_f32_x(), - }), - }) - .collect() - } - - /// Compute a [`RenderFilter`] if the filter is not affected by layout. - pub fn try_render(&self) -> Option { - if self.needs_layout { - return None; - } - - let mut r = Vec::with_capacity(self.filters.len()); - - for f in &self.filters { - match f { - FilterData::Op(op) => r.push(*op), - FilterData::Blur(_) | FilterData::DropShadow { .. } => unreachable!(), - } - } - - Some(r) - } - - /// Returns `true` if this filter is affected by the layout context where it is evaluated. - pub fn needs_layout(&self) -> bool { - self.needs_layout - } - /// Add an opacity adjustment to the filter, zero is fully transparent, one is the input transparency. pub fn opacity>(self, alpha: A) -> Self { let alpha_value = alpha.into().0; @@ -171,6 +111,14 @@ impl Filter { } impl Filter { + /// New default empty. + pub const fn new() -> Filter { + Self { + filters: vec![], + needs_layout: false, + } + } + /// New [`Filter::opacity`]. pub fn new_opacity>(alpha: A) -> Filter { Filter::default().opacity(alpha) @@ -221,6 +169,66 @@ impl Filter { } } +impl Filter { + fn op(mut self, op: FilterOp) -> Self { + self.filters.push(FilterData::Op(op)); + self + } + + /// Compute a [`RenderFilter`] in the current [`LAYOUT`] context. + /// + /// Most filters convert one-to-one, effects that have a [`Length`] value use the + /// layout context to calculate relative values. + /// + /// Relative blur radius lengths are calculated using the `constraints().fill_size().width` value. + /// + /// [`LAYOUT`]: zero_ui_layout::context::LAYOUT + pub fn layout(&self) -> RenderFilter { + self.filters + .iter() + .map(|f| match f { + FilterData::Op(op) => *op, + FilterData::Blur(l) => { + let l = l.layout_f32_x(); + FilterOp::Blur(l, l) + } + FilterData::DropShadow { + offset, + blur_radius, + color, + } => FilterOp::DropShadow(Shadow { + offset: offset.layout().to_wr().to_vector(), + color: RenderColor::from(*color), + blur_radius: blur_radius.layout_f32_x(), + }), + }) + .collect() + } + + /// Compute a [`RenderFilter`] if the filter is not affected by layout. + pub fn try_render(&self) -> Option { + if self.needs_layout { + return None; + } + + let mut r = Vec::with_capacity(self.filters.len()); + + for f in &self.filters { + match f { + FilterData::Op(op) => r.push(*op), + FilterData::Blur(_) | FilterData::DropShadow { .. } => unreachable!(), + } + } + + Some(r) + } + + /// Returns `true` if this filter is affected by the layout context where it is evaluated. + pub fn needs_layout(&self) -> bool { + self.needs_layout + } +} + impl fmt::Debug for Filter { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { if f.alternate() { diff --git a/zero-ui-color/src/gradient.rs b/zero-ui-color/src/gradient.rs index 520c50646..09f303ab5 100644 --- a/zero-ui-color/src/gradient.rs +++ b/zero-ui-color/src/gradient.rs @@ -8,9 +8,12 @@ use zero_ui_view_api::unit::*; use crate::*; /// Specifies how to draw the gradient outside the first and last stop. -#[derive(Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)] +#[derive(Clone, Default, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)] pub enum ExtendMode { - /// Default value. The color values at the ends of the gradient vector fill the remaining space. + /// The color values at the ends of the gradient vector fill the remaining space. + /// + /// This is the default mode. + #[default] Clamp, /// The gradient is repeated until the space is filled. Repeat, @@ -441,7 +444,7 @@ impl ColorStop { /// /// A [`Length::Default`] offset indicates that the color stop is positional. /// - /// # Resolution + /// # Layout /// /// When a [`GradientStops`] calculates layout, positional stops are resolved like this: /// diff --git a/zero-ui-color/src/lib.rs b/zero-ui-color/src/lib.rs index 371a74673..92238bcad 100644 --- a/zero-ui-color/src/lib.rs +++ b/zero-ui-color/src/lib.rs @@ -1313,7 +1313,7 @@ impl ColorPair { } } -/// Defines the color space for color interpolation in a context. +/// Defines the color space for color interpolation. /// /// See [`with_lerp_space`] for more details. #[derive(Default, Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)] @@ -1331,6 +1331,9 @@ pub enum LerpSpace { } /// Gets the lerp space used for color interpolation. +/// +/// Must be called only inside the [`with_lerp_space`] closure or in the lerp implementation of a variable animating +/// with [`rgba_sampler`] or [`hsla_linear_sampler`]. pub fn lerp_space() -> LerpSpace { LERP_SPACE.get_clone() } diff --git a/zero-ui-color/src/mix.rs b/zero-ui-color/src/mix.rs index 972efbe02..5d18f54fe 100644 --- a/zero-ui-color/src/mix.rs +++ b/zero-ui-color/src/mix.rs @@ -52,7 +52,7 @@ macro_rules! impl_mix { $( paste! { - #[doc = "Mix `background` over `self` using the [`MixBlendMode::`" $Mode "`]."] + #[doc = "Mix `background` over `self` using the [`MixBlendMode::" $Mode "`]."] /// $(#[$meta])* pub fn [](self, background: PreMulRgba) -> PreMulRgba { @@ -104,7 +104,7 @@ macro_rules! impl_mix { /// $(#[$meta])* /// - /// This method converts both [`PreMulRgba`] and the result back to `Rgba`. + /// This method converts both inputs to [`PreMulRgba`] and the result back to `Rgba`. pub fn [](self, background: Rgba) -> Rgba { self.pre_mul().[](background.pre_mul()).to_rgba() } @@ -116,7 +116,7 @@ macro_rules! impl_mix { /// $(#[$ns_meta])* /// - /// This method converts both [`Hsla`] and the result back to `Rgba`. + /// This method converts both inputs to [`Hsla`] and the result back to `Rgba`. pub fn [](self, background: Rgba) -> Rgba { self.to_hsla().[](background.to_hsla()).to_rgba() } diff --git a/zero-ui-view-api/src/config.rs b/zero-ui-view-api/src/config.rs index cdaaedd50..d7eeebc61 100644 --- a/zero-ui-view-api/src/config.rs +++ b/zero-ui-view-api/src/config.rs @@ -154,10 +154,10 @@ impl fmt::Debug for FontAntiAliasing { /// Color scheme preference. #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] pub enum ColorScheme { - /// Dark foreground, light background. + /// Dark text, light background. Light, - /// Light foreground, dark background. + /// Light text, dark background. Dark, } impl Default for ColorScheme { diff --git a/zero-ui-wgt-fill/src/node.rs b/zero-ui-wgt-fill/src/node.rs index 1aa5c44f2..646b0af9d 100644 --- a/zero-ui-wgt-fill/src/node.rs +++ b/zero-ui-wgt-fill/src/node.rs @@ -114,9 +114,9 @@ where /// Linear gradient. /// /// Can be used as a node that fills the available space with the gradient, or can continue building a linear -/// gradient. +/// or tiled linear gradient. /// -/// Use [`gradient`] or [`linear_gradient`] to build. +/// Use [`gradient`] or [`linear_gradient`] to start building. /// /// [`gradient`]: fn@gradient pub struct LinearGradient { @@ -187,12 +187,9 @@ where /// Tiled linear gradient. /// /// Can be used as a node that fills the available space with the gradient tiles, or can continue building a -/// repeating linear gradient. +/// tiled linear gradient. /// -/// -/// Use [`gradient`], [`linear_gradient`] to build. -/// -/// [`gradient`]: fn@gradient +/// Use [`LinearGradient::tile`] to build. pub struct TiledLinearGradient { stops: S, axis: A, @@ -260,10 +257,10 @@ where /// Radial gradient. /// -/// Can be used as a node that fills the available space with the gradient, or can continue building a linear -/// gradient. +/// Can be used as a node that fills the available space with the gradient, or can continue building a radial +/// or tiled radial gradient. /// -/// Use [`gradient`] or [`radial_gradient`] to build. +/// Use [`gradient`] or [`radial_gradient`] to start building. /// /// [`gradient`]: fn@gradient pub struct RadialGradient { @@ -336,8 +333,7 @@ where /// /// Can be used as a node that fills the available space with the gradient tiles, or can continue building the gradient. /// -/// -/// Use [`gradient`], [`radial_gradient`] to build. +/// Use [`RadialGradient::tile`] to build. /// /// [`gradient`]: fn@gradient pub struct TiledRadialGradient { @@ -411,10 +407,10 @@ where /// Conic gradient. /// -/// Can be used as a node that fills the available space with the gradient, or can continue building a linear -/// gradient. +/// Can be used as a node that fills the available space with the gradient, or can continue building the conic +/// or a tiled conic gradient. /// -/// Use [`gradient`] or [`conic_gradient`] to build. +/// Use [`gradient`] or [`conic_gradient`] to start building. /// /// [`gradient`]: fn@gradient pub struct ConicGradient { @@ -487,7 +483,7 @@ where /// /// Can be used as a node that fills the available space with the gradient tiles, or can continue building the gradient. /// -/// Use [`gradient`], [`conic_gradient`] to build. +/// Use [`ConicGradient::tile`] to build. /// /// [`gradient`]: fn@gradient pub struct TiledConicGradient { diff --git a/zero-ui/src/color.rs b/zero-ui/src/color.rs index b995e418f..925afc3f3 100644 --- a/zero-ui/src/color.rs +++ b/zero-ui/src/color.rs @@ -114,7 +114,7 @@ pub use zero_ui_wgt::color_scheme; pub use zero_ui_wgt_fill::node::flood; -/// Color filters. +/// Color filter types and properties. pub mod filter { pub use zero_ui_color::filter::{ColorMatrix, Filter, RenderFilter}; @@ -126,7 +126,7 @@ pub mod filter { }; } -/// Color gradient. +/// Color gradient types and nodes. pub mod gradient { pub use zero_ui_color::gradient::{ stops, ColorStop, ExtendMode, GradientRadius, GradientRadiusBase, GradientStop, GradientStops, LinearGradientAxis,