NAME
Imager::DTP::Letter - letter handling module for Imager::DTP package
SYNOPSIS
use Imager::DTP::Letter;
# first, define font & letter string
my $font = Imager::Font->new(file=>'path/to/foo.ttf',type=>'ft2',
size=>16,color=>'#000000',aa=>1);
my $text = 'A';
# create instance - basic way
my $ltr = Imager::DTP::Letter->new();
$ltr->setText(text=>$text); # set text
$ltr->setFont(font=>$font); # set font
$ltr->setScale(x=>1.2,y=>0.5); # set transform scale (optional)
# create instance - or the shorcut way
my $ltr = Imager::DTP::Letter->new(text=>$text,font=>$font,
xscale=>1.2,yscale=>0.5);
# draw letter on target image
my $target = Imager->new(xsize=>50,ysize=>50);
$target->box(filled=>1,color=>'#FFFFFF'); # with white background
$ltr->draw(target=>$target,x=>10,y=>10);
# and write out image to file
$target->write(file=>'result.jpg',type=>'jpeg');DESCRIPTION
Imager::DTP::Letter is a module intended for handling each letter/character in a whole text string (sentence or paragraph). Each Imager::DTP::Letter instance will hold one letter/character internally, and it holds various information about the letter/character, most of it aquired from Imager::Font->bounding_box() method. Thus, Imager::DTP::Letter is intended to act as a single letter with font information (such as ascent/descent) bundled together. It is allowed to set more than one letter/character to a single Imager::DTP::Letter instance, but still, the whole Imager::DTP package will handle the instance as 'single letter'.
METHODS
BASIC METHODS
new
Can be called with or without options.
use Imager::DTP::Letter;
my $ltr = Imager::DTP::Letter->new();
# or perform setText & setFont method at the same time
my $font = Imager::Font->new(file=>'path/to/foo.ttf',type=>'ft2',
size=>16);
my $text = 'A';
my $ltr = Imager::DTP::Letter->new(text=>$text,font=>$font);
# also, can setScale at the same time too.
my $ltr = Imager::DTP::Letter->new(text=>$text,font=>$font,
xscale=>1.2,yscale=>0.5);setText
Set letter/character to the instance. You must supply some letter/character to text option (it must not be undef or ''). And for multi-byte letter/characters, text must be encoded to utf8, with it's internal utf8-flag ENABLED (This could be done by using utf8::decode() method).
$ltr->setText(text=>'Z');
# each time setText is called, previous text will be cleared.
# like this, internal property will be 'X', not 'ZX'.
$ltr->setText(text=>'X'); setFont
Must supply an Imager::Font object with freetype option (type=>'ft2'). Might work just fine with other font types like type=>'t1' and type=>'tt' too... it's just that I haven't tried yet :P
my $font = Imager::Font->new(file=>'path/to/foo.ttf',type=>'ft2',
size=>16);
$ltr->setFont(font=>$font);The following Imager::Font options are forced to these values internally. Other options will work fine.
utf8 => 1
vlayout => 0
setScale
By setting x and y scaling to ratios other than 1.0 (default setting), you can make letters wider/narrower, or longer/shorter (width and height transformation).
# make width of letter to 80%
$ltr->setScale(x=>0.8);
# make width 120% and height 60%
$ltr->setScale(x=>1.2,y=>0.6);Transformation is done by using Imager::Font->transform() method, with the help of Imager::Matrix2d module.
draw
Draw letter/character to the target image (Imager object).
my $target = Imager->new(xsize=>50,ysize=>50);
$ltr->draw(target=>$target,x=>10,y=>10);Imager->String() method is called internally, so you can pass any extra Imager::String options to it by setting in 'others' option.
# passing Imager::String options
$ltr->draw(target=>$target,x=>10,y=>10,others=>{aa=>1});But the following Imager::String options are forced to these values internally, meant for proper result. Other options will work fine.
utf8 => 1
vlayout => 0
align => 0
There is an extra debug option, which will draw a 'letter width x letter ascent' gray box around the letter. Handy for checking the letter's bounding size/position.
# debug mode
$ltr->draw(target=>$target,x=>10,y=>10,debug=>1);GETTER METHODS
Calling these methods will return a property value corresponding to the method name.
getText
Returns the letter/character string.
getFont
Returns a reference (pointer) to the Imager::Font object.
getScale
Returns an array containing the current x/y scale setting.
my($x,$y) = $self->getScale();getWidth
getHeight
getAscent
getDescent
getAdvancedWidth
getLeftBearing
getRightBearing
getGlobalAscent
getGlobalDescent
getEndOffset
These returns the designated property value (in pixels) of current letter, when drawn with the current font setting. See Imager::Font::BBox's documentation for description on each properties.
TODO
change Carp-only error handling to something more elegant.
AUTHOR
Toshimasa Ishibashi, <iandeth99@ybb.ne.jp>
COPYRIGHT & LICENSE
Copyright 2005 Toshimasa Ishibashi, all rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.