=encoding euc-jp

=head1 名前

SVG::Element - SVG.pmのための要素生成部分

=head1 バージョン

1.22

=head1 作者

Ronan Oger, ronan@roasp.com

=head1 参考資料

perl(1),L<SVG>,L<SVG::XML>,L<SVG::Element>,L<SVG::Parser>, L<SVG::Manual>
http://www.roasp.com/
http://www.perlsvg.com/
http://www.roitsystems.com/
http://www.w3c.org/Graphics/SVG/

=head2 tag (alias: element)
 
$tag = $SVG->tag($name, %attributes)


汎用的な要素ジェネレータ。$nameという名前で、%attributesで指定された属性を持った
要素を作成します。このメソッドが、ほとんどの明示的な要素ジェネレータの
基本となります。

B<Example:>

    my $tag = $SVG->tag('g', transform=>'rotate(-45)');

=head2 anchor

$tag = $SVG->anchor(%attributes)

anchor要素を生成します。anchorはオブジェクトを'ライブ'(つまりクリッカブル）に
します。そのため描画されるオブジェクトあるいはグループ要素を子供として
必要とします。

B<Example:>

    # anchorの生成
    $tag = $SVG->anchor(
        -href=>'http://here.com/some/simpler/SVG.SVG'
    );
    # anchorに円を追加。その円はクリックできます。
    $tag->circle(cx=>10,cy=>10,r=>1);

    # URLとターゲットを持つ、より複雑なanchor
    $tag = $SVG->anchor(
          -href   => 'http://somewhere.org/some/other/page.html',
          -target => 'new_window'
    );

=head2 circle

$tag = $SVG->circle(%attributes)

(cx,cy)に半径rの円を描きます。

B<Example:>

    my $tag = $SVG->circlecx=>4, cy=>2, r=>1);

=head2 ellipse

$tag = $SVG->ellipse(%attributes)

(cx,cy)に半径rx, ryの楕円を描きます。

B<Example:>

    my $tag = $SVG->ellipse(
        cx=>10, cy=>10,
        rx=>5, ry=>7,
        id=>'ellipse',
        style=>{
            'stroke'=>'red',
            'fill'=>'green',
            'stroke-width'=>'4',
            'stroke-opacity'=>'0.5',
            'fill-opacity'=>'0.2'
        }
    );

=head2 rectangle (alias: rect)

$tag = $SVG->rectangle(%attributes)

(x,y)に幅'width'、高さ'height'で、角の丸みの径が'rx'と'ry'の四角を描きます。

B<Example:>

    $tag = $SVG->rectangle(
        x=>10, y=>20,
        width=>4, height=>5,
        rx=>5.2, ry=>2.4,
        id=>'rect_1'
    );

=head2 image

 $tag = $SVG->image(%attributes)

(x,y)に幅'width'、高さ'height'で、'-href'で結び付けられたイメージ・リソースを
描きます。L<"use">もご覧ください。

B<Example:>

    $tag = $SVG->image(
        x=>100, y=>100,
        width=>300, height=>200,
        '-href'=>"image.png", #may also embed SVG, e.g. "image.SVG"
        id=>'image_1'
    );

B<Output:>

    <image xlink:href="image.png" x="100" y="100" width="300" height="200"/>

=head2 use

$tag = $SVG->use(%attributes)

SVGドキュメントに入っているエンティティからコンテンツを取り出し、それを
(x,y)に幅'width'、高さ'height'で、'-href'で結び付けられたイメージ・リソースに
適用します。

B<Example:>

    $tag = $SVG->use(
        x=>100, y=>100,
        width=>300, height=>200,
        '-href'=>"pic.SVG#image_1",
        id=>'image_1'
    );

B<Output:>

    <use xlink:href="pic.SVG#image_1" x="100" y="100" width="300" height="200"/>

SVGの仕様に従い、SVGでの'use'要素は外部のSVGファイルの中の1つの要素を示すことが
出来ます。

=head2 polygon

$tag = $SVG->polygon(%attributes)

'x1,y1,x2,y2,x3,y3,... xy,yn'という形式の文字列によって定義される頂点で
n角の多角形を描きます。座標データから適切な文字列を生成するために便利な
L<"get_path">メソッドが提供されます。

