Руководство по использованию PDF::API2 для начинающихPerl, Python — блог программиста

Данное руководство создавалось для PDF::API2 версии 20020226.221611 . Соответственно, описываемые
методы в других версиях модуля могут работать не корректно или не работать совсем. Данное руководство не претендует на полноту и точность изложения описания работы с модулем PDF::API2 для Perl. Скорее, оно является неким обзорным материалом, который предназначен помочь программистам Perl в практической работе, при создании PDF-документов.

Введение
Используемая терминология
Руководство
Приложение к руководству
1. Примеры кода
2. Полезные ссылки

Введение

Когда у меня возникла необходимость в предоставлении пользователю документов в формате PDF,
и использовании модуля PDF::API2, обнаружилось, что русскоязычный интернет содержит крайне мало
информации на данную тему. Возможно, составленное руководство сможет частично восполнить этот пробел. Кроме того, в тексте приводятся ссылки на полезную информацию, которой мне не хватало для решения поставленной задачи.

Используемая терминология

API (Application Programming Interface) - "Интерфейс прикладного программирования" -
набор ("библиотека") стандартных процедур, программных прерываний, вызовов, форматов данных и
других средств, которые должны использовать прикладные программы для реализации своих функций.

PDF (Portable Document Format) - метафайловый формат, предложенный фирмой Adobe для
графических файлов (векторных и растровых), содержащих иллюстрации и текст с большим набором шрифтов и гипертекстовыми ссылками с целью передачи их по сети в сжатом виде. Версия PDF3 позволяет сохранять все установки для выводного устройства, записанные в файле формата PostScript. Восстановление формата PDF из формата PostScript производится с использованием опции Exchange. Этим обеспечивается оперативная возможность передачи графических файлов по электронной почте. PDF позволяет не заботиться о наличии необходимых шрифтов у адресата, поскольку они подгружаются непосредственно в файл.

Особенностью формата является также возможность использования различных способов сжатия для разных типов объектов. Для работы с форматом PDF фирма Adobe выпустила пакет программ Acrobat. Входящий в этот пакет Acrobat Distiller переводит в PDF PostScript-файлы, Acrobat Exchange позволяет их редактировать (устанавливать внутренние ссылки, ссылки на внешние звуковые и видеофайлы, Web-ссылки и т.д.). Существует и ряд других графических редакторов, позволяющих создавать файлы в формате PDF.

Бесплатно распространяемую утилиту Adobe Acrobat Reader, которая позволяет читать документы и
распечатывать их на принтере (однако не дает возможности создавать или изменять их) можно получить по адресу: www. adobe.com/acrobat.

Файлы PDF используют расширение *.pdf.

Версия формата PDF/A прошла сертификацию стандартом архивирования ISO [584-586, 959, 1640].

Источник: (словари Яндекса)

Руководство

1. Преимущества формата PDF

Основные преимущества:

Кроссплатформенность. Просмотр PDF-файлов возможен практически на всех самых
распространенных платформах, с помощью бесплатной программы Acrobat Reader.
Независимость от наличия (отсутствия) шрифтов на компьютере пользователя. Шрифты, как и
другие данные, при создании встраиваются в PDF-документ.
Независимость от настроек принтера.
Полное соответствие внешнего вида PDF-документа на экране компьютера и распечатанного на
принтере. Данное преимущество имеет особенно большое значение при печати финансовых и юридических
документов.
Небольшой размер PDF-файлов.
Криптозащита, шифрование файлов, управление доступом. PDF-формат позволяет устанавливать
ограничения на просмотр, редактирование и печать документа. Возможна защита этих действий паролем.

Еще одно преимущество, актуальное при использовании PDF-документов в интернете:

Простота генерации многостраничных документов (данная возможность с трудом реализуется для
обычных html-документов, и поддерживается ограниченным числом браузеров)

2 Основные принципы работы с PDF-документами через PDF::API2

Модуль PDF::API2 не дает возможностей для редактирования существующих pdf-документов, с поиском в них текста, рисунков и их последующей заменой. В основном, он предназначен для создания новых
документов.

Основные типы объектов, которые могут использоваться на странице PDF-документа: контуры (path
object), текст (text object) и растр (image object). Для описания объектов используется язык, по функциям аналогичный PostScript.

