KGameSvgDocument Class Reference

#include <kgamesvgdocument.h>

Collaboration diagram for KGameSvgDocument:

Collaboration graph
[legend]

List of all members.

Public Types

enum  MatrixOption { ApplyToCurrentMatrix = 0x01, ReplaceCurrentMatrix = 0x02 }
enum  StylePropertySortOption { Unsorted = 0x01, UseInkscapeOrder = 0x02 }
 Options for sorting style properties when building a style attribute. More...
typedef QFlags
< MatrixOption
MatrixOptions
typedef QFlags
< StylePropertySortOption
StylePropertySortOptions

Public Member Functions

 KGameSvgDocument ()
 KGameSvgDocument (const KGameSvgDocument &doc)
virtual ~KGameSvgDocument ()
KGameSvgDocumentoperator= (const KGameSvgDocument &doc)
QDomNode elementByUniqueAttributeValue (const QString &attributeName, const QString &attributeValue)
QDomNode elementById (const QString &attributeValue)
void load ()
void 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.
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)


Detailed Description

A class for manipulating an SVG file using DOM This class is a wrapper around QDomDocument for SVG files. It:
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.


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.

References d.

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.

References KGameSvgDocumentPrivate::findElementById(), and setCurrentNode().

Referenced by elementById().

Here is the call graph for this function:

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()

Definition at line 177 of file kgamesvgdocument.cpp.

References elementByUniqueAttributeValue().

Here is the call graph for this function:

void KGameSvgDocument::load (  ) 

Reads the SVG file svgFilename() into DOM.

Returns:
nothing

Definition at line 182 of file kgamesvgdocument.cpp.

References KGameSvgDocumentPrivate::m_svgFilename.

Referenced by load().

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.

References load(), and setSvgFilename().

Here is the call graph for this function:

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.

References ApplyToCurrentMatrix, ReplaceCurrentMatrix, setTransformMatrix(), and transformMatrix().

Here is the call graph for this function:

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.

References ApplyToCurrentMatrix, ReplaceCurrentMatrix, setTransformMatrix(), and transformMatrix().

Here is the call graph for this function:

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.

References ApplyToCurrentMatrix, ReplaceCurrentMatrix, setTransformMatrix(), and transformMatrix().

Referenced by skew().

Here is the call graph for this function:

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.

References shear().

Here is the call graph for this function:

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.

References ApplyToCurrentMatrix, ReplaceCurrentMatrix, setTransformMatrix(), and transformMatrix().

Here is the call graph for this function:

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.

References KGameSvgDocumentPrivate::m_currentNode.

Referenced by nodeToSvg().

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.

References KGameSvgDocumentPrivate::m_currentNode, and KGameSvgDocumentPrivate::setCurrentElement().

Referenced by elementByUniqueAttributeValue().

Here is the call graph for this function:

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.

References KGameSvgDocumentPrivate::m_svgFilename.

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.

References KGameSvgDocumentPrivate::m_svgFilename.

Referenced by load().

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.

References styleProperties().

Referenced by styleProperties().

Here is the call graph for this function:

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.

References setStyleProperties(), styleProperties(), and UseInkscapeOrder.

Here is the call graph for this function:

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.

References currentNode(), def(), defs(), KGameSvgDocumentPrivate::findElementById(), KGameSvgDocumentPrivate::SVG_XML_APPEND, and KGameSvgDocumentPrivate::SVG_XML_PREPEND.

Referenced by nodeToByteArray().

Here is the call graph for this function:

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.

References nodeToSvg().

Here is the call graph for this function:

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.

References KGameSvgDocumentPrivate::m_currentElement.

Referenced by styleProperties().

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.

References KGameSvgDocumentPrivate::m_currentElement.

Referenced by setStyleProperties().

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.

Referenced by def(), and nodeToSvg().

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.

References defs().

Referenced by nodeToSvg().

Here is the call graph for this function:

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.

References KGameSvgDocumentPrivate::m_currentElement.

Referenced by setTransformMatrix(), and transformMatrix().

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.

References KGameSvgDocumentPrivate::m_currentElement.

Referenced by setTransformMatrix().

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.

References KGameSvgDocumentPrivate::setStyleHasTrailingSemicolon(), style(), and styleProperty().

Referenced by setStyleProperties(), setStyleProperty(), and styleProperty().

Here is the call graph for this function:

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.

References KGameSvgDocumentPrivate::m_inkscapeOrder, setStyle(), KGameSvgDocumentPrivate::styleHasTrailingSemicolon(), styleProperties(), and UseInkscapeOrder.

Referenced by setStyleProperty().

Here is the call graph for this function:

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.

References transform().

Referenced by rotate(), scale(), setTransformMatrix(), shear(), and translate().

Here is the call graph for this function:

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.

References ApplyToCurrentMatrix, setTransform(), transform(), and transformMatrix().

Referenced by rotate(), scale(), shear(), and translate().

Here is the call graph for this function:


The documentation for this class was generated from the following files:
Generated on Sun Mar 16 08:03:22 2008 for Libkdegames by  doxygen 1.5.3