donner::svg::SVGDocument Class Reference

Represents a parsed SVG document containing a tree of SVGElement nodes. More...

#include "donner/svg/SVGDocument.h"

Classes
struct	Settings
	Document settings which configure the document behavior. More...

Public Types
using	SvgParseCallback
	Callback used to parse external SVG content referenced from within a document.

Public Member Functions
	SVGDocument ()
	Constructor to create an empty SVGDocument with default settings.
	SVGDocument (Settings settings)
	Constructor to create an empty SVGDocument.
Registry &	unsafeRegistry ()
	Get the underlying ECS Registry, which holds all data for the document.
const Registry &	unsafeRegistry () const
	Get the underlying ECS Registry, which holds all data for the document.
Registry &	registry ()
	Get the underlying ECS Registry, which holds all data for the document, for advanced use.
const Registry &	registry () const
	Get the underlying ECS Registry, which holds all data for the document, for advanced use.
SVGDocumentHandle	handle () const
	Get the internal shared document handle used by this value facade.
ThreadingMode	threadingMode () const
	Current DOM threading policy for this document.
void	setThreadingMode (ThreadingMode mode)
	Set the DOM threading policy for this document.
DocumentReadAccess	readAccess () const
	Acquire scoped read access to the underlying document state.
DocumentWriteAccess	writeAccess () const
	Acquire scoped write access to the underlying document state.
template<typename Callback>
decltype(auto)	withReadAccess (Callback &&callback) const
	Run a callback with scoped read access to this document.
template<typename Callback>
decltype(auto)	withWriteAccess (Callback &&callback) const
	Run a callback with scoped write access to this document.
bool	hasSourceStore () const
	Return true if the parsed SVG document has owned XML source text.
std::string_view	source () const
	Return the current XML source text owned by this parsed SVG document.
std::uint64_t	sourceVersion () const
	Return the current XML source version, or 0 for documents without source text.
xml::ApplySourceEditResult	applySourceEdit (const xml::XMLEditIntent &intent)
	Apply an incremental source edit through the underlying XML document and update the SVG semantic projection from emitted XML mutations.
xml::ApplySourceEditResult	setElementAttribute (const SVGElement &element, const xml::XMLQualifiedNameRef &name, std::string_view value)
	Set an element attribute and return any XML-owned source edit result.
xml::ApplySourceEditResult	removeElementAttribute (const SVGElement &element, const xml::XMLQualifiedNameRef &name)
	Remove an element attribute and return any XML-owned source edit result.
xml::ApplySourceEditResult	insertElement (const SVGElement &parent, const SVGElement &element, std::optional< SVGElement > referenceElement=std::nullopt)
	Insert an element into the document tree and return any XML-owned source edit result.
xml::ApplySourceEditResult	removeElement (const SVGElement &element)
	Remove an element from the document tree and return any XML-owned source edit result.
EntityHandle	rootEntityHandle () const
	Get the root ECS Entity of the document, for advanced use.
SVGSVGElement	svgElement () const
	Get the root "<svg>" element of the document.
void	setCanvasSize (int width, int height)
	Set the canvas (output image) size to a fixed width and height, in pixels.
void	useAutomaticCanvasSize ()
	Automatically determine the canvas size from the root <svg> element's width and height attributes.
Vector2i	canvasSize () const
	Get the current canvas size, or the default size (512x512) if the canvas size has not been explicitly set.
int	width () const
	Get the width of the SVG document, in pixels.
int	height () const
	Get the height of the SVG document, in pixels.
Transform2d	canvasFromDocumentTransform () const
	Returns the transform that maps points from the SVG document's viewBox coordinate space into the canvas-scaled output space.
bool	operator== (const SVGDocument &other) const
	Returns true if the two SVGDocument handles reference the same underlying document.
std::optional< SVGElement >	querySelector (std::string_view selector)
	Find the first element in the tree that matches the given CSS selector.

Static Public Member Functions
static SVGDocument	CreateFromHandle (SVGDocumentHandle handle)
	Rehydrate an SVGDocument facade from an internal shared document handle.

Friends
class	SVGElement
class	parser::SVGParserImpl

