mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-16 23:24:24 +00:00
* 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.
238 lines
9.2 KiB
Rust
238 lines
9.2 KiB
Rust
//! 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);
|
||
}
|
||
}
|