使用PDFLib生成PDF文档（C语言版）--使用指导

1.      基本环境

①    打开、关闭、文档信息设定：

新建PDFLib对象，PDF_new()

设定错误处理的方式，PDF_set_parameter(p, "errorpolicy", "return")，return标示当发生错误时直接从Lib函数中返回。

设定文档信息，PDF_set_value()

新建一个PDF文件，PDF_begin_document()

新建一个页面，PDF_begin_page_ext()

关闭一个页面，PDF_end_page_ext()

关闭PDF文件，PDF_end_document()

释放PDFLib对象，PDF_delete()

例外处理，PDF_TRY()和PDF_CATCH()

②       示例代码：

#include <stdio.h>
#include "pdflib.h"

int main(int argc, char *argv[])
{
          Example();
          return 0;
}

int Example(void)
{
         PDF *p;

         if ((p = PDF_new()) == (PDF *) 0){
                   printf("Couldn't create PDFlib object (out of memory)!/n");
                   return(2);
         }

         PDF_TRY(p) {
                   /* This means we must check return values of load_font() etc. */
                   PDF_set_parameter(p, "errorpolicy", "return");

                   if (PDF_begin_document(p, "d://hello.pdf", 0, "") == -1) {
                            printf("Error: %s/n", PDF_get_errmsg(p));
                            return(2);
                   }

                   /* This line is required to avoid problems on Japanese systems */
                   PDF_set_parameter(p, "hypertextencoding", "host");
                   PDF_set_parameter(p, "fakebold", "true");

                   PDF_set_info(p, "Creator", "hello.c");
                   PDF_set_info(p, "Author", "Thomas Merz");
                   PDF_set_info(p, "Title", "Hello, world (C)!");

                   PDF_begin_page_ext(p, a4_width, a4_height, "");

                   PDF_setcolor(p, "fill", "cmyk", 1, 0,0,0);
                   PDF_rect(p, 250,250, 100, 50);
                   PDF_fill(p);

                   PDF_end_page_ext(p, "");
                   PDF_end_document(p, "");
         }

         PDF_CATCH(p) {
                   printf("PDFlib exception occurred in sample:/n");
                   printf("[%d] %s: %s/n",
                            PDF_get_errnum(p), PDF_get_apiname(p), PDF_get_errmsg(p));
                   PDF_delete(p);
                   getchar();
                   return(2);
         }

         PDF_delete(p);
         return 0;
}

2.    文字输出

①       加载字体

使用PDF_load_font()函数。目前在Windows 平台下，似乎只能加载可以安装到Windows系统中的字体。

如果加载已经安装到系统中的字体（在C:/windows/fonts文件夹下），可以直接通过字体的名字加载，如：

font = PDF_load_font(p, "MS UI Gothic", 0, "host", "");

font = PDF_load_font(p, "MKZ2", 0, "unicode", "");

    也可以通过制定字体文件加载字体，如：

            PDF_set_parameter(p, "FontOutline", "MKZ2=C://windows//fonts// MKZ2.ttf");

font= PDF_load_font(p, "MKZ2", 0, "unicode", "");

"host"和"unicode"是用于字体编码的方式，host日文系统下具体与代码页cp932等相关，中文系统下与cp936相关。Unicode与PDF所规定的CMAP文件相关，如：UniJIS-UCS2-H、EUC-H等的编码文件。因为字体已经安装到了Windows系统中，具体的字体编码方式，操作系统能够自动处理，无需我们显式的指定。

加载字体是一件很耗费时间的工作，大概能占到整个处理的1/4左右。PDFLib已经作了些优化，当一个字体只要加载过一次，再次加载就会使用前面产生的字体句柄，不再重新生成。

PDFLIb加载字体时默认是嵌入的，这样会增大输出的PDF文件。好处是当文件被移动到其他系统上时，打开文件时不受字体的影响，否则，打开文件前需要先安装字体。我们这次的项目，生成的PDF文件需要用FTP转送到Solaris系统，并且要送入打印机，所以必须以嵌入方式加载的字体。

②       设置字体

使用PDF_setfont（）函数，如：

    PDF_setfont(p, font, 30);

30指的是字号，也就是字体的高度。但这个和系统的缩放比例相关。如果设字体前设定系统的缩放比例为2,实际输出的字体的高度为60个单位。PSEdit的字体的输出过程中，绝大部分采用的是变换系统坐标的方法来确定字体的大小，所以编程中使用了PDF_setfont(p, font, 1)的方式，即字体的大小为当前系统的缩放比例的值相同。

③       文字输出

PDFLib的文字处理，较PostScript而言，加强了功能，增加了大量文字及段落等的处理。但本次PSEdit编程中，受于以前软件框架的限制，只使用了单字输出的功能PDF_info_textline（），尽管这个函数也能用于输出一个字符串。

PDF_info_textline函数有个选项列表，提供的功能相当丰富。基本上覆盖了对字体的所有的变化和变形。如：倾斜、旋转、缩放、着色、偏移以及指定字体等等。

④       文字阴影

采用在相互错开的位置上输出两次同样的字符，实现阴影。

⑤       空心字

通过指定PDF_info_textline函数的三个选项参数textrendering、strokewidth 、strokecolor来实现。如输出空心字，边缘宽1个单位，边缘色为青色，边缘线圆头连接：

       PDF_setlinejoin(p, 1);

       PDF_fit_textline(p, "ABCDEF", 0, 50, 550, "textrendering=1 strokewidth=1 strokecolor={CMYK 1 0 0 0}");

