Represents a single SVG element (e.g., <rect>, <circle>, <g>, <text>, etc.) within an SVGDocument. More...

#include "donner/svg/SVGElement.h"

Inheritance diagram for donner::svg::SVGElement:

Collaboration diagram for donner::svg::SVGElement:

Classes
class	ScopedMutation
	Scoped mutation helper that runs cleanup before committing the mutation revision. More...

Public Member Functions
	SVGElement (const SVGElement &other)
	Create another reference to the same SVGElement.
	SVGElement (SVGElement &&other) noexcept
	Move constructor.
	~SVGElement () noexcept
	Destructor.
SVGElement &	operator= (const SVGElement &other)
	Create another reference to the same SVGElement.
SVGElement &	operator= (SVGElement &&other) noexcept
	Move assignment operator.
ElementType	type () const
	Get the ElementType for known XML element types.
std::optional< ElementType >	tryType () const
	Get the ElementType if this handle still has SVG element identity.
xml::XMLQualifiedNameRef	tagName () const
	Get the XML tag name string for this element.
std::optional< xml::XMLQualifiedNameRef >	tryTagName () const
	Get the XML tag name if this handle still has XML tree identity.
bool	isKnownType () const
	Returns true if this is a known element type, returns false if this is an donner::svg::SVGUnknownElement.
EntityHandle	unsafeEntityHandle () const
	Get the underlying donner::EntityHandle.
EntityHandle	entityHandle () const
	Get the underlying donner::EntityHandle, for advanced use-cases that require direct access to the ECS.
template<typename Callback>
decltype(auto)	withReadAccess (Callback &&callback) const
	Run a callback with scoped read access to this element's document and resolved entity handle.
template<typename Callback>
decltype(auto)	withWriteAccess (Callback &&callback) const
	Run a callback with scoped write access to this element's document and resolved entity handle.
RcString	id () const
	Get the element id, the value of the "id" attribute.
void	setId (std::string_view id)
	Set the element id, the value of the "id" attribute.
RcString	className () const
	Get the element class name, the value of the "class" attribute.
void	setClassName (std::string_view name)
	Set the element class name, the value of the "class" attribute.
void	setStyle (std::string_view style)
	Set the element style, the value of the "style" attribute.
void	updateStyle (std::string_view style)
	Update the element style, adding new attributes or overridding existing ones (without removing them).
ParseResult< bool >	trySetPresentationAttribute (std::string_view name, std::string_view value)
	Set the value of a presentation attribute, such as "fill" or "stroke".
bool	hasAttribute (const xml::XMLQualifiedNameRef &name) const
	Returns true if the element has an attribute with the given name.
std::optional< RcString >	getAttribute (const xml::XMLQualifiedNameRef &name) const
	Get the value of an attribute, if it exists.
SmallVector< xml::XMLQualifiedNameRef, 1 >	findMatchingAttributes (const xml::XMLQualifiedNameRef &matcher) const
	Find attributes matching the given name matcher.
SmallVector< xml::XMLQualifiedNameRef, 10 >	attributes () const
	Get the list of attributes for this element.
void	setAttribute (const xml::XMLQualifiedNameRef &name, std::string_view value)
	Set the value of a generic XML attribute, which may be either a presentation attribute or custom user-provided attribute.
void	removeAttribute (const xml::XMLQualifiedNameRef &name)
	Remove an attribute, which may be either a presentation attribute or custom user-provided attribute.
SVGDocument	ownerDocument ()
	Get an owning reference to the SVGDocument containing this element.
std::optional< SVGElement >	parentElement () const
	Get this element's parent, if it exists.
std::optional< SVGElement >	firstChild () const
	Get the first child of this element, if it exists.
std::optional< SVGElement >	lastChild () const
	Get the last child of this element, if it exists.
std::optional< SVGElement >	previousSibling () const
	Get the previous sibling of this element, if it exists.
std::optional< SVGElement >	nextSibling () const
	Get the next sibling of this element, if it exists.
void	insertBefore (const SVGElement &newNode, std::optional< SVGElement > referenceNode)
	Insert `newNode` as a child, before `referenceNode`.
void	appendChild (const SVGElement &child)
	Append `child` as a child of the current node.
void	replaceChild (const SVGElement &newChild, const SVGElement &oldChild)
	Replace `oldChild` with `newChild` in the tree, removing `oldChild` and inserting `newChild` in its place.
void	removeChild (const SVGElement &child)
	Remove `child` from this node.
void	remove ()
	Remove this node from its parent, if it has one.
