This file is indexed.

/usr/include/KF5/KF5KDEGames/libkdegamesprivate/kgamesvgdocument.h is in libkf5kdegames-dev 4:15.12.3-0ubuntu1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
/** @file
 * This file contains the KGameSvgDocument class, used for manipulating
 * an SVG file using DOM.
 */

/***************************************************************************
 *   Copyright (C) 2007 Mark A. Taff <kde@marktaff.com>                    *
 *                                                                         *
 *   This program is free software; you can redistribute it and/or modify  *
 *   it under the terms of the GNU Library General Public License          *
 *   version 2 as published by the Free Software Foundation                *
 *                                                                         *
 *   This program is distributed in the hope that it will be useful,       *
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 *   GNU Library General Public License for more details.                  *
 *                                                                         *
 *   You should have received a copy of the GNU Library General Public     *
 *   License along with this program; if not, write to the                 *
 *   Free Software Foundation, Inc.,                                       *
 *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.         *
 ***************************************************************************/

#ifndef _KGAMESVGDOCUMENT_H_
#define _KGAMESVGDOCUMENT_H_

#include <QtCore/QHash>
#include <QtCore/QStringList>
#include <QtGui/QMatrix>
#include <QtXml/QDomDocument>
#include <QLoggingCategory>

#include "libkdegamesprivate_export.h"

Q_DECLARE_LOGGING_CATEGORY(GAMES_LIB)

class KGameSvgDocumentPrivate;

/**
 * \class KGameSvgDocument kgamesvgdocument.h <KGameSvgDocument>
 * 
 * @brief A class for manipulating an SVG file using DOM
 *
 * This class is a wrapper around QDomDocument for SVG files.
 * It:
 * @li implements elementById();
 * @li manipulates a node's style properties; and,
 * @li 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 
 * QSvgRenderer::load().
 *
 * To read an SVG file into DOM:
 * @code
 * KGameSvgDocument svgDom;
 * svgDom.load("/path/to/svgFile.svg");
 * @endcode
 *
 * To find a node with a specific value in its id attribute, for example where id="playerOneGamepiece":
 * @code
 * QDomNode playerOneGamepiece = svgDom.elementById("playerOneGamepiece");
 *
 * // This works too
 * QDomNode playerOneGamepiece = svgDom.elementByUniqueAttributeValue("id", "playerOneGamepiece");
 * @endcode
 *
 * Most methods operate on the last node found by @c elementById() or @c 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 @c setCurrentNode() with the node you are
 * wanting to modify to see if this is the issue.  Consider the following code for example:
 * @code
 * 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
 * @endcode
 *
 * To skew the @c currentNode():
 * @code
 * // Skew the horizontal axis 7.5 degrees
 * svgDom.skew(-7.5, 0, KGameSvgDocument::ReplaceCurrentMatrix);
 * @endcode
 * 
 * @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 @c x^2, and you will
 *     very quickly run into overflow issues.
 *
 * To output @c currentNode() to be rendered:
 * @code
 * QSvgRenderer svgRenderer;
 * QByteArray svg = svgDom.nodeToByteArray();
 * svgRenderer.load(svg);
 * @endcode
 *
 * To output the whole document to be rendered (See QDomDocument::toByteArray()):
 * @code
 * QSvgRenderer svgRenderer;
 * QByteArray svg = svgDom.toByteArray();
 * svgRenderer.load(svg);
 * @endcode
 * 
 * @see QDomDocument, QSvgRenderer
 * @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. ;-)
 */
class KDEGAMESPRIVATE_EXPORT KGameSvgDocument : public QDomDocument
{
public:
    /**
     * @brief Constructor
     */
    explicit KGameSvgDocument();

    /**
     * @brief Copy Constructor
     */
    KGameSvgDocument(const KGameSvgDocument &doc);

    /**
     * @brief Destructor
     */
    virtual ~KGameSvgDocument();

    /**
     * @brief Assignment Operator
     */
    KGameSvgDocument& operator=(const KGameSvgDocument &doc);

    /**
     * @brief Options for applying (multiplying) or replacing the current matrix
     */ 
    enum MatrixOption {
        /**
        * Apply to current matrix
        */
        ApplyToCurrentMatrix = 0x01,
        /**
        * Replace the current matrix
        */
        ReplaceCurrentMatrix = 0x02
    };
    /** @brief Q_DECLARE_FLAGS macro confuses doxygen, so create typedef's manually */
    typedef QFlags<MatrixOption> MatrixOptions;

