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

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);

DESCRIPTION.
    Imager::DTP is a text drawing add-on for 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.

  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.

    English Page
        http://iandeth.dyndns.org/mycpan/Imager-DTP/sample_viewer_en.html

    Japanese Page
        http://iandeth.dyndns.org/mycpan/Imager-DTP/sample_viewer_ja.html

  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.

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

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

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

    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".

    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.

    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.

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

TODO
    See each basic module's TODO section.

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.

SEE ALSO
    Imager, Imager::DTP::Textbox, Imager::DTP::Line, Imager::DTP::Letter