B<Example:>

    # 五画形
    my $xv = [0,2,4,5,1];
    my $yv = [0,0,2,7,5];

    $points = $a->get_path(
        x=>$xv, y=>$yv,
        -type=>'polygon'
    );

    $c = $a->polygon(
        %$points,
        id=>'pgon1',
        style=>\%polygon_style
    );

SEE ALSO:

L<"polyline">, L<"path">, L<"get_path">.

=head2 polyline

$tag = $SVG->polyline(%attributes)

'x1,y1,x2,y2,x3,y3,... xy,yn'という形式の文字列によって定義される点を
持つn点の折れ線を描きます。座標データから適切な文字列を生成するために便利な
L<"get_path">メソッドが提供されます。

B<Example:>

    # a 10-pointsaw-tooth pattern
    my $xv = [0,1,2,3,4,5,6,7,8,9];
    my $yv = [0,1,0,1,0,1,0,1,0,1];

    $points = $a->get_path(
        x=>$xv, y=>$yv,
        -type=>'polyline',
        -closed=>'true' #その折れ線が閉じるかどうかを指定
    );

    my $tag = $a->polyline (
        %$points,
        id=>'pline_1',
        style=>{
            'fill-opacity'=>0,
            'stroke-color'=>'rgb(250,123,23)'
        }
    );

=head2 line

$tag = $SVG->line(%attributes)

(x1,y1) と (x2,y2)という２点の直線を描きます。

B<Example:>

    my $tag = $SVG->line(
        id=>'l1',
        x1=>0, y1=>10,
        x2=>10, y2=>0
    );

複数の結び付けられた線を描くためには、L<"polyline">を使ってください。

=head2 text

$text = $SVG->text(%attributes)->cdata();

$text_path = $SVG->text(-type=>'path');
$text_span = $text_path->text(-type=>'span')->cdata('A');
$text_span = $text_path->text(-type=>'span')->cdata('B');
$text_span = $text_path->text(-type=>'span')->cdata('C');


イメージに描かれるテキスト文字列のためのコンテナを定義します。

B<Input:> 
    -type    = パスのタイプ (path | polyline | polygon)
    -type    = テキスト要素のタイプ  (path | span | normal [default])

B<Example:>

    my $text1 = $SVG->text(
        id=>'l1', x=>10, y=>10
    )->cdata('hello, world');

    my $text2 = $SVG->text(
        id=>'l1', x=>10, y=>10, -cdata=>'hello, world');

    my $text = $SVG->text(
        id=>'tp', x=>10, y=>10 -type=>path)
        ->text(id=>'ts' -type=>'span')
        ->cdata('hello, world');

SEE ALSO:

    L<"desc">, L<"cdata">.

=head2 title

$tag = $SVG->title(%attributes)

イメージのタイトルを生成します。

B<Example:>

    my $tag = $SVG->title(id=>'document-title')->cdata('This is the title');

=head2 desc

$tag = $SVG->desc(%attributes)

イメージの説明(=description)を生成します。

B<Example:>

    my $tag = $SVG->desc(id=>'document-desc')->cdata('This is a description');

=head2 comment

$tag = $SVG->comment(@comments)

イメージの説明を生成します。

B<Example:>

    my $tag = $SVG->comment('comment 1','comment 2','comment 3');

=head2 pi

$tag = $SVG->pi(@pi)

処理命令(processing instruction)の集合を生成します。

B<Example:>

    my $tag = $SVG->pi('instruction one','instruction two','instruction three');

    returns: 
      <lt>?instruction one?<gt>
      <lt>?instruction two?<gt>
      <lt>?instruction three?<gt>

=head2 script

$tag = $SVG->script(%attributes)

