SVG(3pm) - f33

1SVG(3)                User Contributed Perl Documentation               SVG(3)
2
3
4

NAME

6       SVG - Perl extension for generating Scalable Vector Graphics (SVG)
7       documents.
8

SYNOPSIS

10           #!/usr/bin/perl
11           use strict;
12           use warnings;
13           use SVG;
14
15           # create an SVG object
16           my $svg= SVG->new( width => 200, height => 200);
17
18           # use explicit element constructor to generate a group element
19           my $y = $svg->group(
20               id => 'group_y',
21               style => {
22                   stroke => 'red',
23                   fill   => 'green'
24               },
25           );
26
27           # add a circle to the group
28           $y->circle( cx => 100, cy => 100, r => 50, id => 'circle_in_group_y' );
29
30           # or, use the generic 'tag' method to generate a group element by name
31           my $z = $svg->tag('g',
32                           id    => 'group_z',
33                           style => {
34                               stroke => 'rgb(100,200,50)',
35                               fill   => 'rgb(10,100,150)'
36                           }
37                       );
38
39           # create and add a circle using the generic 'tag' method
40           $z->tag('circle', cx => 50, cy => 50, r => 100, id => 'circle_in_group_z');
41
42           # create an anchor on a rectangle within a group within the group z
43           my $k = $z->anchor(
44               id      => 'anchor_k',
45               -href   => 'http://test.hackmare.com/',
46               target => 'new_window_0'
47           )->rectangle(
48               x     => 20, y      => 50,
49               width => 20, height => 30,
50               rx    => 10, ry     => 5,
51               id    => 'rect_k_in_anchor_k_in_group_z'
52           );
53
54           # now render the SVG object, implicitly use svg namespace
55           print $svg->xmlify;
56
57           # or render a child node of the SVG object without rendering the entire object
58           print $k->xmlify; #renders the anchor $k above containing a rectangle, but does not
59                             #render any of the ancestor nodes of $k
60
61
62           # or, explicitly use svg namespace and generate a document with its own DTD
63           print $svg->xmlify(-namespace=>'svg');
64
65           # or, explicitly use svg namespace and generate an inline docunent
66           print $svg->xmlify(
67               -namespace => "svg",
68               -pubid => "-//W3C//DTD SVG 1.0//EN",
69               -inline   => 1
70           );
71
72       See the other modules in this distribution: SVG::DOM, SVG::XML,
73       SVG::Element, and SVG::Extension.
74
75       See SVG::Parser for reading SVG files as "SVG" objects.
76
77   Converting SVG to PNG and other raster image formats
78       The convert command of <http://www.imagemagick.org/> (also via
79       Image::Magick ) can convert SVG files to PNG and other formats.
80
81       Image::LibRSVG can convert SVG to other format.
82

EXAMPLES

84       examples/circle.pl generates the following image:
85
86         <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
87         <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
88         <svg height="200" width="200" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
89         <title >I am a title</title>
90         <g id="group_y" style="fill: green; stroke: red">
91         <circle cx="100" cy="100" id="circle_in_group_y" r="50" />
92         <!-- This is a comment -->
93         </g>
94         </svg>
95
96       That you can either embed directly into HTML or can include it using:
97
98          <object data="file.svg" type="image/svg+xml"></object>
99
100       (The image was converted to png using Image::LibRSVG. See the
101       svg2png.pl script in the examples directory.)
102
103       See also the examples directory in this distribution which contain
104       several fully documented examples.
105

DESCRIPTION

