PDF::API2 - A Perl Module Chain to faciliate the Creation and Modification of High-Quality "Portable Document Format" Files.


NAME

PDF::API2 - A Perl Module Chain to faciliate the Creation and Modification of High-Quality ``Portable Document Format (aka. PDF)'' Files.


SYNOPSIS

    use PDF::API2;
    #
    $pdf = PDF::API2->new;
    $pdf = PDF::API2->open('some.pdf');
    $page = $pdf->page;
    $page = $pdf->openpage($pagenum);
    $img = $pdf->image('some.jpg');
    $font = $pdf->corefont('Times-Roman');
    $font = $pdf->ttfont('TimesNewRoman.ttf');


GENERIC METHODS

$pdf = PDF::API->new %opts
Creates a new pdf-file object. If you know beforehand to save the pdf to file you can give the '-file' option, to minimize possible memory requirements later-on.

Example:

    $pdf = PDF::API2->new();
    ...
    print $pdf->stringify;
    $pdf = PDF::API2->new();
    ...
    $pdf->saveas("our/new.pdf");
    $pdf = PDF::API2->new(-file => 'our/new.pdf');
    ...
    $pdf->save;

$pdf = PDF::API->open $pdffile
Opens an existing PDF for modification.

Example:

    $pdf = PDF::API2->open('my/old.pdf');
    ...
    $pdf->saveas("our/new.pdf");
    $pdf = PDF::API2->open('our/to/be/updated.pdf');
    ...
    $pdf->update;

$pdf = PDF::API->openScalar $pdfstream
Opens an existing PDF-stream for modification.

Example:

    open($fh,'our/stream.pdf') or die "$@";
    @pdf = <$fh>;
    $pdf = PDF::API->openScalar(join('',@pdf));
    ...
    $pdf->saveas('our/new.pdf');

$pdf->preferences %opts
Controls viewing-preferences for the pdf.

Page Mode Options:

-fullscreen ... Full-screen mode, with no menu bar, window controls, or any other window visible.

-thumbs ... Thumbnail images visible.

-outlines ... Document outline visible.

Page Layout Options:

-singlepage ... Display one page at a time.

-onecolumn ... Display the pages in one column.

-twocolumnleft ... Display the pages in two columns, with oddnumbered pages on the left.

-twocolumnright ... Display the pages in two columns, with oddnumbered pages on the right.

Viewer Options:

-hidetoolbar ... Specifying whether to hide tool bars.

-hidemenubar ... Specifying whether to hide menu bars.

-hidewindowui ... Specifying whether to hide user interface elements.

-fitwindow ... Specifying whether to resize the document’s window to the size of the displayed page.

-centerwindow ... Specifying whether to position the document’s window in the center of the screen.

-displaytitle ... Specifying whether the window’s title bar should display the document title taken from the Title entry of the document information dictionary.

-afterfullscreenthumbs ... Thumbnail images visible after Full-screen mode.

-afterfullscreenoutlines ... Document outline visible after Full-screen mode.

-printscalingnone
... Set the default print setting for page scaling to none.

Initial Page Option:

-firstpage => [ $pageobj, %opts] ... Specifying the page to be displayed, plus one of the following options:

Initial Page Options:

-fit => 1 ... Display the page designated by page, with its contents magnified just enough to fit the entire page within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the page within the window in the other dimension.

-fith => $top ... Display the page designated by page, with the vertical coordinate top positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of the page within the window.

-fitv => $left ... Display the page designated by page, with the horizontal coordinate left positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of the page within the window.

-fitr => [ $left, $bottom, $right, $top ] ... Display the page designated by page, with its contents magnified just enough to fit the rectangle specified by the coordinates left, bottom, right, and top entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the rectangle within the window in the other dimension.

-fitb => 1 ... Display the page designated by page, with its contents magnified just enough to fit its bounding box entirely within the window both horizontally and vertically. If the required horizontal and vertical magnification factors are different, use the smaller of the two, centering the bounding box within the window in the other dimension.

-fitbh => $top ... Display the page designated by page, with the vertical coordinate top positioned at the top edge of the window and the contents of the page magnified just enough to fit the entire width of its bounding box within the window.

