libkdegames

KGameSvgDocument Class Reference

#include <kgamesvgdocument.h>

Inheritance diagram for KGameSvgDocument:

[legend]

List of all members.

Detailed Description

A class for manipulating an SVG file using DOM.

This class is a wrapper around QDomDocument for SVG files. It:

implements elementById();
manipulates a node's style properties; and,
manipulates a node's transform properties.

Note:: The DOM standard requires all changes to be "live", so we cannot cache any values from the file; instead, we always have to query the DOM for the current value. This also means that style & matrix changes we make happen to the DOM immediately.

A typical use is to read in an SVG file, edit the style or transform attributes in DOM as desired, and then output a QByteArray suitable for being loaded with KSvgRenderer::load().

To read an SVG file into DOM:

 KGameSvgDocument svgDom;
 svgDom.load("/path/to/svgFile.svg");

To find a node with a specific value in its id attribute, for example where id="playerOneGamepiece":

 QDomNode playerOneGamepiece = svgDom.elementById("playerOneGamepiece");

 // This works too
 QDomNode playerOneGamepiece = svgDom.elementByUniqueAttributeValue("id", "playerOneGamepiece");

Most methods operate on the last node found by elementById() or elementByUniqueAttributeValue(). If the methods are working on the wrong node, then you are mistaken about which node was the last node (or you found a bug). Try calling setCurrentNode() with the node you are wanting to modify to see if this is the issue. Consider the following code for example:

 QDomNode playerOneGamepiece = svgDom.elementById("playerOneGamepiece");
 QDomNode playerTwoGamepiece = svgDom.elementById("playerTwoGamepiece");

 // Set player one's game piece to have a white fill
 svgDom.setStyleProperty("fill", "#ffffff");  // INCORRECT: playerTwoGamepiece is the last node, not playerOneGamepiece

 svgDom.setCurrentNode(playerOneGamepiece);   // CORRECT: Set current node to the node we want,
 svgDom.setStyleProperty("fill", "#ffffff");  // then we modify the node

To skew the currentNode():

 // Skew the horizontal axis 7.5 degrees
 svgDom.skew(-7.5, 0, KGameSvgDocument::ReplaceCurrentMatrix);

Warning:: Be careful when using the KGameSvgDocument::ApplyToCurrentMatrix flag. It multiplies the matrices, so if you repeatedly apply the same matrix to a node, you have a polynomial series x^2, and you will very quickly run into overflow issues.

To output currentNode() to be rendered:

 KSvgRenderer svgRenderer;
 QByteArray svg = svgDom.nodeToByteArray();
 svgRenderer.load(svg);

To output the whole document to be rendered (See QDomDocument::toByteArray()):

 KSvgRenderer svgRenderer;
 QByteArray svg = svgDom.toByteArray();
 svgRenderer.load(svg);

See also:: QDomDocument, KSvgRenderer

Author:: Mark A. Taff <kde@marktaff.com>

Version:: 0.1

Todo:: Add convenience functions for getting/setting individual style properties. I haven't completely convinced myself of the utility of this, so don't hold your breathe. ;-)

Definition at line 113 of file kgamesvgdocument.h.


Public Types
enum	MatrixOption { ApplyToCurrentMatrix = 0x01, ReplaceCurrentMatrix = 0x02 }
enum	StylePropertySortOption { Unsorted = 0x01, UseInkscapeOrder = 0x02 }
typedef QFlags< MatrixOption >	MatrixOptions
typedef QFlags < StylePropertySortOption >	StylePropertySortOptions
Public Member Functions
	KGameSvgDocument ()
	KGameSvgDocument (const KGameSvgDocument &doc)
virtual	~KGameSvgDocument ()
KGameSvgDocument &	operator= (const KGameSvgDocument &doc)
QDomNode	elementByUniqueAttributeValue (const QString &attributeName, const QString &attributeValue)
QDomNode	elementById (const QString &attributeValue)
void	load ()
void	load (const QString &svgFilename)
void	rotate (double degrees, const MatrixOptions &options=ApplyToCurrentMatrix)
void	translate (int xPixels, int yPixels, const MatrixOptions &options=ApplyToCurrentMatrix)
void	shear (double xRadians, double yRadians, const MatrixOptions &options=ApplyToCurrentMatrix)
void	skew (double xDegrees, double yDegrees, const MatrixOptions &options=ApplyToCurrentMatrix)
void	scale (double xFactor, double yFactor, const MatrixOptions &options=ApplyToCurrentMatrix)
QDomNode	currentNode () const
void	setCurrentNode (const QDomNode &node)
QString	svgFilename () const
void	setSvgFilename (const QString &svgFilename)
QString	styleProperty (const QString &propertyName) const
void	setStyleProperty (const QString &propertyName, const QString &propertyValue)
QString	nodeToSvg () const
QByteArray	nodeToByteArray () const
QString	style () const
void	setStyle (const QString &styleAttribute)
QDomNodeList	patterns () const
QDomNodeList	linearGradients () const
QDomNodeList	radialGradients () const
QDomNodeList	defs () const
QDomNode	def () const
QString	transform () const
void	setTransform (const QString &transformAttribute)
QHash< QString, QString >	styleProperties () const
void	setStyleProperties (const QHash< QString, QString > &_styleProperties, const StylePropertySortOptions &options=Unsorted)
QMatrix	transformMatrix () const
void	setTransformMatrix (QMatrix &matrix, const MatrixOptions &options=ApplyToCurrentMatrix)

