###
PDF
###


****
NAME
****


Kernel::System::PDF - pdf lib


***********
DESCRIPTION
***********


Functions for generating PDF files.


****************
PUBLIC INTERFACE
****************


new()
=====


Don't use the constructor directly, use the ObjectManager instead:


.. code-block:: perl

     my $PDFObject = $Kernel::OM->Get('Kernel::System::PDF');


Please note that currently you should only create one PDF object per instance of
this class.


DocumentNew()
=============


Create a new PDF Document

These font aliases are available in all methods:
        Proportional
        ProportionalBold
        ProportionalItalic
        ProportionalBoldItalic
        Monospaced
        MonospacedBold
        MonospacedItalic
        MonospacedBoldItalic


.. code-block:: perl

     $True = $PDFObject->DocumentNew(
         Title     => 'The Document Title',  # Title of PDF Document
         Encode    => 'utf-8',               # Charset of Document
         Testfonts => 1,                     # (optional) default 0
     );



PageBlankNew()
==============


Create a new, blank Page


.. code-block:: perl

     $True = $PDFObject->PageBlankNew(
         Width           => 200,          # (optional) default 595 (Din A4) - _ both or nothing
         Height          => 300,          # (optional) default 842 (Din A4) -
         PageOrientation => 'landscape',  # (optional) default normal (normal|landscape)
         MarginTop       => 40,           # (optional) default 0 -
         MarginRight     => 40,           # (optional) default 0  |_ all or nothing
         MarginBottom    => 40,           # (optional) default 0  |
         MarginLeft      => 40,           # (optional) default 0 -
         ShowPageNumber  => 0,            # (optional) default 1
     );



PageNew()
=========


Create a new Page


.. code-block:: perl

     $PDFObject->PageNew(
         Width           => 200,                 # (optional) default 595 (Din A4)
         Height          => 300,                 # (optional) default 842 (Din A4)
         PageOrientation => 'landscape',         # (optional) default normal (normal|landscape)
         MarginTop       => 40,                  # (optional) default 0
         MarginRight     => 40,                  # (optional) default 0
         MarginBottom    => 40,                  # (optional) default 0
         MarginLeft      => 40,                  # (optional) default 0
         ShowPageNumber  => 0,                   # (optional) default 1
         LogoFile        => '/path/to/file.jpg', # (optional) you can use jpg, gif and png-Images
         HeaderRight     => 'Header Right Text', # (optional)
         HeadlineLeft    => 'Headline Text',     # (optional)
         HeadlineRight   => 'Headline Text',     # (optional)
         FooterLeft      => 'Footer Left Text',  # (optional)
         FooterRight     => 'Footer Right Text', # (optional)
     );



DocumentOutput()
================


Return the PDF as string


.. code-block:: perl

     $DocumentString = $PDFObject->DocumentOutput();



Table()
=======


Add a table.

In case of missing or misused parameters, \ ``undef``\  is returned in scalar context
and an empty list is returned in list context.


