Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | package SVG::Manual; |
2 | ||
3 | =pod | |
4 | ||
5 | =head1 NAME | |
6 | ||
7 | SVG - Perl extension for generating Scalable Vector Graphics (SVG) documents | |
8 | ||
9 | =head2 VERSION | |
10 | ||
11 | Version 2.24 (29.01.03) | |
12 | Covers SVG-2.27 distribution | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | #!/usr/bin/perl -w | |
17 | use strict; | |
18 | use SVG; | |
19 | ||
20 | # create an SVG object | |
21 | my $svg= SVG->new(width=>200,height=>200); | |
22 | ||
23 | # use explicit element constructor to generate a group element | |
24 | my $y=$svg->group( | |
25 | id => 'group_y', | |
26 | style => { stroke=>'red', fill=>'green' } | |
27 | ); | |
28 | ||
29 | # add a circle to the group | |
30 | $y->circle(cx=>100, cy=>100, r=>50, id=>'circle_in_group_y'); | |
31 | ||
32 | # or, use the generic 'tag' method to generate a group element by name | |
33 | my $z=$svg->tag('g', | |
34 | id => 'group_z', | |
35 | style => { | |
36 | stroke => 'rgb(100,200,50)', | |
37 | fill => 'rgb(10,100,150)' | |
38 | } | |
39 | ); | |
40 | ||
41 | # create and add a circle using the generic 'tag' method | |
42 | $z->tag('circle', cx=>50, cy=>50, r=>100, id=>'circle_in_group_z'); | |
43 | ||
44 | # create an anchor on a rectangle within a group within the group z | |
45 | my $k = $z->anchor( | |
46 | id => 'anchor_k', | |
47 | -href => 'http://test.hackmare.com/', | |
48 | -target => 'new_window_0' | |
49 | )->rectangle( | |
50 | x => 20, y => 50, | |
51 | width => 20, height => 30, | |
52 | rx => 10, ry => 5, | |
53 | id => 'rect_k_in_anchor_k_in_group_z' | |
54 | ); | |
55 | ||
56 | # now render the SVG object, implicitly use svg namespace | |
57 | print $svg->xmlify; | |
58 | ||
59 | # or render a child node of the SVG object without rendering the entire object | |
60 | print $k->xmlify; #renders the anchor $k above containing a rectangle, but does not | |
61 | #render any of the ancestor nodes of $k | |
62 | ||
63 | ||
64 | # or, explicitly use svg namespace and generate a document with its own DTD | |
65 | print $svg->xmlify(-namespace=>'svg'); | |
66 | ||
67 | # or, explicitly use svg namespace and generate an in-line docunent | |
68 | print $svg->xmlify( | |
69 | -namespace => "svg", | |
70 | -pubid => "-//W3C//DTD SVG 1.0//EN", | |
71 | -inline => 1 | |
72 | ); | |
73 | ||
74 | =head1 DESCRIPTION | |
75 | ||
76 | SVG is a 100% Perl module which generates a nested data structure containing the | |
77 | DOM representation of an SVG (Scalable Vector Graphics) image. Using SVG, you | |
78 | can generate SVG objects, embed other SVG instances into it, access the DOM | |
79 | object, create and access javascript, and generate SMIL animation content. | |
80 | ||
81 | =head2 General Steps to generating an SVG document | |
82 | ||
83 | Generating SVG is a simple three step process: | |
84 | ||
85 | =over 4 | |
86 | ||
87 | =item 1 The first step is to construct a new SVG object with L<"new">. | |
88 | ||
89 | =item 2 The second step is to call element constructors to create SVG elements. | |
90 | Examples of element constructors are L<"circle"> and L<"path">. | |
91 | ||
92 | =item 3 The third and last step is to render the SVG object into XML using the | |
93 | L<"xmlify"> method. | |
94 | ||
95 | =back | |
96 | ||
97 | The L<"xmlify"> method takes a number of optional arguments that control how SVG | |
98 | renders the object into XML, and in particular determine whether a stand-alone | |
99 | SVG document or an inline SVG document fragment is generated: | |
100 | ||
101 | =over ( | |
102 | ||
103 | =item -stand-alone | |
104 | ||
105 | A complete SVG document with its own associated DTD. A namespace for the SVG | |
106 | elements may be optionally specified. | |
107 | ||
108 | =item -in-line | |
109 | ||
110 | An in-line SVG document fragment with no DTD that be embedded within other XML | |
111 | content. As with stand-alone documents, an alternate namespace may be specified. | |
112 | ||
113 | =back | |
114 | ||
115 | No XML content is generated until the third step is reached. Up until this | |
116 | point, all constructed element definitions reside in a DOM-like data structure | |
117 | from which they can be accessed and modified. | |
118 | ||
119 | =head2 EXPORTS | |
120 | ||
121 | None. However, SVG permits both options and additional element methods to be | |
122 | specified in the import list. These options and elements are then available | |
123 | for all SVG instances that are created with the L<"new"> constructor. For example, | |
124 | to change the indent string to two spaces per level: | |
125 | ||
126 | use SVG qw(-indent => " "); | |
127 | ||
128 | With the exception of -auto, all options may also be specified to the L<"new"> | |
129 | constructor. The currently supported options are: | |
130 | ||
131 | -auto enable autoloading of all unrecognised method calls (0) | |
132 | -indent the indent to use when rendering the SVG into XML ("\t") | |
133 | -inline whether the SVG is to be standalone or inlined (0) | |
134 | -printerror print SVG generation errors to standard error (1) | |
135 | -raiseerror die if a generation error is encountered (1) | |
136 | -nostub only return the handle to a blank SVG document without any elements | |
137 | ||
138 | SVG also allows additional element generation methods to be specified in the | |
139 | import list. For example to generate 'star' and 'planet' element methods: | |
140 | ||
141 | use SVG qw(star planet); | |
142 | ||
143 | or: | |
144 | ||
145 | use SVG ("star","planet"); | |
146 | ||
147 | This will add 'star' to the list of elements supported by SVG.pm (but not of | |
148 | course other SVG parsers...). Alternatively the '-auto' option will allow | |
149 | any unknown method call to generate an element of the same name: | |
150 | ||
151 | use SVG (-auto => 1, "star", "planet"); | |
152 | ||
153 | Any elements specified explicitly (as 'star' and 'planet' are here) are | |
154 | predeclared; other elements are defined as and when they are seen by Perl. Note | |
155 | that enabling '-auto' effectively disables compile-time syntax checking for | |
156 | valid method names. | |
157 | ||
158 | B<Example:> | |
159 | ||
160 | use SVG ( | |
161 | -auto => 0, | |
162 | -indent => " ", | |
163 | -raiserror => 0, | |
164 | -printerror => 1, | |
165 | "star", "planet", "moon" | |
166 | ); | |
167 | ||
168 | =head1 SEE ALSO | |
169 | ||
170 | perl(1), L<SVG::XML>, L<SVG::Element>, L<SVG::DOM>, L<SVG::Parser> | |
171 | http://roasp.com/ | |
172 | http://www.w3c.org/Graphics/SVG/ | |
173 | ||
174 | =head1 AUTHOR | |
175 | ||
176 | Ronan Oger, RO IT Systemms GmbH, ronan@roasp.com | |
177 | ||
178 | =head1 CREDITS | |
179 | ||
180 | Peter Wainwright, peter@roasp.com Excellent ideas, beta-testing, SVG::Parser | |
181 | Fredo, http://www.penguin.at0.net/~fredo/ - provided initial feedback | |
182 | for early SVG.pm versions | |
183 | Adam Schneider, improvements to xmlescp providing improved character support | |
184 |