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.

SEE ALSO

Imager, Imager::DTP

cpanm Imager::DTP::Line

perl -MCPAN -e shell
install Imager::DTP::Line