.. code-block:: perl

     Return
         $Return{State}
         $Return{RequiredWidth}
         $Return{RequiredHeight}
         $Return{CellData}                # (reference) complete calculated
         $Return{ColumnData}              # (reference) complete calculated
 
     %Return = $PDFObject->Table(
         CellData            => $CellData,    # 2D arrayref (see example)
         ColumnData          => $ColumnData,  # arrayref (see example)
         RowData             => $RowData,     # arrayref (see example)
         Type                => 'Cut',        # (optional) default ReturnLeftOver (ReturnLeftOver|ReturnLeftOverHard|Cut)
         Width               => 300,          # (optional) default maximal width
         Height              => 400,          # (optional) default minimal height
         Font                => 'Monospaced', # (optional) default Proportional (see DocumentNew())
         FontSize            => 9,            # (optional) default 11
         FontColor           => 'red',        # (optional) default black
         FontColorEven       => 'blue',       # (optional) cell font color for even rows
         FontColorOdd        => 'green',      # (optional) cell font color for odd rows
         Align               => 'right',      # (optional) default left (left|center|right)
         Lead                => 3,            # (optional) default 1
         Padding             => 18,           # (optional) default 3
         PaddingTop          => 10,           # (optional) top cell padding, overides Padding
         PaddingRight        => 30,           # (optional) right cell padding, overides Padding
         PaddingBottom       => 30,           # (optional) bottom cell padding, overides Padding
         PaddingLeft         => 10,           # (optional) left cell padding, overides Padding
         BackgroundColor     => '#101010',    # (optional) default white
         BackgroundColorEven => '#F0F0F0',    # (optional) cell background color for even rows
         BackgroundColorOdd  => '#A0A0A0',    # (optional) cell background color for odd rows
         Border              => 1,            # (optional) default 1 (values between 0 and 20)
         BorderColor         => '#FF0000',    # (optional) default black
     );
 
     $CellData = [
         [
             {
                 Content         => "Cell 1 (Row 1, Column 1)",  # (optional)
                 Font            => 'Monospaced',                   # (optional) (see DocumentNew())
                 FontSize        => 13,                         # (optional)
                 FontColor       => '#00FF00',                 # (optional)
                 Align           => 'center',                      # (optional)
                 Lead            => 7,                              # (optional)
                 BackgroundColor => '#101010',           # (optional)
             },
             {
                 Content => "Cell 2 (Row 1, Column 2)",
             },
         ],
         [
             {
                 Content => "Cell 3 (Row 2, Column 1)",
             },
             {
                 Content => "Cell 4 (Row 2, Column 2)",
             },
         ],
     ];
 
     $ColumData = [        # this array was automaticly generated, if not given
         {
             Width => 11,  # (optional)
         },
         {
             Width => 44,
         },
     ];
 
     $RowData = [           # this array was automaticly generated, if not given
         {
             Height => 11,  # (optional)
         },
         {
             Height => 44,
         },
     ];



Text()
======


Output a text line


.. code-block:: perl

     Return
         $Return{State}
         $Return{RequiredWidth}
         $Return{RequiredHeight}
         $Return{LeftOver}
 
     %Return = $PDFObject->Text(
         Text     => 'Text',              # Text
         Width    => 300,                 # (optional) available width of textblock
         Height   => 200,                 # (optional) available height of textblock
         Type     => 'Cut',               # (optional) default ReturnLeftOver (ReturnLeftOver|ReturnLeftOverHard|Cut)
         Font     => 'ProportionalBold',  # (optional) default Proportional  (see DocumentNew())
         FontSize => 15,                  # (optional) default 10
         Color    => '#FF0000',           # (optional) default #000000
         Align    => 'center',            # (optional) default left (left|center|right)
         Lead     => 20,                  # (optional) default 1 distance between lines
     );



Image()
=======


Output a image


.. code-block:: perl

     $True = $PDFObject->Image(
         File   => '/path/image.gif',  # (gif|jpg|png)
         Type   => 'ReturnFalse',      # (optional) default Reduce (ReturnFalse|Reduce)
         Width  => 300,                # width of image
         Height => 150,                # height of image
     );



HLine()
=======


Output a horizontal line


.. code-block:: perl

     $True = $PDFObject->HLine(
         Width     => 300,           # (optional) default 'end of printable dimension'
         Type      => 'ReturnFalse', # (optional) default Cut (ReturnFalse|Cut)
         Color     => '#101010',     # (optional) default black
         LineWidth => 1,             # (optional) default 1
     );



PositionSet()
=============


Set new position on current page


.. code-block:: perl

     $True = $PDFObject->PositionSet(
         Move => 'absolut',  # (optional) default absolut (absolut|relativ)
         X    => 10,         # (optional) (<integer>|left|center|right)
         Y    => 20,         # (optional) (<integer>|top|middle|bottom)
     );



PositionGet()
=============


Get position on current page


.. code-block:: perl

     Return
         $Position{X}
         $Position{Y}
 
     %Position = $PDFObject->PositionGet();



DimSet()
========


Set active dimension


.. code-block:: perl

     $Dim = $PDFObject->DimSet(
         Dim => 'printable',  # (optional) default content (content|printable)
     );



DimGet()
========


Get active dimension (printable or content)


.. code-block:: perl

     $Dim = $PDFObject->DimGet();



_TableCalculate()
=================


calculate params of table.


.. code-block:: perl

     Return  # normally no return required, only references
         %Param


The returned hash is usually not needed, as the passed in references are
modified in place.
In case of missing or misused parameters, C<undef> is returned in scalar context
and an empty list is returned in list context.