Javascriptあるいはその他の互換性のあるスクリプト言語であるECMAscriptを使った、
動的な(クライアント側）スクリプトのためのスクリプト・コンテナを生成します。

B<Example:>

    my $tag = $SVG->script(-type=>"text/ecmascript");

    # javascriptの行末を管理するよう注意して、
    # cdtaを持ったscriptタグを入れてください
    # qq|text| あるいは qq/text/ （このtextがスクリプト）
    # が、このためにうまく機能します。

    $tag->cdata(qq|function d(){
        //簡単な表示関数
        for(cnt = 0; cnt < d.length; cnt++)
            document.write(d[cnt]);//ループの終わり
        document.write("<BR>");//改行の出力
      }|
    );

=head2 path

$tag = $SVG->path(%attributes)

path要素を描画します。pathの頂点はパラメータあるいはL<"get_path">メソッドを
使って求められたものになります。

B<Example:>

    # path定義で描画される 10点のノコギリ状のパターン
    my $xv = [0,1,2,3,4,5,6,7,8,9];
    my $yv = [0,1,0,1,0,1,0,1,0,1];

    $points = $a->get_path(
        x => $xv,
        y => $yv,
        -type   => 'path',
        -closed => 'true'  #折れ線が閉じるように指定
    );

    $tag = $SVG->path(
        %$points,
        id  => 'pline_1',
        style => {
            'fill-opacity' => 0,
            'fill-color'   => 'green',
            'stroke-color' => 'rgb(250,123,23)'
        }
    );


SEE ALSO:

L<"get_path">.

=head2 get_path

$path = $SVG->get_path(%attributes)

複数の点を持つSVG描画オブジェクト定義（path、polyline、polygon)に合うよう
形式が正しく整えられた点のテキスト文字列を返します。

B<Input:> 以下の属性があります：

    -type     = パスの種類(path | polyline | polygon)
    x         = X座標の配列へのリファレンス
    y         = Y座標の配列へのリファレンス