Система координат является двумерной, и имеет начало в левом нижнем углу листа. Ось X направлена
вправо, ось Y - вверх. Единицей измерения является 1/72 дюйма. Геометрическая плоскость, на которой
расположена система координат - бесконечна.

Ограничение документа происходит с помощью указания физических границ страницы (MediaBox). Также можно задать страницам документа границы видимой области (CropBox).

3 Создание документа PDF

Подключаем модуль PDF::API2

3: use PDF::API2;

1	3: use PDF::API2;

Создаем новый объект PDF::API2 - документ в формате PDF. Каждый созданный объект позволяет
работать только с одним документом

10: my $pdf = PDF::API2->new;

1	10: my $pdf = PDF::API2->new;

При вызове $pdf->page($page) происходит создание новой страницы PDF-документа. По умолчанию, новая страница добавляется в конец документа. Для добавления страницы в середину документа или в начало, нужно указать номер создаваемой страницы.

Если указать в качестве номера "-1" - страница будет вставлена перед последней страницей. Если $page = 1; вставка будет производиться в начало документа, перед первой страницей.

11: my $page = $pdf->page();

1	11: my $page = $pdf->page();

MediaBox определяет границы физической страницы. CropBox - границы видимой
области. Если параметры CropBox не указаны, он принимается равным MediaBox. CropBox лучше задавать с помощью 4х параметров: $page->cropbox($llx, $lly, $urx, $ury);. С помощью CropBox удобно задавать поля страницы.

12: $page->mediabox($w,$h);
13: #$page->bleedbox($w,$h);
14: #$page->cropbox($w,$h);
15: #$page->artbox($w,$h);

12: $page->mediabox($w,$h);

13: #$page->bleedbox($w,$h);

14: #$page->cropbox($w,$h);

15: #$page->artbox($w,$h);

4 Открытие существующего документа PDF для редактирования, импортирование данных

Иногда возникает необходимость предоставить клиенту заполненную квитанцию, бланк и т.д. В подобных ситуациях будет проще не создавать квитанцию с нуля, а просто открыть готовый документ и добавить в него нужную информацию.

$pdf = PDF::API2->open($FILE_NAME); - открывает существующий PDF-документ для редактирования. Стоит отметить, что PDF::API2 не предоставляет возможность отредактировать содержащиеся в документе данные. Можно только дополнить файл новой информацией. $page = $pdf->openpage($page_number); - создает объект для редактирования страницы с номером $page_number открытого ранее документа.

8: my $pdf = PDF::API2->open("helloworld.pdf");
9: my $page = $pdf->openpage(1);

1 2	8: my $pdf = PDF::API2->open("helloworld.pdf"); 9: my $page = $pdf->openpage(1);

Можно также создать новый документ и импортировать в него страницу(ы) из созданного ранее
документа.

$pageobj = $pdf->importpage($sourcepdf, $sourceindex, $targetindex) - импортирует страницу с номером $sourceindex из документа $sourcepdf, на место страницы с номером $targetindex в текущий документ.

Если $sourceindex или $targetindex принимают значение "-1" или "0" - будут производиться операции
с последней страницей документа.

5: my $import_pdf = PDF::API2->open("helloworld.pdf");
6: my $pdf = PDF::API2->new;
7:
8: my $page = $pdf->importpage($import_pdf, 1, 1);

5: my $import_pdf = PDF::API2->open("helloworld.pdf");

6: my $pdf = PDF::API2->new;

8: my $page = $pdf->importpage($import_pdf, 1, 1);

Еще один вариант импортирования страниц из строннего PDF-документа описан в п.6.2. данного руководства.

5 Работа с текстовыми данными

5.1 Управление шрифтами при создании PDF-документа

Как уже было сказано, все объявленные (даже если шрифт не использовался) при создании PDF-документа шрифты, во время сохранения будут подгружены непосредственно в файл.

14: my $font_ps = $pdf->psfont("timesbd8.pfb","timesbd8.afm");
15: # my $font_tt = $pdf->ttfont('verdana.ttf');
16: # my $font_cf = $pdf->corefont('Helvetica');

14: my $font_ps = $pdf->psfont("timesbd8.pfb","timesbd8.afm");

15: # my $font_tt = $pdf->ttfont('verdana.ttf');

16: # my $font_cf = $pdf->corefont('Helvetica');

PDF::API2 позволяет работать со шрифтами типа:

