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
Returns the width (in pixels) of the instance.
getHeight
Returns the height (in pixels) of the instance.
getAscent
Returns the ascent (in pixels) of the instance.
getDescent
Returns the descent (in pixels) of the instance.
getAdvancedWidth
Returns the advanced width (in pixels) of the instance.
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.