SVG(3pm) - f38

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 contains
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 is 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             -->
221

METHODS

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