-fitbv => $left ... Display the page designated by page, with the horizontal coordinate left positioned at the left edge of the window and the contents of the page magnified just enough to fit the entire height of its bounding box within the window.

-xyz => [ $left, $top, $zoom ] ... Display the page designated by page, with the coordinates (left, top) positioned at the top-left corner of the window and the contents of the page magnified by the factor zoom. A zero (0) value for any of the parameters left, top, or zoom specifies that the current value of that parameter is to be retained unchanged.

Example:

    $pdf->preferences(
        -fullscreen => 1,
        -onecolumn => 1,
        -afterfullscreenoutlines => 1,
        -firstpage => [ $pageobj , -fit => 1],
    );

$val = $pdf->default $parameter
$pdf->default $parameter, $val
Gets/Sets default values for the behaviour of ::API2.

Supported Parameters:

nounrotate ... prohibits API2 from rotating imported/opened page to re-create a default pdf-context.

pageencaps ... enables than API2 will add save/restore commands upon imported/opened pages to preserve graphics-state for modification.

copyannots ... enables importing of annotations (*EXPERIMENTAL*).

$bool = $pdf->isEncrypted
Checks if the previously opened pdf is encrypted.

@meta_data_attribs = $pdf->infoMetaAttributes @meta_data_attribs
Sets/Gets the supported info-structure tags.

Example:

    @attrs = $pdf->infoMetaAttributes;
    print "Supported Attributes: @attr\n";
    @attrs = $pdf->infoMetaAttributes('CustomField1');
    print "Supported Attributes: @attr\n";

$xml = $pdf->xmpMetadata $xml
Sets/Gets the XMP XML data-stream.

Example:

    $xml = $pdf->xmpMetadata;
    print "PDFs Metadata reads: $xml\n";
    $xml=<<EOT;
    <?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?>
    <?adobe-xap-filters esc="CRLF"?>
    <x:xmpmeta xmlns:x='adobe:ns:meta/' x:xmptk='XMP toolkit 2.9.1-14, framework 1.6'>
    <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#' xmlns:iX='http://ns.adobe.com/iX/1.0/'>
    <rdf:Description rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8' xmlns:pdf='http://ns.adobe.com/pdf/1.3/' pdf:Producer='Acrobat Distiller 6.0.1 for Macintosh'></rdf:Description>
    <rdf:Description rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8' xmlns:xap='http://ns.adobe.com/xap/1.0/' xap:CreateDate='2004-11-14T08:41:16Z' xap:ModifyDate='2004-11-14T16:38:50-08:00' xap:CreatorTool='FrameMaker 7.0' xap:MetadataDate='2004-11-14T16:38:50-08:00'></rdf:Description>
    <rdf:Description rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8' xmlns:xapMM='http://ns.adobe.com/xap/1.0/mm/' xapMM:DocumentID='uuid:919b9378-369c-11d9-a2b5-000393c97fd8'/>
    <rdf:Description rdf:about='uuid:b8659d3a-369e-11d9-b951-000393c97fd8' xmlns:dc='http://purl.org/dc/elements/1.1/' dc:format='application/pdf'><dc:description><rdf:Alt><rdf:li xml:lang='x-default'>Adobe Portable Document Format (PDF)</rdf:li></rdf:Alt></dc:description><dc:creator><rdf:Seq><rdf:li>Adobe Systems Incorporated</rdf:li></rdf:Seq></dc:creator><dc:title><rdf:Alt><rdf:li xml:lang='x-default'>PDF Reference, version 1.6</rdf:li></rdf:Alt></dc:title></rdf:Description>
    </rdf:RDF>
    </x:xmpmeta>
    <?xpacket end='w'?>
    EOT
    $xml = $pdf->xmpMetadata($xml);
    print "PDFs Metadata now reads: $xml\n";
    
=cut