107       SVG is a 100% Perl module which generates a nested data structure
108       containing the DOM representation of an SVG (Scalable Vector Graphics)
109       image. Using SVG, you can generate SVG objects, embed other SVG
110       instances into it, access the DOM object, create and access javascript,
111       and generate SMIL animation content.
112
113   General Steps to generating an SVG document
114       Generating SVG is a simple three step process:
115
116       1 Construct a new SVG object with "new".
117       2 Call element constructors such as "circle" and "path" to create SVG
118       elements.
119       3 Render the SVG object into XML using the "xmlify" method.
120
121       The "xmlify" method takes a number of optional arguments that control
122       how SVG renders the object into XML, and in particular determine
123       whether a standalone SVG document or an inline SVG document fragment is
124       generated:
125
126   -standalone
127       A complete SVG document with its own associated DTD. A namespace for
128       the SVG elements may be optionally specified.
129
130   -inline
131       An inline SVG document fragment with no DTD that be embedded within
132       other XML content. As with standalone documents, an alternate namespace
133       may be specified.
134
135       No XML content is generated until the third step is reached. Up until
136       this point, all constructed element definitions reside in a DOM-like
137       data structure from which they can be accessed and modified.
138
139   EXPORTS
140       None. However, SVG permits both options and additional element methods
141       to be specified in the import list. These options and elements are then
142       available for all SVG instances that are created with the "new"
143       constructor. For example, to change the indent string to two spaces per
144       level:
145
146           use SVG (-indent => "  ");
147
148       With the exception of -auto, all options may also be specified to the
149       "new" constructor. The currently supported options and their default
150       value are:
151
152           # processing options
153           -auto       => 0,       # permit arbitrary autoloading of all unrecognised elements
154           -printerror => 1,       # print error messages to STDERR
155           -raiseerror => 1,       # die on errors (implies -printerror)
156
157           # rendering options
158           -indent     => "\t",    # what to indent with
159           -elsep      => "\n",    # element line (vertical) separator
160                                   #     (note that not all agents ignor trailing blanks)
161           -nocredits  => 0,       # enable/disable credit note comment
162           -namespace  => '',      # The root element's (and it's children's) namespace prefix
163
164           # XML and Doctype declarations
165           -inline     => 0,       # inline or stand alone
166           -docroot    => 'svg',   # The document's root element
167           -version    => '1.0',
168           -extension  => '',
169           -encoding   => 'UTF-8',
170           -xml_svg    => 'http://www.w3.org/2000/svg',   # the svg xmlns attribute
171           -xml_xlink  => 'http://www.w3.org/1999/xlink', # the svg tag xmlns:xlink attribute
172           -standalone => 'yes',
173           -pubid      => "-//W3C//DTD SVG 1.0//EN",      # formerly -identifier
174           -sysid      => 'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd', # the system id
175
176       SVG also allows additional element generation methods to be specified
177       in the import list. For example to generate 'star' and 'planet' element
178       methods:
179
180           use SVG qw(star planet);
181
182       or:
183
184           use SVG ("star","planet");
185
186       This will add 'star' to the list of elements supported by SVG.pm (but
187       not of course other SVG parsers...). Alternatively the '-auto' option
188       will allow any unknown method call to generate an element of the same
189       name:
190
191           use SVG (-auto => 1, "star", "planet");
192
193       Any elements specified explicitly (as 'star' and 'planet' are here) are
194       predeclared; other elements are defined as and when they are seen by
195       Perl. Note that enabling '-auto' effectively disables compile-time
196       syntax checking for valid method names.
197
198           use SVG (
199               -auto       => 0,
200               -indent     => "  ",
201               -raiseerror  => 0,
202               -printerror => 1,
203               "star", "planet", "moon"
204           );
205
206   Default SVG tag
207       The Default SVG tag will generate the following XML:
208
209         $svg = SVG->new;
210         print $svg->xmlify;
211
212       Resulting XML snippet:
213
214         <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
215         <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd">
216         <svg height="100%" width="100%" xmlns="http://www.w3.org/2000/svg" xmlns:svg="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
217             <!--
218               Generated using the Perl SVG Module V2.50
219                 by Ronan Oger
220               Info: http://www.roitsystems.com/
221             -->
222

METHODS

