From: Наталья Анисимова
Newsgroups: email
Date: Mon, 23 Apr 2008 17:02:14 +0000 (UTC)
Subject: Руководство по использованию Perl модуля PDF::API2 для начинающих
Название и версия
Данное руководство создавалось для PDF::API2 версии 20020226.221611 .
Соответственно, описываемые методы в других версиях модуля могут
работать не корректно или не работать совсем. Данное руководство не
претендует на полноту и точность изложения описания работы с модулем
PDF::API2 для Perl. Скорее, оно является неким обзорным материалом,
который предназначен помочь программистам Perl в практической работе,
при создании PDF-документов.
Когда у меня возникла необходимость в предоставлении пользователю
документов в формате 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;
Создаем новый объект PDF::API2 - документ в формате PDF. Каждый
созданный объект позволяет работать только с одним документом
10: my $pdf = PDF::API2->new;
При вызове $pdf->page($page) происходит создание новой страницы
PDF-документа. По умолчанию, новая страница добавляется в конец
документа. Для добавления страницы в середину документа или в начало,
нужно указать номер создаваемой страницы.
Если указать в качестве номера "-1" - страница будет вставлена перед
последней страницей. Если $page = 1; вставка будет производиться в
начало документа, перед первой страницей.
11: my $page = $pdf->page();
MediaBox определяет границы физической страницы. CropBox - границы
видимой области. Если параметры CropBox не указаны, он принимается
равным MediaBox. CropBox лучше задавать с помощью 4х параметров:
$page->cropbox($llx, $lly, $urx, $ury);. С помощью CropBox удобно
задавать поля страницы.
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);
Можно также создать новый документ и импортировать в него страницу(ы)
из созданного ранее документа.
$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);
Еще один вариант импортирования страниц из строннего PDF-документа
описан в п.[21]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');
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);
При стандартном использовании переменная $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 Работа с цветом
Вспомогательный источник: PDF/API2/Lite.pm
Задаем цвет текста. По умолчанию используется черный.
22: $txt->fillcolor('blue');
PDF::API2 позволяет использовать для определения цвета шрифта
различные форматы.
Самый простой вариант - указать наименование цвета.
PDF-файлы выстраивают "снизу вверх". Элементы (текст, картинки, линии
и т.д.), добавленные позднее, будут перекрывать собой элементы
опубликованные ранее. Так, если мы сначала добавим в документ
текстовую строку, а потом нарисуем в той же области большой
прямоугольник - строка окажется под прямоугольником и не будет видна,
либо видна только частично.
18: my $txt=$page->text;
Выбираем шрифт для вывода текста, и определяем его размер:
19: $txt->font($font_tnr,10);
Можно задать межсимвольный интервал и интервал между словами:
20: $txt->charspace(0.6);
21: $txt->wordspace(2);
Указываем координаты для размещения текста, отступ от левого и нижнего
краев страницы в выбранной единице измерения (в данном случае - px).
23: $txt->translate(400,300);
Выводим текст.
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);
Однако, несмотря на удобство, метод 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);
25: $txt->compress();
6 Графические данные в PDF - документе
---------------------------------------
6.1 Вставка графических изображений в PDF - документ
20: my $gfx=$page->gfx;
Определяем изображение, указываем URL к нему и размеры. Метод image
может работать с файлами формата: .jpeg, .png, .pnm.
21: my $img = $pdf->image("/htdocs/flower.jpg", 100, 60);
Выбираем изображение, подлежащее выводу, и указываем координаты
размещения.
22: $gfx->image($img,$x,$y);
Следует отметить, что по умолчанию, для вывода изображений на странице
используется разрешение 72 dpi. Чтобы вывести изображение с
разрешением 150 или 300 dpi, можно указать масштаб 72/150 (или 72/300)
или назначить требуемую высоту и ширину изображения:
Примечание: DPI - (англ. dots per inch) - количество пикселей на дюйм.
Указание DPI позволяет "привязать" изображение, размеры которого
задаются в относительных единицах (пикселях) к физическим - дюймам.
DPI используется при работе с разрешением принтера или сканера. Для
указания разрешения монитора традиционно используют пиксели.
Источник: http://ru.wikipedia.org/wiki/DPI
23: $gfx->close;
Прорисовываем изображение в документе, с учетом всех выше указанных
инструкции.
24: $gfx->stroke;
25: $gfx->compress();
6.2 Импортирование PDF - документов
Импортирует указанную страницу из стороннего pdf-документа, и
позволяет ее использовать аналогично импортируемым в создаваемый
документ картинкам.
6.3 Создание графических изображений средствами PDF::API2
Рисуем прямоугольник
Создаем новый графический объект:
20: my $gfx=$page->gfx;
Определяем цвет заливки прямоугольника. Как и при использовании
шрифтов, данные о цветовой настройке встраиваются непосредственно в
документ. Цвет будет встроен в документ, даже если он определен, но не
используется в дальнейшем.
26: $gfx->fillcolor('blue');
Строим прямоугольник. Для этого указываем координаты X (отсчет слева)
и Y (отсчет снизу) расположения прямоугольника, а также его ширину и
высоту соответственно.
27: $gfx->rectxy(200,200,300,300);
Разворачиваем прямоугольник на 45 градусов.
28: $gfx->rotate(45);
Ранее мы только "настраивали" параметры будущего прямоугольника.
Теперь добавляем его в наш PDF-документ. Метод stroke прорисовывает
контуры геометрической фигуры. Метод fill выполняет заливку объекта
выбранным цветом.
Устанавливаем "курсор" в требуемое место страницы.
43: $line->move(300, 200);
Из определенной с помощью move позиции, проводим линию до точки,
задаваемой командой line.
44: $line->line(400, 400);
Эту команду можно выполнять несколько раз подряд, тогда начало каждой
новой линии будет исходить из точки, где заканчивается линия
предыдущая.
hline(X) - проводит горизонтальную линию из установленной командой
move (или ранее выполненными командами hline, vline, line) точки. Х -
координата точки на оси координат X. Аналогично функционирует команда
vline(Y) - проводит вертикальную линию до точки Y на вертикальной оси
системы координат.
45: $line->hline(20);
46: $line->vline(20);
Итак, линия определена, но еще не прорисована. Выводим линию,
используя заданный цвет:
48: $line->stroke;
Другие геометрические объекты
По аналогии с прямоугольником можно нарисовать следующие
геометрические фигуры:
Возвращаем документ как строку символов. Stringify удобно использовать
при динамической генерации pdf-документов по запросу пользователя и их
незамедлительной передаче клиенту.
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);
* Документация PDF::API2 на search.cpan.org
* Официальные спецификации формата PDF
* PDF::API2. Tutorial. Rick Measham
RU
* Создание сайтов с возможностью печати PDF на примере PDF::API2 (www.opennet.ru)
* Валентин Синицын. Статья. Работаем с PDF из Perl. Системный
администратор, N3. Март, 2006.
794 Прочтений • [Руководство по использованию Perl модуля PDF::API2 для начинающих (pdf perl image graph print)] [08.05.2012] [Комментариев: 0]
Vova
