Files
craft-libs/crates/wordmodel/src/fill.rs
T
Dylan M. Taylor 08882273d1 Add craft-wordmodel: WordCraft's document model without its editing code (#963)
* Add craft-wordmodel: WordCraft's document model without its editing code

WordCraft's crates/doc (wordcraft-doc, at 07f97737) moved as it is, so the DOCX,
RTF, ODT and other text-format crates can read into and write from one model.
Module paths, type names and serde attributes are unchanged: an app that
re-exports the crate keeps its native file format.

Left in the app: range editing (edit.rs), IME text and equation editing. Not
model, and already in craft-libs: code pages (craft-rtf), the ZIP entry-count
check (craft-opc), the compound-file guard (craft-cfb). The paragraph walks
moved to walk.rs and the unit helpers of wordcraft-geom to geom.rs.

* craft-wordmodel: math_tree, the arguments of an equation node and a walk over its runs

The DOCX reader and writer walk an equation's runs. The walk and the child
accessors it uses were in WordCraft's equation editor (math_edit.rs), which
stays in the app; they are structure, not editing.

* craft-wordmodel: keep the document operations (edit.rs) with the model

The DOCX and RTF readers use them: alternative-format chunks are merged into
a document with adopt_blocks, and a reader formats ranges with format_range
and inserts objects. They operate on the document, not on a view, so they
belong beside it. The tests that drove them come back with them; the
paragraph walks stay in walk.rs and edit re-exports them.

base64 0.23, as WordCraft and craft-offcrypto use.
2026-11-11 19:43:08 -05:00