corefont - набор основных шрифтов, которые Adobe позволяет разработчикам использовать бесплатно. В эту группу также входят некоторые шрифты от компании Microsoft. Шрифты предоставляются модулем PDF::API2, и не требуют дополнительной установки.
psfont - шрифты Post Script.
Дополнительная информация (Источник: www.paratype.ru):
Язык программирования PostScript был разработан фирмой Adobe Systems для описания сложных графические объектов. За неимением реальных альтернатив в 80-90-х годах язык PostScript широко использовался при подготовке печатных изданий, и его интерпретаторы были встроены во многие принтеры и устройства отображения графической информации. Хотя этот формат и основывается на использовании языка PostScript для описания печатной страницы документа, он не требует для печати обязательного применения принтеров семейства PostScript. При использовании принтеров PostScript шрифт просто загружается в память принтера, а применение обычных принтеров требует выполнения операции растрирования шрифта (то есть преобразования в набор отдельных точек) и последующей посылки на принтер растрового образа страницы.

Наиболее известная и распространенная сегодня реализация языка PostScript - формат документов PDF, поддерживаемый продуктами серии Acrobat. Почти что все, что может быть сделано в PostScript может быть реализовано в PDF.

Когда мы говорим шрифты PostScript, мы обычно имеем ввиду шрифты PostScript Type 1. Это общепринятый стандарт для цифровых шрифтов (ISO 9541). Шрифт формата Type 1 - специальная форма программы PostScript и особый формат файла, который ориентирован на описание шрифта. В языке PostScript существуют и другие стандарты описания шрифтов - Type 0, Type 2, Type 3, ..., однако сейчас они почти не используются или используются для специальных целей. В последние годы язык PostScript был расширен, чтобы обеспечить поддержку шрифтовых возможностей стандартов TrueType и OpenType. Новые устройства с языком Adobe PostScript сейчас поддерживают все 3 шрифтовых стандарта.

Шрифт PostScript состоит из нескольких файлов: Шрифт PostScript для Windows может состоять из 2-х, 3-х или 4-х файлов. Набор из 3 файлов состоит из файла с расширением PFB (Print Font Binary), который содержит информацию о контурах; файла с расширением AFM (Adobe Font Metrics), содержащего информацию о ширинах символов и кернинге; INF файла, содержащего дополнительную информацию,
которая требуется для инсталляции. В процессе инсталляции Windows генерирует PFM файл (Print Font Metrics), в основе которого лежит информация из AFM и INF файлов. Далее используется только PFB и PFM файлы. Некоторые производители генерируют PFM файлы самостоятельно и поставляют своим клиентам
только два этих файла. Этого достаточно для нормального использования. Некоторые так же добавляют AFM файлы, а некоторые поставляют все 4 файла.

Шрифт PostScript для Macintosh состоит из файла-чемодана (suitcase) и принтерного файла. Если вы купили гарнитуру, а не одно начертание, то у вас может быть один чемодан на всю семью и несколько принтерных файлов, по одному для каждого начертания - Нормального (Regular), Курсивного (Italic), Жирного (Bold) и Жирного Курсивного (Bold Italic). Другой подход предполагает комплектацию каждого начертания отдельным файлом-чемоданом. В этом случае семья из 4 шрифтов будет состоять из 8 файлов. Гарнитуры могут поставляться с "совмещенными начертаниями" или с "разделенными начертаниями". Одна гарнитура может содержать до 4 начертаний, но иногда она содержит только Нормальное и Жирное, или Нормальное и Курсивное начертание.
ttfont - шрифты TrueType.
Дополнительная информация (Источник: www.paratype.ru):
Шрифты TrueType были придуманы специалистами компании Apple Computer в ходе конкурентной борьбы
с технологией PostScript. Позднее лицензия на шрифты TrueType была приобретена фирмой Microsoft с целью включения их в свои операционные системы. В отличие от шрифтов PostScript, шрифты TrueType не используют специального языка для описания формата печатной страницы. Шрифты TrueType могут содержать до 65000 символов, расположенных в порядке, определенном стандартом Unicode. В действительности, не все шрифты содержат расширенные наборы символов, большинство европейских изготовителей ограничиваются стандартной комплектацией западноевропейской
кодировки (т.н. Latin 1).

