6ef13b2cc8a6
shape_fill.rs
//! Shape Format › Shape Fill (#1500): a solid colour with its transparency, or a gradient, for
//! every selected shape, text box and drawing canvas.
use serde_json::Value;
use std::sync::Arc;
use wordcraft_doc::Pos;
use wordcraft_doc::fill::{Fill, Gradient, GradientFlip, GradientKind, PathShape};
use wordcraft_doc::para::InlineObject;
use wordcraft_doc::props::Rgb;
use wordcraft_doc::wordart::GradStop;
use super::objects::{edit_obj, picked_objects, selected_all};
use crate::{CmdError, CmdResult, CommandSpec, Session, p};
/// Most shapes one command fills (a selection over a whole document).
const MAX_FILL_SHAPES: usize = 10_000;
/// Most stops read from a command (the fill keeps at most `MAX_STOPS` after sanitizing).
const MAX_PARAM_STOPS: usize = 64;
pub fn specs() -> Vec<CommandSpec> {
vec![
CommandSpec::new("shape.fill", "Shape Fill", "Shape Format › Shape Styles", shape_fill)
.params(
r#"{"color": "RRGGBB" | null, "transparency"?: %} | {"gradient": {"stops": [{"pos": %, "color": "RRGGBB", "transparency"?: %}], "type"?: "linear|radial|rectangular|path", "angle"?: deg, "focus"?: [l, t, r, b], "tile"?: [l, t, r, b], "scaled"?: bool, "rotateWithShape"?: bool}} (tile: percent insets of the gradient's area; scaled: a linear angle scaled with the shape; a colour alone keeps the shape's transparency; angle: linear only, 0 = left to right, 90 = top to bottom; focus: percent insets of where a radial, rectangular or path gradient starts; applies to every selected shape, text box and canvas background)"#,
)
.when(super::objects::has_shape_or_canvas),
]
}
/// What a `shape.fill` command sets.
enum Change {
None,
/// A colour, with its transparency or (`None`) keeping each shape's.
Solid(Rgb, Option<f32>),
Fill(Fill),
}
fn shape_fill(s: &mut Session, v: &Value) -> CmdResult {
let change = parse(v)?;
let targets = targets(s);
if targets.is_empty() {
return Err(CmdError::Disabled("no shape selected".into()));
}
let mut last = Value::Null;
for pos in &targets {
let o = edit_obj(s, pos, |o| {
let slot = match o {
InlineObject::Shape { fill, .. } => fill,
o => match super::canvas::style_mut(o) {
Some(style) => &mut style.fill,
None => return,
},
};
*slot = match &change {
Change::None => None,
Change::Fill(f) => Some(f.clone()),
Change::Solid(color, t) => {
let kept = match slot {
Some(Fill::Solid { transparency, .. }) => *transparency,
_ => 0.0,
};
Fill::Solid { color: *color, transparency: t.unwrap_or(kept) }.sanitized()
}
};
})?;
last = serde_json::to_value(o).unwrap_or(Value::Null);
}
Ok(serde_json::json!({"object": last, "count": targets.len()}))
}
/// The shapes and canvases in the selection and those added to it (Shift+click).
fn targets(s: &Session) -> Vec<Pos> {
let fillable = |o: &InlineObject| matches!(o, InlineObject::Shape { .. }) || o.is_canvas();
let mut out: Vec<Pos> = selected_all(s, MAX_FILL_SHAPES).into_iter().filter(|(_, o)| fillable(o)).map(|(pos, _)| pos).collect();
for pos in picked_objects(s) {
if !out.contains(&pos) && s.doc.para_at(&pos).and_then(|q| q.object_at(pos.off)).is_some_and(fillable) {
out.push(pos);
}
}
out
}
fn color(v: &Value) -> Result<Rgb, CmdError> {
p::str(v, "color").and_then(Rgb::parse).ok_or_else(|| CmdError::Params("`color`: \"RRGGBB\"".into()))
}
fn parse(v: &Value) -> Result<Change, CmdError> {
let Some(g) = v.get("gradient") else {
return match v.get("color") {
None | Some(Value::Null) => Ok(Change::None),
Some(_) => Ok(Change::Solid(color(v)?, p::f32(v, "transparency"))),
};
};
let bad = |m: &str| CmdError::Params(format!("`gradient`: {m}"));
if !g.is_object() {
return Err(bad("an object"));
}
let stops = g
.get("stops")
.and_then(Value::as_array)
.ok_or_else(|| bad("`stops` is a list"))?
.iter()
.take(MAX_PARAM_STOPS)
.map(|st| Ok(GradStop { pos: p::f32(st, "pos").unwrap_or(0.0), color: color(st)?, transparency: p::f32(st, "transparency").unwrap_or(0.0) }))
.collect::<Result<Vec<_>, CmdError>>()?;
if stops.len() < 2 {
return Err(bad("two or more stops"));
}
let rect = |key: &str, default: f32| -> Option<[f32; 4]> {
let a = g.get(key)?.as_array()?;
let mut r = [default; 4];
for (slot, x) in r.iter_mut().zip(a) {
*slot = x.as_f64().map_or(default, |x| x as f32);
}
Some(r)
};
let path = |shape| GradientKind::Path { shape, focus: rect("focus", 50.0).unwrap_or([50.0; 4]) };
let kind = match p::str(g, "type").unwrap_or("linear") {
"linear" => {
GradientKind::Linear { angle: p::f32(g, "angle").unwrap_or(90.0), scaled: g.get("scaled").and_then(Value::as_bool).unwrap_or(false) }
}
"radial" => path(PathShape::Circle),
"rectangular" => path(PathShape::Rect),
"path" => path(PathShape::Shape),
t => return Err(bad(&format!("unknown type `{t}`"))),
};
let rot_with_shape = g.get("rotateWithShape").and_then(Value::as_bool).unwrap_or(true);
let fill = Fill::Gradient(Arc::new(Gradient { stops, kind, tile: rect("tile", 0.0), rot_with_shape, flip: GradientFlip::None }));
fill.sanitized().map(Change::Fill).ok_or_else(|| bad("no stops"))
}
/// The `shape.fill` params that set `fill` (`None`: no fill).
pub fn params(fill: Option<&Fill>) -> Value {
use serde_json::json;
match fill {
None => json!({"color": null}),
Some(Fill::Solid { color, transparency }) => json!({"color": color.hex(), "transparency": transparency}),
Some(Fill::Gradient(g)) => {
let stops: Vec<Value> = g.stops.iter().map(|s| json!({"pos": s.pos, "color": s.color.hex(), "transparency": s.transparency})).collect();
let mut out = json!({"stops": stops, "rotateWithShape": g.rot_with_shape});
if let Some(t) = g.tile {
out["tile"] = json!(t);
}
match g.kind {
GradientKind::Linear { angle, scaled } => {
out["type"] = json!("linear");
out["angle"] = json!(angle);
out["scaled"] = json!(scaled);
}
GradientKind::Path { shape, focus } => {
out["type"] = json!(match shape {
PathShape::Circle => "radial",
PathShape::Rect => "rectangular",
PathShape::Shape => "path",
});
out["focus"] = json!(focus);
}
}
json!({"gradient": out})
}
}
}
/// The directions Format Shape offers for a linear gradient, as angles (0 = left to right, 90 =
/// top to bottom).
pub const LINEAR_DIRECTIONS: [f32; 8] = [45.0, 90.0, 135.0, 0.0, 180.0, 315.0, 270.0, 225.0];
/// The directions Format Shape offers for radial and rectangular gradients, as where they start
/// (percent insets, left, top, right, bottom): each corner, then the centre.
pub const PATH_DIRECTIONS: [[f32; 4]; 5] =
[[100.0, 100.0, 0.0, 0.0], [0.0, 100.0, 100.0, 0.0], [50.0, 50.0, 50.0, 50.0], [100.0, 0.0, 0.0, 100.0], [0.0, 0.0, 100.0, 100.0]];
fn grad(stops: &[(f32, Rgb)], kind: GradientKind) -> Fill {
let stops = stops.iter().map(|&(pos, color)| GradStop { pos, color, transparency: 0.0 }).collect();
Fill::Gradient(Arc::new(Gradient { stops, kind, tile: None, rot_with_shape: true, flip: GradientFlip::None }))
}
/// The gradient Format Shape's Gradient fill starts from, from the theme's first accent
/// whatever the shape's colour (as Word 365 does): four stops, 0% at 95% lighter, 74% and 83%
/// at 55% lighter, 100% at 70% lighter, top to bottom, scaled with the shape.
pub fn default_gradient(accent1: Rgb) -> Fill {
let lighter = |off: f64| {
let c = accent1.modified("lumMod", 1.0 - off);
c.modified("lumOff", off)
};
let stops = [(0.0, 0.95), (74.0, 0.55), (83.0, 0.55), (100.0, 0.7)]
.into_iter()
.map(|(pos, off)| GradStop { pos, color: lighter(off), transparency: 0.0 })
.collect();
let g = Gradient { stops, kind: GradientKind::Linear { angle: 90.0, scaled: true }, tile: None, rot_with_shape: true, flip: GradientFlip::None };
Fill::Gradient(Arc::new(g))
}
/// Where each corner tile's gradient starts (percent insets) and the tile rectangle Word gives
/// it: from the bottom-right, bottom-left, top-right and top-left corners. Observed for the
/// bottom-right corner (`fillToRect l=t=100%`, `tileRect r=b=-100%`); the others mirror it.
const CORNERS: [([f32; 4], [f32; 4]); 4] = [
([100.0, 100.0, 0.0, 0.0], [0.0, 0.0, -100.0, -100.0]),
([0.0, 100.0, 100.0, 0.0], [-100.0, 0.0, 0.0, -100.0]),
([100.0, 0.0, 0.0, 100.0], [0.0, -100.0, -100.0, 0.0]),
([0.0, 0.0, 100.0, 100.0], [-100.0, -100.0, 0.0, 0.0]),
];
/// The tile rectangle Word gives a radial or rectangular gradient starting at `focus`: a corner's,
/// or none from the centre.
pub fn corner_tile(focus: [f32; 4]) -> Option<[f32; 4]> {
CORNERS.iter().find(|(f, _)| *f == focus).map(|(_, t)| *t)
}
/// Shape Fill › Gradient's Light and Dark Variations of `c`, each with its name, in Word's
/// order (a grid five wide): three stops at 0, 50 and 100%, light ones `c` tinted to 66, 44.5
/// and 23.5% with saturation ×1.6, dark ones shaded to 30, 67.5 and 100% with saturation
/// ×1.15 (as Word writes them); linear ones scaled with the shape, the rest circular.
pub fn variations(c: Rgb) -> [Vec<(Fill, String)>; 2] {
let tiles = |m: &str, steps: [f64; 3], sat: f64| -> Vec<(Fill, String)> {
let stop = |i: usize| {
let color = c.modified(m, steps[i]).modified("satMod", sat);
GradStop { pos: i as f32 * 50.0, color, transparency: 0.0 }
};
let fill = |kind, tile| {
let g = Gradient { stops: (0..3).map(stop).collect(), kind, tile, rot_with_shape: true, flip: GradientFlip::None };
Fill::Gradient(Arc::new(g))
};
let lin = |angle: f32| (fill(GradientKind::Linear { angle, scaled: true }, None), linear_direction_name(angle));
let corner = |i: usize| {
let (focus, tile) = CORNERS[i];
(fill(GradientKind::Path { shape: PathShape::Circle, focus }, Some(tile)), path_direction_name(focus))
};
let centre = (fill(GradientKind::Path { shape: PathShape::Circle, focus: [50.0; 4] }, None), path_direction_name([50.0; 4]));
vec![
lin(45.0),
lin(90.0),
lin(135.0),
corner(0),
corner(1),
lin(0.0),
centre,
lin(180.0),
corner(2),
corner(3),
lin(315.0),
lin(270.0),
lin(225.0),
]
};
[tiles("tint", [0.66, 0.445, 0.235], 1.6), tiles("shade", [0.3, 0.675, 1.0], 1.15)]
}
/// The 30 preset gradients from the theme's six accents: per accent, soft, lit from the top,
/// deep, lit from the bottom and centre glow. Our own design (the repo's clean-room rule: no
/// copying Word's presets), on the same accents-by-styles grid as Word's.
pub fn presets(theme: &[Rgb]) -> Vec<Fill> {
let accent = |i: usize| theme.get(4 + i).copied().unwrap_or(Rgb(68, 114, 196));
let down = GradientKind::Linear { angle: 90.0, scaled: false };
let mut out = Vec::with_capacity(30);
for style in 0..5 {
for i in 0..6 {
let c = accent(i);
out.push(match style {
0 => grad(&[(0.0, c.modified("tint", 0.2)), (100.0, c.modified("tint", 0.6))], down),
1 => grad(&[(0.0, c.modified("tint", 0.4)), (50.0, c), (100.0, c.modified("shade", 0.75))], down),
2 => grad(&[(0.0, c), (100.0, c.modified("shade", 0.5))], down),
3 => grad(&[(0.0, c.modified("shade", 0.75)), (50.0, c), (100.0, c.modified("tint", 0.4))], down),
_ => grad(
&[(0.0, c.modified("tint", 0.4)), (100.0, c.modified("shade", 0.75))],
GradientKind::Path { shape: PathShape::Circle, focus: [50.0; 4] },
),
});
}
}
out
}
/// The preset styles' names, in [`presets`]'s order (each for accents 1 to 6).
pub const PRESET_STYLES: [&str; 5] = ["Soft", "Lit from Top", "Deep", "Lit from Bottom", "Center Glow"];
/// The name of the linear direction at `angle`.
pub fn linear_direction_name(angle: f32) -> String {
match angle.round() as i32 {
0 => "Linear Right",
45 => "Linear Diagonal - Top Left to Bottom Right",
90 => "Linear Down",
135 => "Linear Diagonal - Top Right to Bottom Left",
180 => "Linear Left",
225 => "Linear Diagonal - Bottom Right to Top Left",
270 => "Linear Up",
315 => "Linear Diagonal - Bottom Left to Top Right",
_ => "Linear",
}
.into()
}
/// The name of the radial or rectangular direction starting at `focus`.
pub fn path_direction_name(focus: [f32; 4]) -> String {
match focus.map(|v| v.round() as i32) {
[0, 0, 100, 100] => "From Top Left Corner",
[100, 0, 0, 100] => "From Top Right Corner",
[0, 100, 100, 0] => "From Bottom Left Corner",
[100, 100, 0, 0] => "From Bottom Right Corner",
_ => "From Center",
}
.into()
}
/// Stop editing for the Format Shape pane's gradient stops bar. Stops stay in position order; a
/// gradient keeps 2 to `MAX_STOPS` of them.
pub mod stops {
use wordcraft_doc::props::Rgb;
use wordcraft_doc::wordart::{GradStop, MAX_STOPS};
/// The gradient's colour and transparency at `pos` (percent).
pub fn at(stops: &[GradStop], pos: f32) -> (Rgb, f32) {
let after = stops.iter().position(|s| s.pos >= pos);
let (a, b) = match after {
Some(0) | None => {
let s = if after.is_none() { stops.last() } else { stops.first() };
return s.map_or((Rgb::BLACK, 0.0), |s| (s.color, s.transparency));
}
Some(i) => (stops[i - 1], stops[i]),
};
let t = if b.pos > a.pos { (pos - a.pos) / (b.pos - a.pos) } else { 0.0 };
let mix = |x: u8, y: u8| (f32::from(x) + (f32::from(y) - f32::from(x)) * t).round().clamp(0.0, 255.0) as u8;
(Rgb(mix(a.color.0, b.color.0), mix(a.color.1, b.color.1), mix(a.color.2, b.color.2)), a.transparency + (b.transparency - a.transparency) * t)
}
/// Adds a stop at `pos` in the gradient's colour there; its index, or `None` when full.
pub fn add(stops: &mut Vec<GradStop>, pos: f32) -> Option<usize> {
if stops.len() >= MAX_STOPS {
return None;
}
let pos = if pos.is_finite() { pos.clamp(0.0, 100.0) } else { 50.0 };
let (color, transparency) = at(stops, pos);
let i = stops.iter().position(|s| s.pos > pos).unwrap_or(stops.len());
stops.insert(i, GradStop { pos, color, transparency });
Some(i)
}
/// Removes stop `i` unless only two are left; whether it did.
pub fn remove(stops: &mut Vec<GradStop>, i: usize) -> bool {
if stops.len() <= 2 || i >= stops.len() {
return false;
}
stops.remove(i);
true
}
/// Moves stop `i` to `pos`, keeping the stops in order; its new index.
pub fn move_to(stops: &mut Vec<GradStop>, i: usize, pos: f32) -> usize {
if i >= stops.len() || !pos.is_finite() {
return i;
}
let mut s = stops.remove(i);
s.pos = pos.clamp(0.0, 100.0);
let j = stops.iter().position(|o| o.pos > s.pos).unwrap_or(stops.len());
stops.insert(j, s);
j
}
}
#[cfg(test)]
mod tests {
use super::{Change, params, parse, stops};
use std::sync::Arc;
use wordcraft_doc::fill::{Fill, Gradient, GradientFlip, GradientKind, PathShape};
/// The variations Word writes for accent 1 (`tint`/`shade` with `satMod`, observed in Word 365).
#[test]
fn variations_follow_words() {
use super::variations;
let c = Rgb(0x15, 0x60, 0x82);
let [light, dark] = variations(c);
assert_eq!((light.len(), dark.len()), (13, 13));
assert_eq!(light[1].1, "Linear Down");
assert_eq!(light[6].1, "From Center");
let Fill::Gradient(g) = &light[0].0 else { panic!() };
assert_eq!(g.kind, GradientKind::Linear { angle: 45.0, scaled: true });
assert_eq!(g.stops.iter().map(|s| s.pos).collect::<Vec<_>>(), [0.0, 50.0, 100.0]);
assert!(g.stops[0].color.0 > g.stops[2].color.0 || g.stops[0].color.2 < g.stops[2].color.2, "lighter towards the end: {:?}", g.stops);
let Fill::Gradient(g) = &light[3].0 else { panic!() };
assert_eq!(
(g.kind, g.tile),
(GradientKind::Path { shape: PathShape::Circle, focus: [100.0, 100.0, 0.0, 0.0] }, Some([0.0, 0.0, -100.0, -100.0]))
);
let Fill::Gradient(g) = super::default_gradient(c) else { panic!() };
assert_eq!(g.stops.iter().map(|s| s.pos).collect::<Vec<_>>(), [0.0, 74.0, 83.0, 100.0], "Word's starting gradient");
assert_eq!(g.stops[1].color, g.stops[2].color);
assert!(g.stops.iter().all(|s| s.color.0 > c.0 && s.color.1 > c.1), "lighter than the accent");
let Fill::Gradient(g) = &dark[1].0 else { panic!() };
assert_eq!(g.stops[2].color, c.modified("satMod", 1.15), "the last dark stop is the colour itself");
}
#[test]
fn params_set_the_fill_they_were_made_from() {
let g = |kind| {
Fill::Gradient(Arc::new(Gradient {
stops: vec![st(0.0, 10, 0.0), st(40.0, 90, 25.0), st(100.0, 250, 100.0)],
kind,
tile: None,
rot_with_shape: false,
flip: GradientFlip::None,
}))
};
let fills = [
Fill::Solid { color: Rgb(1, 2, 3), transparency: 35.0 },
g(GradientKind::Linear { angle: 135.0, scaled: false }),
g(GradientKind::Linear { angle: 45.0, scaled: true }),
g(GradientKind::Path { shape: PathShape::Circle, focus: [100.0, 0.0, 0.0, 100.0] }),
g(GradientKind::Path { shape: PathShape::Rect, focus: [50.0; 4] }),
g(GradientKind::Path { shape: PathShape::Shape, focus: [50.0; 4] }),
];
let tiled = super::variations(Rgb(9, 9, 9))[0][3].0.clone();
for f in fills.into_iter().chain([tiled]) {
let v = params(Some(&f));
let back = match parse(&v) {
Ok(Change::Fill(f)) => f,
Ok(Change::Solid(c, t)) => Fill::Solid { color: c, transparency: t.unwrap_or(0.0) },
_ => panic!("{v}"),
};
assert_eq!(back, f, "{v}");
}
assert!(matches!(parse(¶ms(None)), Ok(Change::None)));
}
use wordcraft_doc::props::Rgb;
use wordcraft_doc::wordart::{GradStop, MAX_STOPS};
fn st(pos: f32, c: u8, transparency: f32) -> GradStop {
GradStop { pos, color: Rgb(c, c, c), transparency }
}
#[test]
fn stops_are_added_in_the_gradients_colour_moved_in_order_and_kept_two_to_ten() {
let mut g = vec![st(0.0, 0, 0.0), st(100.0, 200, 50.0)];
assert_eq!(stops::add(&mut g, 25.0), Some(1));
assert_eq!((g[1].color, g[1].transparency), (Rgb(50, 50, 50), 12.5));
assert_eq!(stops::add(&mut g, f32::NAN), Some(2), "a junk position goes in the middle");
assert_eq!(stops::move_to(&mut g, 1, 300.0), 3, "past the end: last");
assert_eq!(g.iter().map(|s| s.pos).collect::<Vec<_>>(), [0.0, 50.0, 100.0, 100.0]);
assert_eq!(stops::move_to(&mut g, 3, -1.0), 1, "after the stop already at 0%");
assert!(stops::remove(&mut g, 0) && stops::remove(&mut g, 0));
assert!(!stops::remove(&mut g, 0), "two stops stay");
assert!(!stops::remove(&mut vec![st(0.0, 0, 0.0); 3], 7));
while stops::add(&mut g, 10.0).is_some() {}
assert_eq!(g.len(), MAX_STOPS);
assert_eq!(stops::at(&g, 200.0).0, g[g.len() - 1].color);
assert_eq!(stops::at(&[], 5.0), (Rgb::BLACK, 0.0));
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.