Member Typedef Documentation

typedef QFlags<MatrixOption> KGameSvgDocument::MatrixOptions

Q_DECLARE_FLAGS macro confuses doxygen, so create typedef's manually.

Definition at line 150 of file kgamesvgdocument.h.

typedef QFlags<StylePropertySortOption> KGameSvgDocument::StylePropertySortOptions

Q_DECLARE_FLAGS macro confuses doxygen, so create typedef's manually.

Definition at line 166 of file kgamesvgdocument.h.

Member Enumeration Documentation

enum KGameSvgDocument::MatrixOption

Options for applying (multiplying) or replacing the current matrix.

Enumerator:

ApplyToCurrentMatrix	Apply to current matrix.
ReplaceCurrentMatrix	Replace the current matrix.

Definition at line 139 of file kgamesvgdocument.h.

enum KGameSvgDocument::StylePropertySortOption

Options for sorting style properties when building a style attribute.

Enumerator:

Unsorted	When building a style attribute, do not sort.
UseInkscapeOrder	When building a style attribute, sort properties the same way Inkscape does.

Definition at line 155 of file kgamesvgdocument.h.

Constructor & Destructor Documentation

KGameSvgDocument::KGameSvgDocument ( ) [explicit]

Constructor.

Definition at line 143 of file kgamesvgdocument.cpp.

KGameSvgDocument::KGameSvgDocument ( const KGameSvgDocument & doc )

Copy Constructor.

Definition at line 147 of file kgamesvgdocument.cpp.

KGameSvgDocument::~KGameSvgDocument ( ) [virtual]

Destructor.

Definition at line 152 of file kgamesvgdocument.cpp.

Member Function Documentation

KGameSvgDocument & KGameSvgDocument::operator= ( const KGameSvgDocument & doc )

Assignment Operator.

Definition at line 157 of file kgamesvgdocument.cpp.

QDomNode KGameSvgDocument::elementByUniqueAttributeValue	(	const QString &	attributeName,
		const QString &	attributeValue
	)

Returns the node with the given value for the given attribute.

Returns the element whose attribute given in attributeName is equal to the value given in attributeValue.

QDomDocument::elementById() always returns a null node because TT says they can't know which attribute is the id attribute. Here, we allow the id attribute to be specified.

This function also sets m_currentNode to this node.

Parameters:

	attributeName	The name of the identifing attribute, such as "id" to find.
	attributeValue	The value to look for in the attribute `attributeName` The values held in this attribute must be unique in the document, or the consequences may be unpredictably incorrect. You've been warned. ;-)

Returns:: the matching node, or a null node if no matching node found

Definition at line 164 of file kgamesvgdocument.cpp.

QDomNode KGameSvgDocument::elementById ( const QString & attributeValue )

Returns a node with the given id.

This is a convenience function. We call elementByUniqueAttributeValue(), but we assume that the name of the attribute is "id". This assumption will be correct for valid SVG files.

Returns the element whose ID is equal to elementId. If no element with the ID was found, this function returns a null element.

Parameters:

attributeValue

The value of the id attribute to find

Returns:: the matching node, or a null node if no matching node found

See also:: elementByUniqueAttributeValue()

Reimplemented from QDomDocument.

Definition at line 177 of file kgamesvgdocument.cpp.

void KGameSvgDocument::load ( )

Reads the SVG file svgFilename() into DOM.

Returns:: nothing

Definition at line 182 of file kgamesvgdocument.cpp.

void KGameSvgDocument::load ( const QString & svgFilename )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

This function permits specifying the svg file and loading it at once.

Parameters:

svgFilename

The filename of the SVG file to open.

Returns:: nothing

Definition at line 213 of file kgamesvgdocument.cpp.

void KGameSvgDocument::rotate	(	double	degrees,
		const MatrixOptions &	options = `ApplyToCurrentMatrix`
	)

Rotates the origin of the current node counterclockwise.

Parameters:

	degrees	The amount in degrees to rotate by.
	options	Apply to current matrix or replace current matrix.