bool	operator== (const SVGElement &other) const
	Returns true if the two SVGElement handles reference the same underlying document.
bool	operator!= (const SVGElement &other) const
	Returns true if the two SVGElement handles reference the same underlying document.
template<typename Derived>
bool	isa () const
	Return true if this element "is a" instance of type, if it be cast to a specific type with cast.
template<typename Derived>
Derived	cast ()
	Cast this element to its derived type.
template<typename Derived>
Derived	cast () const
	Cast this element to its derived type (const version).
template<typename Derived>
std::optional< Derived >	tryCast ()
	Cast this element to its derived type, if possible.
template<typename Derived>
std::optional< const Derived >	tryCast () const
	Cast this element to its derived type, if possible.
std::optional< SVGElement >	querySelector (std::string_view selector)
	Find the first element in the tree that matches the given CSS selector.
const PropertyRegistry &	getComputedStyle () const
	Get the computed CSS style of this element, after the CSS cascade has been applied.

Protected Member Functions
	SVGElement (EntityHandle handle)
	Internal constructor to create an SVGElement from an donner::EntityHandle.
template<typename InvalidateCallback>
ScopedMutation< std::decay_t< InvalidateCallback > >	mutationScope (InvalidateCallback &&invalidateOnScopeExit) const
	Create a scoped mutation that runs `invalidateOnScopeExit` before the revision commit.
std::optional< ParseDiagnostic >	setAttributeFromXMLMutation (const xml::XMLQualifiedNameRef &name, std::string_view value)
	Set an attribute from an XML mutation and return any SVG semantic parse diagnostic.
void	removeAttributeFromXMLMutation (const xml::XMLQualifiedNameRef &name)
	Remove an attribute from an XML mutation without writing back to XML source.
Registry &	unsafeRegistry () const
	Get the underlying ECS Registry, which holds all data for the document, for advanced use.
Registry &	registry () const
	Get the underlying ECS Registry, which holds all data for the document, for advanced use.
EntityHandle	toHandle (Entity entity) const
	Convert an Entity to an EntityHandle, for advanced use.

Static Protected Member Functions
static DocumentWriteAccess	CreateElementWriteAccess (SVGDocument &document)
	Acquire write access for creating an element in a document.
static DocumentMutationBatch	CreateElementMutationBatch (SVGDocument &document)
	Acquire a mutation scope for creating an element in a document.
static EntityHandle	CreateEmptyEntity (SVGDocument &document)
	Create a new Entity within the document ECS, and return a handle to it.
static EntityHandle	CreateEmptyEntity (DocumentWriteAccess &access)
	Create a new Entity within a guarded document ECS, and return a handle to it.
static void	CreateEntityOn (EntityHandle handle, const xml::XMLQualifiedNameRef &tagName, ElementType Type)
	Create a new SVG element instance on a given donner::Entity.

Protected Attributes
ElementAnchor	handle_
	The lifetime-aware ECS entity anchor for this element.

Friends
class	parser::AttributeParser
class	DonnerController
class	SVGDocument

Detailed Description

Represents a single SVG element (e.g., <rect>, <circle>, <g>, <text>, etc.) within an SVGDocument.

SVGElement provides a DOM-like API for traversing the document tree (parentElement(), firstChild(), nextSibling()), querying and setting attributes (getAttribute(), setAttribute()), and modifying the tree structure (appendChild(), removeChild()).

Elements are lightweight value types — copying an SVGElement creates another handle to the same underlying element, not a deep copy. Use isa<Derived>() and cast<Derived>() to work with element-specific APIs (e.g., SVGCircleElement, SVGPathElement).

For advanced queries like hit-testing, see DonnerController.

See also: SVGDocument

Constructor & Destructor Documentation

◆ SVGElement()

donner::svg::SVGElement::SVGElement ( EntityHandle handle )

explicitprotected

Internal constructor to create an SVGElement from an donner::EntityHandle.

To create an SVGElement, use the static Create methods on the derived class, such as donner::svg::SVGCircleElement::Create.

Parameters

handle EntityHandle to wrap.

Member Function Documentation

◆ appendChild()

void donner::svg::SVGElement::appendChild ( const SVGElement & child )

Append child as a child of the current node.

If child is already in the tree, it is first removed from its parent before reinsertion.

Precondition: child must not be an ancestor of this element (would create a cycle).

Parameters

child Node to append.

◆ attributes()

SmallVector< xml::XMLQualifiedNameRef, 10 > donner::svg::SVGElement::attributes ( ) const

Get the list of attributes for this element.

Returns: The qualified names of attributes present on this element.