Detailed Description

Represents a parsed SVG document containing a tree of SVGElement nodes.

To create a document, parse SVG content with donner::svg::parser::SVGParser::ParseSVG, or construct an empty document and build the tree programmatically. Access the root <svg> element with svgElement(), find elements with querySelector(), and render with donner::svg::Renderer.

SVGDocument and SVGElement expose a familiar DOM API for traversal and manipulation (e.g., firstChild(), appendChild(), querySelector()). Elements are lightweight value types that can be copied and passed on the stack.

SVGDocument defaults to ThreadingMode::SingleThreaded. To access the DOM from multiple threads, opt into ThreadingMode::ConcurrentDom and use the DOM facade APIs or scoped access helpers. Direct ECS access through registry() and entityHandle() is only conditionally safe while the caller holds an explicit document access guard.

Note

Internally, data is stored using an Entity Component System (ECS) for cache-friendly access during rendering. The registry() and entityHandle() accessors expose this for advanced use cases, but most users can ignore the ECS layer entirely.

See also

SVGElement

---

Class Documentation

donner::svg::SVGDocument::Settings

struct donner::svg::SVGDocument::Settings

Document settings which configure the document behavior.

Collaboration diagram for donner::svg::SVGDocument::Settings:

Class Members
ProcessingMode	processingMode = ProcessingMode::DynamicInteractive	Processing mode for this document. Defaults to donner::svg::ProcessingMode::DynamicInteractive.
unique_ptr< ResourceLoaderInterface >	resourceLoader	Resource loader to use for loading external resources.
SvgParseCallback	svgParseCallback	Callback to parse SVG content into sub-documents.

Member Typedef Documentation

SvgParseCallback

using donner::svg::SVGDocument::SvgParseCallback

Initial value:

 std::function<std::optional<SVGDocumentHandle>(
      const std::vector<uint8_t>& svgContent, ParseWarningSink& warningSink)>

Callback used to parse external SVG content referenced from within a document.

Constructor & Destructor Documentation

SVGDocument()

donner::svg::SVGDocument::SVGDocument ( Settings settings )

explicit

Constructor to create an empty SVGDocument.

To load a document from an SVG file, use donner::svg::parser::SVGParser::ParseSVG.

Parameters

settings

Settings to configure the document.

Member Function Documentation

applySourceEdit()

xml::ApplySourceEditResult donner::svg::SVGDocument::applySourceEdit

(

const xml::XMLEditIntent &

intent

)

Apply an incremental source edit through the underlying XML document and update the SVG semantic projection from emitted XML mutations.

Parameters

intent

Source edit request.

canvasFromDocumentTransform()

Transform2d donner::svg::SVGDocument::canvasFromDocumentTransform

(

)

const

Returns the transform that maps points from the SVG document's viewBox coordinate space into the canvas-scaled output space.

This bakes in the preserveAspectRatio fit (letterbox offset + uniform scale) between the viewBox and the current canvas size.

Naming: per the destFromSource convention, applying this transform to a viewBox-space point yields a canvas-space point — i.e. it is canvasFromDocument, despite an earlier misnomer. Callers that need the opposite direction (canvas pixel → document viewBox coordinate, e.g. click math in editors/viewers) should invert it.

CreateFromHandle()

SVGDocument donner::svg::SVGDocument::CreateFromHandle ( SVGDocumentHandle handle )

inlinestatic

Rehydrate an SVGDocument facade from an internal shared document handle.

Parameters

handle

Shared document-state handle to wrap.

Returns

A new SVGDocument facade referencing the same underlying document state.

handle()

SVGDocumentHandle donner::svg::SVGDocument::handle ( ) const

inline

Get the internal shared document handle used by this value facade.

Returns

Shared document-state handle backing this SVGDocument.

height()

int donner::svg::SVGDocument::height ( ) const

inline

Get the height of the SVG document, in pixels.

This is the height of the canvas, which may be different from the height of the SVG content.

insertElement()

xml::ApplySourceEditResult donner::svg::SVGDocument::insertElement	(	const SVGElement &	parent,
		const SVGElement &	element,
		std::optional< SVGElement >	referenceElement = std::nullopt )