Returns:: nothing

See also:: QMatrix::rotate()

Definition at line 219 of file kgamesvgdocument.cpp.

void KGameSvgDocument::translate	(	int	xPixels,
		int	yPixels,
		const MatrixOptions &	options = `ApplyToCurrentMatrix`
	)

Moves the origin of the current node.

Parameters:

	xPixels	The number of pixels to move the x-axis by.
	yPixels	The number of pixels to move the y-axis by.
	options	Apply to current matrix or replace current matrix.

Returns:: nothing

See also:: QMatrix::translate()

Definition at line 235 of file kgamesvgdocument.cpp.

void KGameSvgDocument::shear	(	double	xRadians,
		double	yRadians,
		const MatrixOptions &	options = `ApplyToCurrentMatrix`
	)

Shears the origin of the current node.

Parameters:

	xRadians	The amount in radians to shear (skew) the x-axis by.
	yRadians	The amount in radians to shear (skew) the y-axis by.
	options	Apply to current matrix or replace current matrix.

Returns:: nothing

See also:: QMatrix::shear()

Definition at line 251 of file kgamesvgdocument.cpp.

void KGameSvgDocument::skew	(	double	xDegrees,
		double	yDegrees,
		const MatrixOptions &	options = `ApplyToCurrentMatrix`
	)

Skews the origin of the current node.

This is a convenience function. It simply coverts it's arguments to radians, then calls shear().

Parameters:

	xDegrees	The amount in degrees to shear (skew) the x-axis by.
	yDegrees	The amount in degrees to shear (skew) the y-axis by.
	options	Apply to current matrix or replace current matrix.

Returns:: nothing

See also:: shear()

Definition at line 267 of file kgamesvgdocument.cpp.

void KGameSvgDocument::scale	(	double	xFactor,
		double	yFactor,
		const MatrixOptions &	options = `ApplyToCurrentMatrix`
	)

Scales the origin of the current node.

Note:: Neither xFactor nor yFactor may be zero, otherwise you scale the element into nonexistence.

Parameters:

	xFactor	The factor to scale the x-axis by.
	yFactor	The factor to scale the y-axis by.
	options	Apply to current matrix or replace current matrix.

Returns:: nothing

See also:: QMatrix::scale()

Definition at line 275 of file kgamesvgdocument.cpp.

QDomNode KGameSvgDocument::currentNode ( ) const

Returns the last node found by elementById, or null if node not found.

Returns:: The current node

See also:: setCurrentNode()

Definition at line 295 of file kgamesvgdocument.cpp.

void KGameSvgDocument::setCurrentNode ( const QDomNode & node )

Sets the current node.

Parameters:

node

The node to set currentNode to.

Returns:: nothing

See also:: currentNode()

Definition at line 300 of file kgamesvgdocument.cpp.

QString KGameSvgDocument::svgFilename ( ) const

Returns the name of the SVG file this DOM represents.

Returns:: The current filename.

See also:: setSvgFilename()

Definition at line 306 of file kgamesvgdocument.cpp.

void KGameSvgDocument::setSvgFilename ( const QString & svgFilename )

Sets the current SVG filename.

Parameters:

svgFilename

The filename of the SVG file to open.

Returns:: nothing

See also:: svgFilename()

Definition at line 311 of file kgamesvgdocument.cpp.

QString KGameSvgDocument::styleProperty ( const QString & propertyName ) const

Returns the value of the style property given for the current node.

Note:: Internally, we create a hash with styleProperties, then return the value of the propertyName property. As such, if you need the values of multiple properties, it will be more efficient to call styleProperties() and then use the hash directly.

See KGameSvgDocumentPrivate::m_inkscapeOrder for a list of common SVG style properties

Parameters:

propertyName

the name of the property to return

Returns:: The value style property given, or null if no such property for this node.

See also:: setStyleProperty(), styleProperties(), setStyleProperties()

Definition at line 316 of file kgamesvgdocument.cpp.

void KGameSvgDocument::setStyleProperty	(	const QString &	propertyName,
		const QString &	propertyValue
	)

Sets the value of the style property given for the current node.

Note:: Internally, we create a hash with styleProperties, then update the propertyName to propertyValue, before finally applying the hash to DOM via setStyleProperties(). Because of this, if you need to set multiple properties per node, it will be more efficient to call styleProperties(), modify the hash it returns, and then apply the hash with setStyleProperties().

Parameters:

	propertyName	The name of the property to set.
	propertyValue	The value of the property to set.

Returns:: nothing

See also:: styleProperty(), styleProperties(), setStyleProperties()

Definition at line 321 of file kgamesvgdocument.cpp.

QString KGameSvgDocument::nodeToSvg ( ) const

Returns the current node and it's children as a new xml svg document.

