Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man3 / Pastel::Graphics.3

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Pastel::Graphics 3"
.TH Pastel::Graphics 3 "2003-04-29" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
Pastel::Graphics \- Graphics context.\r
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Pastel;
.Ve
.PP
.Vb 3
\&  my $graphics = Pastel::Graphics->new(...);\r
\&  $graphics->foo();\r
\&  $graphics->bar();
.Ve
.PP
.Vb 1
\&  $graphics->show(); #dump the graphics on STDOUT
.Ve
.PP
.Vb 1
\&     -or-
.Ve
.PP
.Vb 2
\&  my $string = $graphics->get_svg(); # get the graphic as string\r
\&  print $string;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Pastel::Graphics\*(C'\fR is the main workhorse of Pastel. It is equivalent to\r
Java Graphics2D class. Each program first has to create once instance\r
of this class, then call methods on this and lastly dump the whole\r
instance onto \s-1STDOUT\s0 or get it as string.\r
.PP
The class provides the graphics context in that it hold all the\r
necessary informations for drawing any graphics object correctly.\r
.PP
All styles like fonts, color and strokes are set into this class by\r
calling appropriate methods. Shapes and Strings are drawn by calling\r
\&\f(CW\*(C`draw()\*(C'\fR and \f(CW\*(C`draw_string()\*(C'\fR methods. For a tutorial introduction see\r
Pastel programming manual.\r
.PP
There are certain shortcut methods that are inbuilt into this\r
module. You can draw shapes without creating additional\r
objects. Notable among these classes of methods are \f(CW\*(C`draw_3D_rect()\*(C'\fR\r
and \f(CW\*(C`draw_round_rect()\*(C'\fR which are not availble from the\r
Pastel::Geometry::Rectangle class.\r
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.Sh "\fInew()\fP"
.IX Subsection "new()"
Creates and returns a new \f(CW\*(C`Pastel::Graphics\*(C'\fR object.\r
.PP
.Vb 3
\&  Usage : $graphics = Pastel::Graphics->new(-width=>$w,\r
\&                                               -height=>$h,\r
\&                                               -DTD   =>$dtd );
.Ve
.PP
.Vb 6
\&   Args : $w  - Optional. Width of the SVG document in pixels. If not\r
\&                provided default is 800.\r
\&          $h  - Optional. Height of the SVG document in pixels. If not\r
\&                provided the default is 600.\r
\&         $dtd - Optional. DTD used for SVG document. You can pass your\r
\&                own DTD.
.Ve
.PP
.Vb 1
\& Returns: Pastel::Graphics object
.Ve
.SH "METHODS"
.IX Header "METHODS"
.Sh "\fIset_font()\fP"
.IX Subsection "set_font()"
Set the font for all the graphics object. Any string drawn using\r
\&\f(CW\*(C`draw_string()\*(C'\fR after calling this method will be drawn using the\r
font presently set using this method. Note that\r
\&\f(CW\*(C`Pastel::Text::AttributedString\*(C'\fR objects are immune to font\r
context. To set the font of \f(CW\*(C`Pastel::Text::AttributedString\*(C'\fR you need\r
to set the font by setting it as attribute of the \f(CW\*(C`AttributedString\*(C'\fR\r
object.\r
.PP
.Vb 1
\&  Usage   : set_font($font)
.Ve
.PP
.Vb 1
\&  Args    : $font is a  Pastel::Font object.
.Ve
.PP
.Vb 1
\&  Returns : Nothing.
.Ve
.Sh "\fIset_paint()\fP"
.IX Subsection "set_paint()"
Sets the color of the graphics context. Any drawing of shapes or text\r
will be carried out using the color presently set in the graphics\r
context. The color can be solid color of Pastel::Color object or a\r
gradient implementing Pastel::GradientI interface.\r
.PP
.Vb 1
\& Usage   : set_paint($color)
.Ve
.PP
.Vb 1
\& Args    : $color is a Pastel::Color or Pastel::GradientI object.
.Ve
.PP
.Vb 1
\& Returns : Nothing.
.Ve
.Sh "\fIset_stroke()\fP"
.IX Subsection "set_stroke()"
If the current graphics context has the stroke object set then all\r
further drawings will be stroked. The stroke color will be the current\r
color set using \f(CW\*(C`set_paint()\*(C'\fR method. The swith off the stroking you\r
need to unset the stroke by calling this method without any argument.\r
.PP
Because stroking is done using the current color set in the graphics\r
context, to draw an object with both stroke and fill where the\r
stroke-color and the fill-color are different, you need to fill the\r
object first and set a different color before you draw the object. To\r
draw a rectangle with blue border and red fill you might do this:\r
.PP
.Vb 10
\&             $g = Pastel::Graphics->new();\r
\&             $g->set_paint(Pastel::Color->red());\r
\&             $g->set_stroke( Pastel::BasicStroke->new(-width=>5) );\r
\&             my $rect = Pastel::Geometry::Rectangle(\r
\&                                                 -x=>20,-y=>30,\r
\&                                                 -width=>100,-height=>150\r
\&                                                   );\r
\&             $g->fill($rect); # filled with red color\r
\&             $g->set_paint(Pastel::Color->blue());\r
\&             $g->draw($rect);
.Ve
.PP
.Vb 2
\&  Usage   : set_stroke($stroke) # set the stroke object\r
\&            set_stroke()        # unset stroking
.Ve
.PP
.Vb 1
\&  Args    : $stroke is a Pastel::BasicStroke object.
.Ve
.PP
.Vb 1
\&  Returns : Nothing.
.Ve
.Sh "\fIget_font()\fP"
.IX Subsection "get_font()"
Returns the current font object in the graphics context.\r
.PP
.Vb 1
\& Usage   : get_font();
.Ve
.PP
.Vb 1
\& Args    : Nothing.
.Ve
.PP
.Vb 1
\& Returns : Pastel::Font object.
.Ve
.Sh "\fIget_paint()\fP"
.IX Subsection "get_paint()"
Returns the current paint object in the graphics context.\r
.PP
.Vb 1
\& Usage   : $g->get_paint()
.Ve
.PP
.Vb 1
\& Args    : Nothing.
.Ve
.PP
.Vb 1
\& Returns : Pastel::Color or object implementing Pastel::GradientI interface.
.Ve
.Sh "\fIget_stroke()\fP"
.IX Subsection "get_stroke()"
Return the current stroke object in the graphics context. \r
.PP
.Vb 1
\&  Usage   :  get_stroke()
.Ve
.PP
.Vb 1
\&  Args    :  Nothing.
.Ve
.PP
.Vb 1
\&  Returns :  Pastel::BasicStroke object if stroke is set or undef if not set.
.Ve
.Sh "\fIdraw_rect()\fP"
.IX Subsection "draw_rect()"
Shortcut function to draw a rectangle without creating additional\r
object. The rectangle is stroked with the current \f(CW\*(C`BasicStroke\*(C'\fR\r
object. If the \f(CW\*(C`BasicStroke\*(C'\fR is not set then the rectangle is created\r
using an 1 pixel width line. The color of the line is determined by\r
the current paint.\r
.PP
.Vb 1
\&  Usage   : draw_rect($x, $y, $width, $height)
.Ve
.PP
.Vb 4
\&  Args    : $x     - X coordinate of the top left corner vertice of rectangle.\r
\&            $y     - Y coordinate of the top left corner vertice of rectangle.\r
\&            $width - Width of the rectangle.\r
\&            $height- Height of the rectangle.
.Ve
.PP
.Vb 1
\&  Returns : Nothing.
.Ve
.Sh "\fIfill_rect()\fP"
.IX Subsection "fill_rect()"
Shortcut function to draw a filled rectangle without creating\r
additional objects. The rectangle is filled with the current paint in\r
the graphics context.\r
.PP
.Vb 1
\&  Usage  : fill_rect($x, $y, $width, $height);
.Ve
.PP
.Vb 4
\&  Args   : $x     - X coordinate of the top left corner of the rectangle.\r
\&           $y     - Y coordinate of the top left corner of the rectangle.\r
\&           $width - Width of the rectangle in pixels.\r
\&           $height- Height of the rectangle in pixels.
.Ve
.PP
.Vb 1
\& Returns  : Nothing
.Ve
.Sh "\fIdraw_round_rect()\fP"
.IX Subsection "draw_round_rect()"
Shortcut fuction to draw open rectangle with rounded corners. The\r
rectangle is stroked with the current stroke if it is set. Otherwise\r
it is drawn with 1 pixel width line. The color is determined by the\r
current paint object.\r
.PP
.Vb 2
\&  Usage : draw_round_rect($x, $y, $width, $height,\r
\&                         $arc_width, $arc_height);
.Ve
.PP
.Vb 6
\&   Args : $x          - X coordinate of the top left hand corner.\r
\&          $y          - Y coordinate of the top left hand corner.\r
\&          $width      - Width of the rectangle.\r
\&          $height     - Height of the rectangle.\r
\&          $arc_width  - Horizontal diameter of the arc at the four corners.\r
\&          $arc_height - vertical diameter of the arc at the four corners.
.Ve
.PP
.Vb 1
\& Returns : Nothing
.Ve
.Sh "\fIdraw_fill_round_rect()\fP"
.IX Subsection "draw_fill_round_rect()"
Draws a filled rectangle with rounded corners. The rectangle is filled\r
with the current paint object in the graphics context.\r
.PP
.Vb 2
\&  Usage : $g->draw_fill_round_rect($x, $y, $width, $height,\r
\&                              $arc_width, $arc_height);
.Ve
.PP
.Vb 6
\&   Args : $x          - X coordinate of the top left hand corner.\r
\&          $y          - Y coordinate of the top left hand corner.\r
\&          $width      - Width of the rectangle.\r
\&          $height     - Height of the rectangle.\r
\&          $arc_width  - Horizontal diameter of the arc at the four corners.\r
\&          $arc_height - vertical diameter of the arc at the four corners.
.Ve
.PP
.Vb 1
\&  Returns : Nothing
.Ve
.Sh "\fIdraw_3D_rect()\fP"
.IX Subsection "draw_3D_rect()"
Draws a highlighted 3D effect rectangle. \r
.PP
.Vb 1
\&  Usage   : $g->draw_3D_rect($x, $y, $width, $height, $raised, $bevel);
.Ve
.PP
.Vb 6
\&  Args    : $x - Top left corner X coordinate  of the rectangle.\r
\&            $y - Top left corner Y coordinate  of the rectangle.\r
\&            $width - Width of the rectangle.\r
\&            $height - Height of the rectangle.\r
\&            $raised - Optional. Takes value "true" or "false". Default "true". \r
\&            $bevel  - Optional. Width of the bevel. Default 1.
.Ve
.PP
.Vb 1
\&  Returns : Nothing
.Ve
.Sh "\fIdraw()\fP"
.IX Subsection "draw()"
Draws a \f(CW\*(C`Pastel::Shape\*(C'\fR object. The object is stroked using the current\r
stroke object in the graphics context using the current paint object\r
in the graphics context. The method works for any object which is a\r
subclass of \f(CW\*(C`Pastel::Shape\*(C'\fR.\r
.PP
If you subclass Pastel::Shape. The child class must implement\r
\&\f(CW\*(C`get_shape()\*(C'\fR method, which should return an instance of the graphics\r
primitive (classes in \f(CW\*(C`Pastel::Geometry\*(C'\fR).\r
.PP
.Vb 1
\& Usage   : draw($shape)
.Ve
.PP
.Vb 2
\& Args    : $shape - an object subclassed from Pastel::Shape. All the\r
\&                    classes in Pastel::Geometry are subclass of Pastel::Shape.
.Ve
.PP
.Vb 1
\& Returns : Nothing
.Ve
.Sh "\fIdraw_string()\fP;"
.IX Subsection "draw_string();"
Draws the string supplied in the co-ordinates specified. Three types\r
of strings can be drawn using this method. Native perl strings can be\r
supplied which will be internally converted into suitable format. The\r
entities are automatically escaped. You can even pass perl unicode\r
strings directly into the method.\r
.PP
The methods also accepts \f(CW\*(C`Pastel::String\*(C'\fR objects which are nothing\r
but an \s-1XML\s0 formatted container for the perl string.\r
.PP
In both these above cases the font in which the string will drawn is\r
the current font object in the graphics context. The strings will also\r
be stroked with the current stroke in the graphics context and it will\r
drawn in the current paint color. \r
.PP
The method also accepts \f(CW\*(C`Pastel::Text::AttributedString\*(C'\fR object. In\r
Java you pass an \f(CW\*(C`AttributedCharacterIterator\*(C'\fR into this method. In\r
Pastel you pass the \f(CW\*(C`AttributedString\*(C'\fR object\r
itself. \f(CW\*(C`AttributedString\*(C'\fR object are immune to current graphics\r
context. If you want to change the stroke or color of the\r
\&\f(CW\*(C`AttributedString\*(C'\fR do so in the directly in the object.\r
.PP
A major way in which \f(CW\*(C`Pastel\*(C'\fR differs from \f(CW\*(C`Java2D\*(C'\fR is that the\r
coordinates can be arrays of numbers each determining the coordinated\r
of each character in the string. See \s-1SVG\s0 specification for more\r
details.\r
.PP
.Vb 4
\&  Usage : draw_string("perl string", $x, $y);\r
\&          draw_string("perl string", \e@x, \e@y);\r
\&          draw_string( $string,$x, $y);\r
\&          draw_string( $string, \e@x, \e@y);
.Ve
.PP
.Vb 6
\&  Args : The method takes 3 arguments. The first argument can be an\r
\&         object of type Pastel::String or a pure perl string or\r
\&         Pastel::Text::AttributedString. The string supplied is converted to\r
\&         XML form automatically. All character code above 126 is converted to\r
\&         "&xff;" form. "<", ">", "&" and other XML entities are automatically\r
\&         created.
.Ve
.PP
.Vb 6
\&         The second argument can be a single numerical value\r
\&         indicating the X cordinate of the first character of the\r
\&         string or the middle of the total length of the string or the\r
\&         last character depending on text anchoring. This argument\r
\&         also be a reference to an array indicating the X coordinates\r
\&         of successive characters in the string.
.Ve
.PP
.Vb 3
\&         The third argument can be a single numerical or a reference\r
\&         to an array of numericals indicating the Y coordinate of the\r
\&         baseline of the glyph used for drawing the font.
.Ve
.Sh "\fIshow()\fP"
.IX Subsection "show()"
Dumps the graphics object as \s-1SVG\s0 on \s-1STDOUT\s0.\r
.PP
.Vb 1
\& Usage   : show()
.Ve
.PP
.Vb 1
\& Args    : Nothing.
.Ve
.PP
.Vb 1
\& Returns : Nothing.
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.SH "COPYRIGHTS"
.IX Header "COPYRIGHTS"
Copyright (c) 2003 by Malay <curiouser@ccmb.res.in>. All rights reserved.\r
.PP
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.\r