Value dragging and undo

Structure continuous dragging as begin, preview, commit, or cancel, and understand how it relates to Blender undo.

A continuous drag is one complete operation

Users expect preview while dragging, commit on release, and restoration on cancellation. This differs from a normal action per pixel. Supported properties are location, rotation_euler, and scale, not a general undo system for all Blender properties.

Existing add-ons should reuse their operations/undo logic. For these transform capabilities, read Transform API guide; do not apply them to materials, file writes, or arbitrary actions.

Prepare real targets and values

Read the target identifier from the current scene state and pass it unchanged to the transform API. Do not use display names or construct identifiers yourself.
Fix targets/properties at begin and capture initial three-axis values.
Position/scale use three values; rotation_euler uses radians. Convert displayed degrees explicitly at the boundary.
Report deleted/invalid targets or mode changes as failures, not success.

Organize begin, preview, and completion

Step	Handling
Begin	begin declares targets; drag can manage the pointer sequence.
Preview	update may submit only changed pairs. The SDK accumulates the latest values for each target/property pair; the final commit must still cover all targets.
Commit	Await commit and inspect write, preview, and undo fields.
Cancel	cancel requests cancellation. Route changes or control destruction must also end active operations.

drag supplies pointer handling and preview/commit/cancel/error callbacks. Choose one lifecycle owner; do not handle the same gesture twice.

A returned request still needs result checks

commit results include previewErrors, writeErrors, undoPushed, and optional error codes. A resolved Promise does not prove every write/undo step succeeded. Use this only inside an existing commit callback with its result.

Commit-result checking fragment

javascript

const hasErrors = result.previewErrors > 0 || result.writeErrors > 0 || Boolean(result.undoErrorCode);
output.textContent = hasErrors
  ? "变换或撤销发生错误，请查看错误信息并核对场景。"
  : result.undoPushed
    ? "变换已确认，可检查撤销结果。"
    : "操作已结束，本次没有新增撤销记录，请核对实际场景。";

output is an existing message element. No new undo record does not necessarily mean failure, but does not justify claiming undo is available. Check errors and the actual scene.

Prevent state refresh fighting gestures

Subscriptions may deliver snapshots during dragging. Use isSuppressed for the matching target/property to avoid overwriting previews with stale values. Reconcile after completion; local display values are not permanent scene truth.

Verify the complete process in a real scene

Release after dragging: object and displayed values agree.
Esc: expected values restore and the control leaves dragging state.
Undo/redo after commit: scene and subscribed display agree; inspect real records.
Closing or removing the target mid-drag ends interaction with a reason.

The website demonstrates the interaction; verify undo behavior in Blender.

Based on public transform types and scene examples.

Back to User guide · All topics