.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Text::Align 3"
.TH Text::Align 3 "2003-02-25" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
GD::Text::Align \- Draw aligned strings
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use GD;
\&  use GD::Text::Align;
\&
\&  my $gd = GD::Image\->new(800,600);
\&  # allocate colours, do other things.
\&
\&  my $align = GD::Text::Align\->new($gd
\&    valign => \*(Aqtop\*(Aq,
\&    halign => \*(Aqright\*(Aq,
\&  );
\&  $align\->set_font(\*(Aqarial\*(Aq, 12);
\&  $align\->set_text(\*(Aqsome string\*(Aq);
\&  @bb = $align\->bounding_box(200, 400, PI/3);
\&  # you can do things based on the bounding box here
\&  $align\->draw(200, 400, PI/3);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
GD::Text::Align provides an object that draws a string aligned
to a coordinate at an angle.
.PP
For builtin fonts only two angles are valid: 0 and \s-1PI/2.\s0 All other
angles will be converted to one of these two.
.SH "METHODS"
.IX Header "METHODS"
This class inherits everything from GD::Text. I will only discuss the
methods and attributes here that are not discussed there, or that have a
different interface or behaviour. Methods directly inherited include
\&\f(CW\*(C`set_text\*(C'\fR and \f(CW\*(C`set_font\*(C'\fR.
.SS "GD::Text::Align\->new($gd_object, attrib => value, ...)"
.IX Subsection "GD::Text::Align->new($gd_object, attrib => value, ...)"
Create a new object. The first argument to new has to be a valid
GD::Image object. The other arguments will be passed on to the set
method.
.ie n .SS "$align\->set(attrib => value, ...)"
.el .SS "\f(CW$align\fP\->set(attrib => value, ...)"
.IX Subsection "$align->set(attrib => value, ...)"
Set an attribute. Valid attributes are the ones discussed in
GD::Text and:
.IP "valign, halign" 4
.IX Item "valign, halign"
Vertical and horizontal alignment of the string. See also set_valign and
set_halign.
.IP "colour, color" 4
.IX Item "colour, color"
Synonyms. The colour to use to draw the string. This should be the index
of the colour in the GD::Image object's palette. The default value is
the last colour in the \s-1GD\s0 object's palette at the time of the creation
of \f(CW$align\fR.
.ie n .SS "$align\->get(attribute)"
.el .SS "\f(CW$align\fP\->get(attribute)"
.IX Subsection "$align->get(attribute)"
Get the value of an attribute.
Valid attributes are all the attributes mentioned in GD::Text, the
attributes mentioned under the \f(CW\*(C`set\*(C'\fR method and
.IP "x, y and angle" 4
.IX Item "x, y and angle"
The x and y coordinate and the angle to be used. You can only do this
after a call to the draw or bounding_box methods. Note that these
coordinates are not necessarily the same ones that were passed in.
Instead, they are the coordinates from where the \s-1GD\s0 methods will start
drawing. I doubt that this is very useful to anyone.
.PP
Note that while you can set the colour with both 'color' and 'colour',
you can only get it as 'colour'. Sorry, but such is life in Australia.
.ie n .SS "$align\->set_valign(value)"
.el .SS "\f(CW$align\fP\->set_valign(value)"
.IX Subsection "$align->set_valign(value)"
Set the vertical alignment of the string to one of 'top', 'center',
\&'base' or 'bottom'. For builtin fonts the last two are the same. The
value 'base' denotes the baseline of a TrueType font.
Returns true on success, false on failure.
.ie n .SS "$align\->set_halign(value)"
.el .SS "\f(CW$align\fP\->set_halign(value)"
.IX Subsection "$align->set_halign(value)"
Set the horizontal alignment of the string to one of 'left', 'center',
or 'right'. 
Returns true on success, false on failure.
.ie n .SS "$align\->set_align(valign, halign)"
.el .SS "\f(CW$align\fP\->set_align(valign, halign)"
.IX Subsection "$align->set_align(valign, halign)"
Set the vertical and horizontal alignment. Just here for convenience.
See also \f(CW\*(C`set_valign\*(C'\fR and \f(CW\*(C`set_halign\*(C'\fR.
Returns true on success, false on failure.
.ie n .SS "$align\->draw(x, y, angle)"
.el .SS "\f(CW$align\fP\->draw(x, y, angle)"
.IX Subsection "$align->draw(x, y, angle)"
Draw the string at coordinates \fIx\fR, \fIy\fR at an angle \fIangle\fR in
radians. The x and y coordinate become the pivot around which the
string rotates.
.PP
Note that for the builtin \s-1GD\s0 fonts the only two valid angles are 0 and
\&\s-1PI/2.\s0
.PP
Returns the bounding box of the drawn string (see \f(CW\*(C`bounding_box()\*(C'\fR).
.ie n .SS "$align\->bounding_box(x, y, angle)"
.el .SS "\f(CW$align\fP\->bounding_box(x, y, angle)"
.IX Subsection "$align->bounding_box(x, y, angle)"
Return the bounding box of the string to draw. This returns an
eight-element list (exactly like the GD::Image\->stringTTF method):
.PP
.Vb 4
\&  (x1,y1) lower left corner
\&  (x2,y2) lower right corner
\&  (x3,y3) upper right corner
\&  (x4,y4) upper left corner
.Ve
.PP
Note that upper, lower, left and right are relative to the string, not
to the canvas.
.PP
The bounding box can be used to make decisions about whether to move the
string or change the font size prior to actually drawing the string.
.SH "NOTES"
.IX Header "NOTES"
As with all Modules for Perl: Please stick to using the interface. If
you try to fiddle too much with knowledge of the internals of this
module, you may get burned. I may change them at any time.
.PP
You can only use TrueType fonts with version of \s-1GD \s0> 1.20, and then
only if compiled with support for this. If you attempt to do it
anyway, you will get errors.
.PP
In the following, terms like 'top', 'upper', 'left' and the like are all
relative to the string to be drawn, not to the canvas.
.SH "BUGS"
.IX Header "BUGS"
Any bugs inherited from GD::Text.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
copyright 1999
Martien Verbruggen (mgjv@comdyn.com.au)
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\s-1GD\s0, GD::Text, GD::Text::Wrap