sub xmpMetadata { my $self=shift @_;

    if(!defined($self->{catalog}->{Metadata})) 
    {
            $self->{catalog}->{Metadata}=PDFDict();
            $self->{catalog}->{Metadata}->{Type}=PDFName('Metadata');
            $self->{catalog}->{Metadata}->{Subtype}=PDFName('XML');
            $self->{pdf}->new_obj($self->{catalog}->{Metadata});
    } 
    else 
    {
        $self->{catalog}->{Metadata}->realise;
        $self->{catalog}->{Metadata}->{' stream'}=unfilter($self->{catalog}->{Metadata}->{Filter}, $self->{catalog}->{Metadata}->{' stream'});
        delete $self->{catalog}->{Metadata}->{' nofilt'};
        delete $self->{catalog}->{Metadata}->{Filter};
    }
    
    my $md=$self->{catalog}->{Metadata};
    
    if(defined $_[0])
    {
        $md->{' stream'}=$_[0];
        delete $md->{Filter};
        delete $md->{' nofilt'};
        $self->{pdf}->out_obj($md);
        $self->{pdf}->out_obj($self->{catalog});
    }
    return($md->{' stream'});
}

$pdf->pageLabel $index $options
Sets PageLabel options.

Supported Options:

-style ... 'Roman', 'roman', 'decimal', 'Alpha' or 'alpha'.

-start ... restart numbering at given number.

-prefix ... text prefix for numbering.

Example:

        $pdf->pageLabel( 0, {
                -style => 'roman',
        } ); # start with roman numbering
        $pdf->pageLabel( 4, {
                -style => 'decimal',
        } ); # switch to arabic
        $pdf->pageLabel( 32, {
                -start => 1,
                -prefix => 'A-'
        } ); # numbering for appendix A
    
        $pdf->pageLabel( 36, {
                -start => 1,
                -prefix => 'B-'
        } ); # numbering for appendix B
    
        $pdf->pageLabel( 40, {
                -style => 'Roman'
                -start => 1,
                -prefix => 'Index '
        } ); # numbering for index
    
=cut

sub pageLabel { my $self=shift @_;

        $self->{catalog}->{PageLabels}||=PDFDict();
        $self->{catalog}->{PageLabels}->{Nums}||=PDFArray();
        
        my $arr=$self->{catalog}->{PageLabels}->{Nums};
        while(scalar @_)
        {
                my $index=shift @_;
                my $opts=shift @_;
                
                $arr->add_elements(PDFNum($index));
                my $d=PDFDict();
                if($opts->{-style} eq 'Roman')
                {
                        $d->{S}=PDFName('R');
                }
                elsif($opts->{-style} eq 'roman')
                {
                        $d->{S}=PDFName('r');
                }
                elsif($opts->{-style} eq 'Alpha')
                {
                        $d->{S}=PDFName('A');
                }
                elsif($opts->{-style} eq 'alpha')
                {
                        $d->{S}=PDFName('a');
                }
                else
                {
                        $d->{S}=PDFName('D');
                }
                if(defined $opts->{-prefix})
                {
                        $d->{P}=PDFStr($opts->{-prefix});
                }
                if(defined $opts->{-start})
                {
                        $d->{St}=PDFNum($opts->{-start});
                }
                                
                $arr->add_elements($d);
        }
}

$pdf->finishobjects @objects
Force objects to be written to file if available.

Example:

    $pdf = PDF::API2->new(-file => 'our/new.pdf');
    ...
    $pdf->finishobjects($page, $gfx, $txt);
    ...
    $pdf->save;

$pdf->update
Updates a previously ``opened'' document after all changes have been applied.

Example:

    $pdf = PDF::API2->open('our/to/be/updated.pdf');
    ...
    $pdf->update;

$pdf->saveas $file
Saves the document to file.

Example:

    $pdf = PDF::API2->new();
    ...
    $pdf->saveas("our/new.pdf");

$pdf->end
Destroys the document.


PAGE METHODS

$page = $pdf->page
$page = $pdf->page $index
Returns a new page object or inserts-and-returns a new page at $index.

Note: on $index

    -1 ... is inserted before the last page
    1 ... is inserted before page number 1 (the first page)
    0 ... is simply appended

$pageobj = $pdf->openpage $index
Returns the pageobject of page $index.

Note: on $index

    -1,0 ... returns the last page
    1 ... returns page number 1

Example: (A Document with 99 Pages)

    $page = $pdf->openpage(1);   # returns the first page
    $page = $pdf->openpage(99);  # returns the last page
    $page = $pdf->openpage(-1);  # returns the last page
    $page = $pdf->openpage(999); # returns undef