    /**
     * Options for sorting style properties when building a style attribute
     */ 
    enum StylePropertySortOption {
        /**
        * When building a style attribute, do not sort
        */
        Unsorted = 0x01,
        /**
        * When building a style attribute, sort properties the same way Inkscape does
        */
        UseInkscapeOrder = 0x02
    };
    /** @brief Q_DECLARE_FLAGS macro confuses doxygen, so create typedef's manually */
    typedef QFlags<StylePropertySortOption> StylePropertySortOptions;

    /**
     * @brief Returns the node with the given value for the given attribute.
     *
     * Returns the element whose attribute given in @p attributeName is equal to the value
     * given in @p 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 @p m_currentNode to this node.
     *
     * @param attributeName The name of the identifing attribute, such as "id" to find.
     * @param attributeValue The value to look for in the attribute @p 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
     */
    QDomNode elementByUniqueAttributeValue(const QString& attributeName, const QString& attributeValue);

    /**
     * @brief 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.
     *
     * @param attributeValue The value of the id attribute to find
     * @returns the matching node, or a null node if no matching node found
     * @see elementByUniqueAttributeValue()
     */
    QDomNode elementById(const QString& attributeValue);

    /**
     * @brief Reads the SVG file svgFilename() into DOM.
     * @returns nothing
     */
    void load();

    /**
     * @overload
     * @brief This function permits specifying the svg file and loading it at once.
     *
     * @param svgFilename The filename of the SVG file to open.
     * @returns nothing
     */
    void load(const QString& svgFilename);

    /**
     * @brief Rotates the origin of the current node counterclockwise.
     *
     * @param degrees The amount in degrees to rotate by.
     * @param options Apply to current matrix or replace current matrix.
     * @returns nothing
     * @see QMatrix#rotate()
     */
    void rotate(double degrees, const MatrixOptions& options = ApplyToCurrentMatrix);

    /**
     * @brief Moves the origin of the current node
     *
     * @param xPixels The number of pixels to move the x-axis by.
     * @param yPixels The number of pixels to move the y-axis by.
     * @param options Apply to current matrix or replace current matrix.
     * @returns nothing
     * @see QMatrix::translate()
     */
    void translate(int xPixels, int yPixels, const MatrixOptions& options = ApplyToCurrentMatrix);

    /**
     * @brief Shears the origin of the current node.
     *
     * @param xRadians The amount in radians to shear (skew) the x-axis by.
     * @param yRadians The amount in radians to shear (skew) the y-axis by.
     * @param options Apply to current matrix or replace current matrix.
     * @returns nothing
     * @see QMatrix::shear()
     */
    void shear(double xRadians, double yRadians, const MatrixOptions& options = ApplyToCurrentMatrix);

    /**
     * @brief Skews the origin of the current node.
     *
     * This is a convenience function.  It simply coverts it's arguments to
     * radians, then calls shear().
     *
     * @param xDegrees The amount in degrees to shear (skew) the x-axis by.
     * @param yDegrees The amount in degrees to shear (skew) the y-axis by.
     * @param options Apply to current matrix or replace current matrix.
     * @returns nothing
     * @see shear()
     */
    void skew(double xDegrees, double yDegrees, const MatrixOptions& options = ApplyToCurrentMatrix);

    /**
     * @brief Scales the origin of the current node.
     *
     * @note Neither @c xFactor nor @c yFactor may be zero, otherwise you scale
     *        the element into nonexistence.
     *
     * @param xFactor The factor to scale the x-axis by.
     * @param yFactor The factor to scale the y-axis by.
     * @param options Apply to current matrix or replace current matrix.
     * @returns nothing
     * @see QMatrix::scale()
     */
    void scale(double xFactor, double yFactor, const MatrixOptions& options = ApplyToCurrentMatrix);

    /**
     * @brief Returns the last node found by elementById, or null if node not found
     * 
     * @returns The current node
     * @see setCurrentNode()
     */
    QDomNode currentNode() const;

    /**
     * @brief Sets the current node.
     *
     * @param node The node to set currentNode to.
     * @returns nothing
     * @see currentNode()
     */
    void setCurrentNode(const QDomNode& node);

    /**
     * @brief Returns the name of the SVG file this DOM represents.
     * 
     * @returns The current filename.
     * @see setSvgFilename()
     */
    QString svgFilename() const;

    /**
     * @brief Sets the current SVG filename.
     *
     * @param svgFilename The filename of the SVG file to open.
     * @returns nothing
     * @see svgFilename()
     */
    void setSvgFilename(const QString& svgFilename);