Returns:: The xml for the new svg document

Definition at line 331 of file kgamesvgdocument.cpp.

QByteArray KGameSvgDocument::nodeToByteArray ( ) const

Builds a new svg document and returns a QByteArray suitable for passing to KSvgRenderer::load().

Internally, we call nodeToSvg() and then convert to a QByteArray, so this method should be called instead of nodeToSvg().

Returns:: the QByteArray

Definition at line 382 of file kgamesvgdocument.cpp.

QString KGameSvgDocument::style ( ) const

Returns the style attribute of the current node.

Unless you are parsing your own style attribute for some reason, you probably want to use styleProperty() or styleProperties().

Returns:: The style atttibute.

See also:: styleProperty() styleProperties()

Definition at line 387 of file kgamesvgdocument.cpp.

void KGameSvgDocument::setStyle ( const QString & styleAttribute )

Sets the style attribute of the current node.

Unless you are parsing your own style attribute for some reason, you probably want to use setStyleProperty() or setStyleProperties().

Parameters:

styleAttribute

The style attribute to apply.

Returns:: nothing

See also:: setStyleProperty() setStyleProperties()

Definition at line 392 of file kgamesvgdocument.cpp.

QDomNodeList KGameSvgDocument::patterns ( ) const

Returns the patterns in the document.

Returns:: The patterns in the document

Definition at line 397 of file kgamesvgdocument.cpp.

QDomNodeList KGameSvgDocument::linearGradients ( ) const

Returns the linearGradients in the document.

Returns:: The linearGradients in the document

Definition at line 402 of file kgamesvgdocument.cpp.

QDomNodeList KGameSvgDocument::radialGradients ( ) const

Returns the radialGradients in the document.

Returns:: The radialGradients in the document

Definition at line 407 of file kgamesvgdocument.cpp.

QDomNodeList KGameSvgDocument::defs ( ) const

Returns the defs in the document.

Returns:: The defs in the document

Definition at line 412 of file kgamesvgdocument.cpp.

QDomNode KGameSvgDocument::def ( ) const

Returns the first def in the document.

Returns:: The first def in the document

Definition at line 417 of file kgamesvgdocument.cpp.

QString KGameSvgDocument::transform ( ) const

Returns the transform attribute of the current node.

Returns:: The transform atttibute.

See also:: setTransform(), transformMatrix(), setTransformMatrix()

Definition at line 422 of file kgamesvgdocument.cpp.

void KGameSvgDocument::setTransform ( const QString & transformAttribute )

Sets the transform attribute of the current node.

As this function works on QStrings, it replaces the existing transform attribute. If you need to multiply, use setTransformMatrix() instead.

Parameters:

transformAttribute

The transform attribute to apply.

Returns:: nothing

See also:: transform(), transformMatrix(), setTransformMatrix()

Definition at line 427 of file kgamesvgdocument.cpp.

QHash< QString, QString > KGameSvgDocument::styleProperties ( ) const

Returns a hash of the style properties of the current node.

Returns:: The style properties.

See also:: setStyleProperties()

Definition at line 432 of file kgamesvgdocument.cpp.

void KGameSvgDocument::setStyleProperties	(	const QHash< QString, QString > &	_styleProperties,
		const StylePropertySortOptions &	options = `Unsorted`
	)

Sets the style properties of the current node.

The only(?) reason to set useInkscapeOrder to true is if you are saving the svg xml to a file that may be human-edited later, for consistency. There is a performance hit, since hashes store their data unsorted.

Parameters:

	_styleProperties	The hash of style properties to apply.
	options	Apply the hash so the properties are in the same order as Inkscape writes them.

Returns:: nothing

See also:: styleProperties()

Definition at line 459 of file kgamesvgdocument.cpp.

QMatrix KGameSvgDocument::transformMatrix ( ) const

Returns the transform attribute of the current node as a matrix.

Returns:: The matrix for the transform atttibute.

See also:: setTransformMatrix()

Definition at line 499 of file kgamesvgdocument.cpp.

void KGameSvgDocument::setTransformMatrix	(	QMatrix &	matrix,
		const MatrixOptions &	options = `ApplyToCurrentMatrix`
	)

Sets the transform attribute of the current node.

Parameters:

	matrix	The matrix to apply.
	options	Should we apply matrix to the current matrix? We modify matrix internally if `options` includes ApplyToCurrentMatrix, so it can't be passed as const. Normally we want to apply the existing matrix. If we apply the matrix, we potentially end up squaring with each call, e.g. x^2.

Returns:: nothing

See also:: transformMatrix()

Definition at line 613 of file kgamesvgdocument.cpp.

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

libkdegames

KGameSvgDocument Class Reference

Detailed Description

Public Types

Public Member Functions

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

libkdegames

API Reference