238 lines
9.2 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! Shape fills: what paints a shape's, text box's or canvas's interior, and a shape outline's
//! gradient (DrawingML `a:solidFill` / `a:gradFill`, ECMA-376 §20.1.8.54 and §20.1.8.33; VML
//! `v:fill`).
//!
//! A gradient is kept as the file states it (stops, linear angle or path focus, tile rectangle,
//! `rotWithShape`, flip) so saving writes it back; drawing approximates rectangular and
//! shape-following paths as circular. Transparencies are percent (0 = opaque); rectangles are
//! percent insets (left, top, right, bottom) from the shape's edges.
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use std::sync::Arc;
use crate::props::Rgb;
#[cfg(test)]
use crate::wordart::MAX_STOPS;
use crate::wordart::{GradStop, clamp, sanitized_stops};
/// A shape's fill. In `.json` documents an opaque solid fill is written `[r, g, b]` as before
/// fills had transparency or gradients; the rest are tagged (`{"type": "gradient", ...}`).
#[derive(Clone, Debug, PartialEq)]
pub enum Fill {
Solid { color: Rgb, transparency: f32 },
Gradient(Arc<Gradient>),
}
/// A gradient fill.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct Gradient {
pub stops: Vec<GradStop>,
pub kind: GradientKind,
/// `a:tileRect`: where the gradient's area sits relative to the shape (percent insets).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub tile: Option<[f32; 4]>,
/// Turns with the shape (`rotWithShape`).
#[serde(default)]
pub rot_with_shape: bool,
#[serde(default, skip_serializing_if = "GradientFlip::is_none")]
pub flip: GradientFlip,
}
/// How a gradient runs.
#[derive(Clone, Copy, Debug, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "camelCase")]
pub enum GradientKind {
/// Along a line at `angle` degrees (0 = left to right, 90 = top to bottom). `scaled`: the
/// angle is scaled with the shape's aspect ratio.
Linear {
angle: f32,
#[serde(default)]
scaled: bool,
},
/// Outwards from `focus` (percent insets from the shape's edges, `a:fillToRect`).
Path { shape: PathShape, focus: [f32; 4] },
}
/// A path gradient's outline (`a:path/@path`).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum PathShape {
Circle,
Rect,
Shape,
}
/// How the gradient's tile is mirrored when tiled (`a:gradFill/@flip`).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum GradientFlip {
#[default]
None,
X,
Y,
Xy,
}
impl GradientFlip {
pub fn is_none(&self) -> bool {
*self == GradientFlip::None
}
}
/// Largest rectangle inset kept, percent (hostile files).
const MAX_INSET: f32 = 1000.0;
fn rect(r: [f32; 4]) -> [f32; 4] {
r.map(|v| clamp(v, -MAX_INSET, MAX_INSET, 0.0))
}
impl Fill {
/// An opaque solid fill.
pub fn solid(color: Rgb) -> Fill {
Fill::Solid { color, transparency: 0.0 }
}
/// The one colour standing for the fill where only one fits: the solid colour, or a
/// gradient's middle stop.
pub fn main_color(&self) -> Rgb {
match self {
Fill::Solid { color, .. } => *color,
Fill::Gradient(g) => g.stops.get(g.stops.len() / 2).map_or(Rgb::BLACK, |s| s.color),
}
}
/// Finite, in range: at most [`MAX_STOPS`] stops, in order, positions and transparencies
/// 0–100%, angles 0–360°. A gradient with one stop is that stop's solid colour; with none,
/// no fill (`None`).
pub fn sanitized(&self) -> Option<Fill> {
Some(match self {
Fill::Solid { color, transparency } => Fill::Solid { color: *color, transparency: clamp(*transparency, 0.0, 100.0, 0.0) },
Fill::Gradient(g) => {
let stops = sanitized_stops(&g.stops);
match stops[..] {
[] => return None,
[s] => return Some(Fill::Solid { color: s.color, transparency: s.transparency }),
_ => {}
}
let kind = match g.kind {
GradientKind::Linear { angle, scaled } => {
GradientKind::Linear { angle: clamp(angle, -1e6, 1e6, 0.0).rem_euclid(360.0) % 360.0, scaled }
}
GradientKind::Path { shape, focus } => GradientKind::Path { shape, focus: rect(focus) },
};
Fill::Gradient(Arc::new(Gradient { stops, kind, tile: g.tile.map(rect), rot_with_shape: g.rot_with_shape, flip: g.flip }))
}
})
}
}
/// The tagged `.json` form of fills other than opaque solid ones.
#[derive(Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "camelCase")]
enum Tagged {
Solid {
color: Rgb,
#[serde(default)]
transparency: f32,
},
Gradient(Gradient),
}
#[derive(Deserialize)]
#[serde(untagged)]
enum AnyForm {
Plain(Rgb),
Tagged(Tagged),
}
impl Serialize for Fill {
fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
match self {
Fill::Solid { color, transparency: 0.0 } => color.serialize(s),
Fill::Solid { color, transparency } => Tagged::Solid { color: *color, transparency: *transparency }.serialize(s),
Fill::Gradient(g) => Tagged::Gradient(Gradient::clone(g)).serialize(s),
}
}
}
impl<'de> Deserialize<'de> for Fill {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Fill, D::Error> {
Ok(match AnyForm::deserialize(d)? {
AnyForm::Plain(color) => Fill::solid(color),
AnyForm::Tagged(Tagged::Solid { color, transparency }) => Fill::Solid { color, transparency },
AnyForm::Tagged(Tagged::Gradient(g)) => Fill::Gradient(Arc::new(g)),
})
}
}
#[cfg(test)]
mod tests {
use super::*;
fn stop(pos: f32, color: Rgb, transparency: f32) -> GradStop {
GradStop { pos, color, transparency }
}
fn grad(stops: Vec<GradStop>, kind: GradientKind) -> Fill {
Fill::Gradient(Arc::new(Gradient { stops, kind, tile: None, rot_with_shape: true, flip: GradientFlip::None }))
}
#[test]
fn opaque_solid_fills_are_written_as_before_and_old_documents_load() {
let f = Fill::solid(Rgb(1, 2, 3));
assert_eq!(serde_json::to_string(&f).ok().as_deref(), Some("[1,2,3]"));
assert_eq!(serde_json::from_str::<Fill>("[1,2,3]").ok(), Some(f));
}
#[test]
fn transparent_and_gradient_fills_round_trip_tagged() {
let fills = [
Fill::Solid { color: Rgb::WHITE, transparency: 70.0 },
grad(vec![stop(0.0, Rgb(9, 9, 9), 0.0), stop(100.0, Rgb::WHITE, 50.0)], GradientKind::Linear { angle: 90.0, scaled: true }),
Fill::Gradient(Arc::new(Gradient {
stops: vec![stop(0.0, Rgb::BLACK, 0.0), stop(100.0, Rgb::WHITE, 0.0)],
kind: GradientKind::Path { shape: PathShape::Rect, focus: [50.0, 50.0, 50.0, 50.0] },
tile: Some([-10.0, 0.0, 0.0, 0.0]),
rot_with_shape: false,
flip: GradientFlip::Xy,
})),
];
for f in fills {
let json = serde_json::to_string(&f).unwrap_or_default();
assert!(json.contains("\"type\""), "{json}");
assert_eq!(serde_json::from_str::<Fill>(&json).ok(), Some(f), "{json}");
}
}
#[test]
fn hostile_fills_are_sanitized() {
let many: Vec<GradStop> = (0..30).map(|i| stop(100.0 - i as f32, Rgb::BLACK, f32::NAN)).collect();
let Some(Fill::Gradient(g)) = grad(many, GradientKind::Linear { angle: -450.0, scaled: false }).sanitized() else { panic!() };
assert_eq!(g.stops.len(), MAX_STOPS);
assert!(g.stops.windows(2).all(|w| w[0].pos <= w[1].pos) && g.stops.iter().all(|s| s.transparency == 0.0));
assert_eq!(g.kind, GradientKind::Linear { angle: 270.0, scaled: false });
let path = grad(
vec![stop(150.0, Rgb::BLACK, 200.0), stop(-5.0, Rgb::WHITE, 0.0)],
GradientKind::Path { shape: PathShape::Circle, focus: [f32::NAN, 1e9, -1e9, 5.0] },
);
let Some(Fill::Gradient(g)) = path.sanitized() else { panic!() };
assert_eq!((g.stops[0].pos, g.stops[1].pos, g.stops[1].transparency), (0.0, 100.0, 100.0));
assert_eq!(g.kind, GradientKind::Path { shape: PathShape::Circle, focus: [0.0, MAX_INSET, -MAX_INSET, 5.0] });
assert_eq!(
grad(vec![stop(0.0, Rgb::WHITE, 30.0)], GradientKind::Linear { angle: 0.0, scaled: false }).sanitized(),
Some(Fill::Solid { color: Rgb::WHITE, transparency: 30.0 })
);
assert_eq!(grad(vec![], GradientKind::Linear { angle: 0.0, scaled: false }).sanitized(), None);
assert_eq!(Fill::Solid { color: Rgb::BLACK, transparency: f32::NAN }.sanitized(), Some(Fill::solid(Rgb::BLACK)));
}
#[test]
fn main_colour_is_the_middle_stop() {
let g = grad(
vec![stop(0.0, Rgb(1, 0, 0), 0.0), stop(50.0, Rgb(2, 0, 0), 0.0), stop(100.0, Rgb(3, 0, 0), 0.0)],
GradientKind::Linear { angle: 0.0, scaled: false },
);
assert_eq!(g.main_color(), Rgb(2, 0, 0));
assert_eq!(Fill::solid(Rgb::WHITE).main_color(), Rgb::WHITE);
}
}