line
stmt
bran
cond
sub
pod
time
code
1
package SVG;
2
3
25
25
1388118
use strict;
25
210
25
624
4
25
25
116
use warnings;
25
36
25
559
5
6
25
25
8536
use SVG::XML;
25
54
25
1964
7
25
25
9738
use parent qw(SVG::Element SVG::Extension);
25
6881
25
128
8
25
25
1474
use Scalar::Util qw/weaken/;
25
42
25
24236
9
10
our $VERSION = '2.87';
11
12
=pod
13
14
=encoding UTF-8
15
16
=head1 NAME
17
18
SVG - Perl extension for generating Scalable Vector Graphics (SVG) documents.
19
20
=head1 SYNOPSIS
21
22
#!/usr/bin/perl
23
use strict;
24
use warnings;
25
use SVG;
26
27
# create an SVG object
28
my $svg= SVG->new( width => 200, height => 200);
29
30
# use explicit element constructor to generate a group element
31
my $y = $svg->group(
32
id => 'group_y',
33
style => {
34
stroke => 'red',
35
fill => 'green'
36
},
37
);
38
39
# add a circle to the group
40
$y->circle( cx => 100, cy => 100, r => 50, id => 'circle_in_group_y' );
41
42
# or, use the generic 'tag' method to generate a group element by name
43
my $z = $svg->tag('g',
44
id => 'group_z',
45
style => {
46
stroke => 'rgb(100,200,50)',
47
fill => 'rgb(10,100,150)'
48
}
49
);
50
51
# create and add a circle using the generic 'tag' method
52
$z->tag('circle', cx => 50, cy => 50, r => 100, id => 'circle_in_group_z');
53
54
# create an anchor on a rectangle within a group within the group z
55
my $k = $z->anchor(
56
id => 'anchor_k',
57
-href => 'http://test.hackmare.com/',
58
target => 'new_window_0'
59
)->rectangle(
60
x => 20, y => 50,
61
width => 20, height => 30,
62
rx => 10, ry => 5,
63
id => 'rect_k_in_anchor_k_in_group_z'
64
);
65
66
# now render the SVG object, implicitly use svg namespace
67
print $svg->xmlify;
68
69
# or render a child node of the SVG object without rendering the entire object
70
print $k->xmlify; #renders the anchor $k above containing a rectangle, but does not
71
#render any of the ancestor nodes of $k
72
73
74
# or, explicitly use svg namespace and generate a document with its own DTD
75
print $svg->xmlify(-namespace=>'svg');
76
77
# or, explicitly use svg namespace and generate an inline docunent
78
print $svg->xmlify(
79
-namespace => "svg",
80
-pubid => "-//W3C//DTD SVG 1.0//EN",
81
-inline => 1
82
);
83
84
85
See the other modules in this distribution:
86
L,
87
L,
88
L,
89
and L.
90
91
See L for reading SVG files as C objects.
92
93
=head2 Converting SVG to PNG and other raster image formats
94
95
The B command of L (also via L ) can convert SVG files to PNG
96
and other formats.
97
98
L can convert SVG to other format.
99
100
=head1 EXAMPLES
101
102
examples/circle.pl generates the following image:
103
104
105
106
107
I am a title
108
109
110
111
112
113
114
That you can either embed directly into HTML or can include it using:
115
116
117
118
=for HTML
119
120
(The image was converted to png using L. See the svg2png.pl script in the examples directory.)
121
122
=for HTML
123
124
See also the B directory in this distribution which contains several fully documented examples.
125
126
=head1 DESCRIPTION
127
128
SVG is a 100% Perl module which generates a nested data structure containing the
129
DOM representation of an SVG (Scalable Vector Graphics) image. Using SVG, you
130
can generate SVG objects, embed other SVG instances into it, access the DOM
131
object, create and access javascript, and generate SMIL animation content.
132
133
=head2 General Steps to generating an SVG document
134
135
Generating SVG is a simple three step process:
136
137
=over 4
138
139
=item 1 Construct a new SVG object with L<"new">.
140
141
=item 2 Call element constructors such as L<"circle"> and L<"path"> to create SVG elements.
142
143
=item 3 Render the SVG object into XML using the L<"xmlify"> method.
144
145
=back
146
147
The L method takes a number of optional arguments that control how SVG
148
renders the object into XML, and in particular determine whether a standalone
149
SVG document or an inline SVG document fragment is generated:
150
151
=head2 -standalone
152
153
A complete SVG document with its own associated DTD. A namespace for the SVG
154
elements may be optionally specified.
155
156
=head2 -inline
157
158
An inline SVG document fragment with no DTD that is embedded within other XML
159
content. As with standalone documents, an alternate namespace may be specified.
160
161
No XML content is generated until the third step is reached. Up until this
162
point, all constructed element definitions reside in a DOM-like data structure
163
from which they can be accessed and modified.
164
165
=head2 EXPORTS
166
167
None. However, SVG permits both options and additional element methods to be
168
specified in the import list. These options and elements are then available
169
for all SVG instances that are created with the L constructor. For example,
170
to change the indent string to two spaces per level:
171
172
use SVG (-indent => " ");
173
174
With the exception of -auto, all options may also be specified to the L
175
constructor. The currently supported options and their default value are:
176
177
# processing options
178
-auto => 0, # permit arbitrary autoloading of all unrecognised elements
179
-printerror => 1, # print error messages to STDERR
180
-raiseerror => 1, # die on errors (implies -printerror)
181
182
# rendering options
183
-indent => "\t", # what to indent with
184
-elsep => "\n", # element line (vertical) separator
185
# (note that not all agents ignor trailing blanks)
186
-nocredits => 0, # enable/disable credit note comment
187
-namespace => '', # The root element's (and it's children's) namespace prefix
188
189
# XML and Doctype declarations
190
-inline => 0, # inline or stand alone
191
-docroot => 'svg', # The document's root element
192
-version => '1.0',
193
-extension => '',
194
-encoding => 'UTF-8',
195
-xml_svg => 'http://www.w3.org/2000/svg', # the svg xmlns attribute
196
-xml_xlink => 'http://www.w3.org/1999/xlink', # the svg tag xmlns:xlink attribute
197
-standalone => 'yes',
198
-pubid => "-//W3C//DTD SVG 1.0//EN", # formerly -identifier
199
-sysid => 'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd', # the system id
200
201
SVG also allows additional element generation methods to be specified in the
202
import list. For example to generate 'star' and 'planet' element methods:
203
204
use SVG qw(star planet);
205
206
or:
207
208
use SVG ("star","planet");
209
210
This will add 'star' to the list of elements supported by SVG.pm (but not of
211
course other SVG parsers...). Alternatively the '-auto' option will allow
212
any unknown method call to generate an element of the same name:
213
214
use SVG (-auto => 1, "star", "planet");
215
216
Any elements specified explicitly (as 'star' and 'planet' are here) are
217
predeclared; other elements are defined as and when they are seen by Perl. Note
218
that enabling '-auto' effectively disables compile-time syntax checking for
219
valid method names.
220
221
use SVG (
222
-auto => 0,
223
-indent => " ",
224
-raiseerror => 0,
225
-printerror => 1,
226
"star", "planet", "moon"
227
);
228
229
=head2 Default SVG tag
230
231
The Default SVG tag will generate the following XML:
232
233
$svg = SVG->new;
234
print $svg->xmlify;
235
236
Resulting XML snippet:
237
238
239
240
241
245
246
=head1 METHODS
247
248
SVG provides both explicit and generic element constructor methods. Explicit
249
generators are generally (with a few exceptions) named for the element they
250
generate. If a tag method is required for a tag containing hyphens, the method
251
name replaces the hyphen with an underscore. ie: to generate tag
252
you would use method $svg->column_heading(id=>'new').
253
254
255
All element constructors take a hash of element attributes and options;
256
element attributes such as 'id' or 'border' are passed by name, while options for the
257
method (such as the type of an element that supports multiple alternate forms)
258
are passed preceded by a hyphen, e.g '-type'. Both types may be freely
259
intermixed; see the L<"fe"> method and code examples throughout the documentation
260
for more examples.
261
262
=head2 new (constructor)
263
264
$svg = SVG->new(%attributes)
265
266
Creates a new SVG object. Attributes of the document SVG element be passed as
267
an optional list of key value pairs. Additionally, SVG options (prefixed with
268
a hyphen) may be set on a per object basis:
269
270
my $svg1 = SVG->new;
271
272
my $svg2 = SVG->new(id => 'document_element');
273
274
my $svg3 = SVG->new(
275
-printerror => 1,
276
-raiseerror => 0,
277
-indent => ' ',
278
-docroot => 'svg', #default document root element (SVG specification assumes svg). Defaults to 'svg' if undefined
279
-sysid => 'abc', #optional system identifyer
280
-pubid => "-//W3C//DTD SVG 1.0//EN", #public identifyer default value is "-//W3C//DTD SVG 1.0//EN" if undefined
281
-namespace => 'mysvg',
282
-inline => 1
283
id => 'document_element',
284
width => 300,
285
height => 200,
286
);
287
288
BsvgE> root element.>
289
290
Default SVG options may also be set in the import list. See L<"EXPORTS"> above
291
for more on the available options.
292
293
Furthermore, the following options:
294
295
296
-version
297
-encoding
298
-standalone
299
-namespace Defines the document or element level namespace. The order of assignment priority is element,document .
300
-inline
301
-identifier
302
-nostub
303
-dtd (standalone)
304
305
may also be set in xmlify, overriding any corresponding values set in the SVG->new declaration
306
307
308
=head2 xmlify (alias: to_xml render serialise serialize)
309
310
$string = $svg->xmlify(%attributes);
311
312
Returns xml representation of svg document.
313
314
B
315
316
Name Default Value
317
-version '1.0'
318
-encoding 'UTF-8'
319
-standalone 'yes'
320
-namespace 'svg' - namespace for elements
321
-inline '0' - If '1', then this is an inline document.
322
-pubid '-//W3C//DTD SVG 1.0//EN';
323
-dtd (standalone) 'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd'
324
325
326
=head2 tag (alias: element)
327
328
$tag = $svg->tag($name, %attributes)
329
330
Generic element generator. Creates the element named $name with the attributes
331
specified in %attributes. This method is the basis of most of the explicit
332
element generators.
333
334
my $tag = $svg->tag('g', transform=>'rotate(-45)');
335
336
337
=head2 anchor
338
339
$tag = $svg->anchor(%attributes)
340
341
Generate an anchor element. Anchors are put around objects to make them
342
'live' (i.e. clickable). It therefore requires a drawn object or group element
343
as a child.
344
345
=head3 optional anchor attributes
346
347
The following attributes are expected for anchor tags (any any tags which use -href links):
348
349
=head2 -href required
350
351
=head2 -type optional
352
353
=head2 -role optional
354
355
=head2 -title optional
356
357
=head2 -show optional
358
359
=head2 -arcrole optional
360
361
=head2 -actuate optional
362
363
=head2 target optional
364
365
For more information on the options, refer to the w3c XLink specification at
366
L
367
368
B
369
370
# generate an anchor
371
$tag = $SVG->anchor(
372
-href=>'http://here.com/some/simpler/SVG.SVG'
373
-title => 'new window 2 example title',
374
-actuate => 'onLoad',
375
-show=> 'embed',
376
377
);
378
379
For more information about the options above, refer to Link section in the SVG recommendation: L
380
381
# add a circle to the anchor. The circle can be clicked on.
382
$tag->circle(cx => 10, cy => 10, r => 1);
383
384
# more complex anchor with both URL and target
385
$tag = $SVG->anchor(
386
-href => 'http://somewhere.org/some/other/page.html',
387
target => 'new_window'
388
);
389
390
391
# generate an anchor
392
$tag = $svg->anchor(
393
-href=>'http://here.com/some/simpler/svg.svg'
394
);
395
# add a circle to the anchor. The circle can be clicked on.
396
$tag->circle(cx => 10, cy => 10, r => 1);
397
398
# more complex anchor with both URL and target
399
$tag = $svg->anchor(
400
-href => 'http://somewhere.org/some/other/page.html',
401
target => 'new_window'
402
);
403
404
=head2 circle
405
406
$tag = $svg->circle(%attributes)
407
408
Draw a circle at (cx,cy) with radius r.
409
410
my $tag = $svg->circle(cx => 4, cy => 2, r => 1);
411
412
=head2 ellipse
413
414
$tag = $svg->ellipse(%attributes)
415
416
Draw an ellipse at (cx,cy) with radii rx,ry.
417
418
use SVG;
419
420
# create an SVG object
421
my $svg= SVG->new( width => 200, height => 200);
422
423
my $tag = $svg->ellipse(
424
cx => 10,
425
cy => 10,
426
rx => 5,
427
ry => 7,
428
id => 'ellipse',
429
style => {
430
'stroke' => 'red',
431
'fill' => 'green',
432
'stroke-width' => '4',
433
'stroke-opacity' => '0.5',
434
'fill-opacity' => '0.2',
435
}
436
);
437
438
See The B
439
440
=for HTML
441
442
=head2 rectangle (alias: rect)
443
444
$tag = $svg->rectangle(%attributes)
445
446
Draw a rectangle at (x,y) with width 'width' and height 'height' and side radii
447
'rx' and 'ry'.
448
449
$tag = $svg->rectangle(
450
x => 10,
451
y => 20,
452
width => 4,
453
height => 5,
454
rx => 5.2,
455
ry => 2.4,
456
id => 'rect_1'
457
);
458
459
=head2 image
460
461
$tag = $svg->image(%attributes)
462
463
Draw an image at (x,y) with width 'width' and height 'height' linked to image
464
resource '-href'. See also L<"use">.
465
466
$tag = $svg->image(
467
x => 100,
468
y => 100,
469
width => 300,
470
height => 200,
471
'-href' => "image.png", #may also embed SVG, e.g. "image.svg"
472
id => 'image_1'
473
);
474
475
B
476
477
478
479
=head2 use
480
481
$tag = $svg->use(%attributes)
482
483
Retrieve the content from an entity within an SVG document and apply it at
484
(x,y) with width 'width' and height 'height' linked to image resource '-href'.
485
486
$tag = $svg->use(
487
x => 100,
488
y => 100,
489
width => 300,
490
height => 200,
491
'-href' => "pic.svg#image_1",
492
id => 'image_1'
493
);
494
495
B
496
497
498
499
According to the SVG specification, the 'use' element in SVG can point to a
500
single element within an external SVG file.
501
502
=head2 polygon
503
504
$tag = $svg->polygon(%attributes)
505
506
Draw an n-sided polygon with vertices at points defined by a string of the form
507
'x1,y1,x2,y2,x3,y3,... xy,yn'. The L<"get_path"> method is provided as a
508
convenience to generate a suitable string from coordinate data.
509
510
# a five-sided polygon
511
my $xv = [0, 2, 4, 5, 1];
512
my $yv = [0, 0, 2, 7, 5];
513
514
my $points = $svg->get_path(
515
x => $xv,
516
y => $yv,
517
-type =>'polygon'
518
);
519
520
my $poly = $svg->polygon(
521
%$points,
522
id => 'pgon1',
523
style => \%polygon_style
524
);
525
526
SEE ALSO:
527
528
L<"polyline">, L<"path">, L<"get_path">.
529
530
=head2 polyline
531
532
$tag = $svg->polyline(%attributes)
533
534
Draw an n-point polyline with points defined by a string of the form
535
'x1,y1,x2,y2,x3,y3,... xy,yn'. The L<"get_path"> method is provided as a
536
convenience to generate a suitable string from coordinate data.
537
538
# a 10-pointsaw-tooth pattern
539
my $xv = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
540
my $yv = [0, 1, 0, 1, 0, 1, 0, 1, 0, 1];
541
542
my $points = $svg->get_path(
543
x => $xv,
544
y => $yv,
545
-type => 'polyline',
546
-closed => 'true' #specify that the polyline is closed.
547
);
548
549
my $tag = $svg->polyline (
550
%$points,
551
id =>'pline_1',
552
style => {
553
'fill-opacity' => 0,
554
'stroke' => 'rgb(250,123,23)'
555
}
556
);
557
558
=head2 line
559
560
$tag = $svg->line(%attributes)
561
562
Draw a straight line between two points (x1,y1) and (x2,y2).
563
564
my $tag = $svg->line(
565
id => 'l1',
566
x1 => 0,
567
y1 => 10,
568
x2 => 10,
569
y2 => 0,
570
);
571
572
To draw multiple connected lines, use L<"polyline">.
573
574
=head2 text
575
576
$text = $svg->text(%attributes)->cdata();
577
578
$text_path = $svg->text(-type=>'path');
579
$text_span = $text_path->text(-type=>'span')->cdata('A');
580
$text_span = $text_path->text(-type=>'span')->cdata('B');
581
$text_span = $text_path->text(-type=>'span')->cdata('C');
582
583
Define the container for a text string to be drawn in the image.
584
585
B
586
587
-type = path type (path | polyline | polygon)
588
-type = text element type (path | span | normal [default])
589
590
my $text1 = $svg->text(
591
id => 'l1',
592
x => 10,
593
y => 10
594
)->cdata('hello, world');
595
596
my $text2 = $svg->text(
597
id => 'l1',
598
x => 10,
599
y => 10,
600
-cdata => 'hello, world',
601
);
602
603
my $text = $svg->text(
604
id => 'tp',
605
x => 10,
606
y => 10,
607
-type => path,
608
)
609
->text(id=>'ts' -type=>'span')
610
->cdata('hello, world');
611
612
SEE ALSO:
613
614
L<"desc">, L<"cdata">.
615
616
=head2 title
617
618
$tag = $svg->title(%attributes)
619
620
Generate the title of the image.
621
622
my $tag = $svg->title(id=>'document-title')->cdata('This is the title');
623
624
=head2 desc
625
626
$tag = $svg->desc(%attributes)
627
628
Generate the description of the image.
629
630
my $tag = $svg->desc(id=>'document-desc')->cdata('This is a description');
631
632
=head2 comment
633
634
$tag = $svg->comment(@comments)
635
636
Generate the description of the image.
637
638
my $tag = $svg->comment('comment 1','comment 2','comment 3');
639
640
=head2 pi (Processing Instruction)
641
642
$tag = $svg->pi(@pi)
643
644
Generate a set of processing instructions
645
646
my $tag = $svg->pi('instruction one','instruction two','instruction three');
647
648
returns:
649
?instruction one?
650
?instruction two?
651
?instruction three?
652
653
=head2 script
654
655
$tag = $svg->script(%attributes)
656
657
Generate a script container for dynamic (client-side) scripting using
658
ECMAscript, Javascript or other compatible scripting language.
659
660
my $tag = $svg->script(-type=>"text/ecmascript");
661
#or my $tag = $svg->script();
662
#note that type ecmascript is not Mozilla compliant
663
664
# populate the script tag with cdata
665
# be careful to manage the javascript line ends.
666
# Use qq{text} or q{text} as appropriate.
667
# make sure to use the CAPITAL CDATA to poulate the script.
668
$tag->CDATA(qq{
669
function d() {
670
//simple display function
671
for(cnt = 0; cnt < d.length; cnt++)
672
document.write(d[cnt]);//end for loop
673
document.write(" ");//write a line break
674
}
675
});
676
677
=head2 path
678
679
$tag = $svg->path(%attributes)
680
681
Draw a path element. The path vertices may be provided as a parameter or
682
calculated using the L<"get_path"> method.
683
684
# a 10-pointsaw-tooth pattern drawn with a path definition
685
my $xv = [0,1,2,3,4,5,6,7,8,9];
686
my $yv = [0,1,0,1,0,1,0,1,0,1];
687
688
$points = $svg->get_path(
689
x => $xv,
690
y => $yv,
691
-type => 'path',
692
-closed => 'true' #specify that the polyline is closed
693
);
694
695
$tag = $svg->path(
696
%$points,
697
id => 'pline_1',
698
style => {
699
'fill-opacity' => 0,
700
'fill' => 'green',
701
'stroke' => 'rgb(250,123,23)'
702
}
703
);
704
705
706
SEE ALSO: L<"get_path">.
707
708
=head2 get_path
709
710
$path = $svg->get_path(%attributes)
711
712
Returns the text string of points correctly formatted to be incorporated into
713
the multi-point SVG drawing object definitions (path, polyline, polygon)
714
715
B attributes including:
716
717
-type = path type (path | polyline | polygon)
718
x = reference to array of x coordinates
719
y = reference to array of y coordinates
720
721
B a hash reference consisting of the following key-value pair:
722
723
points = the appropriate points-definition string
724
-type = path|polygon|polyline
725
-relative = 1 (define relative position rather than absolute position)
726
-closed = 1 (close the curve - path and polygon only)
727
728
#generate an open path definition for a path.
729
my ($points,$p);
730
$points = $svg->get_path(x=>\@x,y=>\@y,-relative=>1,-type=>'path');
731
732
#add the path to the SVG document
733
my $p = $svg->path(%$path, style=>\%style_definition);
734
735
#generate an closed path definition for a a polyline.
736
$points = $svg->get_path(
737
x=>\@x,
738
y=>\@y,
739
-relative=>1,
740
-type=>'polyline',
741
-closed=>1
742
); # generate a closed path definition for a polyline
743
744
# add the polyline to the SVG document
745
$p = $svg->polyline(%$points, id=>'pline1');
746
747
B get_path set_path
748
749
750
=head2 animate
751
752
$tag = $svg->animate(%attributes)
753
754
Generate an SMIL animation tag. This is allowed within any nonempty tag. Refer
755
to the W3C for detailed information on the subtleties of the animate SMIL
756
commands.
757
758
B -method = Transform | Motion | Color
759
760
my $an_ellipse = $svg->ellipse(
761
cx => 30,
762
cy => 150,
763
rx => 10,
764
ry => 10,
765
id => 'an_ellipse',
766
stroke => 'rgb(130,220,70)',
767
fill =>'rgb(30,20,50)'
768
);
769
770
$an_ellipse-> animate(
771
attributeName => "cx",
772
values => "20; 200; 20",
773
dur => "10s",
774
repeatDur => 'indefinite'
775
);
776
777
$an_ellipse-> animate(
778
attributeName => "rx",
779
values => "10;30;20;100;50",
780
dur => "10s",
781
repeatDur => 'indefinite',
782
);
783
784
$an_ellipse-> animate(
785
attributeName => "ry",
786
values => "30;50;10;20;70;150",
787
dur => "15s",
788
repeatDur => 'indefinite',
789
);
790
791
$an_ellipse-> animate(
792
attributeName=>"rx",values=>"30;75;10;100;20;20;150",
793
dur=>"20s", repeatDur=>'indefinite');
794
795
$an_ellipse-> animate(
796
attributeName=>"fill",values=>"red;green;blue;cyan;yellow",
797
dur=>"5s", repeatDur=>'indefinite');
798
799
$an_ellipse-> animate(
800
attributeName=>"fill-opacity",values=>"0;1;0.5;0.75;1",
801
dur=>"20s",repeatDur=>'indefinite');
802
803
$an_ellipse-> animate(
804
attributeName=>"stroke-width",values=>"1;3;2;10;5",
805
dur=>"20s",repeatDur=>'indefinite');
806
807
=head2 group
808
809
$tag = $svg->group(%attributes)
810
811
Define a group of objects with common properties. Groups can have style,
812
animation, filters, transformations, and mouse actions assigned to them.
813
814
$tag = $svg->group(
815
id => 'xvs000248',
816
style => {
817
'font' => [ qw( Arial Helvetica sans ) ],
818
'font-size' => 10,
819
'fill' => 'red',
820
},
821
transform => 'rotate(-45)'
822
);
823
824
=head2 defs
825
826
$tag = $svg->defs(%attributes)
827
828
define a definition segment. A Defs requires children when defined using SVG.pm
829
830
$tag = $svg->defs(id => 'def_con_one',);
831
832
=head2 style
833
834
$svg->tag('style', %styledef);
835
836
Sets/adds style-definition for the following objects being created.
837
838
Style definitions apply to an object and all its children for all properties for
839
which the value of the property is not redefined by the child.
840
841
$tag = $SVG->style(%attributes)
842
843
Generate a style container for inline or xlink:href based styling instructions
844
845
my $tag = $SVG->style(type=>"text/css");
846
847
# Populate the style tag with cdata.
848
# Be careful to manage the line ends.
849
# Use qq{text}, where text is the script
850
851
$tag1->CDATA(qq{
852
rect fill:red;stroke:green;
853
circle fill:red;stroke:orange;
854
ellipse fill:none;stroke:yellow;
855
text fill:black;stroke:none;
856
});
857
858
# Create a external CSS stylesheet reference
859
my $tag2 = $SVG->style(type=>"text/css", -href="/resources/example.css");
860
861
=head2 mouseaction
862
863
$svg->mouseaction(%attributes)
864
865
Sets/Adds mouse action definitions for tag
866
867
=head2 attrib
868
869
$svg->attrib($name, $value)
870
871
Sets/adds attributes of an element.
872
873
Retrieve an attribute:
874
875
$svg->attrib($name);
876
877
Set a scalar attribute:
878
879
$SVG->attrib $name, $value
880
881
Set a list attribute:
882
883
$SVG->attrib $name, \@value
884
885
Set a hash attribute (i.e. style definitions):
886
887
$SVG->attrib $name, \%value
888
889
Remove an attribute:
890
891
$svg->attrib($name,undef);
892
893
B attr attribute
894
895
Sets/replaces attributes for a tag.
896
897
=head2 cdata
898
899
$svg->cdata($text)
900
901
Sets cdata to $text. SVG.pm allows you to set cdata for any tag. If the tag is
902
meant to be an empty tag, SVG.pm will not complain, but the rendering agent will
903
fail. In the SVG DTD, cdata is generally only meant for adding text or script
904
content.
905
906
$svg->text(
907
style => {
908
'font' => 'Arial',
909
'font-size' => 20
910
})->cdata('SVG.pm is a perl module on CPAN!');
911
912
my $text = $svg->text( style => { 'font' => 'Arial', 'font-size' => 20 } );
913
$text->cdata('SVG.pm is a perl module on CPAN!');
914
915
B
916
917
SVG.pm is a perl module on CPAN!
918
919
SEE ALSO:
920
921
L<"CDATA">, L<"desc">, L<"title">, L<"text">, L<"script">.
922
923
=head2 cdata_noxmlesc
924
925
$script = $svg->script();
926
$script->cdata_noxmlesc($text);
927
928
Generates cdata content for text and similar tags which do not get xml-escaped.
929
In othe words, does not parse the content and inserts the exact string into the cdata location.
930
931
=head2 CDATA
932
933
$script = $svg->script();
934
$script->CDATA($text);
935
936
Generates a tag with the contents of $text rendered exactly as supplied. SVG.pm allows you to set cdata for any tag. If the tag is
937
meant to be an empty tag, SVG.pm will not complain, but the rendering agent will
938
fail. In the SVG DTD, cdata is generally only meant for adding text or script
939
content.
940
941
my $text = qq{
942
var SVGDoc;
943
var groups = new Array();
944
var last_group;
945
946
/*****
947
*
948
* init
949
*
950
* Find this SVG's document element
951
* Define members of each group by id
952
*
953
*****/
954
function init(e) {
955
SVGDoc = e.getTarget().getOwnerDocument();
956
append_group(1, 4, 6); // group 0
957
append_group(5, 4, 3); // group 1
958
append_group(2, 3); // group 2
959
}};
960
$svg->script()->CDATA($text);
961
962
963
B
964
965
Escript E
966
![CDATA[
967
var SVGDoc;
968
var groups = new Array();
969
var last_group;
970
971
/*****
972
*
973
* init
974
*
975
* Find this SVG's document element
976
* Define members of each group by id
977
*
978
*****/
979
function init(e) {
980
SVGDoc = e.getTarget().getOwnerDocument();
981
append_group(1, 4, 6); // group 0
982
append_group(5, 4, 3); // group 1
983
append_group(2, 3); // group 2
984
}
985
]]E
986
987
SEE ALSO: L<"cdata">, L<"script">.
988
989
=head2 xmlescp and xmlescape
990
991
$string = $svg->xmlescp($string)
992
$string = $svg->xmlesc($string)
993
$string = $svg->xmlescape($string)
994
995
SVG module does not xml-escape characters that are incompatible with the XML specification. B and B provides this functionality. It is a helper function which generates an XML-escaped string for reserved characters such as ampersand, open and close brackets, etcetera.
996
997
The behaviour of xmlesc is to apply the following transformation to the input string $s:
998
999
$s=~s/&(?!#(x\w\w|\d+?);)/&/g;
1000
$s=~s/>/>/g;
1001
$s=~s/</g;
1002
$s=~s/\"/"/g;
1003
$s=~s/\'/'/g;
1004
$s=~s/([\x00-\x08\x0b\x1f])/''/eg;
1005
$s=~s/([\200-\377])/''.ord($1).';'/ge;
1006
1007
1008
=head2 filter
1009
1010
$tag = $svg->filter(%attributes)
1011
1012
Generate a filter. Filter elements contain L<"fe"> filter sub-elements.
1013
1014
my $filter = $svg->filter(
1015
filterUnits=>"objectBoundingBox",
1016
x=>"-10%",
1017
y=>"-10%",
1018
width=>"150%",
1019
height=>"150%",
1020
filterUnits=>'objectBoundingBox'
1021
);
1022
1023
$filter->fe();
1024
1025
SEE ALSO: L<"fe">.
1026
1027
=head2 fe
1028
1029
$tag = $svg->fe(-type=>'type', %attributes)
1030
1031
Generate a filter sub-element. Must be a child of a L<"filter"> element.
1032
1033
my $fe = $svg->fe(
1034
-type => 'DiffuseLighting' # required - element name omitting 'fe'
1035
id => 'filter_1',
1036
style => {
1037
'font' => [ qw(Arial Helvetica sans) ],
1038
'font-size' => 10,
1039
'fill' => 'red',
1040
},
1041
transform => 'rotate(-45)'
1042
);
1043
1044
Note that the following filter elements are currently supported:
1045
Also note that the elelemts are defined in lower case in the module, but as of version 2.441, any case combination is allowed.
1046
1047
1048
=head2 * feBlend
1049
1050
=head2 * feColorMatrix
1051
1052
=head2 * feComponentTransfer
1053
1054
=head2 * feComposite
1055
1056
=head2 * feConvolveMatrix
1057
1058
=head2 * feDiffuseLighting
1059
1060
=head2 * feDisplacementMap
1061
1062
=head2 * feDistantLight
1063
1064
=head2 * feFlood
1065
1066
=head2 * feFuncA
1067
1068
=head2 * feFuncB
1069
1070
=head2 * feFuncG
1071
1072
=head2 * feFuncR
1073
1074
=head2 * feGaussianBlur
1075
1076
=head2 * feImage
1077
1078
=head2 * feMerge
1079
1080
=head2 * feMergeNode
1081
1082
=head2 * feMorphology
1083
1084
=head2 * feOffset
1085
1086
=head2 * fePointLight
1087
1088
=head2 * feSpecularLighting
1089
1090
=head2 * feSpotLight
1091
1092
=head2 * feTile
1093
1094
=head2 * feTurbulence
1095
1096
1097
SEE ALSO: L<"filter">.
1098
1099
=head2 pattern
1100
1101
$tag = $svg->pattern(%attributes)
1102
1103
Define a pattern for later reference by url.
1104
1105
my $pattern = $svg->pattern(
1106
id => "Argyle_1",
1107
width => "50",
1108
height => "50",
1109
patternUnits => "userSpaceOnUse",
1110
patternContentUnits => "userSpaceOnUse"
1111
);
1112
1113
=head2 set
1114
1115
$tag = $svg->set(%attributes)
1116
1117
Set a definition for an SVG object in one section, to be referenced in other
1118
sections as needed.
1119
1120
my $set = $svg->set(
1121
id => "Argyle_1",
1122
width => "50",
1123
height => "50",
1124
patternUnits => "userSpaceOnUse",
1125
patternContentUnits => "userSpaceOnUse"
1126
);
1127
1128
=head2 stop
1129
1130
$tag = $svg->stop(%attributes)
1131
1132
Define a stop boundary for L<"gradient">
1133
1134
my $pattern = $svg->stop(
1135
id => "Argyle_1",
1136
width => "50",
1137
height => "50",
1138
patternUnits => "userSpaceOnUse",
1139
patternContentUnits => "userSpaceOnUse"
1140
);
1141
1142
=head2 gradient
1143
1144
$tag = $svg->gradient(%attributes)
1145
1146
Define a color gradient. Can be of type B or B
1147
1148
my $gradient = $svg->gradient(
1149
-type => "linear",
1150
id => "gradient_1"
1151
);
1152
1153
=head1 GENERIC ELEMENT METHODS
1154
1155
The following elements are generically supported by SVG:
1156
1157
1158
=head2 * altGlyph
1159
1160
=head2 * altGlyphDef
1161
1162
=head2 * altGlyphItem
1163
1164
=head2 * clipPath
1165
1166
=head2 * color-profile
1167
1168
=head2 * cursor
1169
1170
=head2 * definition-src
1171
1172
=head2 * font-face-format
1173
1174
=head2 * font-face-name
1175
1176
=head2 * font-face-src
1177
1178
=head2 * font-face-url
1179
1180
=head2 * foreignObject
1181
1182
=head2 * glyph
1183
1184
=head2 * glyphRef
1185
1186
=head2 * hkern
1187
1188
=head2 * marker
1189
1190
=head2 * mask
1191
1192
=head2 * metadata
1193
1194
=head2 * missing-glyph
1195
1196
=head2 * mpath
1197
1198
=head2 * switch
1199
1200
=head2 * symbol
1201
1202
=head2 * tref
1203
1204
=head2 * view
1205
1206
=head2 * vkern
1207
1208
See e.g. L for an example of the use of these methods.
1209
1210
=head1 METHODS IMPORTED BY SVG::DOM
1211
1212
The following L elements are accessible through SVG:
1213
1214
=head2 * getChildren
1215
1216
=head2 * getFirstChild
1217
1218
=head2 * getNextChild
1219
1220
=head2 * getLastChild
1221
1222
=head2 * getParent
1223
1224
=head2 * getParentElement
1225
1226
=head2 * getSiblings
1227
1228
=head2 * getElementByID
1229
1230
=head2 * getElementID
1231
1232
=head2 * getElements
1233
1234
=head2 * getElementName
1235
1236
=head2 * getType
1237
1238
=head2 * getAttributes
1239
1240
=head2 * getAttribute
1241
1242
=head2 * setAttributes
1243
1244
=head2 * setAttribute
1245
1246
=head2 * insertBefore
1247
1248
=head2 * insertAfter
1249
1250
=head2 * insertSiblingBefore
1251
1252
=head2 * insertSiblingAfter
1253
1254
=head2 * replaceChild
1255
1256
=head2 * removeChild
1257
1258
=head2 * cloneNode
1259
1260
=cut
1261
1262
#-------------------------------------------------------------------------------
1263
1264
my %default_attrs = (
1265
1266
# processing options
1267
-auto => 0, # permit arbitrary autoloads (only at import)
1268
-printerror => 1, # print error messages to STDERR
1269
-raiseerror => 1, # die on errors (implies -printerror)
1270
1271
# rendering options
1272
-indent => "\t", # what to indent with
1273
-elsep => "\n", # element line (vertical) separator
1274
-nocredits => 0, # enable/disable credit note comment
1275
-namespace =>
1276
'', # The root element's (and it's children's) namespace prefix
1277
1278
# XML and Doctype declarations
1279
-inline => 0, # inline or stand alone
1280
-docroot => 'svg', # The document's root element
1281
-version => '1.0',
1282
-extension => '',
1283
-encoding => 'UTF-8',
1284
-xml_svg => 'http://www.w3.org/2000/svg',
1285
-xml_xlink => 'http://www.w3.org/1999/xlink',
1286
-standalone => 'yes',
1287
-pubid => '-//W3C//DTD SVG 1.0//EN', # formerly -identifier
1288
-sysid => 'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd',
1289
);
1290
1291
sub import {
1292
27
27
2010
my $package = shift;
1293
1294
27
49
my $attr = undef;
1295
27
62
foreach (@_) {
1296
21
100
53
if ($attr) {
100
1297
7
9
$default_attrs{$attr} = $_;
1298
7
10
undef $attr;
1299
}
1300
elsif ( exists $default_attrs{$_} ) {
1301
7
11
$attr = $_;
1302
}
1303
else {
1304
7
50
23
/^-/ and die "Unknown attribute '$_' in import list\n";
1305
7
15
$SVG::Element::autosubs{$_}
1306
= 1; # add to list of autoloadable tags
1307
}
1308
}
1309
1310
# switch on AUTOLOADer, if asked.
1311
27
100
90
if ( $default_attrs{'-auto'} ) {
1312
1
3
*SVG::Element::AUTOLOAD = \&SVG::Element::autoload;
1313
}
1314
1315
# predeclare any additional elements asked for by the user
1316
27
209
foreach my $sub ( keys %SVG::Element::autosubs ) {
1317
1282
2129
$SVG::Element::AUTOLOAD = ("SVG::Element::$sub");
1318
1282
1796
SVG::Element::autoload();
1319
}
1320
1321
27
121
delete $default_attrs{-auto}; # -auto is only allowed here, not in new
1322
1323
27
31525
return ();
1324
}
1325
1326
#-------------------------------------------------------------------------------
1327
1328
=pod
1329
1330
=head1 Methods
1331
1332
SVG provides both explicit and generic element constructor methods. Explicit
1333
generators are generally (with a few exceptions) named for the element they
1334
generate. If a tag method is required for a tag containing hyphens, the method
1335
name replaces the hyphen with an underscore. ie: to generate tag
1336
you would use method $svg->column_heading(id=>'new').
1337
1338
1339
All element constructors take a hash of element attributes and options;
1340
element attributes such as 'id' or 'border' are passed by name, while options for the
1341
method (such as the type of an element that supports multiple alternate forms)
1342
are passed preceded by a hyphen, e.g '-type'. Both types may be freely
1343
intermixed; see the L<"fe"> method and code examples throughout the documentation
1344
for more examples.
1345
1346
=head2 new (constructor)
1347
1348
$svg = SVG->new(%attributes)
1349
1350
Creates a new SVG object. Attributes of the document SVG element be passed as
1351
an optional list of key value pairs. Additionally, SVG options (prefixed with
1352
a hyphen) may be set on a per object basis:
1353
1354
my $svg1 = SVG->new;
1355
1356
my $svg2 = SVG->new(id => 'document_element');
1357
1358
my $svg3 = SVG->new(
1359
-printerror => 1,
1360
-raiseerror => 0,
1361
-indent => ' ',
1362
-elsep => "\n", # element line (vertical) separator
1363
-docroot => 'svg', # default document root element (SVG specification assumes svg). Defaults to 'svg' if undefined
1364
-xml_xlink => 'http://www.w3.org/1999/xlink', # required by Mozilla's embedded SVG engine
1365
-sysid => 'abc', # optional system identifier
1366
-pubid => "-//W3C//DTD SVG 1.0//EN", # public identifier default value is "-//W3C//DTD SVG 1.0//EN" if undefined
1367
-namespace => 'mysvg',
1368
-inline => 1
1369
id => 'document_element',
1370
width => 300,
1371
height => 200,
1372
);
1373
1374
Default SVG options may also be set in the import list. See L<"EXPORTS"> above
1375
for more on the available options.
1376
1377
Furthermore, the following options:
1378
1379
-version
1380
-encoding
1381
-standalone
1382
-namespace
1383
-inline
1384
-pubid (formerly -identifier)
1385
-sysid (standalone)
1386
1387
may also be set in xmlify, overriding any corresponding values set in the SVG->new declaration
1388
1389
=cut
1390
1391
#-------------------------------------------------------------------------------
1392
#
1393
# constructor for the SVG data model.
1394
#
1395
# the new constructor creates a new data object with a document tag at its base.
1396
# this document tag then has either:
1397
# a child entry parent with its child svg generated (when -inline = 1)
1398
# or
1399
# a child entry svg created.
1400
#
1401
# Because the new method returns the $self reference and not the
1402
# latest child to be created, a hash key -document with the reference to the hash
1403
# entry of its already-created child. hence the document object has a -document reference
1404
# to parent or svg if inline is 1 or 0, and parent will have a -document entry
1405
# pointing to the svg child.
1406
#
1407
# This way, the next tag constructor will descend the
1408
# tree until it finds no more tags with -document, and will add
1409
# the next tag object there.
1410
# refer to the SVG::tag method
1411
1412
sub new {
1413
33
33
1
14043
my ( $proto, %attrs ) = @_;
1414
1415
33
33
190
my $class = ref $proto || $proto;
1416
33
52
my $self;
1417
1418
# establish defaults for unspecified attributes
1419
33
191
foreach my $attr ( keys %default_attrs ) {
1420
533
100
958
$attrs{$attr} = $default_attrs{$attr} unless exists $attrs{$attr};
1421
}
1422
33
248
$self = $class->SUPER::new('document');
1423
33
50
209
if ( not $self->{-docref} ) {
1424
33
76
$self->{-docref} = $self;
1425
33
130
weaken( $self->{-docref} );
1426
}
1427
33
50
87
unless ( $attrs{-namespace} ) {
1428
33
33
127
$attrs{'xmlns'} = $attrs{'xmlns'} || $attrs{'-xml_svg'};
1429
}
1430
$attrs{'xmlns:xlink'}
1431
= $attrs{'xmlns:xlink'}
1432
33
50
183
|| $attrs{'-xml_xlink'}
1433
|| 'http://www.w3.org/1999/xlink';
1434
$attrs{'xmlns:svg'}
1435
= $attrs{'xmlns:svg'}
1436
33
50
140
|| $attrs{'-xml_svg'}
1437
|| 'http://www.w3.org/2000/svg';
1438
1439
33
65
$self->{-level} = 0;
1440
33
316
$self->{$_} = $attrs{$_} foreach keys %default_attrs;
1441
1442
# create SVG object according to nostub attribute
1443
33
65
my $svg;
1444
33
50
81
unless ( $attrs{-nostub} ) {
1445
33
213
$svg = $self->svg(%attrs);
1446
33
84
$self->{-document} = $svg;
1447
33
106
weaken( $self->{-document} );
1448
}
1449
1450
# add -attributes to SVG object
1451
# $self->{-elrefs}->{$self}->{name} = 'document';
1452
# $self->{-elrefs}->{$self}->{id} = '';
1453
1454
33
164
return $self;
1455
}
1456
1457
#-------------------------------------------------------------------------------
1458
1459
=pod
1460
1461
=head2 xmlify (alias: to_xml render serialize serialise )
1462
1463
$string = $svg->xmlify(%attributes);
1464
1465
Returns xml representation of svg document.
1466
1467
B
1468
1469
Name Default Value
1470
-version '1.0'
1471
-encoding 'UTF-8'
1472
-standalone 'yes'
1473
-namespace 'svg' - namespace prefix for elements.
1474
Can also be used in any element method to over-ride
1475
the current namespace prefix. Make sure to have
1476
declared the prefix before using it.
1477
-inline '0' - If '1', then this is an inline document.
1478
-pubid '-//W3C//DTD SVG 1.0//EN';
1479
-sysid 'http://www.w3.org/TR/2001/REC-SVG-20010904/DTD/svg10.dtd'
1480
1481
=cut
1482
1483
sub xmlify {
1484
23
23
1
6737
my ( $self, %attrs ) = @_;
1485
1486
23
32
my ( $decl, $ns );
1487
1488
23
35
my $credits = '';
1489
1490
# Give the module and myself credit unless explicitly turned off
1491
23
100
100
117
unless ( $self->{-docref}->{-nocredits}
1492
or $self->{-docref}{-creditsinserted} )
1493
{
1494
17
148
$self->comment(
1495
"\n\tGenerated using the Perl SVG Module V$VERSION\n\tby Ronan Oger\n\n\t"
1496
);
1497
17
34
$self->{-docref}{-creditsinserted} = 1;
1498
}
1499
1500
23
66
foreach my $key ( keys %attrs ) {
1501
2
50
10
next if $key !~ /^-/;
1502
2
4
$self->{$key} = $attrs{$key};
1503
}
1504
1505
23
93
foreach my $key ( keys %$self ) {
1506
551
50
1021
next if $key !~ /^-/;
1507
551
100
1241
$attrs{$key} ||= $self->{$key};
1508
}
1509
1510
23
172
return $self->SUPER::xmlify( $self->{-namespace} );
1511
}
1512
1513
*render = \&xmlify;
1514
*to_xml = \&xmlify;
1515
*serialise = \&xmlify;
1516
*serialize = \&xmlify;
1517
1518
=head2 perlify ()
1519
1520
return the perl code which generates the SVG document as it currently exists.
1521
1522
=cut
1523
1524
sub perlify {
1525
0
0
1
return shift->SUPER::perlify();
1526
}
1527
1528
=head2 toperl ()
1529
1530
Alias for method perlify()
1531
1532
=cut
1533
1534
*toperl = \&perlify;
1535
1536
1;
1537
1538
=pod
1539
1540
=head1 AUTHOR
1541
1542
Ronan Oger, RO IT Systemms GmbH, cpan@roitsystems.com
1543
1544
=head1 MAINTAINER
1545
1546
L
1547
1548
=head1 CREDITS
1549
1550
I would like to thank the following people for contributing to this module with
1551
patches, testing, suggestions, and other nice tidbits:
1552
1553
Peter Wainwright, Excellent ideas, beta-testing, writing SVG::Parser and much of SVG::DOM.
1554
Fredo, http://www.penguin.at0.net/~fredo/ - provided example code and initial feedback for early SVG.pm versions and the idea of a simplified svg generator.
1555
Adam Schneider
1556
Brial Pilpré
1557
Ian Hickson
1558
Steve Lihn
1559
Allen Day
1560
Martin Owens - SVG::DOM improvements in version 3.34
1561
1562
=head1 COPYRIGHT & LICENSE
1563
1564
Copyright 2001- Ronan Oger
1565
1566
The modules in the SVG distribution are distributed under the same license
1567
as Perl itself. It is provided free of warranty and may be re-used freely.
1568
1569
=head1 ARTICLES
1570
1571
L
1572
1573
L
1574
1575
L
1576
1577
=head1 SEE ALSO
1578
1579
L,
1580
L,
1581
L,
1582
L,
1583
L
1584
1585
For Commercial Perl/SVG development, refer to the following sites:
1586
L .
1587
1588
=cut