◆ cast() [1/2]

template<typename Derived>

Derived donner::svg::SVGElement::cast ( )

inline

Cast this element to its derived type.

Precondition: Requires this element to be of type Derived::Type.

Returns: A reference to this element, cast to the derived type.

◆ cast() [2/2]

template<typename Derived>

Derived donner::svg::SVGElement::cast ( ) const

inline

Cast this element to its derived type (const version).

Precondition: Requires this element to be of type Derived::Type.

Returns: A reference to this element, cast to the derived type.

◆ CreateElementMutationBatch()

DocumentMutationBatch donner::svg::SVGElement::CreateElementMutationBatch ( SVGDocument & document )

staticprotected

Acquire a mutation scope for creating an element in a document.

Parameters

document Containing document.

◆ CreateElementWriteAccess()

DocumentWriteAccess donner::svg::SVGElement::CreateElementWriteAccess ( SVGDocument & document )

staticprotected

Acquire write access for creating an element in a document.

Parameters

document Containing document.

◆ CreateEmptyEntity() [1/2]

EntityHandle donner::svg::SVGElement::CreateEmptyEntity ( DocumentWriteAccess & access )

staticprotected

Create a new Entity within a guarded document ECS, and return a handle to it.

Parameters

access Active write access for the containing document.

◆ CreateEmptyEntity() [2/2]

EntityHandle donner::svg::SVGElement::CreateEmptyEntity ( SVGDocument & document )

staticprotected

Create a new Entity within the document ECS, and return a handle to it.

Parameters

document Containing document.

◆ CreateEntityOn()

void donner::svg::SVGElement::CreateEntityOn	(	EntityHandle	handle,
		const xml::XMLQualifiedNameRef &	tagName,
		ElementType	Type )

staticprotected

Create a new SVG element instance on a given donner::Entity.

Parameters

handle	Entity to create the element on.
tagName	XML element type, e.g. "svg" or "rect", which an optional namespace.
Type	Type of the entity.

◆ findMatchingAttributes()

SmallVector< xml::XMLQualifiedNameRef, 1 > donner::svg::SVGElement::findMatchingAttributes ( const xml::XMLQualifiedNameRef & matcher ) const

Find attributes matching the given name matcher.

Parameters

matcher Matcher to use to find attributes. If donner::xml::XMLQualifiedNameRef::namespacePrefix is *, the matcher will match any namespace with the given attribute name.

Returns: A vector of attributes matching the given name matcher.

◆ firstChild()

std::optional< SVGElement > donner::svg::SVGElement::firstChild ( ) const

Get the first child of this element, if it exists.

Returns: The first child element, or std::nullopt if the element has no children.

◆ getAttribute()

std::optional< RcString > donner::svg::SVGElement::getAttribute ( const xml::XMLQualifiedNameRef & name ) const

Get the value of an attribute, if it exists.

Parameters

name	Name of the attribute to get.

Returns: The value of the attribute, or std::nullopt if the attribute does not exist.

◆ getComputedStyle()

const PropertyRegistry & donner::svg::SVGElement::getComputedStyle ( ) const

Get the computed CSS style of this element, after the CSS cascade has been applied.

The returned donner::svg::PropertyRegistry contains resolved values for all CSS properties (fill, stroke, font-size, etc.).

◆ hasAttribute()

bool donner::svg::SVGElement::hasAttribute ( const xml::XMLQualifiedNameRef & name ) const

Returns true if the element has an attribute with the given name.

Parameters

name	Name of the attribute to check.

Returns: true if the attribute exists, false otherwise.

◆ insertBefore()

void donner::svg::SVGElement::insertBefore	(	const SVGElement &	newNode,
		std::optional< SVGElement >	referenceNode )

Insert newNode as a child, before referenceNode.

If referenceNode is std::nullopt, append the child.

If newNode is already in the tree, it is first removed from its parent before reinsertion.

Precondition: newNode must not be an ancestor of this element (inserting a parent as a child of its descendant would create a cycle, which is undefined behavior).

Parameters

newNode	New node to insert.
referenceNode	A child of this node to insert `newNode` before, or `std::nullopt`. Must be a child of the current node.

◆ isa()

template<typename Derived>

bool donner::svg::SVGElement::isa ( ) const

inline

Return true if this element "is a" instance of type, if it be cast to a specific type with cast.

Template Parameters

Derived Type to check.

◆ lastChild()

std::optional< SVGElement > donner::svg::SVGElement::lastChild ( ) const

Get the last child of this element, if it exists.

Returns: The last child element, or std::nullopt if the element has no children.