$xoform = $pdf->importPageIntoForm $sourcepdf, $sourceindex
Returns a form-xobject created from $sourcepdf,$sourceindex. This is useful if you want to transpose the imported page-description somewhat differently onto a page (ie. two-up, four-up, duplex, etc.).

Note: on $index

    -1,0 ... returns the last page
    1 ... returns page number 1

Example:

    $pdf = PDF::API2->new;
    $old = PDF::API2->open('my/old.pdf');
    $xo = $pdf->importPageIntoForm($old,2); # get page 2
    $page = $pdf->page;
    $gfx = $page->gfx;
    $gfx->formimage($xo,0,0,1); # put it on page 1 with scale x1
    $pdf->saveas("our/new.pdf");

Note: you can only import a page from an existing pdf-file!

$pageobj = $pdf->importpage $sourcepdf, $sourceindex, $targetindex
Returns the pageobject of page $targetindex, imported from $sourcepdf,$sourceindex.

Note: on $index

    -1,0 ... returns the last page
    1 ... returns page number 1

Note: you can specify a page object instead as $targetindex so that the contents of the sourcepage will be 'merged into'.

Example:

    $pdf = PDF::API2->new;
    $old = PDF::API2->open('my/old.pdf');
    $page = $pdf->importpage($old,2); # get page 2 into page 1
    $pdf->saveas("our/new.pdf");

Note: you can only import a page from an existing pdf-file!

$pagenumber = $pdf->pages
Returns the number of pages in the document.

$pdf->mediabox $name
$pdf->mediabox $w, $h
$pdf->mediabox $llx, $lly, $urx, $ury
Sets the global mediabox. Other methods: cropbox, bleedbox, trimbox and artbox.

Example:

    $pdf = PDF::API2->new;
    $pdf->mediabox('A4');
    ...
    $pdf->saveas("our/new.pdf");
    $pdf = PDF::API2->new;
    $pdf->mediabox(595,842);
    ...
    $pdf->saveas("our/new.pdf");
    $pdf = PDF::API2->new;
    $pdf->mediabox(0,0,595,842);
    ...
    $pdf->saveas("our/new.pdf");

=cut

sub mediabox { my ($self,$x1,$y1,$x2,$y2) = @_; $self->{pages}->{'MediaBox'}=PDFArray( map { PDFNum(float($_)) } page_size($x1,$y1,$x2,$y2) ); $self; }

$pdf->cropbox $name
$pdf->cropbox $w, $h
$pdf->cropbox $llx, $lly, $urx, $ury
Sets the global cropbox.

Example:

    $pdf = PDF::API2->new;
    $pdf->cropbox('A4');
    ...
    $pdf->saveas("our/new.pdf");
    $pdf = PDF::API2->new;
    $pdf->cropbox(595,842);
    ...
    $pdf->saveas("our/new.pdf");
    $pdf = PDF::API2->new;
    $pdf->cropbox(0,0,595,842);
    ...
    $pdf->saveas("our/new.pdf");

$pdf->bleedbox $name
$pdf->bleedbox $w, $h
$pdf->bleedbox $llx, $lly, $urx, $ury
Sets the global bleedbox.

Example:

    $pdf = PDF::API2->new;
    $pdf->bleedbox('A4');
    ...
    $pdf->saveas("our/new.pdf");
    $pdf = PDF::API2->new;
    $pdf->bleedbox(595,842);
    ...
    $pdf->saveas("our/new.pdf");
    $pdf = PDF::API2->new;
    $pdf->bleedbox(0,0,595,842);
    ...
    $pdf->saveas("our/new.pdf");

$pdf->trimbox $name
$pdf->trimbox $w, $h
$pdf->trimbox $llx, $lly, $urx, $ury
Sets the global trimbox.

Example:

    $pdf = PDF::API2->new;
    $pdf->trimbox('A4');
    ...
    $pdf->saveas("our/new.pdf");
    $pdf = PDF::API2->new;
    $pdf->trimbox(595,842);
    ...
    $pdf->saveas("our/new.pdf");
    $pdf = PDF::API2->new;
    $pdf->trimbox(0,0,595,842);
    ...
    $pdf->saveas("our/new.pdf");

$pdf->artbox $name
$pdf->artbox $w, $h
$pdf->artbox $llx, $lly, $urx, $ury
Sets the global artbox.