224       SVG provides both explicit and generic element constructor methods.
225       Explicit generators are generally (with a few exceptions) named for the
226       element they generate. If a tag method is required for a tag containing
227       hyphens, the method name replaces the hyphen with an underscore. ie: to
228       generate tag <column-heading id="new"> you would use method
229       $svg->column_heading(id=>'new').
230
231       All element constructors take a hash of element attributes and options;
232       element attributes such as 'id' or 'border' are passed by name, while
233       options for the method (such as the type of an element that supports
234       multiple alternate forms) are passed preceded by a hyphen, e.g '-type'.
235       Both types may be freely intermixed; see the "fe" method and code
236       examples throughout the documentation for more examples.
237
238   new (constructor)
239       $svg = SVG->new(%attributes)
240
241       Creates a new SVG object. Attributes of the document SVG element be
242       passed as an optional list of key value pairs. Additionally, SVG
243       options (prefixed with a hyphen) may be set on a per object basis:
244
245           my $svg1 = SVG->new;
246
247           my $svg2 = SVG->new(id => 'document_element');
248
249           my $svg3 = SVG->new(
250               -printerror => 1,
251               -raiseerror => 0,
252               -indent     => '  ',
253               -docroot => 'svg', #default document root element (SVG specification assumes svg). Defaults to 'svg' if undefined
254               -sysid      => 'abc', #optional system identifyer
255               -pubid      => "-//W3C//DTD SVG 1.0//EN", #public identifyer default value is "-//W3C//DTD SVG 1.0//EN" if undefined
256               -namespace => 'mysvg',
257               -inline   => 1
258               id          => 'document_element',
259               width       => 300,
260               height      => 200,
261           );
262
263       SVG instance represents the document and not the "<svg>" root element.
264
265       Default SVG options may also be set in the import list. See "EXPORTS"
266       above for more on the available options.
267
268       Furthermore, the following options:
269
270           -version
271           -encoding
272           -standalone
273           -namespace Defines the document or element level namespace. The order of assignment priority is element,document .
274           -inline
275           -identifier
276           -nostub
277           -dtd (standalone)
278
279       may also be set in xmlify, overriding any corresponding values set in
280       the SVG->new declaration
281
282   xmlify (alias: to_xml render serialise serialize)
283       $string = $svg->xmlify(%attributes);
284
285       Returns xml representation of svg document.
286
287       XML Declaration
288
289           Name               Default Value
290           -version           '1.0'
291           -encoding          'UTF-8'
292           -standalone        'yes'
293           -namespace         'svg'                - namespace for elements
294           -inline            '0' - If '1', then this is an inline document.
295           -pubid             '-//W3C//DTD SVG 1.0//EN';
296           -dtd (standalone)  'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd'
297
298   tag (alias: element)
299       $tag = $svg->tag($name, %attributes)
300
301       Generic element generator. Creates the element named $name with the
302       attributes specified in %attributes. This method is the basis of most
303       of the explicit element generators.
304
305           my $tag = $svg->tag('g', transform=>'rotate(-45)');
306
307   anchor
308       $tag = $svg->anchor(%attributes)
309
310       Generate an anchor element. Anchors are put around objects to make them
311       'live' (i.e. clickable). It therefore requires a drawn object or group
312       element as a child.
313
314       optional anchor attributes
315
316       the following attributes are expected for anchor tags (any any tags
317       which use -href links):
318
319   -href    required
320   -type    optional
321   -role    optional
322   -title   optional
323   -show    optional
324   -arcrole optional
325   -actuate optional
326   target   optional
327       For more information on the options, refer to the w3c XLink
328       specification at <http://www.w3.org/TR/xlink/>
329
330       Example:
331
332           # generate an anchor
333           $tag = $SVG->anchor(
334                -href=>'http://here.com/some/simpler/SVG.SVG'
335                -title => 'new window 2 example title',
336                -actuate => 'onLoad',
337                -show=> 'embed',
338
339           );
340
341       for more information about the options above, refer to Link  section in
342       the SVG recommendation: <http://www.w3.org/TR/SVG11/linking.html#Links>
343
344           # add a circle to the anchor. The circle can be clicked on.
345           $tag->circle(cx => 10, cy => 10, r => 1);
346
347           # more complex anchor with both URL and target
348           $tag = $SVG->anchor(
349                 -href   => 'http://somewhere.org/some/other/page.html',
350                 target => 'new_window'
351           );
352
353
354           # generate an anchor
355           $tag = $svg->anchor(
356               -href=>'http://here.com/some/simpler/svg.svg'
357           );
358           # add a circle to the anchor. The circle can be clicked on.
359           $tag->circle(cx => 10, cy => 10, r => 1);
360
361           # more complex anchor with both URL and target
362           $tag = $svg->anchor(
363                 -href   => 'http://somewhere.org/some/other/page.html',
364                 target => 'new_window'
365           );
366
367   circle
368       $tag = $svg->circle(%attributes)
369
370       Draw a circle at (cx,cy) with radius r.
371
372           my $tag = $svg->circle(cx => 4, cy => 2, r => 1);
373
374   ellipse
375       $tag = $svg->ellipse(%attributes)
376
377       Draw an ellipse at (cx,cy) with radii rx,ry.
378
379           use SVG;
380
381           # create an SVG object
382           my $svg= SVG->new( width => 200, height => 200);
383
384           my $tag = $svg->ellipse(
385               cx => 10,
386               cy => 10,
387               rx => 5,
388               ry => 7,
389               id => 'ellipse',
390               style => {
391                   'stroke'         => 'red',
392                   'fill'           => 'green',
393                   'stroke-width'   => '4',
394                   'stroke-opacity' => '0.5',
395                   'fill-opacity'   => '0.2',
396               }
397           );
398
399       See The example/ellipse.pl
400
401   rectangle (alias: rect)
402       $tag = $svg->rectangle(%attributes)
403
404       Draw a rectangle at (x,y) with width 'width' and height 'height' and
405       side radii 'rx' and 'ry'.
406
407           $tag = $svg->rectangle(
408               x      => 10,
409               y      => 20,
410               width  => 4,
411               height => 5,
412               rx     => 5.2,
413               ry     => 2.4,
414               id     => 'rect_1'
415           );
416
417   image
418        $tag = $svg->image(%attributes)
419
420       Draw an image at (x,y) with width 'width' and height 'height' linked to
421       image resource '-href'. See also "use".
422
423           $tag = $svg->image(
424               x       => 100,
425               y       => 100,
426               width   => 300,
427               height  => 200,
428               '-href' => "image.png", #may also embed SVG, e.g. "image.svg"
429               id      => 'image_1'
430           );
431
432       Output:
433
434           <image xlink:href="image.png" x="100" y="100" width="300" height="200"/>
435
436   use
437       $tag = $svg->use(%attributes)
438
439       Retrieve the content from an entity within an SVG document and apply it
440       at (x,y) with width 'width' and height 'height' linked to image
441       resource '-href'.
442
443           $tag = $svg->use(
444               x       => 100,
445               y       => 100,
446               width   => 300,
447               height  => 200,
448               '-href' => "pic.svg#image_1",
449               id      => 'image_1'
450           );
451
452       Output:
453
454           <use xlink:href="pic.svg#image_1" x="100" y="100" width="300" height="200"/>
455
456       According to the SVG specification, the 'use' element in SVG can point
457       to a single element within an external SVG file.
458
459   polygon
460       $tag = $svg->polygon(%attributes)
461
462       Draw an n-sided polygon with vertices at points defined by a string of
463       the form 'x1,y1,x2,y2,x3,y3,... xy,yn'. The "get_path" method is
464       provided as a convenience to generate a suitable string from coordinate
465       data.
466
467           # a five-sided polygon
468           my $xv = [0, 2, 4, 5, 1];
469           my $yv = [0, 0, 2, 7, 5];
470
471           my $points = $svg->get_path(
472               x     =>  $xv,
473               y     =>  $yv,
474               -type =>'polygon'
475           );
476
477           my $poly = $svg->polygon(
478               %$points,
479               id    => 'pgon1',
480               style => \%polygon_style
481           );
482
483       SEE ALSO:
484
485       "polyline", "path", "get_path".
486
487   polyline
488       $tag = $svg->polyline(%attributes)
489
490       Draw an n-point polyline with points defined by a string of the form
491       'x1,y1,x2,y2,x3,y3,... xy,yn'. The "get_path" method is provided as a
492       convenience to generate a suitable string from coordinate data.
493
494           # a 10-pointsaw-tooth pattern
495           my $xv = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
496           my $yv = [0, 1, 0, 1, 0, 1, 0, 1, 0, 1];
497
498           my $points = $svg->get_path(
499               x       => $xv,
500               y       => $yv,
501               -type   => 'polyline',
502               -closed => 'true' #specify that the polyline is closed.
503           );
504
505           my $tag = $svg->polyline (
506               %$points,
507               id    =>'pline_1',
508               style => {
509                   'fill-opacity' => 0,
510                   'stroke'       => 'rgb(250,123,23)'
511               }
512           );
513
514   line
515       $tag = $svg->line(%attributes)
516
517       Draw a straight line between two points (x1,y1) and (x2,y2).
518
519           my $tag = $svg->line(
520               id => 'l1',
521               x1 =>  0,
522               y1 => 10,
523               x2 => 10,
524               y2 =>  0,
525           );
526
527       To draw multiple connected lines, use "polyline".
528
529   text
530       $text = $svg->text(%attributes)->cdata();
531
532       $text_path = $svg->text(-type=>'path'); $text_span =
533       $text_path->text(-type=>'span')->cdata('A'); $text_span =
534       $text_path->text(-type=>'span')->cdata('B'); $text_span =
535       $text_path->text(-type=>'span')->cdata('C');
536
537       Define the container for a text string to be drawn in the image.
538
539       Input:
540
541           -type     = path type (path | polyline | polygon)
542           -type     = text element type  (path | span | normal [default])
543
544           my $text1 = $svg->text(
545               id => 'l1',
546               x  => 10,
547               y  => 10
548           )->cdata('hello, world');
549
550           my $text2 = $svg->text(
551               id     => 'l1',
552               x      => 10,
553               y      => 10,
554               -cdata => 'hello, world',
555           );
556
557           my $text = $svg->text(
558               id    => 'tp',
559               x     => 10,
560               y     => 10,
561               -type => path,
562           )
563             ->text(id=>'ts' -type=>'span')
564             ->cdata('hello, world');
565
566       SEE ALSO:
567
568       "desc", "cdata".
569
570   title
571       $tag = $svg->title(%attributes)
572
573       Generate the title of the image.
574
575           my $tag = $svg->title(id=>'document-title')->cdata('This is the title');
576
577   desc
578       $tag = $svg->desc(%attributes)
579
580       Generate the description of the image.
581
582           my $tag = $svg->desc(id=>'document-desc')->cdata('This is a description');
583
584   comment
585       $tag = $svg->comment(@comments)
586
587       Generate the description of the image.
588
589           my $tag = $svg->comment('comment 1','comment 2','comment 3');
590
591   pi (Processing Instruction)
592       $tag = $svg->pi(@pi)
593
594       Generate a set of processing instructions
595
596           my $tag = $svg->pi('instruction one','instruction two','instruction three');
597
598           returns:
599             <lt>?instruction one?<gt>
600             <lt>?instruction two?<gt>
601             <lt>?instruction three?<gt>
602
603   script
604       $tag = $svg->script(%attributes)
605
606       Generate a script container for dynamic (client-side) scripting using
607       ECMAscript, Javascript or other compatible scripting language.
608
609           my $tag = $svg->script(-type=>"text/ecmascript");
610           #or my $tag = $svg->script();
611           #note that type ecmascript is not Mozilla compliant
612
613           # populate the script tag with cdata
614           # be careful to manage the javascript line ends.
615           # Use qq{text} or q{text} as appropriate.
616           # make sure to use the CAPITAL CDATA to poulate the script.
617           $tag->CDATA(qq{
618               function d() {
619               //simple display function
620                 for(cnt = 0; cnt < d.length; cnt++)
621                   document.write(d[cnt]);//end for loop
622               document.write("<BR>");//write a line break
623               }
624           });
625
626   path
627       $tag = $svg->path(%attributes)
628
629       Draw a path element. The path vertices may be provided as a parameter
630       or calculated using the "get_path" method.
631
632           # a 10-pointsaw-tooth pattern drawn with a path definition
633           my $xv = [0,1,2,3,4,5,6,7,8,9];
634           my $yv = [0,1,0,1,0,1,0,1,0,1];
635
636           $points = $svg->get_path(
637               x => $xv,
638               y => $yv,
639               -type   => 'path',
640               -closed => 'true'  #specify that the polyline is closed
641           );
642
643           $tag = $svg->path(
644               %$points,
645               id    => 'pline_1',
646               style => {
647                   'fill-opacity' => 0,
648                   'fill'   => 'green',
649                   'stroke' => 'rgb(250,123,23)'
650               }
651           );
652
653       SEE ALSO: "get_path".
654
655   get_path
656       $path = $svg->get_path(%attributes)
657
658       Returns the text string of points correctly formatted to be
659       incorporated into the multi-point SVG drawing object definitions (path,
660       polyline, polygon)
661
662       Input: attributes including:
663
664           -type     = path type (path | polyline | polygon)
665           x         = reference to array of x coordinates
666           y         = reference to array of y coordinates
667
668       Output: a hash reference consisting of the following key-value pair:
669
670           points    = the appropriate points-definition string
671           -type     = path|polygon|polyline
672           -relative = 1 (define relative position rather than absolute position)
673           -closed   = 1 (close the curve - path and polygon only)
674
675           #generate an open path definition for a path.
676           my ($points,$p);
677           $points = $svg->get_path(x=&gt\@x,y=&gt\@y,-relative=&gt1,-type=&gt'path');
678
679           #add the path to the SVG document
680           my $p = $svg->path(%$path, style=>\%style_definition);
681
682           #generate an closed path definition for a a polyline.
683           $points = $svg->get_path(
684               x=>\@x,
685               y=>\@y,
686               -relative=>1,
687               -type=>'polyline',
688               -closed=>1
689           ); # generate a closed path definition for a polyline
690
691           # add the polyline to the SVG document
692           $p = $svg->polyline(%$points, id=>'pline1');
693
694       Aliases: get_path set_path
695
696   animate
697       $tag = $svg->animate(%attributes)
698
699       Generate an SMIL animation tag. This is allowed within any nonempty
700       tag. Refer to the W3C for detailed information on the subtleties of the
701       animate SMIL commands.
702
703       Inputs: -method = Transform | Motion | Color
704
705         my $an_ellipse = $svg->ellipse(
706             cx     => 30,
707             cy     => 150,
708             rx     => 10,
709             ry     => 10,
710             id     => 'an_ellipse',
711             stroke => 'rgb(130,220,70)',
712             fill   =>'rgb(30,20,50)'
713         );
714
715         $an_ellipse-> animate(
716             attributeName => "cx",
717             values        => "20; 200; 20",
718             dur           => "10s",
719             repeatDur     => 'indefinite'
720         );
721
722         $an_ellipse-> animate(
723             attributeName => "rx",
724             values        => "10;30;20;100;50",
725             dur           => "10s",
726             repeatDur     => 'indefinite',
727         );
728
729         $an_ellipse-> animate(
730             attributeName => "ry",
731             values        => "30;50;10;20;70;150",
732             dur           => "15s",
733             repeatDur     => 'indefinite',
734         );
735
736         $an_ellipse-> animate(
737             attributeName=>"rx",values=>"30;75;10;100;20;20;150",
738             dur=>"20s", repeatDur=>'indefinite');
739
740         $an_ellipse-> animate(
741             attributeName=>"fill",values=>"red;green;blue;cyan;yellow",
742             dur=>"5s", repeatDur=>'indefinite');
743
744         $an_ellipse-> animate(
745             attributeName=>"fill-opacity",values=>"0;1;0.5;0.75;1",
746             dur=>"20s",repeatDur=>'indefinite');
747
748         $an_ellipse-> animate(
749             attributeName=>"stroke-width",values=>"1;3;2;10;5",
750             dur=>"20s",repeatDur=>'indefinite');
751
752   group
753       $tag = $svg->group(%attributes)
754
755       Define a group of objects with common properties. Groups can have
756       style, animation, filters, transformations, and mouse actions assigned
757       to them.
758
759           $tag = $svg->group(
760               id        => 'xvs000248',
761               style     => {
762                   'font'      => [ qw( Arial Helvetica sans ) ],
763                   'font-size' => 10,
764                   'fill'      => 'red',
765               },
766               transform => 'rotate(-45)'
767           );
768
769   defs
770       $tag = $svg->defs(%attributes)
771
772       define a definition segment. A Defs requires children when defined
773       using SVG.pm
774
775           $tag = $svg->defs(id  =>  'def_con_one',);
776
777   style
778       $svg->tag('style', %styledef);
779
780       Sets/Adds style-definition for the following objects being created.
781
782       Style definitions apply to an object and all its children for all
783       properties for which the value of the property is not redefined by the
784       child.
785
786         $tag = $SVG->style(%attributes)
787
788       Generate a style container for inline or xlink:href based styling
789       instructions
790
791           my $tag = $SVG->style(type=>"text/css");
792
793           # Populate the style tag with cdata.
794           # Be careful to manage the line ends.
795           # Use qq{text}, where text is the script
796
797           $tag1->CDATA(qq{
798               rect     fill:red;stroke:green;
799               circle   fill:red;stroke:orange;
800               ellipse  fill:none;stroke:yellow;
801               text     fill:black;stroke:none;
802           });
803
804           # Create a external CSS stylesheet reference
805           my $tag2 = $SVG->style(type=>"text/css", -href="/resources/example.css");
806
807   mouseaction
808       $svg->mouseaction(%attributes)
809
810       Sets/Adds mouse action definitions for tag
811
812   attrib
813         $svg->attrib($name, $value)
814
815       Sets/Adds attributes of an element.
816
817       Retrieve an attribute:
818
819           $svg->attrib($name);
820
821       Set a scalar attribute:
822
823           $SVG->attrib $name, $value
824
825       Set a list attribute:
826
827           $SVG->attrib $name, \@value
828
829       Set a hash attribute (i.e. style definitions):
830
831           $SVG->attrib $name, \%value
832
833       Remove an attribute:
834
835           $svg->attrib($name,undef);
836
837       Aliases: attr attribute
838
839       Sets/Replaces attributes for a tag.
840
841   cdata
842       $svg->cdata($text)
843
844       Sets cdata to $text. SVG.pm allows you to set cdata for any tag. If the
845       tag is meant to be an empty tag, SVG.pm will not complain, but the
846       rendering agent will fail. In the SVG DTD, cdata is generally only
847       meant for adding text or script content.
848
849           $svg->text(
850               style => {
851                   'font'      => 'Arial',
852                   'font-size' => 20
853               })->cdata('SVG.pm is a perl module on CPAN!');
854
855           my $text = $svg->text( style => { 'font' => 'Arial', 'font-size' => 20 } );
856           $text->cdata('SVG.pm is a perl module on CPAN!');
857
858       Result:
859
860           <text style="font: Arial; font-size: 20">SVG.pm is a perl module on CPAN!</text>
861
862       SEE ALSO:
863
864       "CDATA", "desc", "title", "text", "script".
865
866   cdata_noxmlesc
867        $script = $svg->script();
868        $script->cdata_noxmlesc($text);
869
870       Generates cdata content for text and similar tags which do not get xml-
871       escaped.  In othe words, does not parse the content and inserts the
872       exact string into the cdata location.
873
874   CDATA
875        $script = $svg->script();
876        $script->CDATA($text);
877
878       Generates a <![CDATA[ ... ]]> tag with the contents of $text rendered
879       exactly as supplied. SVG.pm allows you to set cdata for any tag. If the
880       tag is meant to be an empty tag, SVG.pm will not complain, but the
881       rendering agent will fail. In the SVG DTD, cdata is generally only
882       meant for adding text or script content.
883
884             my $text = qq{
885               var SVGDoc;
886               var groups = new Array();
887               var last_group;
888
889               /*****
890               *
891               *   init
892               *
893               *   Find this SVG's document element
894               *   Define members of each group by id
895               *
896               *****/
897               function init(e) {
898                   SVGDoc = e.getTarget().getOwnerDocument();
899                   append_group(1, 4, 6); // group 0
900                   append_group(5, 4, 3); // group 1
901                   append_group(2, 3);    // group 2
902               }};
903               $svg->script()->CDATA($text);
904
905       Result:
906
907           E<lt>script E<gt>
908             <gt>![CDATA[
909               var SVGDoc;
910               var groups = new Array();
911               var last_group;
912
913               /*****
914               *
915               *   init
916               *
917               *   Find this SVG's document element
918               *   Define members of each group by id
919               *
920               *****/
921               function init(e) {
922                   SVGDoc = e.getTarget().getOwnerDocument();
923                   append_group(1, 4, 6); // group 0
924                   append_group(5, 4, 3); // group 1
925                   append_group(2, 3);    // group 2
926               }
927               ]]E<gt>
928
929       SEE ALSO: "cdata", "script".
930
931   xmlescp and xmlescape
932       $string = $svg->xmlescp($string) $string = $svg->xmlesc($string)
933       $string = $svg->xmlescape($string)
934
935       SVG module does not xml-escape characters that are incompatible with
936       the XML specification. xmlescp and xmlescape provides this
937       functionality. It is a helper function which generates an XML-escaped
938       string for reserved characters such as ampersand, open and close
939       brackets, etcetera.
940
941       The behaviour of xmlesc is to apply the following transformation to the
942       input string $s:
943
944           $s=~s/&(?!#(x\w\w|\d+?);)/&amp;/g;
945           $s=~s/>/&gt;/g;
946           $s=~s/</&lt;/g;
947           $s=~s/\"/&quot;/g;
948           $s=~s/\'/&apos;/g;
949           $s=~s/([\x00-\x08\x0b\x1f])/''/eg;
950           $s=~s/([\200-\377])/'&#'.ord($1).';'/ge;
951
952   filter
953       $tag = $svg->filter(%attributes)
954
955       Generate a filter. Filter elements contain "fe" filter sub-elements.
956
957           my $filter = $svg->filter(
958               filterUnits=>"objectBoundingBox",
959               x=>"-10%",
960               y=>"-10%",
961               width=>"150%",
962               height=>"150%",
963               filterUnits=>'objectBoundingBox'
964           );
965
966           $filter->fe();
967
968       SEE ALSO: "fe".
969
970   fe
971       $tag = $svg->fe(-type=>'type', %attributes)
972
973       Generate a filter sub-element. Must be a child of a "filter" element.
974
975           my $fe = $svg->fe(
976               -type     => 'DiffuseLighting'  # required - element name omitting 'fe'
977               id        => 'filter_1',
978               style     => {
979                   'font'      => [ qw(Arial Helvetica sans) ],
980                   'font-size' => 10,
981                   'fill'      => 'red',
982               },
983               transform => 'rotate(-45)'
984           );
985
986       Note that the following filter elements are currently supported: Also
987       note that the elelemts are defined in lower case in the module, but as
988       of version 2.441, any case combination is allowed.
989
990   * feBlend
991   * feColorMatrix
992   * feComponentTransfer
993   * feComposite
994   * feConvolveMatrix
995   * feDiffuseLighting
996   * feDisplacementMap
997   * feDistantLight
998   * feFlood
999   * feFuncA
1000   * feFuncB
1001   * feFuncG
1002   * feFuncR
1003   * feGaussianBlur
1004   * feImage
1005   * feMerge
1006   * feMergeNode
1007   * feMorphology
1008   * feOffset
1009   * fePointLight
1010   * feSpecularLighting
1011   * feSpotLight
1012   * feTile
1013   * feTurbulence
1014       SEE ALSO: "filter".
1015
1016   pattern
1017       $tag = $svg->pattern(%attributes)
1018
1019       Define a pattern for later reference by url.
1020
1021           my $pattern = $svg->pattern(
1022               id     => "Argyle_1",
1023               width  => "50",
1024               height => "50",
1025               patternUnits        => "userSpaceOnUse",
1026               patternContentUnits => "userSpaceOnUse"
1027           );
1028
1029   set
1030       $tag = $svg->set(%attributes)
1031
1032       Set a definition for an SVG object in one section, to be referenced in
1033       other sections as needed.
1034
1035           my $set = $svg->set(
1036               id     => "Argyle_1",
1037               width  => "50",
1038               height => "50",
1039               patternUnits        => "userSpaceOnUse",
1040               patternContentUnits => "userSpaceOnUse"
1041           );
1042
1043   stop
1044       $tag = $svg->stop(%attributes)
1045
1046       Define a stop boundary for "gradient"
1047
1048          my $pattern = $svg->stop(
1049              id     => "Argyle_1",
1050              width  => "50",
1051              height => "50",
1052              patternUnits        => "userSpaceOnUse",
1053              patternContentUnits => "userSpaceOnUse"
1054          );
1055
1056   gradient
1057       $tag = $svg->gradient(%attributes)
1058
1059       Define a color gradient. Can be of type linear or radial
1060
1061           my $gradient = $svg->gradient(
1062               -type => "linear",
1063               id    => "gradient_1"
1064           );
1065

GENERIC ELEMENT METHODS

1067       The following elements are generically supported by SVG:
1068
1069   * altGlyph
1070   * altGlyphDef
1071   * altGlyphItem
1072   * clipPath
1073   * color-profile
1074   * cursor
1075   * definition-src
1076   * font-face-format
1077   * font-face-name
1078   * font-face-src
1079   * font-face-url
1080   * foreignObject
1081   * glyph
1082   * glyphRef
1083   * hkern
1084   * marker
1085   * mask
1086   * metadata
1087   * missing-glyph
1088   * mpath
1089   * switch
1090   * symbol
1091   * tref
1092   * view
1093   * vkern
1094       See e.g. "pattern" for an example of the use of these methods.
1095

METHODS IMPORTED BY SVG::DOM

1097       The following SVG::DOM elements are accessible through SVG:
1098
1099   * getChildren
1100   * getFirstChild
1101   * getNextChild
1102   * getLastChild
1103   * getParent
1104   * getParentElement
1105   * getSiblings
1106   * getElementByID
1107   * getElementID
1108   * getElements
1109   * getElementName
1110   * getType
1111   * getAttributes
1112   * getAttribute
1113   * setAttributes
1114   * setAttribute
1115   * insertBefore
1116   * insertAfter
1117   * insertSiblingBefore
1118   * insertSiblingAfter
1119   * replaceChild
1120   * removeChild
1121   * cloneNode

Methods

1123       SVG provides both explicit and generic element constructor methods.
1124       Explicit generators are generally (with a few exceptions) named for the
1125       element they generate. If a tag method is required for a tag containing
1126       hyphens, the method name replaces the hyphen with an underscore. ie: to
1127       generate tag <column-heading id="new"> you would use method
1128       $svg->column_heading(id=>'new').
1129
1130       All element constructors take a hash of element attributes and options;
1131       element attributes such as 'id' or 'border' are passed by name, while
1132       options for the method (such as the type of an element that supports
1133       multiple alternate forms) are passed preceded by a hyphen, e.g '-type'.
1134       Both types may be freely intermixed; see the "fe" method and code
1135       examples throughout the documentation for more examples.
1136
1137   new (constructor)
1138       $svg = SVG->new(%attributes)
1139
1140       Creates a new SVG object. Attributes of the document SVG element be
1141       passed as an optional list of key value pairs. Additionally, SVG
1142       options (prefixed with a hyphen) may be set on a per object basis:
1143
1144           my $svg1 = SVG->new;
1145
1146           my $svg2 = SVG->new(id => 'document_element');
1147
1148           my $svg3 = SVG->new(
1149               -printerror => 1,
1150               -raiseerror => 0,
1151               -indent     => '  ',
1152               -elsep      => "\n",  # element line (vertical) separator
1153               -docroot    => 'svg', # default document root element (SVG specification assumes svg). Defaults to 'svg' if undefined
1154               -xml_xlink  => 'http://www.w3.org/1999/xlink', # required by Mozilla's embedded SVG engine
1155               -sysid      => 'abc', # optional system identifier
1156               -pubid      => "-//W3C//DTD SVG 1.0//EN", # public identifier default value is "-//W3C//DTD SVG 1.0//EN" if undefined
1157               -namespace  => 'mysvg',
1158               -inline     => 1
1159               id          => 'document_element',
1160               width       => 300,
1161               height      => 200,
1162           );
1163
1164       Default SVG options may also be set in the import list. See "EXPORTS"
1165       above for more on the available options.
1166
1167       Furthermore, the following options:
1168
1169           -version
1170           -encoding
1171           -standalone
1172           -namespace
1173           -inline
1174           -pubid (formerly -identifier)
1175           -sysid (standalone)
1176
1177       may also be set in xmlify, overriding any corresponding values set in
1178       the SVG->new declaration
1179
1180   xmlify  (alias: to_xml render serialize serialise )
1181       $string = $svg->xmlify(%attributes);
1182
1183       Returns xml representation of svg document.
1184
1185       XML Declaration
1186
1187           Name               Default Value
1188           -version           '1.0'
1189           -encoding          'UTF-8'
1190           -standalone        'yes'
1191           -namespace         'svg' - namespace prefix for elements.
1192                                      Can also be used in any element method to over-ride
1193                                      the current namespace prefix. Make sure to have
1194                                      declared the prefix before using it.
1195           -inline            '0' - If '1', then this is an inline document.
1196           -pubid             '-//W3C//DTD SVG 1.0//EN';
1197           -sysid             'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd'
1198
1199   perlify ()
1200       return the perl code which generates the SVG document as it currently
1201       exists.
1202
1203   toperl ()
1204       Alias for method perlify()
1205

AUTHOR

1207       Ronan Oger, RO IT Systemms GmbH, cpan@roitsystems.com
1208

MAINTAINER

1210       Gabor Szabo <http://szabgab.com/>
1211

CREDITS

1213       I would like to thank the following people for contributing to this
1214       module with patches, testing, suggestions, and other nice tidbits:
1215
1216       Peter Wainwright, Excellent ideas, beta-testing, writing SVG::Parser
1217       and much of SVG::DOM.  Fredo, http://www.penguin.at0.net/~fredo/ -
1218       provided example code and initial feedback for early SVG.pm versions
1219       and the idea of a simplified svg generator.  Adam Schneider, Brial
1220       Pilpré, Ian Hickson Steve Lihn, Allen Day Martin Owens - SVG::DOM
1221       improvements in version 3.34
1222

COPYRIGHT & LICENSE

1224       Copyright 2001- Ronan Oger
1225
1226       The modules in the SVG distribution are distributed under the same
1227       license as Perl itself. It is provided free of warranty and may be re-
1228       used freely.
1229

ARTICLES

1231       SVG using Perl <http://szabgab.com/svg-using-perl.html>
1232
1233       SVG - Scalable Vector Graphics with Perl
1234       <http://perlmaven.com/scalable-vector-graphics-with-perl>
1235
1236       Combining SVG and PSGI <http://perlmaven.com/combining-svg-and-psgi>
1237