⑥       立体字和艺术字，这个属于描画字的范围，输出方式是组合起来的多组直线和曲线，线段封闭后，剪切区域形成字体的轮廓区域，然后再用某中颜色或填充模式进行填充。所以每一个立体字和艺术字，都是一个复杂的剪切图形。

3.    图像输出

①         图像的输出使用PDF_load_image和PDF_fit_image，输出图像变得相当简单了。当然，简单的副作用就是，限制了许多对所加载的图像的处理功能。保留的几个功能是：着色，缩放，旋转。这似乎对一般的PDF文件也足够了。

②         图像的最小网点，似乎只是报纸打印行业为了使图像不失真而采取的一种特殊的图像离散化处理。这种处理功能在很通用的图像处理中间件LeadTools中没有提供，可见最小网点并非一种普遍适用的图像处理手段，应该在更为专业性的图像处理工具中才有。

4.    图形输出

①       路径（path），指的是某个特定区域的边界。路径是任何图形的基础。

②       能够长生路径的操作事实上只有两种：画直线（PDF_moveto，PDF_lineto）和画曲线（圆PDF_circle、弧PDF_arc和PDF_arcn、曲线PDF_curveto）

③       描边（PDF_stroke），沿路经使用指定的颜色（PDF_setcolor）和指定的线宽（PDF_setlinewidth）进行着色。

④       填充（PDF_fill），首先关闭路径（PDF_closepath把最后一个点和开始点连接直线），然后用指定的颜色（PDF_setcolor）对封闭区域着色。

⑤       梯度填充(PDF_shfill)，是从一种颜色平滑过渡到令一种颜色的填充。填充前先需要生成颜色模式（PDF_shading）。例如梯度填充一个矩形，颜色为从蓝色从红色过渡：

PDF_setcolor(p, "fill", "cmyk", 1, 0, 0, 0);

PDF_rect(p, 200 , 500, 200, 100);

PDF_clip(p);

handle = PDF_shading( p, "axial", 210, 550, 350, 550, 0, 1, 0, 0,"extend0=true extend1=true N=1" );

PDF_shfill( p, handle );

要实现多组颜色梯度填充，只能把区域安相关颜色分成多个区域，每个区域安两种颜色填充。

⑥       剪切（PDF_clip），把当前封闭的区域独立出来，任何超出这个剪切区域的操作都将无效。剪切，尤其是复杂区域的剪切是图形图像处理中的高级处理，其低层实现需要极高超的编程技巧和理论水平。剪切处理应当说是PostScript和PDF中最具有技术含量的部分。

剪切时值得注意的是，要恢复到前切前的状态，只能使用PDF_save和PDF_restore完成。

⑦       坐标变换：位移（PDF_translate）、旋转（PDF_rotate）、缩放（PDF_scale）、歪斜（PDF_skew）、应用转换矩阵（PDF_concate）。这种对于应用者而言比较简单的坐标系统，其实是整个系统的精华所在，它为各种形式的图形表现，提供的最基本和坚实的支持。

5.    嵌入PDF文档

①       把其他的PDF文件的页嵌入到当前的PDF文件中，可以指定位置、大小、旋转，但无法改变颜色。例：

handle = PDF_open_pdi_document(p, "d://font.pdf", 0, "");
if (handle == -1) {
    printf("Error: %s/n", PDF_get_errmsg(p));
    return(2);
}
page = PDF_open_pdi_page(p, handle, 1, "");
if (handle == -1) {
    printf("Error: %s/n", PDF_get_errmsg(p));
    return(2);
}

PDF_fit_pdi_page(p, page, 50, 150, "");
PDF_close_pdi_page(p, page);
PDF_close_pdi_document(p, handle);

6.   颜色

①       CMYK色：和本次开发相关的颜色空间是CMYK色彩空间。颜色的值为0~1，全部为0标示白色，全部为1表示黑色。

②       专色：和这个名字反映出来的意思一样，就是某种特殊的颜色。一般都和打印机相关，指某种超出打印机混合色之外的颜色。

在PSEdit的改造过程中使用了两个（但不一定都用了）自定义的特色：S1和S2。没有使用其他的­（如工业标准定义的）特色。但为什么要这么做，我还无法理解，也许仅仅是为了分版的需要，

③       在PDFLib中，每一个特色都得按一个颜色空间的级别对待。比如画一条线，除了基本的CMYK色要画一次外，应用几个特色，就需要重画几次，在PDF文件中，可以设定OverPrint属性，来查看最终的（混合色）显示效果。

④       例：

调用内置专色：

handle = PDF_makespotcolor(p, "PANTONE 871 C", 0);
PDF_setcolor(p, "stroke", "spot", handle, 0.5, 0, 0);
PDF_moveto(p, 100, 620);
PDF_lineto(p, 250, 620);
PDF_stroke(p);

生成自定义专色：

PDF_setcolor(p, "stroke", "cmyk", 0, 0, 1, 0);
handle = PDF_makespotcolor(p, "S1", 0);
PDF_setcolor(p, "stroke", "spot", handle, 0.4, 0, 0);
PDF_moveto(p, 100, 620);
PDF_lineto(p, 250, 620);
PDF_stroke(p);