Example:

    $pdf = PDF::API2->new;
    $pdf->artbox('A4');
    ...
    $pdf->saveas("our/new.pdf");
    $pdf = PDF::API2->new;
    $pdf->artbox(595,842);
    ...
    $pdf->saveas("our/new.pdf");
    $pdf = PDF::API2->new;
    $pdf->artbox(0,0,595,842);
    ...
    $pdf->saveas("our/new.pdf");


FONT METHODS

@allFontDirs = PDF::API2::addFontDirs $dir1, ..., $dirN
Adds one or more directories to the search-path for finding font files. Returns the list of searched directories.

$font = $pdf->corefont $fontname [, %options]
Returns a new adobe core font object.

See the PDF::API2::Resource::Font::CoreFont manpage for an explanation.


B<Examples:>
    $font = $pdf->corefont('Times-Roman');
    $font = $pdf->corefont('Times-Bold');
    $font = $pdf->corefont('Helvetica');
    $font = $pdf->corefont('ZapfDingbats');

Valid %options are:
  '-encode' ... changes the encoding of the font from its default.
  '-dokern' ... enables kerning if data is available.

$font = $pdf->psfont $psfile [, %options]
Returns a new adobe type1 font object.

See the PDF::API2::Resource::Font::Postscript manpage for an explanation.

Examples:

    $font = $pdf->psfont( 'Times-Book.pfa', -afmfile => 'Times-Book.afm' );
    $font = $pdf->psfont( '/fonts/Synest-FB.pfb', -pfmfile => '/fonts/Synest-FB.pfm' );

Valid %options are:

  '-encode' ... changes the encoding of the font from its default.
  '-afmfile' ... specifies that font metrics to be read from the
                adobe font metrics file (AFM).
  '-pfmfile' ... specifies that font metrics to be read from the
                windows printer font metrics file (PFM).
                (this option overrides the -encode option)
  '-dokern' ... enables kerning if data is available.

$font = $pdf->ttfont $ttfile [, %options]
Returns a new truetype or opentype font object.

See the PDF::API2::Resource::CIDFont::TrueType manpage for an explanation.

Examples:

    $font = $pdf->ttfont('Times.ttf');
    $font = $pdf->ttfont('Georgia.otf');

Valid %options are:

  '-encode' ... changes the encoding of the font from its default.
  '-isocmap' ... per default the MS Unicode Map is used, if this 
                 option is given the ISO Unicode Map will be used.
  '-dokern' ... enables kerning if data is available.
  '-noembed' ... disables embedding the fontfile.

$font = $pdf->cjkfont $cjkname [, %options]
Returns a new cjk font object.

See the PDF::API2::Resource::CIDFont::CJKFont manpage for an explanation.

Examples:

    $font = $pdf->cjkfont('korean');
    $font = $pdf->cjkfont('traditional');

Valid %options are:

  '-encode' ... changes the encoding of the font from its default.

$font = $pdf->synfont $basefont [, %options]
Returns a new synthetic font object.

See the PDF::API2::Resource::Font::SynFont manpage for an explanation.

Examples:

    $cf = $pdf->corefont('Times-Roman',-encode=>'latin1');
    $sf = $pdf->synfont($cf,-slant=>0.85);  # compressed 85%
    $sfb= $pdf->synfont($cf,-bold=>1);      # embolden by 10em
    $sfi= $pdf->synfont($cf,-oblique=>-12); # italic at -12 degrees

Valid %options are:

-slant ... slant/expansion factor (0.1-0.9 = slant, 1.1+ = expansion).

-oblique ... italic angle (+/-)

-bold ... embolding factor (0.1+, bold=1, heavy=2, ...)

-space ... additional charspacing in em (0-1000)

$font = $pdf->bdfont $bdffile
Returns a new BDF font object, based on the specified adobe-bdf file.

See the PDF::API2::Resource::Font::BdFont manpage for an explanation.

$font = $pdf->unifont @fontspecs, %options
Returns a new uni-font object, based on the specified fonts and options.

BEWARE: This is not a true pdf-object, but a virtual/abstract font-definition !

See the PDF::API2::Resource::UniFont manpage for an explanation.

Valid %options are:

  '-encode' ... changes the encoding of the font from its default.


IMAGE METHODS