◆ mutationScope()

template<typename InvalidateCallback>

ScopedMutation< std::decay_t< InvalidateCallback > > donner::svg::SVGElement::mutationScope ( InvalidateCallback && invalidateOnScopeExit ) const

inlineprotected

Create a scoped mutation that runs invalidateOnScopeExit before the revision commit.

Parameters

invalidateOnScopeExit Callable invoked while write access is still held.

◆ nextSibling()

std::optional< SVGElement > donner::svg::SVGElement::nextSibling ( ) const

Get the next sibling of this element, if it exists.

For tight traversal loops in ThreadingMode::ConcurrentDom, wrap the loop in withReadAccess so each step can reuse the same read access.

Returns: The next sibling element, or std::nullopt if the element has no next sibling.

◆ parentElement()

std::optional< SVGElement > donner::svg::SVGElement::parentElement ( ) const

Get this element's parent, if it exists.

Returns: The parent element, or std::nullopt if this is the root element or the element has not been inserted into a document tree.

◆ previousSibling()

std::optional< SVGElement > donner::svg::SVGElement::previousSibling ( ) const

Get the previous sibling of this element, if it exists.

Returns: The previous sibling element, or std::nullopt if the element has no previous sibling.

◆ querySelector()

std::optional< SVGElement > donner::svg::SVGElement::querySelector ( std::string_view selector )

Find the first element in the tree that matches the given CSS selector.

This method performs its own scoped read. For repeated DOM reads in ThreadingMode::ConcurrentDom, wrap the surrounding scan in withReadAccess so nested reads reuse the same document access.

auto element = document.svgElement().querySelector("#elementId");

To find things relative to the current element, use :scope:

auto rectInElement = element.querySelector(":scope > rect");

Parameters

selector CSS selector to match. If the selector string is invalid, returns std::nullopt (no error is reported).

Returns: The first matching element, or std::nullopt if no element matches.

◆ remove()

void donner::svg::SVGElement::remove ( )

Remove this node from its parent, if it has one.

Has no effect if this has no parent.

◆ removeAttribute()

void donner::svg::SVGElement::removeAttribute ( const xml::XMLQualifiedNameRef & name )

Remove an attribute, which may be either a presentation attribute or custom user-provided attribute.

If this is a presentation attribute, the presentation attributes value will be removed (internally by setting the value to 'inherit').

Parameters

name	Name of the attribute to remove.

◆ removeAttributeFromXMLMutation()

void donner::svg::SVGElement::removeAttributeFromXMLMutation ( const xml::XMLQualifiedNameRef & name )

protected

Remove an attribute from an XML mutation without writing back to XML source.

Parameters

name	Name of the attribute to remove.

◆ removeChild()

void donner::svg::SVGElement::removeChild ( const SVGElement & child )

Remove child from this node.

Parameters

child Child to remove, must be a child of the current node.

◆ replaceChild()

void donner::svg::SVGElement::replaceChild	(	const SVGElement &	newChild,
		const SVGElement &	oldChild )

Replace oldChild with newChild in the tree, removing oldChild and inserting newChild in its place.

If newChild is already in the tree, it is first removed from its parent before reinsertion.

Precondition: newChild must not be an ancestor of this element (would create a cycle).

Parameters

newChild	New child to insert.
oldChild	Old child to remove, must be a child of the current node.

◆ setAttribute()

void donner::svg::SVGElement::setAttribute	(	const xml::XMLQualifiedNameRef &	name,
		std::string_view	value )

Set the value of a generic XML attribute, which may be either a presentation attribute or custom user-provided attribute.

This API supports a superset of trySetPresentationAttribute, however its parse errors are ignored. If the attribute is not a presentation attribute, or there are parse errors the attribute will be stored as a custom attribute instead.

Parameters

name	Name of the attribute to set.
value	New value to set.

◆ setAttributeFromXMLMutation()

std::optional< ParseDiagnostic > donner::svg::SVGElement::setAttributeFromXMLMutation	(	const xml::XMLQualifiedNameRef &	name,
		std::string_view	value )

protected

Set an attribute from an XML mutation and return any SVG semantic parse diagnostic.

Invalid presentation-attribute values are still stored in the XML attribute projection, but leave the previous valid SVG semantic component in place.

Parameters

name	Name of the attribute to set.
value	New value to set.

◆ setClassName()

void donner::svg::SVGElement::setClassName ( std::string_view name )

Set the element class name, the value of the "class" attribute.

Parameters

name	New class name to set.

◆ setId()

void donner::svg::SVGElement::setId ( std::string_view id )

