AttributeWriteback.h File Reference

Builds a TextPatch that updates an SVG element's attribute in the source text. This is the bridge between a canvas tool mutation (e.g. a drag that changes transform) and the source pane. More...

#include <optional>
#include <string_view>
#include <vector>
#include "donner/base/xml/XMLQualifiedName.h"
#include "donner/editor/TextPatch.h"
#include "donner/svg/SVGElement.h"

Include dependency graph for AttributeWriteback.h:

This graph shows which files directly or indirectly include this file:

Classes
struct	donner::editor::AttributeWritebackPathSegment
	Stable element locator for canvas→text writeback and selection remap. More...
struct	donner::editor::AttributeWritebackTarget
	Path to an element through element children only, from the SVG root down. More...

Namespaces
namespace	donner
	Top-level Donner namespace, which is split into different sub-namespaces such as donner::svg and donner::css.

Functions
std::optional< AttributeWritebackTarget >	donner::editor::captureAttributeWritebackTarget (const svg::SVGElement &element)
	Capture a stable path to an element that can be resolved against a later version of the source text or a re-parsed document.
std::optional< svg::SVGElement >	donner::editor::resolveAttributeWritebackTarget (svg::SVGDocument &document, const AttributeWritebackTarget &target)
	Resolve a previously-captured writeback target in the current SVG document.
std::optional< TextPatch >	donner::editor::buildAttributeWriteback (std::string_view source, const svg::SVGElement &element, std::string_view attrName, std::string_view newValue)
	Build a TextPatch that sets the given attribute to the new value in the source text.
std::optional< TextPatch >	donner::editor::buildAttributeWriteback (std::string_view source, const AttributeWritebackTarget &target, std::string_view attrName, std::string_view newValue)
	Build a TextPatch that sets the given attribute using a stable target captured from an earlier frame.
std::optional< TextPatch >	donner::editor::buildAttributeRemoveWriteback (std::string_view source, const AttributeWritebackTarget &target, std::string_view attrName)
	Build a TextPatch that removes the given attribute from the target element in the source text.
std::optional< TextPatch >	donner::editor::buildElementRemoveWriteback (std::string_view source, const AttributeWritebackTarget &target)
	Build a TextPatch that removes the target element from the source text.

Detailed Description

Builds a TextPatch that updates an SVG element's attribute in the source text. This is the bridge between a canvas tool mutation (e.g. a drag that changes transform) and the source pane.

The writeback path first tries the element's tracked source start offset. If that no longer points at the same opening tag in the current source, it re-finds the element via its XML tree path, then locates the attribute's byte span and returns a TextPatch splice. If the attribute doesn't exist in the source yet, the patch inserts name="value" before the element's closing >.

See docs/design_docs/structured_text_editing.md M3.

Function Documentation

buildAttributeRemoveWriteback()

std::optional< TextPatch > donner::editor::buildAttributeRemoveWriteback	(	std::string_view	source,
		const AttributeWritebackTarget &	target,
		std::string_view	attrName )

Build a TextPatch that removes the given attribute from the target element in the source text.

Parameters

source	The current source text (from the text editor buffer).
target	Stable locator for the target element.
attrName	The attribute name to remove (e.g. "transform").

Returns

A TextPatch deleting the attribute if it exists, std::nullopt if the source no longer contains the targeted element, the attribute is already absent, or the source cannot be patched safely.

buildAttributeWriteback() [1/2]

std::optional< TextPatch > donner::editor::buildAttributeWriteback	(	std::string_view	source,
		const AttributeWritebackTarget &	target,
		std::string_view	attrName,
		std::string_view	newValue )

Build a TextPatch that sets the given attribute using a stable target captured from an earlier frame.

Parameters

source	The current source text (from the text editor buffer).
target	Stable locator for the target element.
attrName	The attribute name (e.g. "transform", "fill").
newValue	The new attribute value (unescaped — will be XML-escaped internally).

Returns

A TextPatch if the writeback can be performed, or std::nullopt if the source no longer contains the targeted element or cannot be patched safely.

buildAttributeWriteback() [2/2]

std::optional< TextPatch > donner::editor::buildAttributeWriteback	(	std::string_view	source,
		const svg::SVGElement &	element,
		std::string_view	attrName,
		std::string_view	newValue )

Build a TextPatch that sets the given attribute to the new value in the source text.

Parameters

source	The current source text (from the text editor buffer).
element	The target element.
attrName	The attribute name (e.g. "transform", "fill").
newValue	The new attribute value (unescaped — will be XML-escaped internally).

Returns

A TextPatch if the writeback can be performed, or std::nullopt if the element can't be resolved in the current source, the attribute value can't be escaped (contains NUL or surrogates), or the source text is too stale/malformed to patch safely.

buildElementRemoveWriteback()

std::optional< TextPatch > donner::editor::buildElementRemoveWriteback	(	std::string_view	source,
		const AttributeWritebackTarget &	target )

Build a TextPatch that removes the target element from the source text.

Parameters

source	The current source text (from the text editor buffer).
target	Stable locator for the target element.

Returns

A TextPatch deleting the full element span if it exists, or std::nullopt if the source no longer contains the targeted element or cannot be patched safely.

captureAttributeWritebackTarget()

std::optional< AttributeWritebackTarget > donner::editor::captureAttributeWritebackTarget

(

const svg::SVGElement &

element

)

Capture a stable path to an element that can be resolved against a later version of the source text or a re-parsed document.

Parameters

element

The element to snapshot.

Returns

A stable locator for the element, or std::nullopt if the element does not have an XML node backing it.

resolveAttributeWritebackTarget()

std::optional< svg::SVGElement > donner::editor::resolveAttributeWritebackTarget	(	svg::SVGDocument &	document,
		const AttributeWritebackTarget &	target )

Resolve a previously-captured writeback target in the current SVG document.

Parameters

document	The current document.
target	The target to resolve.

Returns

The matching element, or std::nullopt if the tree shape changed and the original path no longer exists.