.. code-block:: perl

     %Return = $PDFObject->_TableCalculate(
         CellData            => $CellData,     # 2D arrayref (see example)
         ColumnData          => $ColumnData,   # arrayref (see example)
         RowData             => $RowData,      # arrayref (see example)
         Width               => 300,           # (optional) default default maximal width
         Height              => 400,           # (optional) default minimal height
         Font                => 'Monospaced',  # (optional) default Proportional (see DocumentNew())
         FontSize            => 9,             # (optional) default 11
         FontColor           => 'red',         # (optional) default black
         FontColorEven       => 'blue',        # (optional) cell font color for even rows
         FontColorOdd        => 'green',       # (optional) cell font color for odd rows
         Align               => 'right',       # (optional) default left (left|center|right)
         Lead                => 3,             # (optional) default 1
         PaddingTop          => 10,            # (optional) top cell padding, overides Padding
         PaddingRight        => 30,            # (optional) right cell padding, overides Padding
         PaddingBottom       => 30,            # (optional) bottom cell padding, overides Padding
         PaddingLeft         => 10,            # (optional) left cell padding, overides Padding
         BackgroundColor     => '#101010',     # (optional) default white
         BackgroundColorEven => '#F0F0F0',     # (optional) cell background color for even rows
         BackgroundColorOdd  => '#A0A0A0',     # (optional) cell background color for odd rows
         Border              => 1,             # (optional) default 1 (values between 0 and 20)
         BorderColor         => '#FF0000',     # (optional) default black
     );
 
     $CellData = [
         [
             {
                 Content         => "Cell 1 (Row 1, Column 1)",  # (optional)
                 Font            => 'Monospaced',                # (optional)
                 FontSize        => 13,                          # (optional)
                 FontColor       => '#00FF00',                   # (optional)
                 Align           => 'center',                    # (optional)
                 Lead            => 7,                           # (optional)
                 BackgroundColor => '#101010',                   # (optional)
             },
             {
                 Content => "Cell 2 (Row 1, Column 2)",
             },
         ],
         [
             {
                 Content => "Cell 3 (Row 2, Column 1)",
             },
             {
                 Content => "Cell 4 (Row 2, Column 2)",
             },
         ],
     ];
 
     $ColumData = [        # this array was automaticly generated, if not given
         {
             Width => 11,  # (optional)
         },
         {
             Width => 44,
         },
     ];
 
     $RowData = [           # this array was automaticly generated, if not given
         {
             Height => 11,  # (optional)
         },
         {
             Height => 44,
         },
     ];



_TableBlockNextCalculate()
==========================


calculate what block can output next


.. code-block:: perl

    Return
        $Return{State}
        $Return{ReturnBlock}
        $Return{ReturnRowStart}
        $Return{ReturnColumnStart}
        $Return{ReturnColumnStop}
 
    %Return = $PDFObject->_TableBlockNextCalculate(
        CellData   => $CellData,    # 2D arrayref
        ColumnData => $ColumnData,  # arrayref
    );



_TableRowCalculate()
====================


calculate row of table


.. code-block:: perl

    Return  # normally no return required, only references
        %Param
 
    %Return = $PDFObject->_TableRowCalculate(
        CellData   => $CellData,    # 2D arrayref
        RowData    => $RowData,     # arrayref
        ColumnData => $ColumnData,  # arrayref
        Row        => 3,            # current row
    );



_TableCellOutput()
==================


output a cell of a table


.. code-block:: perl

    Return
        $Return{State}
        $Return{RequiredWidth}
        $Return{RequiredHeight}
        $Return{LeftOver}
 
    %Return = $PDFObject->_TableCellOutput(
        Width           => 70,
        Height          => 40,
        Text            => 'Text',
        Type            => 'Cut',
        Font            => 'ProportionalBold',
        FontSize        => 15,
        FontColor       => '#FF0000',
        Align           => 'center',
        Lead            => 20,
        PaddingTop      => 10,
        PaddingRight    => 30,
        PaddingBottom   => 30,
        PaddingLeft     => 10,
        BackgroundColor => '#101010',
        Border          => 1,
        BorderColor     => '#FF0000',
    );



_TableCellOnCount()
===================


count all active cells


.. code-block:: perl

    Return
        $CellCount
 
    $Count = $PDFObject->_TableCellOnCount(
        CellData => $CellData,  # 2D arrayref
    );



_TextCalculate()
================


calculate required values of given text