Шрифт в формате TrueType - это один файл. В системе Windows он имеет расширение TTF, а в Mac OS это файл-чемодан (suitcase) с ресурсом SFNT. В Mac OS X встроен шрифтовой процессор нового поколения, который кроме шрифтов с ресурсом SFNT, поддерживает и файлы TTF, созданные для Windows. Так что файл с расширением TTF можно использовать на обеих операционных платформах.

Особенности $pdf->ttfont

Не смотря на то, что шрифты по-умолчанию подгружаются в файл документа, это условие не является
обязательным.

$font = $pdf->ttfont($ttfile, $lazy);

1	$font = $pdf->ttfont($ttfile, $lazy);

При стандартном использовании переменная $lazy, как правило, опускается. Однако, если
установить ей значение, равное "1" - указанный в $pdf->ttfont($ttfile, $lazy) шрифт не будет встроен в pdf-документ.

Преимущества данного подхода:

т.к. шрифт не встраивается, соответственно размер файла конечного PDF-документа уменьшается
программисту нет необходимости беспокоиться о поиске (покупке) необходимых шрифтов, запоминании их месторасположения, названий и т.п. Достаточно использовать стандартные обозначения шрифтов:
- arial arialbold arialitalic arialbolditalic arialblack
- comicsansms comicsansmsbold
- couriernew couriernewbold couriernewitalic couriernewbolditalic
- tahoma tahomabold
- timesnewroman timesnewromanbold timesnewromanitalic timesnewromanbolditalic
- verdana verdanabold verdanaitalic verdanabolditalic
- wingdings
Дополнительное удобство для пользователей Acrobat Reader версии 5 и старше: возможен поиск и замена шрифтов.

Недостатки:

Созданный подобным образом документ, смогут прочитать только пользователи Windows OC.
Возможно, что ОС клиента не поддерживает русский (или любой другой, отличный от английского) язык и отображение русскоязычных документов будет происходит в искаженном виде.

5.2 Работа с цветом