Set the element id, the value of the "id" attribute.

Parameters

id	New id to set.

◆ setStyle()

void donner::svg::SVGElement::setStyle ( std::string_view style )

Set the element style, the value of the "style" attribute.

Parameters

style New style to set.

◆ toHandle()

EntityHandle donner::svg::SVGElement::toHandle ( Entity entity ) const

inlineprotected

Convert an Entity to an EntityHandle, for advanced use.

Parameters

entity Entity to convert.

◆ tryCast() [1/2]

template<typename Derived>

std::optional< Derived > donner::svg::SVGElement::tryCast ( )

inline

Cast this element to its derived type, if possible.

Return std::nullopt otherwise.

Returns: A reference to this element, cast to the derived type, or std::nullopt if the element is not of the correct type.

◆ tryCast() [2/2]

template<typename Derived>

std::optional< const Derived > donner::svg::SVGElement::tryCast ( ) const

inline

Cast this element to its derived type, if possible.

Return std::nullopt otherwise (const version).

Returns: A reference to this element, cast to the derived type, or std::nullopt if the element is not of the correct type.

◆ trySetPresentationAttribute()

ParseResult< bool > donner::svg::SVGElement::trySetPresentationAttribute	(	std::string_view	name,
		std::string_view	value )

Set the value of a presentation attribute, such as "fill" or "stroke".

Note that this accepts the CSS value, not the XML attribute value.

For example, for the following XML attributes they need to be mapped as follows before calling:

gradientTransform -> transform
patternTransform -> transform

Parameters

name	Name of the attribute to set.
value	New value to set.

Returns: true if the attribute was set, false if the attribute is not a valid presentation attribute for this element, or a ParseDiagnostic if the value is invalid.

◆ unsafeEntityHandle()

EntityHandle donner::svg::SVGElement::unsafeEntityHandle ( ) const

inline

Get the underlying donner::EntityHandle.

This is an unsafe advanced escape hatch. In ThreadingMode::ConcurrentDom, callers must hold an explicit document access guard while reading or mutating the returned handle.

◆ updateStyle()

void donner::svg::SVGElement::updateStyle ( std::string_view style )

Update the element style, adding new attributes or overridding existing ones (without removing them).

Parameters

style Style updates to apply, as a CSS style string (e.g. "fill:red;").

◆ withReadAccess()

template<typename Callback>

decltype(auto) donner::svg::SVGElement::withReadAccess ( Callback && callback ) const

inline

Run a callback with scoped read access to this element's document and resolved entity handle.

In ThreadingMode::ConcurrentDom, use this to batch repeated reads such as sibling traversal or descendant scans under one document read lock.

Parameters

callback Callable invoked as callback(DocumentReadAccess&, EntityHandle).

◆ withWriteAccess()

template<typename Callback>

decltype(auto) donner::svg::SVGElement::withWriteAccess ( Callback && callback ) const

inline

Run a callback with scoped write access to this element's document and resolved entity handle.

Nested DOM setters called by the callback reuse this write access and coalesce their mutation revision bumps. Raw ECS mutations made through the handle should call DocumentWriteAccess::bumpMutationRevision().

Parameters

callback Callable invoked as callback(DocumentWriteAccess&, EntityHandle).

The documentation for this class was generated from the following file:

donner/svg/SVGElement.h

Classes

Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ SVGElement()

Member Function Documentation

◆ appendChild()

◆ attributes()

◆ cast() [1/2]

◆ cast() [2/2]

◆ CreateElementMutationBatch()

◆ CreateElementWriteAccess()

◆ CreateEmptyEntity() [1/2]

◆ CreateEmptyEntity() [2/2]

◆ CreateEntityOn()

◆ findMatchingAttributes()

◆ firstChild()

◆ getAttribute()

◆ getComputedStyle()

◆ hasAttribute()

◆ insertBefore()

◆ isa()

◆ lastChild()

◆ mutationScope()

◆ nextSibling()

◆ parentElement()

◆ previousSibling()

◆ querySelector()

◆ remove()

◆ removeAttribute()

◆ removeAttributeFromXMLMutation()

◆ removeChild()

◆ replaceChild()

◆ setAttribute()

◆ setAttributeFromXMLMutation()

◆ setClassName()

◆ setId()

◆ setStyle()

◆ toHandle()

◆ tryCast() [1/2]

◆ tryCast() [2/2]

◆ trySetPresentationAttribute()

◆ unsafeEntityHandle()

◆ updateStyle()

◆ withReadAccess()

◆ withWriteAccess()