.. code-block:: perl

    Return
        $Return{State}
        $Return{RequiredWidth}
        $Return{RequiredHeight}
        $Return{LeftOver}
        $Return{PossibleRows}  # (Array Ref)
 
    %Return = $PDFObject->_TextCalculate(
        Text     => $Text,               # text
        Type     => 'Cut',               # (ReturnLeftOver|ReturnLeftOverHard|Cut)
        Width    => 300,                 # available width
        Height   => 200,                 # available height
        Font     => 'ProportionalBold',  # font of text
        FontSize => 6,                   # fontsize of text
        Lead     => 20,                  # lead
    );



_StringWidth()
==============


calculate width of given text


.. code-block:: perl

    $Width = $PDFObject->_StringWidth(
        Text     => 'Text',              # text
        Font     => 'ProportionalBold',  # font of text
        FontSize => 6,                   # fontsize of text
    );



_PrepareText()
==============


prepare given text for output


.. code-block:: perl

    $Width = $PDFObject->_PrepareText(
        Text => 'Text',  # text
    );



_CurPageNumberSet()
===================


set number of current page


.. code-block:: perl

    $PDFObject->_CurPageNumberSet(
        ShowPageNumber => 0,  # (optional) default 1
    );



_CurPageDimSet()
================


Set current Page Dimension


.. code-block:: perl

    $PDFObject->_CurPageDimSet(
        Width           => 123,          # (optional) default 595 (Din A4)
        Height          => 321,          # (optional) default 842 (Din A4)
        PageOrientation => 'landscape',  # (optional) (normal|landscape)
    );



_CurPageDimGet()
================


Get current Page Dimension (Width, Height)


.. code-block:: perl

    Return
        $CurPageDim{Width}
        $CurPageDim{Height}
 
    %CurPageDim = $PDFObject->_CurPageDimGet();



_CurPageDimCheck()
==================


Check given X an/or Y if inside the page dimension


.. code-block:: perl

    $True = $PDFObject->_CurPageDimCheck(
        X => 200,  # (optional)
        Y => 100,  # (optional)
    );



_CurPrintableDimSet()
=====================


Set current Printable Dimension


.. code-block:: perl

    $True = $PDFObject->_CurPrintableDimSet(
        Top    => 20,  # (optional)
        Right  => 20,  # (optional)
        Bottom => 20,  # (optional)
        Left   => 20,  # (optional)
    );



_CurPrintableDimGet()
=====================


Get current Printable Dimension


.. code-block:: perl

    Return
        $CurPrintableDim{Top}
        $CurPrintableDim{Right}
        $CurPrintableDim{Bottom}
        $CurPrintableDim{Left}
        $CurPrintableDim{Width}
        $CurPrintableDim{Height}
 
    %CurPrintableDim = $PDFObject->_CurPrintableDimGet();



_CurPrintableDimCheck()
=======================


Check given X an/or Y if inside the printable dimension


.. code-block:: perl

    $True = $PDFObject->_CurPrintableDimCheck(
        X => 200,  # (optional)
        Y => 100,  # (optional)
    );



_CurContentDimSet()
===================


Set current Content Dimension


.. code-block:: perl

    $True = $PDFObject->_CurContentDimSet(
        Top    => 20,  # (optional)
        Right  => 20,  # (optional)
        Bottom => 20,  # (optional)
        Left   => 20,  # (optional)
    );



_CurContentDimGet()
===================


Get current Content Dimension


.. code-block:: perl

    Return
        $CurContentDim{Top}
        $CurContentDim{Right}
        $CurContentDim{Bottom}
        $CurContentDim{Left}
        $CurContentDim{Width}
        $CurContentDim{Height}
 
    %CurContentDim = $PDFObject->_CurContentDimGet();



_CurContentDimCheck()
=====================


Check given X an/or Y if inside the content dimension


.. code-block:: perl

    $True = $PDFObject->_CurContentDimCheck(
        X => 200,  # (optional)
        Y => 100,  # (optional)
    );



_CurPositionSet()
=================


Set current Position


.. code-block:: perl

    $True = $PDFObject->_CurPositionSet(
        X => 20,  # (optional)
        Y => 20,  # (optional)
    );



_CurPositionGet()
=================


Get current Position


.. code-block:: perl

    Return
        $CurPosition{X}
        $CurPosition{Y}
 
    %CurPosition = $PDFObject->_CurPositionGet();