B<Output:> 以下のキー-値のペアで構成されるハッシュのリファレンス:

    points    = 適切なポイント定義文字列
    -type     = path|polygon|polyline
    -relative = 1 (絶対位置ではなく相対位置で定義）
    -closed   = 1 (曲線を閉じる- path と polygon のみ)

B<Example:>

    #pathのためのパス定義を生成
    my ($points,$p);
    $points = $SVG->get_path(x=&gt\@x,y=&gt\@y,-relative=&gt1,-type=&gt'path');
 
    #pathにSVGドキュメントを追加
    my $p = $SVG->path(%$path, style=>\%style_definition);

    #polylineのための閉じられたpath定義を生成
    $points = $SVG->get_path(
        x=>\@x,
        y=>\@y,
        -relative=>1,
        -type=>'polyline',
        -closed=>1
    ); # polylineのための閉じられたpath定義を生成

    # polylineをSVGドキュメントに追加
    $p = $SVG->polyline(%$points, id=>'pline1');

B<Aliases:> get_path set_path

=head2 animate

$tag = $SVG->animate(%attributes)

SMILアニメーション・タグを生成します。これは何か空でないタグが入っていることが
許されます。アニメーションSMILコマンドの細かい点に関する詳細な情報は
W3Cを参照してください。

B<Inputs:> -method = Transform | Motion | Color

  my $an_ellipse = $SVG->ellipse(
      cx=>30,cy=>150,rx=>10,ry=>10,id=>'an_ellipse',
      stroke=>'rgb(130,220,70)',fill=>'rgb(30,20,50)'); 

  $an_ellipse-> animate(
      attributeName=>"cx",values=>"20; 200; 20",dur=>"10s", repeatDur=>'indefinite');

  $an_ellipse-> animate(
      attributeName=>"rx",values=>"10;30;20;100;50",
      dur=>"10s", repeatDur=>'indefinite');

  $an_ellipse-> animate(
      attributeName=>"ry",values=>"30;50;10;20;70;150",
      dur=>"15s", repeatDur=>'indefinite');

  $an_ellipse-> animate(
      attributeName=>"rx",values=>"30;75;10;100;20;20;150",
      dur=>"20s", repeatDur=>'indefinite');

  $an_ellipse-> animate(
      attributeName=>"fill",values=>"red;green;blue;cyan;yellow",
      dur=>"5s", repeatDur=>'indefinite');

  $an_ellipse-> animate(
      attributeName=>"fill-opacity",values=>"0;1;0.5;0.75;1",
      dur=>"20s",repeatDur=>'indefinite');

  $an_ellipse-> animate(
      attributeName=>"stroke-width",values=>"1;3;2;10;5",
      dur=>"20s",repeatDur=>'indefinite');

=head2 group

$tag = $SVG->group(%attributes)

共通のプロパティを持つオブジェクトのグループを定義します。groupは
style,animation,filter,transformation、そしてそれらに結び付けられた
マウス・アクションを持つことができます。

B<Example:>

    $tag = $SVG->group(
        id      => 'xvs000248',
        style    => {
            'font'    => [ qw( Arial Helvetica sans ) ],
            'font-size' => 10,
            'fill'    => 'red',
        },
        transform => 'rotate(-45)'
    );

=head2 defs

$tag = $SVG->defs(%attributes)

定義セグメントを定義します。SVG.pmを使って定義されるとき、defsは子供を必要とします。

B<Example:>

    $tag = $SVG->defs(id  =>  'def_con_one',);

=head2 style

$SVG->style(%styledef)

生成される以下のオブジェクトのためのスタイル定義を設定/追加します。

そのプロパティの値が子供により再定義されない全てのプロパティのために
スタイル定義はオブジェクトとすべてのその子供に適用します。

=head2 mouseaction

$SVG->mouseaction(%attributes)

タグのためのマウス・アクション定義を設定/追加します。

=head2 attrib

$SVG->attrib($name, $value)

タグのための属性を設定/置換します。

属性の取り出し:

    $svg->attrib($name);

スカラ属性の設定:

    $SVG->attrib $name, $value

リスト属性の設定:

    $SVG->attrib $name, \@value

ハッシュ属性の設定(つまりスタイル定義):

    $SVG->attrib $name, \%value

属性の削除:

    $svg->attrib($name,undef);

B<Aliases:> attr attribute

=head2 cdata

$SVG->cdata($text)

与えられたままで描画される$textの内容を持った<![CDATA[ ... ]]>タグを生成します。
SVG.pmは、すべてのタグにcdataを設定することを可能にしています。
タグが空タグの場合、SVG.pmは文句をいいませんが、描画エージョントはコケるでしょう。
SVG DTDでは、cdataは一般にテキストやスクリプトの内容を追加することだけを意味します。

B<Example:>

    $SVG->text(
        style => {
            'font'    => 'Arial',
            'font-size' => 20
        })->cdata('SVG.pm is a perl module on CPAN!');

    my $text = $SVG->text(style=>{'font'=>'Arial','font-size'=>20});
    $text->cdata('SVG.pm is a perl module on CPAN!');


B<Result:>

    E<lt>text style="font: Arial; font-size: 20" E<gt>SVG.pm is a perl module on CPAN!E<lt>/text E<gt>

SEE ALSO:

  L<"CDATA"> L<"desc">, L<"title">, L<"text">, L<"script">.

=head2 CDATA

 $script = $SVG->script();
 $script->CDATA($text);


与えられたもの、そのままで描画される$textの内容を持った<![CDATA[ ... ]]>タグを生成します。
SVG.pmはすべてのタグにcdataを設定することを可能にしています。
タグが空タグの場合、SVG.pmは文句をいいませんが、描画エージョントはコケるでしょう。
SVG DTDでは、cdataは一般にテキストやスクリプトの内容を追加することだけを意味します。

B<Example:>

      my $text = qq而
        var SVGDoc;
        var groups = new Array();
        var last_group;
        
        /*****
        *
        *   init
        *
        *   Find this SVG's document element
        *   Define members of each group by id
        *
        *****/
        function init(e) {
            SVGDoc = e.getTarget().getOwnerDocument();
            append_group(1, 4, 6); // group 0
            append_group(5, 4, 3); // group 1
            append_group(2, 3); // group 2
        }而;
        $SVG->script()->CDATA($text);


B<Result:>

    E<lt>script E<gt>
      <gt>![CDATA[
        var SVGDoc;
        var groups = new Array();
        var last_group;
        
        /*****
        *
        *   init
        *
        *   Find this SVG's document element
        *   Define members of each group by id
        *
        *****/
        function init(e) {
            SVGDoc = e.getTarget().getOwnerDocument();
            append_group(1, 4, 6); // group 0
            append_group(5, 4, 3); // group 1
            append_group(2, 3); // group 2
        }
        ]]E<gt>

SEE ALSO:

  L<"cdata">, L<"script">.

=head2 filter

$tag = $SVG->filter(%attributes)

filterを生成します。filter要素はL<"fe">というfilterサブ要素を持ちます。

B<Example:>

    my $filter = $SVG->filter(
        filterUnits=>"objectBoundingBox",
        x=>"-10%",
        y=>"-10%",
        width=>"150%",
        height=>"150%",
        filterUnits=>'objectBoundingBox'
    );

    $filter->fe();

SEE ALSO:

L<"fe">.

=head2 fe

$tag = $SVG->fe(-type=>'type', %attributes)

filterサブ要素を生成します。L<"filter">要素の子供でなければなりません。

B<Example:>

    my $fe = $SVG->fe(
        -type    => 'DiffuseLighting'  # 必須 - 要素名が省略 'fe'
        id      => 'filter_1',
        style    => {
            'font'    => [ qw(Arial Helvetica sans) ],
            'font-size' => 10,
            'fill'    => 'red',
        },
        transform => 'rotate(-45)'
    );

以下のfilter要素が現在サポートされています：

=over 4

=item * feBlend 

=item * feColorMatrix 

=item * feComponentTransfer 

=item * feComposite

=item * feConvolveMatrix 

=item * feDiffuseLighting 

=item * feDisplacementMap 

=item * feDistantLight 

=item * feFlood 

=item * feFuncA 

=item * feFuncB 

=item * feFuncG 

=item * feFuncR 

=item * feGaussianBlur 

=item * feImage 

=item * feMerge 

=item * feMergeNode 

=item * feMorphology 

=item * feOffset 

=item * fePointLight

=item * feSpecularLighting 

=item * feSpotLight 

=item * feTile 

=item * feTurbulence 

=back

SEE ALSO:

L<"filter">.

=head2 pattern

$tag = $SVG->pattern(%attributes)

urlによって後で参照されるパターンを定義します。

B<Example:>

    my $pattern = $SVG->pattern(
        id   => "Argyle_1",
        width  => "50",
        height => "50",
        patternUnits        => "userSpaceOnUse",
        patternContentUnits => "userSpaceOnUse"
    );

=head2 set

$tag = $SVG->set(%attributes)

必要にあわせて他のセクションでも参照できるよう、１つのセクションでの
SVGオブジェクトのための定義を設定します。

B<Example:>

    my $set = $SVG->set(
        id   => "Argyle_1",
        width  => "50",
        height => "50",
        patternUnits        => "userSpaceOnUse",
        patternContentUnits => "userSpaceOnUse"
    );

=head2 stop

$tag = $SVG->stop(%attributes)

L<"gradient">のためのストップ・バウンダリを定義します。

B<Example:>

   my $pattern = $SVG->stop(
       id    => "Argyle_1",
       width  => "50",
       height => "50",
       patternUnits     => "userSpaceOnUse",
       patternContentUnits => "userSpaceOnUse"
   );

=head2 gradient

$tag = $SVG->gradient(%attributes)

色の傾斜(=gradient)を定義します。B<linear> あるいは B<radial>のタイプにすることができます。

B<Example:>

    my $gradient = $SVG->gradient(
        -type => "linear",
        id  => "gradient_1"
    );

=head1 GENERIC ELEMENT METHODS

以下の要素がSVGによって汎用的にサポートされます:

=over 4

=item * altGlyph

=item * altGlyphDef

=item * altGlyphItem

=item * clipPath

=item * color-profile

=item * cursor

=item * definition-src

=item * font-face-format

=item * font-face-name

=item * font-face-src

=item * font-face-url

=item * foreignObject

=item * glyph

=item * glyphRef

=item * hkern

=item * marker

=item * mask

=item * metadata

=item * missing-glyph

=item * mpath

=item * switch

=item * symbol

=item * tref

=item * view

=item * vkern

=back

これらのメソッドの使い方の例についてはL<"pattern">をご覧ください。