$jpeg = $pdf->image_jpeg $file
Returns a new jpeg image object.

$tiff = $pdf->image_tiff $file
Returns a new tiff image object.

$pnm = $pdf->image_pnm $file
Returns a new pnm image object.

$png = $pdf->image_png $file
Returns a new png image object.

$gif = $pdf->image_gif $file
Returns a new gif image object.

$gdf = $pdf->image_gd $gdobj, %options
Returns a new image object from GD::Image.

Options: The only option currently supported is -lossless => 1.

Examples:

    $jpeg = $pdf->image_jpeg('../some/nice/picture.jpeg');
    $tiff = $pdf->image_tiff('../some/nice/picture.tiff');
    $pnm = $pdf->image_pnm('../some/nice/picture.pnm');
    $png = $pdf->image_png('../some/nice/picture.png');
    $gif = $pdf->image_gif('../some/nice/picture.gif');
    $gdf = $pdf->image_gd($gdobj);


COLORSPACE METHODS

$cs = $pdf->colorspace_act $file
Returns a new colorspace-object based on a adobe-color-table file.

See the PDF::API2::Resource::ColorSpace::Indexed::ACTFile manpage for an explanation of the file format.

$cs = $pdf->colorspace_web
Returns a new colorspace-object based on the web color palette.

See the PDF::API2::Resource::ColorSpace::Indexed::WebColor manpage for an explanation.

$cs = $pdf->colorspace_hue
Returns a new colorspace-object based on the hue color palette.

See the PDF::API2::Resource::ColorSpace::Indexed::Hue manpage for an explanation.

$cs = $pdf->colorspace_separation $tint, $color
Returns a new separation colorspace-object based on the parameters.

$tint can be any valid ink-identifier, including but not limited to: 'Cyan', 'Magenta', 'Yellow', 'Black', 'Red', 'Green', 'Blue' or 'Orange'.

$color must be a valid color-specification limited to: '#rrggbb', '!hhssvv', '%ccmmyykk' or a ``named color'' (rgb).

The colorspace model for will be automatically chosen based on the specified color.

$cs = $pdf->colorspace_devicen \@tintCSx [, $samples]
Returns a new DeviceN colorspace-object based on the parameters.

Example:

    $cy = $pdf->colorspace_separation('Cyan',    '%f000');
    $ma = $pdf->colorspace_separation('Magenta', '%0f00');
    $ye = $pdf->colorspace_separation('Yellow',  '%00f0');
    $bk = $pdf->colorspace_separation('Black',   '%000f');
    $pms023 = $pdf->colorspace_separation('PANTONE 032CV', '%0ff0');
    $dncs = $pdf->colorspace_devicen( [ $cy,$ma,$ye,$bk,$pms023 ] );
    
=cut

The colorspace model for will be automatically chosen based on the first colorspace specified.


BARCODE METHODS

$bc = $pdf->xo_codabar %opts
$bc = $pdf->xo_code128 %opts
$bc = $pdf->xo_2of5int %opts
$bc = $pdf->xo_3of9 %opts
$bc = $pdf->xo_ean13 %opts
creates the specified barcode object as a form-xo.


OTHER METHODS

$xo = $pdf->xo_form
Returns a new form-xobject.

Examples:

    $xo = $pdf->xo_form;

$egs = $pdf->egstate
Returns a new extended graphics state object.

Examples:

    $egs = $pdf->egstate;

$obj = $pdf->pattern
Returns a new pattern-object.

$obj = $pdf->shading
Returns a new shading-object.

$otls = $pdf->outlines
Returns a new or existing outlines object.


RESOURCE METHODS

$pdf->resource $type, $key, $obj, $force
Adds a resource to the global pdf tree.

Example:

    $pdf->resource('Font',$fontkey,$fontobj);
    $pdf->resource('XObject',$imagekey,$imageobj);
    $pdf->resource('Shading',$shadekey,$shadeobj);
    $pdf->resource('ColorSpace',$spacekey,$speceobj);

Note: You only have to add the required resources, if they are NOT handled by the *font*, *image*, *shade* or *space* methods.


BUGS

This module does not work with perl's -l commandline switch.


AUTHOR

alfred reibenschuh


