Live Paint: null ids and bad options under the bucket; docs

- While the Live Paint Bucket is active, a paint or stroke command with
  a null ids or id goes to the bucket's colors, as one without them does.
  Before, it painted the selection, since other commands read a null ids
  or id as no target.
- A bad target or aligned value is refused while the bucket is active,
  as it is with any other tool, instead of changing the bucket's colors.
- stroke.weightUp and stroke.weightDown no longer read the selection's
  active Appearance row while the bucket takes the weight, as stroke.set
  and stroke.setAdvanced already do. The row was not used in that case.
- The params text of gradient.selectStop says that, while the bucket is
  active, it selects a stop of the default paint's gradient, also with an
  object of a symbol instance picked. docs/mcp.md says the same, and that
  paint.editGradient without ids, id or item then changes the bucket's
  gradient.
- docs/mcp.md again says that another tool chosen after the bucket keeps
  its colors until a command or a new selection changes them.
This commit is contained in:
dotCooCoo
2026-11-18 20:29:39 -08:00
parent 2b0d6e5b14
commit db8301307c
6 changed files with 58 additions and 22 deletions
+2 -2
View File
@@ -42,7 +42,7 @@ pub fn specs() -> Vec<CommandSpec> {
"Select Gradient Stop",
[],
None,
"{index: stop index (0 = the start) | null to clear} select a stop of the gradient behind the active proxy (the first selected object's, else the default paint): the stop the Gradient tool's annotator, the Gradient and Color panels and Delete/arrow keys act on; refused while an object of a symbol instance's art is selected → {index}",
"{index: stop index (0 = the start) | null to clear} select a stop of the gradient behind the active proxy (the first selected object's, else the default paint; the default paint's while the Live Paint Bucket is the active tool): the stop the Gradient tool's annotator, the Gradient and Color panels and Delete/arrow keys act on; refused while an object of a symbol instance's art is selected, except while the Live Paint Bucket is the active tool → {index}",
always,
select_stop
),
@@ -532,7 +532,7 @@ fn apply_gradient_edit_in_model(
fn edit_gradient(s: &mut Session, p: &Value) -> Result<Value> {
const C: &str = "paint.editGradient";
// While the Live Paint Bucket is active, the gradient it paints with changes; the selection keeps its own.
let bucket = super::paint::bucket_color_params(s, p);
let bucket = super::paint::bucket_color_params(s, p, C)?;
let p = bucket.as_ref().unwrap_or(p);
let item = item_target(s, p, C)?;
let stroke = edits_stroke(s, p, item, !s.fill_active, C)?;
+1 -1
View File
@@ -209,7 +209,7 @@ fn apply(s: &mut Session, p: &Value) -> Result<Value> {
let preset = s.gradient_preset(name).ok_or_else(|| bad(C, format!("no gradient preset `{name}` (see gradient.presets.list)")))?;
// While the Live Paint Bucket is active, the gradient it paints with changes, chosen by the
// active proxy rather than the selection's Appearance row (as paint.editGradient chooses).
let bucket = super::paint::bucket_color_params(s, p);
let bucket = super::paint::bucket_color_params(s, p, C)?;
let p = bucket.as_ref().unwrap_or(p);
let stroke = edits_stroke(s, p, item_target(s, p, C)?, !s.fill_active, C)?;
let g = &preset.gradient;
+16 -11
View File
@@ -490,7 +490,7 @@ fn apply_to_proxy(s: &mut Session, p: &Value, paint: Paint, cmd: &str) -> Result
/// remember the paint. Replies `{objects}`: how many objects took the paint.
pub(crate) fn apply_paint(s: &mut Session, p: &Value, paint: Paint, fill: bool) -> Result<Value> {
let cmd = if fill { "paint.setFill" } else { "paint.setStroke" };
let bucket = bucket_color_params(s, p);
let bucket = bucket_color_params(s, p, cmd)?;
let p = bucket.as_ref().unwrap_or(p);
let focus = switch_or(p, "focus", true, cmd)?;
let span = spans_targets(p, &paint).map_err(|e| bad(cmd, e))?;
@@ -700,16 +700,21 @@ pub(crate) fn apply_paint(s: &mut Session, p: &Value, paint: Paint, fill: bool)
/// stroke or stroke weight chosen then is what the bucket paints with, so it goes to the defaults
/// and the selection keeps its paint.
pub(crate) fn for_bucket(s: &Session, p: &Value) -> bool {
s.tool_id() == LIVE_PAINT_BUCKET && ["ids", "id", "item"].iter().all(|k| p.get(k).is_none())
// A null `ids` or `id` is no target, as `given_nodes` reads it; `item: null` names the top row.
s.tool_id() == LIVE_PAINT_BUCKET && ["ids", "id"].iter().all(|k| p.get(k).is_none_or(Value::is_null)) && p.get("item").is_none()
}
/// `p` with `ids: []` when [`for_bucket`]: the paint goes to the defaults only. None otherwise.
pub(crate) fn bucket_color_params(s: &Session, p: &Value) -> Option<Value> {
for_bucket(s, p).then(|| {
let mut v = p.as_object().cloned().unwrap_or_default();
v.insert("ids".into(), json!([]));
Value::Object(v)
})
/// A bad `target` or `aligned` is refused first, as it is without the bucket.
pub(crate) fn bucket_color_params(s: &Session, p: &Value, cmd: &str) -> Result<Option<Value>> {
if !for_bucket(s, p) {
return Ok(None);
}
super::appearance::aligned(p, cmd)?;
super::appearance::targets_contents(p)?;
let mut v = p.as_object().cloned().unwrap_or_default();
v.insert("ids".into(), json!([]));
Ok(Some(Value::Object(v)))
}
/// The instance whose object is selected with Direct Selection, and that object's path
@@ -1017,7 +1022,7 @@ pub(super) fn restore_unpainted_stroke(ap: &mut Appearance, index: Option<usize>
}
fn swap(s: &mut Session, p: &Value) -> Result<Value> {
let bucket = bucket_color_params(s, p);
let bucket = bucket_color_params(s, p, "paint.swap")?;
let p = bucket.as_ref().unwrap_or(p);
let targets = paint_targets(s, p)?;
let given = !targets.is_empty();
@@ -1060,7 +1065,7 @@ fn swap(s: &mut Session, p: &Value) -> Result<Value> {
}
fn default_paint(s: &mut Session, p: &Value) -> Result<Value> {
let bucket = bucket_color_params(s, p);
let bucket = bucket_color_params(s, p, "paint.default")?;
let p = bucket.as_ref().unwrap_or(p);
let targets = paint_targets(s, p)?;
let given = !targets.is_empty();
@@ -1112,7 +1117,7 @@ fn default_paint(s: &mut Session, p: &Value) -> Result<Value> {
/// default when there are none) and remember the first target's new paint. The Appearance panel's
/// active item of the proxy's kind is recoloured in each selected object's own stack instead.
fn proxy_recolor(s: &mut Session, p: &Value, cmd: &str, label: &str, f: &dyn Fn(Color) -> Color) -> Result<Value> {
let bucket = bucket_color_params(s, p);
let bucket = bucket_color_params(s, p, cmd)?;
let p = bucket.as_ref().unwrap_or(p);
let stroke = stroke_param(s, p, cmd)?;
// An object of a dynamic symbol instance's art selected with Direct Selection: the solid color
+5 -4
View File
@@ -235,7 +235,7 @@ fn stroke_set(s: &mut Session, p: &Value) -> Result<Value> {
let change = StrokeChange::parse(p, C)?;
// The stroke the Live Paint Bucket paints with changes; the selection keeps its own, and its
// active Appearance row is not a target.
let bucket_p = super::paint::bucket_color_params(s, p);
let bucket_p = super::paint::bucket_color_params(s, p, C)?;
let bucket = bucket_p.is_some();
let p = bucket_p.as_ref().unwrap_or(p);
let item = item_target(s, p, C)?.of_kind(s, false);
@@ -382,9 +382,10 @@ pub(crate) fn step_weight(w: f64, unit: Unit, up: bool) -> f64 {
fn stroke_step(s: &mut Session, p: &Value, up: bool) -> Result<Value> {
let c = if up { "stroke.weightUp" } else { "stroke.weightDown" };
let unit = s.stroke_unit();
let item = item_target(s, p, c)?.of_kind(s, false);
// The weight the Live Paint Bucket paints with changes; the selection keeps its own.
// The weight the Live Paint Bucket paints with changes; the selection keeps its own, and its
// active Appearance row is not a target.
let bucket = super::paint::for_bucket(s, p);
let item = if bucket { ItemTarget::Top } else { item_target(s, p, c)?.of_kind(s, false) };
let ids = if bucket { vec![] } else { item.targets(s, p)? };
if bucket || no_targets(&ids, p) {
let w = step_weight(s.paint.stroke_width, unit, up);
@@ -587,7 +588,7 @@ fn stroke_advanced(s: &mut Session, p: &Value) -> Result<Value> {
}
// As stroke.set: the stroke the Live Paint Bucket paints with changes; the selection keeps its own.
// A brush still goes to the selection.
let bucket_p = if brush.is_none() { super::paint::bucket_color_params(s, p) } else { None };
let bucket_p = if brush.is_none() { super::paint::bucket_color_params(s, p, C)? } else { None };
let bucket = bucket_p.is_some();
let p = bucket_p.as_ref().unwrap_or(p);
let item = item_target(s, p, C)?.of_kind(s, false);
+29 -1
View File
@@ -3273,7 +3273,16 @@ fn live_paint_bucket_paint_and_stroke_commands_leave_the_selection_unpainted() {
move |s: &Session| s.paint.fill == cyan
}),
),
("paint.sampleColor", json!({"color": "#00ffff", "stroke": false}), Box::new(move |s: &Session| s.paint.fill == cyan)),
(
"paint.sampleColor",
json!({"color": "#00ffff", "stroke": false}),
Box::new({
let cyan = cyan.clone();
move |s: &Session| s.paint.fill == cyan
}),
),
// A null `ids` or `id` names no object, as it does for every other command.
("paint.setFill", json!({"color": "#00ffff", "ids": null, "id": null}), Box::new(move |s: &Session| s.paint.fill == cyan)),
("paint.editGradient", json!({"stroke": false, "angle": 45}), Box::new(move |s: &Session| is_gradient(&s.paint.fill))),
(
"paint.editGradient",
@@ -3382,6 +3391,25 @@ fn live_paint_bucket_and_the_selection_keep_their_own_selected_stop() {
assert_eq!(s.selected_stop(), None, "the bucket's stop is not the selection's");
}
/// While the Live Paint Bucket is active, a paint command with a bad `target` or `aligned` is
/// refused, as it is with any other tool, and the bucket's color stays.
#[test]
fn live_paint_bucket_refuses_a_bad_target() {
let mut s = session();
let g = live(&mut s);
s.execute("select.set", &json!({"ids": [g.0]})).unwrap();
s.select_tool("livePaintBucket", ViewInfo::default()).unwrap();
let fill = s.paint.fill.clone();
for (cmd, p) in [
("paint.setFill", json!({"color": "#00ffff", "target": "bogus"})),
("paint.invert", json!({"ids": null, "aligned": "bad"})),
("paint.complement", json!({"aligned": "bad"})),
] {
assert!(s.execute(cmd, &p).is_err(), "{cmd} {p}");
assert_eq!(s.paint.fill, fill, "{cmd} {p}");
}
}
/// While the Live Paint Bucket is active, each preview of a paint command in one interaction starts
/// from the colors the interaction began with, so previewing a swap twice and committing swaps once.
#[test]
+5 -3
View File
@@ -3811,7 +3811,8 @@ already walks Image Trace. Short agent entry points:
moving and transforming, `path.moveAnchors`, `file.place` with `replace`, Puppet Warp, Delete
and Cut, Group, Hide, Lock, Arrange, Expand,
Recolor Artwork, plug-in filters, effects, the gradient commands, `gradient.selectStop`, the Appearance panel's rows and
`symbol.instance.setAppearance`. A Cmd-drag that lends the Selection or Group Selection tool selects the instance whole
`symbol.instance.setAppearance`. While the Live Paint Bucket is the active tool, `paint.editGradient` without `ids`,
`id` or `item` changes the bucket's gradient instead, and `gradient.selectStop` selects a stop of it. A Cmd-drag that lends the Selection or Group Selection tool selects the instance whole
first and moves it. `swatch.unused` and `recolor.colors` count the fills and strokes an instance keeps for objects of its
art. Commands that change nothing in the document, such as `attributes.info`, `css.selection`, `css.export`,
`effect.list` and `object.expand.info`, read the instance. These commands do not check for a selected object and use the instance:
@@ -4587,11 +4588,12 @@ already walks Image Trace. Short agent entry points:
`paint.invert`, `paint.complement`, `paint.sampleColor`, `gradient.presets.apply`, a swatch or the Color Picker), and
`paint.swap` or `paint.default` without `ids` or `id`, becomes the color the bucket paints with, and a stroke weight
(`stroke.set`, `stroke.weightUp`, `stroke.weightDown`) becomes the weight it paints with. The selection keeps its
paint, and no undo step is recorded. The Stroke panel's other options (`stroke.set`, `stroke.setAdvanced` without
paint, and no undo step is recorded. A null `ids` or `id` counts as left out. The Stroke panel's other options (`stroke.set`, `stroke.setAdvanced` without
`brush`) change the stroke for new art and leave the selection as it is; the bucket takes only the color and weight
of that stroke. The Fill and Stroke proxies (`paint.proxies`) show those colors, never mixed, the Stroke panel shows
that stroke as it does with nothing selected, and with New Art Has Basic Appearance off the selection's appearance
does not replace them after a command. They are also the fill and stroke for new art.
does not replace them after a command. They are also the fill and stroke for new art, so another tool chosen
afterwards keeps them until a command or a new selection changes them.
With the Live Paint Bucket selected and no drag in progress, Left and Right without Shift, Alt or Cmd/Ctrl (which
keep their shortcuts) run `paint.setFill {swatch, ids: []}` (or
`paint.setStroke` when the Stroke proxy is in front) with the color swatch before or after the active paint in the