(Вспомогательный источник: http://search.cpan.org/~areibens/PDF-API2-0.69/lib/PDF/API2/Lite.pm PDF/API2/Lite.pm)

Задаем цвет текста. По умолчанию используется черный.

22: $txt->fillcolor('blue');

1	22: $txt->fillcolor('blue');

PDF::API2 позволяет использовать для определения цвета шрифта различные форматы.

Самый простой вариант - указать наименование цвета.

Возможно использование следующих наименований:

aliceblue, antiquewhite, aqua, aquamarine, azure, beige, bisque, black, 
blanchedalmond, blue, blueviolet, brown, burlywood, cadetblue, chartreuse, 
chocolate, coral, cornflowerblue, cornsilk, crimson, cyan, darkblue, darkcyan, 
darkgoldenrod, darkgray, darkgreen, darkgrey, darkkhaki, darkmagenta, 
darkolivegreen, darkorange, darkorchid, darkred, darksalmon, darkseagreen, 
darkslateblue, darkslategray, darkslategrey, darkturquoise, darkviolet, deeppink, 
deepskyblue, dimgray, dimgrey, dodgerblue, firebrick, floralwhite, forestgreen,
fuchsia, gainsboro, ghostwhite, gold, goldenrod, gray, grey, green, greenyellow, 
honeydew, hotpink, indianred, indigo, ivory, khaki, lavender, lavenderblush, 
lawngreen, lemonchiffon, lightblue, lightcoral, lightcyan, lightgoldenrodyellow, 
lightgray, lightgreen, lightgrey, lightpink, lightsalmon, lightseagreen, lightskyblue, 
lightslategray, lightslategrey, lightsteelblue, lightyellow, lime, limegreen, linen, 
magenta, maroon, mediumaquamarine, mediumblue, mediumorchid, mediumpurple, 
mediumseagreen, mediumslateblue, mediumspringgreen, mediumturquoise, 
mediumvioletred, midnightblue, mintcream, mistyrose, moccasin, navajowhite,
navy, oldlace, olive, olivedrab, orange, orangered, orchid, palegoldenrod, palegreen,
paleturquoise, palevioletred, papayawhip, peachpuff, peru, pink, plum, powderblue, 
purple, red, rosybrown, royalblue, saddlebrown, salmon, sandybrown, seagreen, 
seashell, sienna, silver, skyblue, slateblue, slategray, slategrey, snow, springgreen, 
steelblue, tan, teal, thistle, tomato, turquoise, violet, wheat, white, whitesmoke, 
yellow, yellowgreen

aliceblue, antiquewhite, aqua, aquamarine, azure, beige, bisque, black,

blanchedalmond, blue, blueviolet, brown, burlywood, cadetblue, chartreuse,

chocolate, coral, cornflowerblue, cornsilk, crimson, cyan, darkblue, darkcyan,

darkgoldenrod, darkgray, darkgreen, darkgrey, darkkhaki, darkmagenta,

darkolivegreen, darkorange, darkorchid, darkred, darksalmon, darkseagreen,

darkslateblue, darkslategray, darkslategrey, darkturquoise, darkviolet, deeppink,

deepskyblue, dimgray, dimgrey, dodgerblue, firebrick, floralwhite, forestgreen,

fuchsia, gainsboro, ghostwhite, gold, goldenrod, gray, grey, green, greenyellow,

honeydew, hotpink, indianred, indigo, ivory, khaki, lavender, lavenderblush,

lawngreen, lemonchiffon, lightblue, lightcoral, lightcyan, lightgoldenrodyellow,

lightgray, lightgreen, lightgrey, lightpink, lightsalmon, lightseagreen, lightskyblue,

lightslategray, lightslategrey, lightsteelblue, lightyellow, lime, limegreen, linen,

magenta, maroon, mediumaquamarine, mediumblue, mediumorchid, mediumpurple,

mediumseagreen, mediumslateblue, mediumspringgreen, mediumturquoise,

mediumvioletred, midnightblue, mintcream, mistyrose, moccasin, navajowhite,

navy, oldlace, olive, olivedrab, orange, orangered, orchid, palegoldenrod, palegreen,

paleturquoise, palevioletred, papayawhip, peachpuff, peru, pink, plum, powderblue,

purple, red, rosybrown, royalblue, saddlebrown, salmon, sandybrown, seagreen,

seashell, sienna, silver, skyblue, slateblue, slategray, slategrey, snow, springgreen,

steelblue, tan, teal, thistle, tomato, turquoise, violet, wheat, white, whitesmoke,

yellow, yellowgreen

Определение цвета в формате RGB:

22: $txt->fillcolor('#FF0000');

1	22: $txt->fillcolor('#FF0000');

Определение цвета в формате CMYK (cyan, magenta, yellow, black):

22: $txt->fillcolor('%50009900');

1	22: $txt->fillcolor('%50009900');

Задание цвета для начертания линий или заливки цветом графического объекта происходит аналогичным образом.

26: $gfx->fillcolor('blue');

1	26: $gfx->fillcolor('blue');

41: $line->strokecolor('blue');

1	41: $line->strokecolor('blue');

5.3 Добавление текста

PDF-файлы выстраивают "снизу вверх". Элементы (текст, картинки, линии и т.д.), добавленные позднее, будут перекрывать собой элементы опубликованные ранее. Так, если мы сначала добавим в документ текстовую строку, а потом нарисуем в той же области большой прямоугольник - строка окажется под прямоугольником и не будет видна, либо видна только частично.

18: my $txt=$page->text;

1	18: my $txt=$page->text;

Выбираем шрифт для вывода текста, и определяем его размер:

19: $txt->font($font_tnr,10);

1	19: $txt->font($font_tnr,10);

Можно задать межсимвольный интервал и интервал между словами:

20: $txt->charspace(0.6);
21: $txt->wordspace(2);

1 2	20: $txt->charspace(0.6); 21: $txt->wordspace(2);

Указываем координаты для размещения текста, отступ от левого и нижнего краев страницы в выбранной
единице измерения (в данном случае - px).

23: $txt->translate(400,300);

1	23: $txt->translate(400,300);

Выводим текст.

24: $txt->text("Hello world!");

1	24: $txt->text("Hello world!");

Для вывода и одновременного выравнивания текста по правому краю страницы, можно использовать

$txt->text_right($row);

Выравнивание по центру: $txt->text_center($row);

Удобна для использования функция textln. Она позволяет выводить на печать массив строк. Отступы между строками реализуются использованием: $txt->lead(14); - каждая новая строка начинается на 14 px ниже предыдущей. Использование отрицательного значения для lead (например, $txt->lead(-14);) приводит к выводу строк таким образом, что каждая следующая строка располагается выше предыдущей на 14px.

26: $txt->lead(14);
27: $txt->textln(@row_txt);

1 2	26: $txt->lead(14); 27: $txt->textln(@row_txt);

Однако, несмотря на удобство, метод textln (как и text), имеет недостаток: отсутствие
автоматического переноса строк, по достижении ими границ документа. Слишком длинная строка может выйти за границы документа. Чтобы этого избежать, рекомендуется использование функции paragraph. Рaragraph - выводит текст в виде абзаца, при необходимости выполняя автоматический перенос строк, и возвращает $t - отступ от левой границы обозначенного текстового блока в px, позиция вывода последнего символа абзаца; $y2 - позиция курсора относительно вертикальной оси координат на момент окончания вывода текста в px. Текстовые данные функции следует передавать в виде массива слов.

28: my @text = qw(This is functionally the same as the one above, but far less
29: resource-intensive, if you use many pages (possible the same) from one single pdf);

31: my ($t,$y2)=$txt->paragraph($x,$y,$paragraph_width,$paragraph_height,$string_height,@text);

28: my @text = qw(This is functionally the same as the one above, but far less

29: resource-intensive, if you use many pages (possible the same) from one single pdf);

31: my ($t,$y2)=$txt->paragraph($x,$y,$paragraph_width,$paragraph_height,$string_height,@text);

25: $txt->compress();

1	25: $txt->compress();

6 Графические данные в PDF - документе

6.1 Вставка графических изображений в PDF - документ

20: my $gfx=$page->gfx;

1	20: my $gfx=$page->gfx;

Определяем изображение, указываем URL к нему и размеры. Метод image может работать с файлами
формата: .jpeg, .png, .pnm.

21: my $img = $pdf->image("/htdocs/flower.jpg", 100, 60);

1	21: my $img = $pdf->image("/htdocs/flower.jpg", 100, 60);

Выбираем изображение, подлежащее выводу, и указываем координаты размещения.

22: $gfx->image($img,$x,$y);

1	22: $gfx->image($img,$x,$y);

Следует отметить, что по умолчанию, для вывода изображений на странице используется разрешение
72 dpi. Чтобы вывести изображение с разрешением 150 или 300 dpi, можно указать масштаб 72/150 (или 72/300) или назначить требуемую высоту и ширину изображения:

22: $gfx->image($img,200,$y-30,100,60);

1	22: $gfx->image($img,200,$y-30,100,60);

22: $gfx->image($img,0,0,72/300);

1	22: $gfx->image($img,0,0,72/300);

Примечание: DPI - (англ. dots per inch) - количество пикселей на дюйм. Указание DPI позволяет "привязать" изображение, размеры которого задаются в относительных единицах (пикселях) к физическим - дюймам. DPI используется при работе с разрешением принтера или сканера. Для указания разрешения монитора традиционно используют пиксели.

Источник: http://ru.wikipedia.org/wiki/DPI

23: $gfx->close;

1	23: $gfx->close;

Прорисовываем изображение в документе, с учетом всех выше указанных инструкции.

24: $gfx->stroke;

1	24: $gfx->stroke;

25: $gfx->compress();

1	25: $gfx->compress();

6.2 Импортирование PDF - документов

Импортирует указанную страницу из стороннего pdf-документа, и позволяет ее использовать аналогично импортируемым в создаваемый документ картинкам.

$img = $pdf->pdfimage($pdf_file_name,$page_number);
$gfx=$page->gfx;
$gfx->pdfimage($img,0,0,1); # ($img, x_coord, y_coord)

$img = $pdf->pdfimage($pdf_file_name,$page_number);

$gfx=$page->gfx;

$gfx->pdfimage($img,0,0,1); # ($img, x_coord, y_coord)

6.3 Создание графических изображений средствами PDF::API2

Рисуем прямоугольник

Создаем новый графический объект:

20: my $gfx=$page->gfx;

1	20: my $gfx=$page->gfx;

Определяем цвет заливки прямоугольника. Как и при использовании шрифтов, данные о цветовой настройке встраиваются непосредственно в документ. Цвет будет встроен в документ, даже если он определен, но не используется в дальнейшем.

26: $gfx->fillcolor('blue');

1	26: $gfx->fillcolor('blue');

Строим прямоугольник. Для этого указываем координаты X (отсчет слева) и Y (отсчет снизу) расположения прямоугольника, а также его ширину и высоту соответственно.

27: $gfx->rectxy(200,200,300,300);

1	27: $gfx->rectxy(200,200,300,300);

Разворачиваем прямоугольник на 45 градусов.

28: $gfx->rotate(45);

1	28: $gfx->rotate(45);

Ранее мы только "настраивали" параметры будущего прямоугольника. Теперь добавляем его в наш PDF-документ. Метод stroke прорисовывает контуры геометрической фигуры. Метод fill выполняет заливку объекта выбранным цветом.

29: $gfx->stroke;

1	29: $gfx->stroke;

29: $gfx->fill(1);

1	29: $gfx->fill(1);

29: $gfx->fillstroke;

1	29: $gfx->fillstroke;

Рисование линии

Создаем новый графический объект:

40: my $line = $page->gfx;

1	40: my $line = $page->gfx;

Определяем цвет и толщину будущей линии соответственно.

41: $line->strokecolor('blue');
42: $line->linewidth(5);

1 2	41: $line->strokecolor('blue'); 42: $line->linewidth(5);

Устанавливаем "курсор" в требуемое место страницы.

43: $line->move(300, 200);

1	43: $line->move(300, 200);

Из определенной с помощью move позиции, проводим линию до точки, задаваемой командой line.

44: $line->line(400, 400);

1	44: $line->line(400, 400);

Эту команду можно выполнять несколько раз подряд, тогда начало каждой новой линии будет исходить
из точки, где заканчивается линия предыдущая.

hline(X) - проводит горизонтальную линию из установленной командой move (или ранее выполненными командами hline, vline, line) точки. Х - координата точки на оси координат X. Аналогично функционирует команда vline(Y) - проводит вертикальную линию до точки Y на вертикальной оси системы координат.

45: $line->hline(20);

1	45: $line->hline(20);

46: $line->vline(20);

1	46: $line->vline(20);

Итак, линия определена, но еще не прорисована. Выводим линию, используя заданный цвет:

48: $line->stroke;

1	48: $line->stroke;

Другие геометрические объекты

По аналогии с прямоугольником можно нарисовать следующие геометрические фигуры:

$gfx->curve($x1, $y1, $x2, $y2, $x3, $y3);# рисует кривую линию.
$gfx->arc($center_x, $center_y, $radius_hor, $radius_vert, $from_ygol_naklona, $to_ygol_nakona, $move);#Рисует дугу
$gfx->ellipse($x, $y, $radius_hor, $radius_vert); # рисуем эллипс
$gfx->circle($x, $y, $radius); # рисует окружность
$gfx->rect($x,$y, $width,$height);# рисует прямоугольник

$gfx->curve($x1, $y1, $x2, $y2, $x3, $y3);# рисует кривую линию.

$gfx->arc($center_x, $center_y, $radius_hor, $radius_vert, $from_ygol_naklona, $to_ygol_nakona, $move);#Рисует дугу

$gfx->ellipse($x, $y, $radius_hor, $radius_vert); # рисуем эллипс

$gfx->circle($x, $y, $radius); # рисует окружность

$gfx->rect($x,$y, $width,$height);# рисует прямоугольник

7 Вывод PDF-документа пользователю, сохранение документа

Сохранение документа под указанным именем.

50: $pdf->saveas('helloworld.pdf');

1	50: $pdf->saveas('helloworld.pdf');

Возвращаем документ как строку символов. Stringify удобно использовать при динамической генерации
pdf-документов по запросу пользователя и их незамедлительной передаче клиенту.

50: return $pdf->stringify();

1	50: return $pdf->stringify();

Приложение к руководству

1. Примеры кода

Создание документа и вывод текста с помощью paragraph и text

use strict;
use PDF::API2;

my ($w,$h,$f,$str_h)=(596, 842, 39, 14);	

my $pdf=PDF::API2->new;
my $page = $pdf->page();
$page->mediabox($w,$h);

my $font = $pdf->corefont('Helvetica');
my ($x, $y) = ($f, $h-$f);

my $txt=$page->text;

$txt->font($font,12);
$txt->fillcolor('#221E1F');
$txt->charspace(0.7);
$txt->wordspace(2);

my @text = qw(This is functionally the same as the one above, but far less resource);
my ($idt,$y2)=$txt->paragraph(100,700,400,400,14,@text);

$txt->translate(100,300);
$txt->text("idt - $idt, y2 - $y2");

$txt->compress();
$pdf->saveas('helloworld.pdf');
$pdf->end;

use strict;

use PDF::API2;

my ($w,$h,$f,$str_h)=(596, 842, 39, 14);

my $pdf=PDF::API2->new;

my $page = $pdf->page();

$page->mediabox($w,$h);

my $font = $pdf->corefont('Helvetica');

my ($x, $y) = ($f, $h-$f);

my $txt=$page->text;

$txt->font($font,12);

$txt->fillcolor('#221E1F');

$txt->charspace(0.7);

$txt->wordspace(2);

my @text = qw(This is functionally the same as the one above, but far less resource);

my ($idt,$y2)=$txt->paragraph(100,700,400,400,14,@text);

$txt->translate(100,300);

$txt->text("idt - $idt, y2 - $y2");

$txt->compress();

$pdf->saveas('helloworld.pdf');

$pdf->end;

Открытие существующего документа PDF для редактирования

use strict;
use PDF::API2;

my ($w,$h,$f,$str_h)=(596, 842, 39, 14);	
my $pdf = PDF::API2->open("helloworld.pdf");
my $page = $pdf->openpage(1);
$page->cropbox($w,$h);

$pdf->saveas('open.pdf');
$pdf->end;

use strict;

use PDF::API2;

my ($w,$h,$f,$str_h)=(596, 842, 39, 14);

my $pdf = PDF::API2->open("helloworld.pdf");

my $page = $pdf->openpage(1);

$page->cropbox($w,$h);

$pdf->saveas('open.pdf');

$pdf->end;

Импортирование страниц из ранее созданного PDF-документа

use strict;
use PDF::API2;

my ($w,$h,$f,$str_h)=(596, 842, 39, 14);	
my $import_pdf = PDF::API2->open("helloworld.pdf");
my $pdf = PDF::API2->new;

my $page = $pdf->importpage($import_pdf, 1, 1);

$page->cropbox($w,$h);

$pdf->saveas('open.pdf');
$pdf->end;
$import_pdf->end;

use strict;

use PDF::API2;

my ($w,$h,$f,$str_h)=(596, 842, 39, 14);

my $import_pdf = PDF::API2->open("helloworld.pdf");

my $pdf = PDF::API2->new;

my $page = $pdf->importpage($import_pdf, 1, 1);

$page->cropbox($w,$h);

$pdf->saveas('open.pdf');

$pdf->end;

$import_pdf->end;

Публикация изображения

my $gfx=$page->gfx;
	
my $img = $pdf->image("flower.jpg", 2554, 3579);
$gfx->image($img,0,0,596,842);

$gfx->close;
$gfx->stroke;
$gfx->compress();

my $gfx=$page->gfx;

my $img = $pdf->image("flower.jpg", 2554, 3579);

$gfx->image($img,0,0,596,842);

$gfx->close;

$gfx->stroke;

$gfx->compress();

Использование textln для вывода текста

my $txt=$page->text;
$txt->lead($str_h);
$txt->font($font,12);
$txt->charspace(0.6);
$txt->wordspace(2);

my @txt_arr = (
	qq{},
	qq{},
	qq{},
	qq{},
	qq{},
);

$txt->translate(100,500);
$txt->lead(14);
$txt->textln(@txt_arr);

my $txt=$page->text;

$txt->lead($str_h);

$txt->font($font,12);

$txt->charspace(0.6);

$txt->wordspace(2);

my @txt_arr = (

qq{},

);

$txt->translate(100,500);

$txt->lead(14);

$txt->textln(@txt_arr);

Рисуем линию

my $line = $page->gfx;
$line->strokecolor('blue');
$line->move(100, 200);
$line->line(400, 500);
$line->close;
$line->stroke;
$line->compress();

my $line = $page->gfx;

$line->strokecolor('blue');

$line->move(100, 200);

$line->line(400, 500);

$line->close;

$line->stroke;

$line->compress();

2. Полезные ссылки

Документация PDF::API2 на search.cpan.org
Официальные спецификации формата PDF
PDF::API2. Tutorial. Rick Measham

Создание сайтов с возможностью печати PDF на примере PDF::API2 (www.opennet.ru)
Валентин Синицын. Статья. Работаем с PDF из Perl. Системный администратор, N3. Март, 2006.