| 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 |