NAME
Imager::DTP::Line - line handling module for Imager::DTP package.
SYNOPSIS
use Imager::DTP::Line::Horizontal; # or Vertical
# first, define font & text string
my $font = Imager::Font->new(file=>'path/to/foo.ttf',type=>'ft2',
size=>16,color=>'#000000',aa=>1);
my $text = 'master of puppets';
# create instance
my $line = Imager::DTP::Line::Horizontal->new(text=>$text,
font=>$font);
# draw the text string on target image
my $target = Imager->new(xsize=>250,ysize=>50);
$target->box(filled=>1,color=>'#FFFFFF'); # with white background
$line->draw(target=>$target,x=>10,y=>10);
# and write out image to file
$target->write(file=>'result.jpg',type=>'jpeg');DESCRIPTION
Imager::DTP::Line is a module intended for handling chunk of letters lined-up in a single vector, out of the whole text string (sentence or paragraph). Here, the word "Line" is meant to be "a single row", "a single row in a text-wrapped textbox", and not "1-pixel thick line" as in graphical meaning. The text string provided (by setText() method) will be parsed into letters, and each letter will be turned into Imager::DTP::Letter instance internally. Thus, Imager::DTP::Line could be understood as "a content holder for Imager::DTP::Letter instances", or "a box to put Letters in order". Each letter could hold their own font-preferences (like face/size/color), and this could be done by adding text (using setText() method) with different font-preferences one-by-one. Then, you'll only need to call draw() method once to draw all those letters.
# creating instance - basic way
my $line = Imager::DTP::Line::Horizontal->new();
$line->setText(text=>$text,font=>$font); # set text with font
$line->setWspace(pixel=>5); # set space between letters
$line->setLetterScale(x=>1.2,y=>0.5); # set letter transform scale
# creating instance - or the shorcut way
my $line = Imager::DTP::Line::Horizontal->new(text=>$text,
font=>$font, wspace=>5, xscale=>1.2, yscale=>0.5);CLASS RELATION
Imager::DTP::Line is an ABSTRACT CLASS. The extended class would be Imager::DTP::Line::Horizontal and Imager::DTP::Line::Vertical. So you must "use" the extended class (either of Horizonal or Vertical), and not the Imager::DTP::Line itself. The difference between Horizontal and Vertical is as follows:
- Imager::DTP::Line::Horizontal
-
letters are drawn from left to right.
- Imager::DTP::Line::Vertical
-
letters are drawn from top to bottom.
METHODS
BASIC METHODS
new
Can be called with or without options.
use Imager::DTP::Line::Horizontal;
my $line = Imager::DTP::Line::Horizontal->new();
# or perform setText & setWspace method at the same time
my $font = Imager::Font->new(file=>'path/to/foo.ttf',type=>'ft2',
size=>16);
my $text = 'I am the law';
my $line = Imager::DTP::Line::Horizontal->new(text=>$text,
font=>$font,wspace=>5);
# also, can setLetterScale at the same time too.
my $line = Imager::DTP::Line::Horizontal->new(text=>$text,
font=>$font, wspace=>5, xscale=>1.2, yscale=>0.5);setText
Set text string to the instance. Text is optional (without text, it'll act as a blank-line), but when provided, font option must also be provided along with. For multi-byte letters/characters, text must be encoded to utf8, with it's internal utf8-flag ENABLED (This could be done by using utf8::decode() method).
my $font = Imager::Font->new(file=>'path/to/foo.ttf',type=>'ft2',
size=>16);
my $text = 'peace sells';
$line->setText(text=>$text,font=>$font);By default, each time the method is called, it replaces the previous text with the provided new text. But by putting the "add" option, it will add new text to the end of the current text.
# as from above sample, this will make
# the internal text to "peace sells but whos buying?"
my $moreText = ' but whos buying?';
$line->setText(text=>$moreText,add=>1);Font is optional this time. If there is any previous text set, the new text will automatically inherit the font preference of the previous text.
The following characters will be translated to corresponding string internally:
setWspace
Wspace is a blank space between each letters. By setting a value (in pixels), a blank space will be inserted in between each letters. Usefull with multi-byte characters, especially with vertical lines, adding much readability to it. The default value is 0.
# setting a 5 pixel word space
$line->setWspace(pixel=>5);setLetterScale
Setting x/y scale will make each letter transform to the specified ratio. See <Imager::DTP::Letter>->setScale() method for further description.
# make width of each letter to 80%
$line->setLetterScale(x=>0.8);
# make width 120% and height 60%
$line->setLetterScale(x=>1.2,y=>0.6);draw
Draw letters in a single vector, to the target image (Imager object).
my $target = Imager->new(xsize=>250,ysize=>50);
$line->draw(target=>$target,x=>10,y=>10);Each letter is drawn with Imager::DTP::Letter->draw() method, which internally is using Imager->String() method, so you can pass any extra Imager::String options to it by setting in 'others' option (See more details in Imager::DTP::Letter->draw() method description).
# passing Imager::String options
$line->draw(target=>$target,x=>10,y=>10,others=>{aa=>1});There is an extra debug option, which will draw a 'width x height' light gray box underneath, and a gray bounding box fr each letters. Handy for checking each object's bounding size/position.
# debug mode
$line->draw(target=>$target,x=>10,y=>10,debug=>1);GETTER METHODS
Calling these methods will return a property value corresponding to the method name.
getLetters
Returns a reference (pointer) to an array containing all the Imager::DTP::Letter object held internally.
getWidth
Returns the total width of line, meaning sum of all the wspaces in between, and each letter's advanced width.
getAscent
Compares each letter's ascent, and returns the maximum value.
getDescent
Compares each letter's descent, and returns the minimum value (since descent is usually negative integers).
getHeight
Returns the sum of getAscent() + (-getDescent()). This will be the total height of the line.
getWspace
Returns the current value of word space.
BUGS
I can't figure out a way to call vertical-fonts inplemented inside multi-byte fonts. Thus with Imager::DTP::Line::Vertical, punctuation character's position will be weird & odd, since it's just using normal horizontal fonts. There seems to be a report of success with LaTex + Freetype... need more research on it.
TODO
base-line alignment (align=>1)
figure out a way to use vertical-fonts in Imager::DTP::Line::Vertical
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.