Improve Fl_SVG_Image docs

- add 'can_expand' optional parameter to scale()
- don't expose name and e-mail of the nanosvg author in docs
- format example code according to the FLTK coding style
- fix (some) trailing spaces

FTR: all examples compile and work well with current FLTK 1.4.

1 files changed, 84 insertions, 81 deletions

diff --git a/FL/Fl_SVG_Image.H b/FL/Fl_SVG_Image.H
index 1f1d0de05..3b9648e3a 100644
--- a/FL/Fl_SVG_Image.H
+++ b/FL/Fl_SVG_Image.H
@@ -1,19 +1,17 @@
 //
-// "$Id$"
-//
 // SVG Image header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 2017 by Bill Spitzak and others.
+// Copyright 2017-2020 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
 // file is missing or damaged, see the license at:
 //
-//     http://www.fltk.org/COPYING.php
+//     https://www.fltk.org/COPYING.php
 //
 // Please report all bugs and problems on the following page:
 //
-//     http://www.fltk.org/str.php
+//     https://www.fltk.org/str.php
 //
 
 #ifndef FL_SVG_IMAGE_H
@@ -25,107 +23,112 @@ struct NSVGimage;
 
 /** The Fl_SVG_Image class supports loading, caching and drawing of scalable vector graphics (SVG) images.
  The FLTK library performs parsing and rasterization of SVG data using a modified version 
- of the \c nanosvg software (https://github.com/memononen/nanosvg) © 2013-14 Mikko Mononen 
- (memon@inside.org). The software modification allows the option to change the image ratio 
+ of the \c nanosvg software (https://github.com/memononen/nanosvg).
+ The software modification allows the option to change the image ratio
  while performing rasterization.
- 
+
  Use Fl_Image::fail() to check if the Fl_SVG_Image failed to load. fail() returns ERR_FILE_ACCESS 
  if the file could not be opened or read, and ERR_FORMAT if the SVG format could not be decoded. 
  If the image has loaded correctly, w(), h(), and d() should return values greater than zero.
- 
+
  Rasterization is not done until the image is first drawn or resize() is called. Therefore, 
  \ref array is NULL until then. The delayed rasterization ensures an Fl_SVG_Image is always rasterized
  to the exact screen resolution at which it is drawn.
+
+ The Fl_SVG_Image class draws images computed by \c nanosvg with the following known limitations
  
- The Fl_SVG_Image class draws images computed by \c nanosvg: two known limitations are that text
- between \c <text\> and </text\> marks, and \c image elements  are not rendered.
- 
+  - text between \c <text\> and </text\> marks,
+  - \c image elements, and
+  - <use\> statements
+
+ are not rendered.
+
  The FLTK library can optionally be built without SVG support; in that case, 
  class Fl_SVG_Image is unavailable.
 
  Example of displaying a hard-coded svg file:
  \code
- #include <FL/Fl.H>
- #include <FL/Fl_Window.H>
- #include <FL/Fl_Box.H>
- #include <FL/Fl_SVG_Image.H>
-
- // A black rotated rectangle
- const char *svg_data = "<svg viewBox=\"0 0 200 200\" version = \"1.1\">\n"
-                        "<rect x=\"25\" y=\"50\" width=\"150\" height=\"100\" fill=\"black\" "
-                        "transform=\"rotate(45 100 100)\"> </svg>\n";
-
- int main(int argc, char **argv) {
-     Fl_SVG_Image *svg = new Fl_SVG_Image(0, svg_data);       // create SVG object
-     Fl_Window    *win = new Fl_Window(720, 486, "svg test");
-     Fl_Box       *box = new Fl_Box(0,0,win->w(),win->h());
-     box->image(svg);  // assign svg object to Fl_Box
-     win->end();
-     win->show(argc,argv);
-     return(Fl::run());
- }
+  #include <FL/Fl.H>
+  #include <FL/Fl_Window.H>
+  #include <FL/Fl_Box.H>
+  #include <FL/Fl_SVG_Image.H>
+
+  // A black rotated rectangle
+  const char *svg_data = "<svg viewBox=\"0 0 200 200\" version = \"1.1\">\n"
+                         "<rect x=\"25\" y=\"50\" width=\"150\" height=\"100\" fill=\"black\" "
+                         "transform=\"rotate(45 100 100)\"> </svg>\n";
+
+  int main(int argc, char **argv) {
+    Fl_SVG_Image *svg = new Fl_SVG_Image(0, svg_data);       // create SVG object
+    Fl_Window    *win = new Fl_Window(720, 486, "svg test");
+    Fl_Box       *box = new Fl_Box(0, 0, win->w(), win->h());
+    box->image(svg);  // assign svg object to Fl_Box
+    win->end();
+    win->show(argc,argv);
+    return(Fl::run());
+  }
  \endcode
 
  Example of displaying an svg image from a file:
  \code
- #include <errno.h>   // errno
- #include <string.h>  // strerror
- #include <FL/Fl.H>
- #include <FL/Fl_Window.H>
- #include <FL/Fl_Box.H>
- #include <FL/Fl_SVG_Image.H>
- #include <FL/fl_message.H>
- int main(int argc, char **argv) {
-     Fl_Window *win = new Fl_Window(720, 486, "svg test");
-     Fl_Box    *box = new Fl_Box(0,0,win->w(),win->h());
- 
-     // Load svg image from disk, assign to a box
-     const char *svgpath = "/var/tmp/simple.svg";
-     Fl_SVG_Image *svg = new Fl_SVG_Image(svgpath);  // load SVG object from disk
-     switch ( svg->fail() ) {
-         case Fl_Image::ERR_FILE_ACCESS:
-            // File couldn't load? show path + os error to user
-            fl_alert("%s: %s", svgpath, strerror(errno));
-            return 1;
-         case Fl_Image::ERR_FORMAT:
-            // Parsing error
-            fl_alert("%s: couldn't decode image", svgpath);
-            return 1;
-     }
-     box->image(svg);  // assign svg object to box
- 
-     win->end();
-     win->show(argc,argv);
-     return(Fl::run());
- }
+  #include <errno.h>   // errno
+  #include <string.h>  // strerror
+  #include <FL/Fl.H>
+  #include <FL/Fl_Window.H>
+  #include <FL/Fl_Box.H>
+  #include <FL/Fl_SVG_Image.H>
+  #include <FL/fl_message.H>
+  int main(int argc, char **argv) {
+    Fl_Window *win = new Fl_Window(720, 486, "svg test");
+    Fl_Box    *box = new Fl_Box(0, 0, win->w(), win->h());
+
+    // Load svg image from disk, assign to a box
+    const char *svgpath = "/var/tmp/simple.svg";
+    Fl_SVG_Image *svg = new Fl_SVG_Image(svgpath);  // load SVG object from disk
+    switch (svg->fail()) {
+      case Fl_Image::ERR_FILE_ACCESS:
+        // File couldn't load? show path + os error to user
+        fl_alert("%s: %s", svgpath, strerror(errno));
+        return 1;
+      case Fl_Image::ERR_FORMAT:
+        // Parsing error
+        fl_alert("%s: couldn't decode image", svgpath);
+        return 1;
+    }
+    box->image(svg);  // assign svg object to box
+
+    win->end();
+    win->show(argc,argv);
+    return(Fl::run());
+  }
  \endcode
 
  Example of fitting an svg image to a resizable Fl_Box:
  \code
- #include <FL/Fl_Window.H>
- #include <FL/Fl_SVG_Image.H>
- #include <FL/Fl_Box.H>
- 
- class resizable_box : public Fl_Box {
- public:
+  #include <FL/Fl_Window.H>
+  #include <FL/Fl_SVG_Image.H>
+  #include <FL/Fl_Box.H>
+
+  class resizable_box : public Fl_Box {
+  public:
     resizable_box(int w, int h) : Fl_Box(0, 0, w, h, NULL) {}
     virtual void resize(int x, int y, int w, int h) {
-     image()->scale(w, h);
-     Fl_Box::resize(x, y, w, h);
+      image()->scale(w, h, 1, 1); // p3 = proportional, p4 = can_expand
+      Fl_Box::resize(x, y, w, h);
     }
- };
+  };
  
- int main(int argc, char **argv) {
-   Fl_Window *win = new Fl_Window(130, 130);
-   resizable_box *box = new resizable_box(win->w(), win->h());
-   Fl_SVG_Image *svg = new Fl_SVG_Image("/path/to/image.svg");
-   box->image(svg);
-   svg->scale(box->w(), box->h());
-   win->end();
-   win->resizable(win);
-   win->show(argc, argv);
-   return Fl::run();
- }
+  int main(int argc, char **argv) {
+    Fl_Window *win = new Fl_Window(130, 130);
+    resizable_box *box = new resizable_box(win->w(), win->h());
+    Fl_SVG_Image *svg = new Fl_SVG_Image("/path/to/image.svg");
+    box->image(svg);
+    svg->scale(box->w(), box->h());
+    win->end();
+    win->resizable(win);
+    win->show(argc, argv);
+    return Fl::run();
+  }
  \endcode
 
  */