svgicons: API changes proposal

Signed-off-by: Mavridis Philippe <mavridisf@gmail.com>

tdecore/svgicons/ksvgiconengine.cpp

@@ -18,7 +18,6 @@
     Boston, MA 02110-1301, USA.
 */
 
-#include <tqdom.h>
 #include <tqfile.h>
 #include <tqcolor.h>
 #include <tqimage.h>
@@ -540,7 +539,7 @@ KSVGIconEngine::~KSVGIconEngine()
 	delete d;
 }
 
-bool KSVGIconEngine::load(int width, int height, const TQString &path)
+bool KSVGIconEngine::load(const TQString &path, int width, int height)
 {
 	if(path.isNull()) return false;
 
@@ -585,11 +584,24 @@ bool KSVGIconEngine::load(int width, int height, const TQString &path)
 		svgDocument.setContent(buffer);
 	}
 
-	if(svgDocument.isNull())
+  return parse(svgDocument, width, height);
+}
+
+bool KSVGIconEngine::load(int width, int height, const TQString &path)
+{
+    return load(path, width, height);
+}
+
+
+bool KSVGIconEngine::parse(const TQDomDocument& data, int width, int height)
+{
+  if(data.isNull())
+  {
 		return false;
+  }
 
 	// Check for root element
-	TQDomNode rootNode = svgDocument.namedItem("svg");
+	TQDomNode rootNode = data.namedItem("svg");
 	if(rootNode.isNull() || !rootNode.isElement())
 		return false;
 
@@ -691,6 +703,19 @@ bool KSVGIconEngine::load(int width, int height, const TQString &path)
 	return true;
 }
 
+bool KSVGIconEngine::parse(const TQString& data, int width, int height)
+{
+  if(data.isNull())
+  {
+    return false;
+  }
+
+  TQDomDocument svgDocument("svg");
+  svgDocument.setContent(data);
+
+  return parse(svgDocument, width, height);
+}
+
 KSVGIconPainter *KSVGIconEngine::painter()
 {
 	return d->painter;

tdecore/svgicons/ksvgiconengine.h

@@ -21,8 +21,13 @@
 #ifndef KSVGIconEngine_H
 #define KSVGIconEngine_H
 
+#include <tqdom.h>
 #include <tdelibs_export.h>
 
+/**
+ * \file ksvgiconengine.h
+ */
+
 class KSVGIconPainter;
 
 class TDECORE_EXPORT KSVGIconEngine
@@ -31,12 +36,67 @@ public:
 	KSVGIconEngine();
 	~KSVGIconEngine();
 
-	bool load(int width, int height, const TQString &path);
+  /**
+   * @short Reads SVG(Z) document @p path, parses and renders its contents.
+   *
+   * @param path is the path of the SVG document.
+   * @param width is the width of the render result. Omit it or pass 0 to use document's default.
+   * @param height is the height of the render result. Omit it or pass 0 to use document's default.
+   *
+   * @return True if rendering is successful, otherwise false.
+   */
+  bool load(const TQString &path, int width = 0, int height = 0);
+
+  /**
+   * @deprecated
+   * @short Reads SVG(Z) document @p path, parses and renders its contents.
+   *
+   * This function uses the old parameter order which does not allow width and height to be omitted
+   * and is kept for compatibility. Prefer the variant below instead.
+   *
+   * @see load(const TQString&, int, int);
+   */
+  bool load(int width, int height, const TQString &path) KDE_DEPRECATED;
+
+  /**
+   * @short Renders the SVG data stored as DOM in @p data.
+   *
+   * @param data is the TQDocDocument representation of the SVG document to render.
+   * @see load(const TQString&, int, int);
+   */
+  bool parse(const TQDomDocument &data, int width = 0, int height = 0);
 
+  /**
+   * @short Renders the SVG data stored as string in @p data.
+   *
+   * This function is a wrapper provided for convenience.
+   *
+   * @param data is a TQString containing the SVG document to render.
+   * @see parse(const TQDomDocument&, int, int);
+   */
+  bool parse(const TQString &data, int width = 0, int height = 0);
+
+  /**
+   * @short Returns a pointer to the engine's KSVGIconPainter object.
+   *
+   * Typically you won't need access to the painter and you won't be able to do so
+   * from outside tdelibs (since the KSVGIconPainter header is not installed).
+   */
   KSVGIconPainter *painter();
+
+  /**
+   * @short Returns a pointer to the rendered TQImage.
+   */
   TQImage *image();
 
+  /**
+   * @short Returns the rendered image's width.
+   */
   double width();
+
+  /**
+   * @short Returns the rendered image's height.
+   */
   double height();
 
 private: