# distribution version
$VERSION = '0.01';

=pod

=head1 NAME

Imager::DTP - draw text with DTP app-like custom options

=head1 SYNOPSIS

   use Imager::DTP::Textbox::Horizontal;  # or Vertical
   
   # first, define font & text string
   my $font  = Imager::Font->new(file=>'path/to/foo.ttf',type=>'ft2',
               size=>12);
   my $text  = "Brother will kill brother, ";
      $text .= "spilling blood across the land.\n";
      $text .= "Killing for religion, "; 
      $text .= "something I don't understand.";
   # with multi-byte characters, encode it to UTF8, with internal
   # utf-8 flag enabled (using utf8::decode()).
   
   # create textbox instance
   my $tb = Imager::DTP::Textbox::Horizontal->new(
               text=>$text,     # set text
               font=>$font,     # set font
               wspace=>5,       # set word distance (pixels)
               leading=>150,    # set line distance (percent)
               halign=>'left',  # set horizontal alignment
               valign=>'top',   # set vertical alignment
               wrapWidth=>200,  # set text wrap width
               wrapHeight=>180  # set text wrap height
            );
   
   # draw the text string on target image
   my $target = Imager->new(xsize=>250,ysize=>250);
   $tb->draw(target=>$target,x=>10,y=>10);

=head1 DESCRIPTION.

Imager::DTP is a text drawing add-on for L<Imager>, with ability to draw texts horizontally or vertically (from top to bottom), letter-based (not word-based) text wrapping for multi-byte characters, line alignment, and adjustment of distance between letters and lines.  Vertical drawing and letter-based text wrapping are for multi-byte character languages, such as Japanese and Chinese.

=head2 MORE THAN WORDS

I've made an interactive sample viewer page, for quick and essential understanding of what the output will look like, by using Imager::DTP.  You can make the output more complexing and fancy by making full use of the module, but save that for later, and just take a glance at all the basics.

=over

=item English Page

F<http://iandeth.dyndns.org/mycpan/Imager-DTP/sample_viewer_en.html>

=item Japanese Page

F<http://iandeth.dyndns.org/mycpan/Imager-DTP/sample_viewer_ja.html>

=back

=head2 UTF8 ENCODING

With multi-byte characters, text must be encoded to utf8, with it's internal utf8-flag ENABLED. This could be done by using utf8::decode() method, or with Perl5.8 and above, by using Encode::decode() method.

=head2 FULL DESCRIPTION

The main module (the most useful one) of Imager::DTP distribution will be Imager::DTP::Textbox.  So see L<Imager::Textbox>'s documentation for full description on how to use.

=head1 CLASS RELATION

Imager::DTP consists of three basic modules (classes).  These are:

=over

=item L<Imager::DTP::Letter>

Module for handling each letter/character that construct words.  One Imager::Letter instance represents/holds one letter/character.

=item L<Imager::DTP::Line>

Module for handling chunk of Letters, lined-up in a single vector.  The word "Line" means "a single row in a text-wrapped textbox".

=item L<Imager::DTP::Textbox>

A box to store all Lines and Letters in order.  Calculation for text wrapping and line alignment are done within this module.

=back

The class relation of these modules (classes) is as follows:

   Imager::DTP::Textbox = [
       
       Imager::DTP::Line = [
       
           Imager::DTP::Letter,
           Imager::DTP::Letter,
           Imager::DTP::Letter
           ...
       
       ],
       
       Imager::DTP::Line = [
       
           Imager::DTP::Letter,
           Imager::DTP::Letter,
           Imager::DTP::Letter
           ...
       
       ],
       
       ...
       
   ];

So there is no actuall Imager::DTP module (Imager::DTP.pm doesn't exist).  The name space is for bundling all these modules under one package name.

=head1 BUGS

Currently, there is one un-solved problem in Imager::DTP::Line, with drawing multi-byte letters vertically.  See L<Imager::DTP::Line>'s BUGS section for details.

=head1 TODO

See each basic module's TODO section.

=head1 AUTHOR

Toshimasa Ishibashi <iandeth99@ybb.ne.jp>

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=head1 SEE ALSO

L<Imager>, L<Imager::DTP::Textbox>, L<Imager::DTP::Line>, L<Imager::DTP::Letter>

=cut