Insert an element into the document tree and return any XML-owned source edit result.

Parameters

parent	Element that receives element as a child.
element	Element to insert.
referenceElement	Optional existing child to insert before.

querySelector()

std::optional< SVGElement > donner::svg::SVGDocument::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 whole scan in withReadAccess so nested reads reuse the same document access.

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

Complex selectors are supported:

auto element = document.querySelector("svg > g:nth-child(2) > rect");

Parameters

selector

CSS selector to match.

Returns

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

removeElement()

xml::ApplySourceEditResult donner::svg::SVGDocument::removeElement

(

const SVGElement &

element

)

Remove an element from the document tree and return any XML-owned source edit result.

Parameters

element

Element to remove.

removeElementAttribute()

xml::ApplySourceEditResult donner::svg::SVGDocument::removeElementAttribute	(	const SVGElement &	element,
		const xml::XMLQualifiedNameRef &	name )

Remove an element attribute and return any XML-owned source edit result.

Parameters

element	Element whose attribute should be removed.
name	Attribute name to remove.

setCanvasSize()

void donner::svg::SVGDocument::setCanvasSize	(	int	width,
		int	height )

Set the canvas (output image) size to a fixed width and height, in pixels.

This controls the rendered output dimensions and may differ from the SVG's viewBox. If not set, defaults to 512x512 or the size specified by the root <svg> element's width/height attributes (when using useAutomaticCanvasSize()).

Parameters

width	Width of the canvas, in pixels.
height	Height of the canvas, in pixels.

setElementAttribute()

xml::ApplySourceEditResult donner::svg::SVGDocument::setElementAttribute	(	const SVGElement &	element,
		const xml::XMLQualifiedNameRef &	name,
		std::string_view	value )

Set an element attribute and return any XML-owned source edit result.

Source-backed documents mutate through the underlying XML document, then project emitted XML mutations back into SVG semantics. Programmatic documents without source text still mutate the SVG element and return an unapplied result.

Parameters

element	Element whose attribute should be set.
name	Attribute name to set.
value	Raw unescaped attribute value.

setThreadingMode()

void donner::svg::SVGDocument::setThreadingMode ( ThreadingMode mode )

inline

Set the DOM threading policy for this document.

Parameters

mode	New threading mode.

source()

std::string_view donner::svg::SVGDocument::source

(

)

const

Return the current XML source text owned by this parsed SVG document.

Programmatically-created documents may not have source text; in that case this returns an empty view.

unsafeRegistry() [1/2]

Registry & donner::svg::SVGDocument::unsafeRegistry ( )

inline

Get the underlying ECS Registry, which holds all data for the document.

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

unsafeRegistry() [2/2]

const Registry & donner::svg::SVGDocument::unsafeRegistry ( ) const

inline

Get the underlying ECS Registry, which holds all data for the document.

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

useAutomaticCanvasSize()

void donner::svg::SVGDocument::useAutomaticCanvasSize

(

)

Automatically determine the canvas size from the root <svg> element's width and height attributes.

If those attributes are not set, falls back to the default size (512x512).

width()

int donner::svg::SVGDocument::width ( ) const

inline

Get the width of the SVG document, in pixels.

This is the width of the canvas, which may be different from the width of the SVG content.

withReadAccess()

template<typename Callback>

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

inline

Run a callback with scoped read access to this document.

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

Parameters

callback

Callable invoked as callback(DocumentReadAccess&).

withWriteAccess()

template<typename Callback>

decltype(auto) donner::svg::SVGDocument::withWriteAccess

(

Callback &&

callback

)

const

Run a callback with scoped write access to this document.

Nested DOM setters called by the callback reuse this write access and coalesce their mutation revision bumps into one revision increment for the whole callback. Callbacks can accept either DocumentWriteAccess for raw ECS work or SVGDocumentMutation for typed DOM mutation helpers.

Parameters

callback

Callable invoked as callback(DocumentWriteAccess&) or callback(SVGDocumentMutation&).

---

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

• donner/svg/SVGDocument.h