SVG(3pm) - f29

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, SVG::Parser, SVG::Extension
74
75   Converting SVG to PNG and other raster image formats
76       The convert command of <http://www.imagemagick.org/> (also via
77       Image::Magick ) can convert SVG files to PNG and other formats.
78
79       Image::LibRSVG can convert SVG to other format.
80

EXAMPLES

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

DESCRIPTION

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

METHODS

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

GENERIC ELEMENT METHODS

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

METHODS IMPORTED BY SVG::DOM

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

Methods

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

AUTHOR

1205       Ronan Oger, RO IT Systemms GmbH, cpan@roitsystems.com
1206

MAINTAINER

1208       Gabor Szabo <http://szabgab.com/>
1209

CREDITS

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

COPYRIGHT & LICENSE

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

ARTICLES

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