    /**
     * @brief Returns the value of the style property given for the current node.
     * 
     * @note Internally, we create a hash with @c styleProperties, then return the value
     *     of the @c propertyName property.  As such, if you need the values of multiple
     *     properties, it will be more efficient to call @c styleProperties()
     *     and then use the hash directly.
     *
     * See KGameSvgDocumentPrivate::m_inkscapeOrder for a list of common SVG style properties 
     *
     * @param propertyName the name of the property to return
     * @returns The value style property given, or null if no such property for this node.
     * @see setStyleProperty(), styleProperties(), setStyleProperties()
     */
    QString styleProperty(const QString& propertyName) const;

    /**
     * @brief Sets the value of the style property given for the current node.
     * 
     * @note Internally, we create a hash with @c styleProperties, then update the
     *  @p propertyName to @p propertyValue, before finally applying the hash to
     *      DOM via @c setStyleProperties().  Because of this, if you need to set multiple
     *      properties per node, it will be more efficient to call @c styleProperties(), 
     *      modify the hash it returns, and then apply the hash with @c setStyleProperties().
     *
     * @param propertyName The name of the property to set.
     * @param propertyValue The value of the property to set.
     * @returns nothing
     * @see styleProperty(), styleProperties(), setStyleProperties()
     */
    void setStyleProperty(const QString& propertyName, const QString& propertyValue);

    /**
     * @brief Returns the current node and it's children as a new xml svg document.
     * 
     * @returns The xml for the new svg document
     */
    QString nodeToSvg() const;

    /**
     * @brief Builds a new svg document and returns a QByteArray suitable for passing to QSvgRenderer::load().
     *
     * Internally, we call @c nodeToSvg() and then convert to a QByteArray, so this method 
     * should be called @b instead of @c nodeToSvg().
     *
     * @returns the QByteArray
     */
    QByteArray nodeToByteArray() const;

    /**
     * @brief 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 styleProperty() styleProperties()
     */
    QString style() const;

    /**
     * @brief 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().
     * 
     * @param styleAttribute The style attribute to apply.
     * @returns nothing
     * 
     * @see setStyleProperty() setStyleProperties()
     */
    void setStyle(const QString& styleAttribute);

    /**
     * @brief Returns the patterns in the document
     *
     * @returns The patterns in the document
     */
    QDomNodeList patterns() const;

    /**
     * @brief Returns the linearGradients in the document
     *
     * @returns The linearGradients in the document
     */
    QDomNodeList linearGradients() const;

    /**
     * @brief Returns the radialGradients in the document
     *
     * @returns The radialGradients in the document
     */
    QDomNodeList radialGradients() const;

    /**
     * @brief Returns the defs in the document
     *
     * @returns The defs in the document
     */
    QDomNodeList defs() const;

    /**
     * @brief Returns the first def in the document
     *
     * @returns The first def in the document
     */
    QDomNode def() const;

    /**
     * @brief Returns the transform attribute of the current node.
     * @returns The transform atttibute.
     * @see setTransform(), transformMatrix(), setTransformMatrix()
     */
    QString transform() const;

    /**
     * @brief Sets the transform attribute of the current node.
     * 
     * As this function works on QStrings, it <b>replaces</b> the existing
     * transform attribute.  If you need to multiply, use setTransformMatrix() instead.
     *
     * @param transformAttribute The transform attribute to apply.
     * @returns nothing
     * @see transform(), transformMatrix(), setTransformMatrix()
     */
    void setTransform(const QString& transformAttribute);

    /**
     * @brief Returns a hash of the style properties of the current node.
     * @returns The style properties.
     * @see setStyleProperties()
     */
    QHash<QString, QString> styleProperties() const;

    /**
     * @brief 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.
     *
     * @param _styleProperties The hash of style properties to apply.
     * @param options Apply the hash so the properties are in the same order as Inkscape writes them.
     * @returns nothing
     * @see styleProperties()
     */
    void setStyleProperties(const QHash<QString, QString>& _styleProperties, const StylePropertySortOptions& options = Unsorted);

    /**
     * @brief Returns the transform attribute of the current node as a matrix.
     * 
     * @returns The matrix for the transform atttibute.
     * @see setTransformMatrix()
     */
    QMatrix transformMatrix() const;

    /**
     * @brief Sets the transform attribute of the current node.
     *
     * @param matrix The matrix to apply.
     * @param options Should we apply matrix to the current matrix?
     *     We modify matrix internally if @p 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 transformMatrix()
     */
    void setTransformMatrix(QMatrix& matrix, const MatrixOptions& options = ApplyToCurrentMatrix);

private:


    /**
     * @brief d-pointer
     */
    KGameSvgDocumentPrivate * const d;

};
Q_DECLARE_OPERATORS_FOR_FLAGS(KGameSvgDocument::MatrixOptions)
Q_DECLARE_OPERATORS_FOR_FLAGS(KGameSvgDocument::StylePropertySortOptions)

#endif // _KGAMESVGDOCUMENT_H_