HISTORY

    $Log: API2.pm,v $
    Revision 2.15  2008/01/18 00:11:38  areibens
    fixed catalog update and infohash utf16 from http://bugs.debian.org/461167
    Revision 2.14  2007/11/16 19:30:31  areibens
    added -noembed option
    Revision 2.13  2007/11/14 23:01:32  areibens
    fixed relative page insert
    Revision 2.12  2007/11/14 22:49:49  areibens
    added non-embedded truetype font (8-bit only) support
    Revision 2.11  2007/09/18 22:29:31  areibens
    added -printscalingnone option
    Revision 2.10  2007/08/01 23:12:08  areibens
    fix BOM in info strings
    Revision 2.9  2007/05/16 21:45:32  areibens
    fixed importpage doku bug http://rt.cpan.org/Ticket/Display.html?id=27152
    Revision 2.8  2007/05/10 23:38:38  areibens
    added note on importintoform and importpage for existing pdf-file
    Revision 2.7  2007/05/08 18:32:10  areibens
    renamed compress to compressFlate
    Revision 2.6  2007/05/07 20:33:46  areibens
    fix tounicode option
    Revision 2.5  2007/03/17 20:07:21  areibens
    fixed open to CORE::open
    Revision 2.4  2007/03/16 15:28:30  areibens
    replaced IOString dep. with scalar IO.
    Revision 2.3  2007/03/15 14:15:19  areibens
    added pageLabel method
    Revision 2.2  2007/03/14 19:30:25  areibens
    fixed -twocolumnright option typo
    Revision 2.1  2007/02/22 08:00:37  areibens
    changed import* methods to check its first arg -- thanks alankila2@yahoo.ca
    Revision 2.0  2005/11/16 02:16:00  areibens
    revision workaround for SF cvs import not to screw up CPAN
    Revision 1.2  2005/11/16 01:27:48  areibens
    genesis2
    Revision 1.1  2005/11/16 01:19:24  areibens
    genesis
    Revision 1.86  2005/10/21 19:51:05  fredo
    fixed proc_pages
    Revision 1.85  2005/10/20 21:06:39  fredo
    documented '-dokern' option for ttfonts
    Revision 1.84  2005/10/19 21:23:26  fredo
    documented '-dokern' option for core- and psfonts
    Revision 1.83  2005/09/12 16:54:21  fredo
    added -isocmap option
    Revision 1.82  2005/06/17 19:43:45  fredo
    fixed CPAN modulefile versioning (again)
    Revision 1.81  2005/06/17 18:53:04  fredo
    fixed CPAN modulefile versioning (dislikes cvs)
    Revision 1.80  2005/06/10 16:12:49  fredo
    documentation update
    Revision 1.79  2005/03/23 16:42:06  fredo
    fixed typo in infoMetaAttributes
    Revision 1.78  2005/03/21 22:36:36  fredo
    fix for landscape imports
    Revision 1.77  2005/03/15 17:31:06  fredo
    corrected utf8 handling in info tags
    Revision 1.76  2005/03/14 23:53:51  fredo
    added xmpMetadata method to get/set XMP document data
    Revision 1.75  2005/03/14 22:01:05  fredo
    upd 2005
    Revision 1.74  2005/02/25 18:07:48  fredo
    no message
    Revision 1.73  2005/02/17 07:03:14  fredo
    added 'pageencaps' default option to fix unusual styled content streams
    Revision 1.72  2005/02/14 20:09:48  fredo
    fixed an openpage recompression bug / thanks to steve_wu@iinet.net.au
    Revision 1.71  2005/01/03 03:47:52  fredo
    fixed use named destination
    Revision 1.70  2005/01/03 03:46:25  fredo
    added named destination support
    Revision 1.69  2004/12/31 03:12:09  fredo
    no message
    Revision 1.68  2004/12/16 00:30:51  fredo
    added no warn for recursion
    Revision 1.67  2004/11/29 15:19:23  fredo
    added docs for bdfont, synfont and unifont
    Revision 1.66  2004/11/24 20:09:57  fredo
    added unifont
    Revision 1.65  2004/10/17 03:57:21  fredo
    added ToUnicode call for supported fonts
    Revision 1.64  2004/10/01 01:39:24  fredo
    reverted annotations import fix
    Revision 1.63  2004/09/30 23:57:26  fredo
    versioning beautify
    Revision 1.62  2004/09/30 22:40:41  fredo
    fixed pdf-producer to include OS
    Revision 1.61  2004/09/30 21:18:21  fredo
    changed file version back to cvs
    Revision 1.60  2004/09/20 11:22:18  fredo
    added default param to fix import-rotation
    added default param to fix annotation-import
    Revision 1.59  2004/09/03 12:35:09  fredo
    pop'd to new version
    Revision 1.58  2004/08/25 02:59:25  fredo
    disabled memoize since long-running scripts bug from reused adresses
    Revision 1.57  2004/07/24 23:10:55  fredo
    fixed memoize bug for bdf fonts
    Revision 1.56  2004/07/24 23:09:26  fredo
    added bdf fonts
    Revision 1.55  2004/07/23 13:41:11  fredo
    fixed in decoding info dictionary
    Revision 1.54  2004/07/21 08:07:17  fredo
    added devicen colorspace
    Revision 1.53  2004/07/15 14:28:21  fredo
    added devicen colorspace
    Revision 1.52  2004/06/22 01:33:43  fredo
    corrected spelling
    Revision 1.51  2004/06/21 22:33:10  fredo
    added basic pattern/shading handling
    Revision 1.50  2004/06/15 09:06:26  fredo
    forced version to 1.50 for beta state
    Revision 1.30  2004/06/15 08:09:07  fredo
    fixed memoized bug
    Revision 1.29  2004/06/01 00:09:57  fredo
    memoized *font methods for braindead invokers
    Revision 1.28  2004/05/28 11:29:01  fredo
    added -lossless param to gd images
    Revision 1.27  2004/05/21 10:12:29  fredo
    fixed slight importpage quirk
    Revision 1.26  2004/04/18 18:07:19  fredo
    fixed _findFont method
    Revision 1.25  2004/04/07 17:38:00  fredo
    added infoMetaAttributes and support code
    Revision 1.24  2004/04/07 10:48:53  fredo
    fixed handling of ColorSpace/Separation
    Revision 1.23  2004/04/06 21:00:52  fredo
    separation colorspace now a full resource
    Revision 1.22  2004/04/04 23:42:10  fredo
    fixed 270 degree rotation in openpage
    Revision 1.21  2004/04/04 23:36:33  fredo
    added simple separation colorspace
    Revision 1.20  2004/03/20 09:11:45  fredo
    modified font search path methodname
    Revision 1.19  2004/03/20 08:38:38  fredo
    added isEncrypted determinator
    Revision 1.18  2004/03/18 09:43:32  fredo
    added font search path handling
    Revision 1.17  2004/02/12 14:38:33  fredo
    added openScalar method
    Revision 1.16  2004/02/05 13:18:39  fredo
    corrected info hash utf8 usage
    Revision 1.15  2004/02/04 23:43:53  fredo
    pdf info method now properly recognized utf8 parameters
    Revision 1.14  2004/01/21 12:29:06  fredo
    moved release versioning to PDF::API2::Version
    Revision 1.13  2004/01/19 14:16:32  fredo
    update for 0.40_16
    Revision 1.12  2004/01/15 21:26:04  fredo
    docbug: fixed inconsistent links
    Revision 1.11  2004/01/14 18:25:41  fredo
    release update 0.40_15
    Revision 1.10  2004/01/12 13:52:41  fredo
    update for 0.40_14
    Revision 1.9  2004/01/08 23:56:20  fredo
    corrected producer tag versioning, updated to release 0.40_13
    Revision 1.8  2003/12/08 13:05:18  Administrator
    corrected to proper licencing statement
    Revision 1.7  2003/12/08 11:47:38  Administrator
    change step 3 for proper module versioning
    Revision 1.6  2003/12/08 11:46:25  Administrator
    change step 2 for proper module versioning
    Revision 1.5  2003/12/08 11:43:10  Administrator
    change step 1 for proper module versioning
    Revision 1.4  2003/11/30 19:00:43  Administrator
    added Code128/EAN128

    Revision 1.3  2003/11/30 17:07:11  Administrator
    merged into default


=cut

 PDF::API2 - A Perl Module Chain to faciliate the Creation and Modification of High-Quality "Portable Document Format" Files.