下载 - PDFlib

PDFlib GmbH 慕 尼 黑 , 德 国
www.pdflib.com
参 考 手 册
®
一 个 动 态 生 成 PDF 文 件 的 程 序 库
版 本 6.0.3
适 用 于
Cobol, C, C++, Java, Perl, PHP,
Python, RPG, Ruby, 和 Tcl

版 权 所 有 © 1997–2006 PDFlib GmbH 和 Thomas Merz。 保 留 所 有 权 利 。
在 此 授 予 PDFlib 用 户 许 可 , 可 以 内 部 使 用 为 目 的 复 制 本 手 册 的 印 刷 或 数 字 副 本 。
PDFlib GmbH
Tal 40, 80331 München, Germany
www.pdflib.com
电 话 : +49 • 89 • 29 16 46 87
传 真 : +49 • 89 • 29 16 46 86
如 果 您 有 任 何 疑 问 , 请 查 看 groups.yahoo.com/group/pdflib 上 的 PDFlib 邮 件 列 表 及 相 关 存 档 。
许 可 联 系 人 : sales@pdflib.com
商 业 PDFlib 许 可 证 持 有 人 支 持 : support@pdflib.com ( 请 提 供 您 的 许 可 证 号 )
本 出 版 物 及 其 所 含 信 息 “ 按 原 样 ” 提 供 ; 如 有 更 改 , 恕 不 另 行 通 知 , 且 不 应 视 为 PDFlib GmbH 所 做 的
承 诺 。 PDFlib GmbH 不 对 存 在 的 任 何 错 误 和 不 准 确 性 承 担 任 何 责 任 , 不 对 本 出 版 物 做 出 任 何 形 式 ( 明
示 、 默 示 或 法 定 ) 的 保 证 , 并 明 确 声 明 : 不 对 其 适 销 性 、 特 定 用 途 的 实 用 性 以 及 有 关 第 三 方 权 利 的 无
侵 权 做 出 任 何 形 式 的 保 证 。
PDFlib 及 PDFlib 徽 标 是 PDFlib GmbH 的 注 册 商 标 。 在 此 授 予 PDFlib 许 可 证 持 有 者 在 其 产 品 文 档 中 使 用
PDFlib 名 称 和 徽 标 的 权 利 。 但 是 , 并 不 要 求 使 用 PDFlib 名 称 和 徽 标 。
Adobe、Acrobat 和 PostScript 是 Adobe Systems Inc. 的 商 标 。AIX、IBM、OS/390、WebSphere、iSeries
和 zSeries 是 International Business Machines Corporation 的 商 标 。 ActiveX、 Microsoft、 OpenType 和
Windows 是 Microsoft Corporation 的 上 标 。 Apple、 Macintosh 和 TrueType 是 Apple Computer, Inc. 的 商
标 。 Unicode 及 Unicode 徽 标 是 Unicode, Inc. 的 商 标 。 Unix 是 The Open Group 的 商 标 。 Java 和 Solaris
是 Sun Microsystems, Inc. 的 商 标 。 HKS 是 HKS 品 牌 联 名 的 注 册 商 标 :Hostmann-Steinberg、 K+E
Printing Inks、 Schmincke。 其 他 公 司 的 产 品 和 服 务 名 称 可 能 是 其 他 公 司 的 商 标 或 服 务 标 志 。
软 件 应 用 程 序 或 用 户 文 档 中 显 示 的 PANTONE® 颜 色 可 能 不 符 合 PANTONE 确 定 的 标 准 。 有 关 准 确 的 颜
色 , 请 参 阅 最 新 版 的 PANTONE 颜 色 文 献 。 PANTONE® 及 其 他 Pantone, Inc. 商 标 规 Pantone, Inc. ©
Pantone, Inc. 所 有 , 2003。
Pantone, Inc. 是 颜 色 数 据 和 / 或 软 件 的 版 权 所 有 者 , 并 已 授 予 PDFlib GmbH 使 用 许 可 , 但 仅 限 于 同
PDFlib 软 件 一 起 分 发 。 除 非 作 为 执 行 PDFlib 软 件 的 一 部 分 , 否 则 不 得 将 PANTONE 颜 色 数 据 和 / 或 软 件
复 制 到 另 一 此 案 或 存 储 设 备 中 。
PDFlib 包 含 下 列 经 过 修 改 的 第 三 方 软 件 组 件 :
ICClib, 版 权 所 有 © 1997-2002 Graeme W. Gill
GIF 图 像 解 码 器 , 版 权 所 有 © 1990-1994 David Koblas
PNG 图 像 参 考 库 (libpng), 版 权 所 有 © 1998-2004 Glenn Randers-Pehrson
Zlib 压 缩 库 , 版 权 所 有 © 1995-2002 Jean-loup Gailly and Mark Adler
TIFFlib 图 像 库 , 版 权 所 有 © 1988-1997 Sam Leffler, 版 权 所 有 © 1991-1997 Silicon Graphics, Inc.
Eric Young 编 写 的 密 码 软 件 , 版 权 所 有 © 1995-1998 Eric Young (eay@cryptsoft.com)
Independent JPEG Group 的 JPEG 软 件 , 版 权 所 有 © 1991-1998, Thomas G. Lane
PDFlib 包 含 RSA Security, Inc. 的 MD5 消 息 摘 要 算 法 。
作 者 :Thomas Merz
设 计 和 插 图 :Alessio Leonardi
质 量 控 制 ( 手 册 ):Katja Schnelle Romaus、 Kurt Stützer
质 量 控 制 ( 软 件 ): 软 件 开 发 组

目 录
0 应 用 PDFlib 许 可 证 密 钥 9
1 前 言 11
1.1 PDFlib 编 程 11
1.2 PDFlib 6 中 的 主 要 新 增 功 能 12
1.3 PDFlib 功 能 13
1.4 不 同 产 品 中 的 功 能 的 可 用 性 15
2 PDFlib 语 言 绑 定 19
2.1 概 述 19
2.2 Cobol 绑 定 19
2.2.1 有 关 Cobol 的 特 别 注 意 事 项 19
2.2.2 用 Cobol 编 写 的 “Hello world” 示 例 21
2.3 COM 绑 定 24
2.4 C 绑 定 24
2.4.1 有 关 C 的 可 用 性 和 特 别 注 意 事 项 24
2.4.2 用 C 编 写 的 “Hello world” 示 例 24
2.4.3 使 用 PDFlib 作 为 在 运 行 时 加 载 的 DLL 25
2.4.4 C 的 错 误 处 理 26
2.4.5 用 C 进 行 内 存 管 理 27
2.4.6 C 语 言 绑 定 中 的 Unicode 27
2.5 C++ 绑 定 28
2.5.1 有 关 C++ 的 可 用 性 和 特 别 注 意 事 项 28
2.5.2 用 C++ 编 写 的 “Hello world” 示 例 28
2.5.3 C++ 的 错 误 处 理 29
2.5.4 用 C++ 进 行 内 存 管 理 29
2.5.5 C++ 语 言 绑 定 中 的 Unicode 29
2.6 Java 绑 定 29
2.6.1 安 装 PDFlib Java 版 本 29
2.6.2 用 Java 编 写 的 “Hello world” 示 例 30
2.6.3 Java 的 错 误 处 理 31
2.7 .NET 绑 定 32
2.8 Perl 绑 定 32
2.8.1 安 装 PDFlib Perl 版 本 32
2.8.2 用 Perl 编 写 的 “Hello world” 示 例 32
2.8.3 Perl 的 错 误 处 理 33
2.9 PHP 绑 定 33
2.9.1 安 装 PDFlib PHP 版 本 33
2.9.2 用 PHP 编 写 的 “Hello world” 示 例 34
2.9.3 PHP 的 错 误 处 理 36
2.10 Python 绑 定 36
2.10.1 安 装 PDFlib Python 版 本 36
目 录 3

2.10.2 用 Python 编 写 的 “Hello world” 示 例 37
2.10.3 Python 的 错 误 处 理 37
2.11 REALbasic 绑 定 37
2.12 Ruby 绑 定 37
2.12.1 安 装 PDFlib Ruby 版 本 37
2.12.2 用 Ruby 编 写 的 “Hello world” 示 例 38
2.12.3 Ruby 的 错 误 处 理 38
2.12.4 Ruby on Rails 39
2.13 RPG 绑 定 39
2.13.1 为 PDFlib 对 RPG 程 序 进 行 编 译 和 绑 定 39
2.13.2 用 RPG 编 写 的 “Hello world” 示 例 40
2.13.3 RPG 的 错 误 处 理 41
2.14 Tcl 绑 定 43
2.14.1 安 装 PDFlib Tcl 版 本 43
2.14.2 用 Tcl 编 写 的 “Hello world” 示 例 43
2.14.3 Tcl 的 错 误 处 理 44
3 PDFlib 编 程 45
3.1 常 规 编 程 45
3.1.1 PDFlib 程 序 结 构 和 函 数 范 围 45
3.1.2 参 数 45
3.1.3 异 常 处 理 46
3.1.4 PDFlib 虚 拟 文 件 系 统 (PVF) 48
3.1.5 资 源 配 置 和 文 件 搜 索 49
3.1.6 在 内 存 中 生 成 PDF 文 档 51
3.1.7 在 基 于 EBCDIC 的 平 台 上 使 用 PDFlib 52
3.1.8 大 文 件 支 持 52
3.2 页 面 说 明 53
3.2.1 坐 标 系 统 53
3.2.2 页 面 大 小 和 坐 标 限 制 55
3.2.3 路 径 56
3.2.4 模 板 56
3.3 使 用 颜 色 57
3.3.1 颜 色 和 色 彩 空 间 57
3.3.2 图 案 和 平 滑 着 色 58
3.3.3 专 色 58
3.3.4 色 彩 管 理 和 ICC 配 置 文 件 60
3.4 超 文 本 元 素 63
3.4.1 创 建 超 文 本 元 素 的 示 例 63
3.4.2 文 本 域 的 格 式 化 选 项 66
4 文 本 处 理 69
4.1 字 体 和 编 码 概 述 69
4.1.1 支 持 的 字 体 格 式 69
4.1.2 编 码 69
4.1.3 支 持 Unicode 标 准 70
4.2 字 体 格 式 详 细 信 息 71
4.2.1 Windows 和 Mac 上 的 宿 主 字 体 支 持 71
4 目 录

4.2.2 PostScript 字 体 72
4.2.3 TrueType 和 OpenType 字 体 73
4.2.4 用 户 定 义 的 (Type 3) 字 体 74
4.3 字 体 嵌 入 和 子 集 化 75
4.3.1 PDFlib 搜 索 字 体 的 方 法 75
4.3.2 字 体 嵌 入 76
4.3.3 字 体 子 集 化 77
4.4 编 码 详 细 信 息 78
4.4.1 8 位 编 码 78
4.4.2 符 号 字 体 和 特 定 于 字 体 的 编 码 81
4.4.3 TrueType 和 OpenType 字 体 的 字 形 ID 寻 址 82
4.4.4 欧 元 符 号 字 形 82
4.5 Unicode 支 持 83
4.5.1 页 面 内 容 和 超 文 本 的 Unicode 83
4.5.2 内 容 字 符 串 、 超 文 本 字 符 串 和 名 称 字 符 串 84
4.5.3 支 持 Unicode 的 语 言 中 的 字 符 串 处 理 85
4.5.4 不 支 持 Unicode 的 语 言 中 的 字 符 串 处 理 85
4.5.5 字 符 引 用 87
4.5.6 Unicode 兼 容 的 字 体 89
4.6 文 本 规 格 和 文 本 变 体 90
4.6.1 字 体 和 字 符 规 格 90
4.6.2 字 距 调 整 91
4.6.3 文 本 变 体 92
4.7 中 文 、 日 文 和 韩 文 文 本 93
4.7.1 Acrobat 和 PDF 中 支 持 的 CJK 93
4.7.2 标 准 CJK 字 体 和 CMap 93
4.7.3 自 定 义 CJK 字 体 97
4.8 放 置 并 调 整 单 行 文 本 99
4.8.1 简 单 的 文 本 放 置 99
4.8.2 在 文 本 框 中 放 置 文 本 100
4.8.3 对 齐 文 本 100
4.9 多 行 textflow 101
4.9.1 在 限 定 框 中 放 置 textflow 102
4.9.2 段 落 格 式 设 置 选 项 104
4.9.3 内 嵌 选 项 列 表 和 宏 104
4.9.4 制 表 位 106
4.9.5 编 号 列 表 107
4.9.6 控 制 字 符 、 字 符 映 射 和 符 号 字 体 108
4.9.7 断 字 110
4.9.8 控 制 换 行 算 法 111
4.9.9 使 用 textflow 格 式 化 CJK 文 本 113
5 导 入 和 放 置 对 象 115
5.1 导 入 光 栅 图 像 115
5.1.1 基 本 图 像 处 理 115
5.1.2 受 支 持 的 图 像 文 件 格 式 116
5.1.3 图 像 蒙 版 和 透 明 度 118
5.1.4 图 像 着 色 119
5.1.5 多 页 图 像 文 件 120
目 录 5

5.1.6 OPI 支 持 120
5.2 使 用 PDI (PDF 导 入 库 ) 生 成 PDF 页 121
5.2.1 PDI 功 能 和 应 用 程 序 121
5.2.2 与 PDFlib 一 起 使 用 PDI 函 数 121
5.2.3 可 接 受 的 PDF 文 档 122
5.3 放 置 图 像 和 导 入 的 PDF 页 123
5.3.1 缩 放 、 方 向 和 旋 转 123
5.3.2 调 整 页 面 尺 寸 125
6 数 据 变 量 和 块 129
6.1 安 装 PDFlib 块 增 效 工 具 129
6.2 PDFlib 块 概 念 的 概 述 130
6.2.1 文 档 设 计 和 程 序 代 码 的 完 整 分 离 130
6.2.2 块 属 性 131
6.2.3 为 什 么 不 使 用 PDF 表 单 域 ? 132
6.3 建 立 PDFlib 块 132
6.3.1 利 用 PDFlib 块 增 效 工 具 交 互 式 建 立 块 132
6.3.2 编 辑 块 属 性 135
6.3.3 页 和 文 件 之 间 的 块 拷 贝 135
6.3.4 将 PDF 表 单 域 转 换 为 PDFlib 块 136
6.4 用 于 自 动 化 处 理 的 标 准 属 性 138
6.4.1 一 般 属 性 139
6.4.2 Text 属 性 140
6.4.3 Image 属 性 143
6.4.4 PDF 属 性 144
6.4.5 自 定 义 属 性 144
6.5 询 问 块 名 及 其 属 性 145
6.6 PDFlib 块 规 格 146
6.6.1 PDFlib 块 的 PDF 对 象 结 构 146
6.6.2 利 用 pdfmarks 生 成 PDFlib 块 148
7 生 成 各 种 风 格 的 PDF 151
7.1 Acrobat 和 PDF 版 本 151
7.2 加 密 PDF 152
7.2.1 PDF 安 全 性 的 优 缺 点 152
7.2.2 用 PDFlib 保 护 文 档 153
7.3 网 页 优 化 的 ( 线 性 化 的 ) PDF 154
7.4 PDF/X 155
7.4.1 PDF/X 系 列 标 准 155
7.4.2 生 成 符 合 PDF/X 标 准 的 输 出 155
7.4.3 用 PDI 导 入 PDF/X 文 档 158
7.5 标 签 PDF 158
7.5.1 用 PDFlib 生 成 标 签 PDF 159
7.5.2 用 直 接 Text Output 和 Textflows 创 建 标 签 PDF 160
7.5.3 启 动 复 杂 布 局 的 项 目 161
7.5.4 在 Acrobat 中 使 用 标 签 PDF 164
6 目 录

8 用 于 PDFlib、 PDI 和 PPS 的 API 参 考 167
8.1 数 据 类 型 和 命 名 约 定 167
8.1.1 PDFlib 数 据 类 型 167
8.1.2 选 项 列 表 168
8.2 常 规 函 数 170
8.2.1 设 置 170
8.2.2 文 档 和 页 面 172
8.2.3 参 数 处 理 181
8.2.4 PDFlib 虚 拟 文 件 系 统 (PVF) 函 数 182
8.2.5 异 常 处 理 183
8.2.6 实 用 程 序 函 数 184
8.3 文 本 函 数 186
8.3.1 字 体 处 理 186
8.3.2 用 户 定 义 (Type 3) 字 体 189
8.3.3 编 码 定 义 191
8.3.4 简 单 文 本 输 出 191
8.3.5 使 用 文 本 流 的 多 行 文 本 198
8.4 图 形 函 数 206
8.4.1 图 形 状 态 函 数 206
8.4.2 保 存 和 恢 复 图 形 状 态 209
8.4.3 坐 标 系 统 转 换 函 数 210
8.4.4 显 式 图 形 状 态 211
8.4.5 路 径 构 建 213
8.4.6 路 径 绘 制 和 剪 切 216
8.4.7 图 层 参 数 218
8.5 颜 色 函 数 221
8.5.1 设 置 颜 色 和 色 彩 空 间 221
8.5.2 图 案 和 着 色 224
8.6 图 像 和 模 板 函 数 227
8.6.1 图 像 227
8.6.2 模 板 232
8.6.3 缩 览 图 233
8.7 PDF 导 入 函 数 (PDI) 234
8.7.1 文 档 和 页 面 234
8.7.2 其 他 PDI 处 理 237
8.7.3 PDI 参 数 处 理 238
8.8 块 填 充 函 数 (PPS) 240
8.9 超 文 本 函 数 243
8.9.1 动 作 243
8.9.2 命 名 目 标 246
8.9.3 注 释 247
8.9.4 表 单 域 250
8.9.5 书 签 255
8.9.6 文 档 信 息 域 256
8.9.7 不 常 用 的 超 文 本 参 数 和 函 数 257
8.10 标 签 PDF 的 结 构 函 数 259
目 录 7

A 相 关 文 献 263
B PDFlib 快 速 参 考 265
C 修 订 历 史 记 录 270
索 引 271
8 目 录

0 应 用 PDFlib 许 可 证 密 钥
无 论 您 是 否 持 有 PDFlib 的 商 业 许 可 证 , 由 PDFlib GmbH 提 供 的 所 有 二 进 制 版 本 的 PDFlib、
PDFlib+PDI 和 PPS 都 可 以 作 为 功 能 完 整 的 评 估 版 本 使 用 。 然 而 , 未 经 许 可 的 版 本 将 在 所 有
生 成 的 页 上 显 示 www.pdflib.com 演 示 图 章 ( 提 示 标 记 )。 那 些 真 正 对 PDFlib 许 可 证 感 兴 趣
并 希 望 消 除 评 估 期 间 或 原 型 演 示 的 提 示 标 记 的 公 司 , 可 以 将 带 有 简 要 说 明 的 有 关 公 司 和 项
目 的 详 细 信 息 提 交 到 sales@pdflib.com, 以 便 申 请 临 时 许 可 证 密 钥 ( 我 们 保 留 拒 绝 评 估 密 钥
的 权 利 , 例 如 匿 名 请 求 )。
在 您 购 买 许 可 证 密 钥 之 后 , 必 须 应 用 该 密 钥 才 能 消 除 演 示 图 章 。 您 可 以 准 备 一 个 密 钥 文
件 , 在 运 行 时 调 用 PDFlib 函 数 从 文 件 中 获 取 许 可 证 密 钥 ; 或 在 Windows 中 使 用 注 册 表 。 若
使 用 Windows 安 装 程 序 , 您 可 以 在 产 品 安 装 时 键 入 一 个 许 可 证 密 钥 。
在 运 行 中 提 供 许 可 证 密 钥 在 脚 本 或 程 序 中 添 加 一 行 代 码 以 便 在 运 行 时 设 置 许 可 证 密 钥 。
在 实 例 化 PDFlib 对 象 之 后 ( 即 , 在 PDF_new( ) 或 等 同 的 调 用 之 后 ), 紧 接 着 必 须 设 置 license
参 数 。 具 体 的 句 法 将 取 决 于 您 使 用 的 编 程 语 言 :
> C 和 Python:
PDF_set_parameter(p, "license", "...your license key...");
> C++, Java, Ruby 和 PHP5( 面 向 对 象 的 界 面 ):
p.set_parameter("license", "...your license key...");
> Perl, PHP4 和 PHP5( 面 向 函 数 的 界 面 ):
PDF_set_parameter($p, "license", "...your license key...");
> RPG:
d licensekey s 20
d licenseval s 50
c eval licenseopt='license'+x'00'
c eval licenseval='...your license key...'+x'00'
c callp PDF_set_parameter(p:licenseopt:licenseval)
> Tcl:
PDF_set_parameter $p, "license", "...your license key..."
使 用 许 可 证 文 件 > 按 照 下 面 的 格 式 在 文 本 文 件 中 输 入 许 可 证 密 钥 ( 您 可 以 使 用 所 有 PDFlib
分 发 中 包 含 的 许 可 证 文 件 模 板 licensekeys.txt):
PDFlib license file 1.0
# Licensing information for PDFlib GmbH products
PDFlib 6.0.3 ...your license key...
许 可 证 文 件 可 以 包 含 多 个 PDFlib GmbH 产 品 的 许 可 证 密 钥 , 每 一 行 对 应 于 一 个 许 可 证
密 钥 。 接 下 来 , 您 必 须 通 过 以 下 两 种 方 式 之 一 向 PDFlib 通 知 有 关 许 可 证 文 件 的 情 况 :
在 实 例 化 PDFlib 对 象 之 后 ( 即 , PDF_new( ) 或 等 同 的 调 用 之 后 ), 紧 接 着 按 如 下 方 式
设 置 licensefile 参 数 :
> C 和 Python:
PDF_set_parameter(p, "licensefile", "/path/to/licensekeys.txt")
9

C++, Java, Ruby 和 PHP5( 面 向 对 象 的 界 面 ):
p.set_parameter("licensefile", "/path/to/licensekeys.txt");
> Perl, PHP4 和 PHP5( 面 向 函 数 的 界 面 ):
PDF_set_parameter($p, "licensefile", "/path/to/licensekeys.txt");
> In Tcl:
PDF_set_parameter $p, "licensefile", "/path/to/licensekeys.txt"
或 者 , 您 可 以 设 置 环 境 变 量 PDFLIBLICENSEFILE 指 向 相 应 的 许 可 证 文 件 。 在 Windows 使 用
系 统 控 制 面 板 。 在 Unix 则 使 用 类 似 于 以 下 的 命 令 行 :
export PDFLIBLICENSEFILE=/path/to/license/file
Windows 注 册 表 在 Windows 中 您 可 以 在 下 列 注 册 表 条 目 中 输 入 许 可 证 文 件 名 :
HKLM\Software\PDFlib\PDFLIBLICENSEFILE
请 注 意 , 虽 然 PDFlib、 PDFlib+PDI 和 PDFlib 个 性 化 设 置 服 务 器 (PPS) 是 在 一 个 包 装 中 发 送
的 , 但 是 它 们 是 需 要 不 同 许 可 证 密 钥 的 不 同 产 品 。 虽 然 PDFlib+PDI 许 可 证 密 钥 也 对 PDFlib
有 效 , 但 是 反 过 来 则 行 不 通 ,PPS 许 可 证 密 钥 对 PDFlib+PDI 和 PDFlib 有 效 。 所 有 许 可 证 密
钥 都 依 赖 于 平 台 , 只 能 在 所 购 买 的 密 钥 针 对 的 平 台 上 使 用 。
累 积 各 个 CPU 密 钥 若 您 分 为 多 次 购 买 了 多 个 CPU 许 可 证 ( 而 不 是 一 次 性 购 买 了 所 有 这 些
CPU 许 可 证 ), 则 可 以 通 过 在 许 可 文 件 中 相 继 输 入 这 些 密 钥 来 累 积 所 有 密 钥 。 可 以 针 对 各 个
许 可 证 密 钥 多 次 调 用 PDF_set_parameter( ) 函 数 。 但 是 ,Windows 注 册 表 和 Windows 安 装
程 序 不 能 够 用 来 累 积 许 可 证 密 钥 。
更 新 和 升 级 若 您 已 购 买 一 个 更 新 ( 从 产 品 的 旧 版 本 到 同 一 产 品 的 新 版 本 的 更 改 ) 或 升 级
( 从 PDFlib 到 PDFlib+PDI 或 PPS 的 更 改 , 或 者 , 从 PDFlib+PDI 到 PPS 的 更 改 ), 则 必 须 应
用 您 所 接 收 的 用 于 更 新 或 升 级 的 新 的 许 可 证 密 钥 。 不 得 再 使 用 先 前 产 品 的 旧 的 许 可 证 密 钥 。
评 估 未 经 许 可 的 功 能 您 可 以 使 用 未 应 用 任 何 许 可 证 密 钥 的 软 件 完 全 评 估 所 有 功 能 。 不
过 , 一 旦 您 应 用 了 特 定 产 品 的 有 效 许 可 证 密 钥 , 则 将 不 再 可 以 使 用 更 高 类 别 的 功 能 。 例 如 ,
若 您 已 安 装 有 效 的 PDFlib 许 可 证 密 钥 , 则 PDI 功 能 将 不 再 可 以 用 于 测 试 。 同 样 , 在 安 装
PDFlib+PDI 许 可 证 密 钥 后 , PPS 功 能 ( 块 函 数 ) 将 不 再 可 用 。
若 您 已 安 装 某 个 产 品 的 许 可 证 密 钥 , 则 可 以 用 0 ( 零 ) 虚 拟 许 可 证 密 钥 替 换 该 密 钥 来 启
用 更 高 的 产 品 类 别 的 功 能 以 进 行 评 估 。 这 将 启 用 先 前 已 禁 用 的 功 能 , 并 重 新 激 活 所 有 页 的 演
示 图 章 。
许 可 选 项 对 于 在 一 个 或 多 个 服 务 器 上 使 用 PDFlib, 以 及 将 自 己 的 产 品 与 PDFlib 一 起 重 新
分 发 , 可 以 使 用 不 同 的 许 可 选 项 。 我 们 同 时 还 提 供 支 持 和 源 代 码 约 定 。 可 以 在 PDFlib 分 发
中 找 到 许 可 证 详 细 信 息 和 PDFlib 购 买 订 单 。 若 您 有 兴 趣 获 得 商 业 PDFlib 许 可 证 , 或 您 有 任
何 问 题 , 请 与 我 们 联 系 :
PDFlib GmbH, Licensing Department
Tal 40, 80331 München, Germany
www.pdflib.com, 电 话 +49 • 89 • 29 16 46 87, 传 真 +49 • 89 • 29 16 46 86
许 可 证 联 系 人 : sales@pdflib.com
对 PDFlib 被 许 可 方 的 支 持 : support@pdflib.com
10 第 0 章 : 应 用 PDFlib 许 可 证 密 钥

1 前 言
1.1 PDFlib 编 程
什 么 是 PDFlib? PDFlib 是 一 个 库 文 件 , 它 允 许 您 按 照 Adobe 的 可 移 植 文 档 格 式 (PDF) 生 成
文 件 。PDFlib 充 当 您 自 己 的 程 序 的 后 端 。 当 您 ( 程 序 员 ) 负 责 抽 取 要 处 理 的 数 据 时 ,PDFlib
承 担 生 成 PDF 代 码 的 任 务 并 以 图 形 方 式 表 示 数 据 。 尽 管 您 仍 必 须 设 置 文 本 和 图 表 对 象 的 格
式 并 安 排 版 式 , 但 PDFlib 可 让 您 不 用 再 关 注 PDF 的 内 部 细 节 问 题 。 我 们 的 二 进 制 程 序 包 在
一 个 库 中 提 供 了 不 同 的 产 品 :
> PDFlib 包 含 创 建 PDF 输 出 ( 包 括 文 本 、 矢 量 图 形 和 图 像 以 及 超 文 本 元 素 ) 所 必 需 的 所 有
函 数 。
> PDFlib+PDI 包 括 所 有 PDFlib 函 数 , 以 及 用 于 在 已 生 成 的 输 出 中 包 括 现 有 PDF 文 档 页 的
PDF 输 入 库 (PDI)。
> PDFlib Personalization Server (PPS) 包 括 PDFlib+PDI 以 及 用 于 自 动 填 充 PDFlib 块 的 附
加 函 数 。 块 是 页 上 的 占 位 矩 形 , 可 以 用 文 本 、 图 像 或 PDF 页 进 行 填 充 。 可 以 使 用 适 用 于
Adobe Acrobat (Mac 或 Windows) 的 PDFlib 块 增 效 工 具 交 互 式 创 建 块 , 并 使 用 PPS
自 动 进 行 填 充 。 该 增 效 工 具 包 含 在 PPS 中 。
如 何 使 用 PDFlib? PDFlib 可 在 多 种 平 台 上 使 用 , 包 括 Unix、 Windows、 Mac 和 基 于
EBCDIC 的 系 统 ( 如 IBM eServer iSeries 和 zSeries)。 虽 然 PDFlib 自 身 是 用 C 语 言 编 写 的 ,
但 也 可 以 从 多 种 其 他 语 言 或 编 程 环 境 访 问 它 。 这 种 情 况 称 为 “ 语 言 绑 定 ”。 这 些 语 言 绑 定 覆
盖 了 所 有 当 前 Web 和 独 立 应 用 程 序 环 境 。 应 用 程 序 编 程 接 口 (API) 简 单 易 学 , 且 对 于 所 有 的
绑 定 都 是 相 同 的 。 目 前 , 支 持 以 下 的 语 言 绑 定 :
> COM ( 用 于 Visual Basic、 带 有 VBScript 或 JScript 的 Active Server Page、 Borland
Delphi、 Windows Script Host 和 其 他 环 境 )
> ANSI C
> ANSI C++
> Cobol (IBM eServer zSeries)
> Java ( 包 括 servlet)
> .NET ( 用 于 C#、 VB.NET、 ASP.NET 和 其 他 环 境 )
> PHP 超 文 本 处 理 器
> Perl
> Python
> REALbasic
> RPG (IBM eServer iSeries)
> Ruby
> Tcl
使 用 PDFlib 可 以 做 些 什 么 ? PDFlib 的 主 要 目 标 是 在 您 自 己 的 软 件 内 部 或 在 万 维 网 上 动 态
创 建 PDF。 类 似 于 在 Web 服 务 器 上 动 态 创 建 HTML 页 , 您 可 以 使 用 PDFlib 程 序 动 态 创 建
PDF 以 反 映 用 户 输 入 或 一 些 其 他 的 动 态 数 据 ( 例 如 从 Web 服 务 器 的 数 据 库 中 检 索 的 数 据 )。
PDFlib 方 法 具 有 下 面 几 个 优 点 :
> 可 以 在 生 成 数 据 的 应 用 程 序 中 直 接 集 成 PDFlib, 消 除 复 杂 的 创 建 路 径 application–
PostScript–Acrobat Distiller–PDF。
> 这 一 直 接 简 单 的 方 法 意 味 着 , PDFlib 是 生 成 PDF 的 最 快 方 法 , 完 全 适 用 于 Web。
> PDFlib 的 多 线 程 安 全 及 其 可 靠 内 存 和 错 误 处 理 可 支 持 实 现 高 性 能 的 服 务 器 应 用 程 序 。
1.1 PDFlib 编 程 11

PDFlib 可 用 于 多 种 操 作 系 统 和 开 发 环 境 。
有 关 使 用 PDFlib 的 要 求 PDFlib 可 让 用 户 不 用 费 心 了 解 PDF 规 范 即 可 生 成 PDF。 尽 管
PDFlib 会 尽 力 向 用 户 隐 藏 PDF 的 技 术 细 节 , 但 是 对 PDF 有 一 个 大 致 了 解 还 是 有 用 的 。 为 了
最 好 地 使 用 PDFlib, 应 用 程 序 程 序 员 最 好 应 熟 悉 PostScript 的 基 本 图 形 模 型 ( 以 及 PDF)。
不 过 , 对 于 已 使 用 过 用 于 屏 幕 显 示 或 打 印 的 任 何 图 形 API 的 有 相 当 经 验 的 应 用 程 序 程 序 员 ,
掌 握 本 手 册 中 描 述 的 PDFlib API 应 无 困 难 。
本 手 册 的 内 容 本 手 册 描 述 由 PDFlib 提 供 的 API。 手 册 中 没 有 描 述 如 何 构 建 库 二 进 制 文 件
的 过 程 。 本 手 册 中 未 描 述 的 功 能 不 受 支 持 且 不 应 被 使 用 。 本 手 册 并 不 试 图 解 释 Acrobat 功
能 。 有 关 进 一 步 的 参 考 , 请 参 阅 本 手 册 末 尾 所 引 用 的 Acrobat 产 品 文 献 和 资 料 。PDFlib 分 发
包 含 有 关 调 用 PDFlib 功 能 的 附 加 示 例 。
实 例 编 码 T 本 手 册 包 含 了 大 量 编 码 片 断 。 虽 然 PDFlib 支 持 多 种 编 程 语 言 , 本 手 册 只 提 供
C 的 实 例 编 码 。 使 用 其 他 编 程 语 言 的 用 户 需 将 这 些 实 例 编 码 转 换 为 所 用 的 语 言 句 法 。
1.2 PDFlib 6 中 的 主 要 新 增 功 能
下 面 的 列 表 讨 论 PDFlib 6 中 最 重 要 的 新 增 功 能 或 改 进 功 能 。
编 程 改 进 先 前 版 本 中 的 许 多 限 制 已 经 被 取 消 。 例 如 , 可 以 按 照 任 意 顺 序 创 建 页 , 可 以 在 现
有 页 之 间 插 入 新 页 , 可 以 在 以 后 将 更 多 内 容 添 加 到 现 有 页 中 。
图 层 虽 然 PDF 的 图 层 功 能 ( 在 Acrobat 6 中 引 入 ) 对 CAD 和 工 程 设 计 应 用 程 序 很 重 要 ,
但 是 它 也 可 以 用 于 效 果 出 色 的 交 互 文 档 、 多 语 言 文 档 等 。PDFlib 支 持 在 PDF 1.5 中 可 用 的 所
有 图 层 控 制 功 能 , 包 括 在 Acrobat 中 无 法 访 问 的 各 种 控 制 。
Unicode PDFlib 6 允 许 在 所 有 相 关 区 域 ( 例 如 文 件 名 称 、 页 内 容 、 超 文 本 、 表 域 等 ) 中 使
用 Unicode 字 符 串 , 从 而 改 善 了 对 Unicode 标 准 的 支 持 。 这 对 于 欧 洲 和 北 美 洲 之 外 的 用
户 特 别 重 要 。
文 本 格 式 新 的 textflow 格 式 化 程 序 提 供 强 大 而 易 于 使 用 的 功 能 , 可 以 通 过 各 种 选 项 格 式
化 文 本 。Unicode 文 本 、 锯 齿 形 或 分 散 对 齐 形 文 本 、 任 意 字 体 更 改 、 多 行 正 文 文 本 或 发 票 中
的 大 型 表 ― 新 的 textflow 功 能 可 以 处 理 所 有 常 见 的 格 式 化 任 务 。
图 像 处 理 TIFF 图 像 处 理 得 到 了 扩 展 , 可 以 涵 盖 先 前 不 受 支 持 的 TIFF 风 格 , 例 如 压 缩 的
JPEG TIFF 或 Lab 和 YCbCr 色 彩 空 间 。 由 于 PDF 1.5 支 持 16 位 颜 色 深 度 , 因 此 , 每 色 彩 分 量
采 用 16 位 表 示 的 TIFF 和 PNG 图 像 现 在 可 以 在 PDF 中 转 换 为 16 位 色 彩 。 PDFlib 6.0.2 添 加
了 对 JPEG2000 图 像 的 支 持 。
标 签 PDF 根 据 美 国 康 复 法 案 第 508 节 (section 508) 和 其 他 国 家 的 相 应 准 则 , 标 签 PDF 是
残 疾 人 士 访 问 PDF 的 关 键 。 PDFlib 是 第 一 个 程 序 库 从 总 体 上 支 持 标 记 PDF 的 生 成 。 使 用 这
一 新 功 能 , 用 户 可 以 非 常 容 易 的 从 动 态 数 据 里 生 成 标 签 PDF。PDFlib 生 成 的 文 档 将 支 持 所 有
Acrobat 标 签 PDF 的 功 能 如 : 页 重 组 、 朗 读 和 高 质 量 的 输 出 RTF、HTML、XML 等 不 同 的 文
件 格 式 。textflow 格 式 器 与 这 一 功 能 的 组 合 能 迅 速 的 生 成 大 量 的 标 签 PDF。 第 一 次 , 在 网 络
服 务 器 上 动 态 生 成 的 PDF 文 档 可 以 满 足 上 面 提 到 的 残 疾 人 士 可 访 问 性 准 则 。
PDF/X 印 前 标 准 PDFlib 6 是 市 场 上 第 一 款 、 根 据 有 关 印 前 的 最 新 的 PDF/X 2003 版 本 标 准
(PDF/X-1a:2003、PDF/X-2:2003 和 PDF/X-3:2003) 支 持 生 成 和 处 理 PDF 文 档 的 软 件 。PDF/X
12 第 1 章 : 前 言

对 于 在 印 前 行 业 中 的 文 件 交 换 起 到 了 重 要 的 作 用 。 为 了 在 图 片 艺 术 行 业 中 实 现 可 靠 的 数 据 交
换 , 全 世 界 越 来 越 多 的 出 版 商 采 用 PDF/X 作 为 数 据 交 换 的 标 准 。 新 的 2003 版 本 更 新 、 增 强 并
统 一 了 PDF/X 标 准 系 列 。
开 放 印 前 作 业 界 面 (OPI) 图 片 艺 术 行 业 中 的 一 些 工 作 流 程 仍 依 赖 于 PostScript 时 期 的 OPI
标 准 , 并 使 用 嵌 入 在 PDF 文 档 中 的 OPI 信 息 。 PDFlib 6 通 过 提 供 用 于 将 OPI 信 息 添 加 到 导
入 的 图 像 的 选 项 , 可 以 支 持 这 一 标 准 。
线 性 PDF PDFlib 6 可 生 成 线 性 PDF, 也 称 作 “ 网 页 最 优 化 PDF”。 当 用 户 在 网 上 浏 览 具 有
这 一 特 征 的 PDF 时 , 它 将 逐 页 下 载 ( 又 称 byteserving) 从 而 显 著 提 高 用 户 的 使 用 经 验 。
用 于 可 变 数 据 处 理 的 PDFlib 块 为 建 立 PDF 模 版 而 设 计 的 PDFlib 块 用 户 接 口 被 扩 充 并 流
线 化 。 PDFlib 块 现 在 能 用 新 增 的 textflow 格 式 器 填 充 多 行 文 本 。 受 益 于 此 , PDFlib
Personalization Server (PPS) 将 不 再 局 限 于 原 有 的 简 单 的 信 件 合 并 , 它 可 以 应 用 于 更 复 杂 的
排 版 和 文 本 格 式 。
表 单 PDF 所 有 的 表 域 类 型 可 以 通 过 Javascript 或 其 它 动 作 (actions) 生 成 或 加 强 。 因 此
PDF 表 单 可 根 据 用 户 输 出 和 数 据 库 信 息 由 PDFlib 动 态 生 成 。
超 文 本 PDFlib 的 超 文 本 功 能 经 过 了 扩 展 , 可 以 完 全 支 持 用 于 书 签 、 操 作 和 注 释 的 所 有
PDF 选 项 。 可 以 创 建 页 标 签 以 将 符 号 名 称 或 罗 马 数 字 附 加 到 页 上 , 如 i, ii, iii... 或 A-1, A-2 等 。
REALbasic 作 为 所 支 持 的 一 系 列 编 程 环 境 中 的 新 成 员 ,PDFlib 6 引 入 了 在 Mac 和 Windows
上 对 于 REALbasic 的 一 种 新 的 语 言 绑 定 。 REALbasic 是 一 种 用 于 开 发 多 平 台 应 用 程 序 的 语
言 。 用 于 REALbasic 的 PDFlib 6 可 顺 畅 地 集 成 到 RB 的 对 象 模 块 中 , 支 持 Unicode 字 符 串 ,
并 可 让 开 发 人 员 从 REALbasic 内 部 访 问 所 有 的 PDFlib 功 能 。
1.3 PDFlib 功 能
表 1.1 列 出 了 用 于 生 成 和 导 入 PDF 的 主 要 PDFlib 功 能 。PDFlib 6 中 新 功 能 或 改 进 功 能 已 被 标
记 出 来 。
表 1.1 有 关 PDFlib、 PDFlib+PDI 和 PDFlib Personalization Server (PPS) 的 功 能 列 表
主 题
PDF 输 出
功 能
直 接 保 存 在 内 存 中 ( 用 于 Web 服 务 器 ) 或 保 存 在 磁 盘 文 件 上 的 任 意 长 度 的 PDF 文 档
文 本 、 矢 量 图 形 、 图 像 数 据 和 文 件 附 件 的 压 缩
1
1
挂 起 / 继 续 和 插 入 页 等 支 持 不 按 顺 序 创 建 页 的 功 能
PDF 风 格 PDF 1.3、 1.4、 1.5 和 1.6 (Acrobat 4、 5、 6 和 7)
线 性 PDF ( 网 页 最 优 化 PDF), 用 于 Web 逐 页 下 载 ( 又 称 byteserving) 1
PDF 输 入
块
从 现 有 PDF 文 档 ( 仅 PDFlib+PDI 和 PPS) 导 入 页
使 用 用 于 文 本 、 图 像 和 PDF 数 据 ( 仅 PPS) 的 PDFlib 块 个 性 化 设 置 PDF
1
使 用 Acrobat 的 PDFlib 块 增 效 工 具 以 创 建 PDFlib 块 ( 仅 PPS), 重 新 设 计 的 用 户 界 面
图 形 常 见 矢 量 图 形 基 元 : 直 线 、 曲 线 、 弧 线 、 矩 形 等 。
阴 影 平 滑 ( 色 彩 混 和 )、 图 案 填 充 和 描 边
利 用 模 板 有 效 重 用 文 本 或 矢 量 图 形
用 于 文 本 镂 空 、 压 印 等 的 图 形 状 态 参 数
透 明 度 ( 不 透 明 度 ) 和 混 和 模 式
图 层
1 : 可 以 选 择 性 地 启 用 或 禁 用 的 可 选 页 内 容
1.3 PDFlib 功 能 13

表 1.1 有 关 PDFlib、 PDFlib+PDI 和 PDFlib Personalization Server (PPS) 的 功 能 列 表 ( 续 )
主 题
字 体
文 本 输 出
国 际 化
图 像
色 彩
TrueType (ttf 和 ttc) 和 PostScript Type 1 字 体 (pfb 和 pfa 以 及 Mac 上 的 lwfn)
带 有 PostScript 或 TrueType 轮 廓 的 OpenType 字 体 (ttf 和 otf)
AFM 和 PFM PostScript 字 库 量 度 文 件
字 体 嵌 入
直 接 使 用 已 在 Windows 或 Mac 主 机 系 统 上 安 装 的 字 体
TrueType 和 OpenType 字 体 的 子 集
用 于 点 阵 字 体 或 自 定 义 徽 标 的 用 户 自 定 义 的 (Type 3) 字 体
使 用 不 同 字 体 显 示 的 文 本 输 出 ; 下 划 线 文 本 、 上 划 线 文 本 和 删 除 线 文 本
用 于 PostScript 字 体 、 TrueType 字 体 和 OpenType 字 体 的 字 距 调 整
用 于 高 级 拣 字 程 序 的 TrueType 和 OpenType 字 形 ID 寻 址
用 于 标 准 CJK 字 体 的 比 例 宽 度
1
1
用 于 页 内 容 、 超 文 本 和 文 件 名 称 的 Unicode ; UTF-8 和 UCS-2 格 式 , little-endian 和
big-endian
在 COM、 Java、 .NET、 REALbasic、 Tcl 中 完 全 集 成 对 Unicode 字 符 串 的 处 理
支 持 各 种 编 码 ( 国 际 标 准 和 供 应 商 特 定 的 代 码 页 )
从 系 统 (Windows、 IBM eServer iSeries 和 zSeries) 中 获 取 代 码 页
标 准 的 CJK 字 体 和 对 中 文 、 日 文 和 韩 文 文 本 的 CMap 支 持
带 有 Unicode 编 码 的 TrueType 和 OpenType 格 式 的 自 定 义 CJK 字 体
将 Unicode 信 息 嵌 入 PDF 中 以 用 于 Acrobat 中 的 正 确 文 本 提 取
嵌 入 BMP、 GIF、 PNG、 TIFF 1 、 JPEG、 JPEG2000 和 CCITT 光 栅 图 像
自 动 检 测 图 像 文 件 格 式 ( 文 件 格 式 探 查 )
透 明 ( 蒙 版 ) 的 图 像 , 包 括 软 蒙 版
图 像 蒙 版 ( 应 用 了 单 一 色 彩 的 透 明 图 像 )
使 用 专 色 为 图 像 着 色
图 像 插 值 处 理 ( 使 低 分 辨 率 图 像 平 滑 )
灰 度 、 RGB、 CMYK、 CIE L*a*b* 色 彩
内 置 PANTONE® 和 HKS® 专 色 表
用 户 自 定 义 的 专 色
色 彩 ¼‹¿Ì 带 ICC 配 置 文 件 (ICC profile) 的 基 于 ICC 的 色 彩 : 接 受 图 像 中 已 嵌 入 的 配 置 文 件 或 对 图 像 应 用
外 部 描 述 文 件
文 本 、 图 形 和 光 栅 图 像 的 渲 染 方 法
默 认 的 灰 度 、 RGB 和 CMYK 色 彩 空 间 以 便 重 新 映 射 设 备 相 关 的 色 彩
印 前 生 成 符 合 PDF/X-1、 PDF/X-1a、 PDF/X-2 1 1
和 PDF/X-3 标 准 的 输 出 , 包 括 2003 风 格
格 式 设 置
安 全
功 能
嵌 入 ICC 配 置 文 件 (ICC profile) 所 要 输 出 的 设 备 的 输 出 条 件 或 引 用 标 准 输 出 内 容
从 导 入 的 PDF 文 档 ( 仅 PDFlib+PDI 和 PPS) 复 制 输 出 内 容
1
为 导 入 的 图 像 创 建 OPI 1.3 和 OPI 2.0 信 息
分 色 信 息 (PlateColor) 1
textflow 格 式 设 置
1 : 使 用 断 字 、 字 体 和 色 彩 更 改 、 各 种 对 齐 方 法 、 控 制 命 令 , 将 任 意 数 量 的
文 本 格 式 化 到 一 个 或 多 个 矩 形 区 域 内
文 本 行 位 置 和 格 式 设 置
灵 活 多 变 的 图 像 位 置 和 格 式 设 置
使 用 40 位 或 128 位 加 密 生 成 输 出
使 用 权 限 设 置 生 成 输 出
14 第 1 章 : 前 言

表 1.1 有 关 PDFlib、 PDFlib+PDI 和 PDFlib Personalization Server (PPS) 的 功 能 列 表 ( 续 )
主 题
导 入 加 密 的 文 档 ( 要 求 许 可 口 令 ; 仅 PDFlib+PDI 和 PPS)
超 文 本 使 用 所 有 字 段 选 项 和 JavaScript 1 1
创 建 表 域
1
创 建 用 于 书 签 、 注 释 、 页 面 打 开 / 关 闭 和 其 他 事 件 的 动 作
1
使 用 各 种 选 项 和 控 件 创 建 书 签
标 签 PDF
编 程
功 能
支 持 页 面 转 换 效 果 , 例 如 渐 变 和 马 赛 克
创 建 所 有 PDF 注 释 类 型
1 , 例 如 PDF 链 接 、 启 动 链 接 ( 其 他 文 档 类 型 )、 Web 链 接
文 档 信 息 : 标 准 字 段 ( 标 题 、 主 题 、 作 者 、 关 键 字 ) 以 及 没 有 数 量 限 制 的 用 户 自 定 义 的 信 息
字 段
为 链 接 、 书 签 和 文 档 打 开 动 作 的 指 定 的 目 标
浏 览 器 首 选 项 ( 隐 藏 菜 单 栏 等 ) 1
创 建 页 标 签 ( 页 的 符 号 名 称 ) 1
创 建 标 签 PDF 1 , 及 辅 助 功 能 、 页 重 排 和 改 进 内 容 重 规 划 的 结 构 信 息
1
轻 松 地 格 式 化 用 于 标 签 PDF 的 大 量 文 本
支 持 Cobol、COM、C、C++、Java、.NET、Perl、PHP 1 、Python、REALbasic 1 、RPG、Ruby 和
Tcl 的 语 言 绑 定
支 持 多 线 程 服 务 器 应 用 程 序 中 的 多 线 程 安 全 和 可 靠 部 署
支 持 在 内 存 中 提 供 数 据 的 虚 拟 文 件 系 统 , 例 如 数 据 库 中 的 映 像
1. PDFlib 6 中 的 新 增 功 能 或 显 著 改 进
1.4 不 同 产 品 中 的 功 能 的 可 用 性
表 1.2 详 述 了 开 放 原 码 版 本 PDFlib Lite 和 不 同 的 商 业 产 品 中 的 功 能 的 可 用 性 。
表 1.2 不 同 产 品 中 的 功 能 的 可 用 性
PDFlib Lite
( 开 放 原 码 )
功 能
API 函 数 和 参 数
基 本 PDF 生 成 ( 除 以 下 列 出 项 之 外 的 全 部 ) X X X X
语 言 绑 定 C、 C++、 Java、 Perl、 Tcl、 PHP、 Python、 Ruby X X X X
语 言 绑 定 Cobol、 COM、 .NET、 REALbasic、 RPG – X X X
支 持 EBCDIC 系 统 – X X X
口 令 保 护 和 权 限 设 置 带 有 userpassword、 masterpassword、
– X X X
permissions 选 项 的 PDF_begin_document( )
线 性 PDF 带 有 linearize 选 项 的 PDF_begin_document( ) – X X X
字 体 子 集 带 有 subsetting 选 项 的 PDF_load_font( ) – X X X
kerning 带 有 kerning 选 项 的 PDF_load_font( ) – X X X
访 问 Mac 和 Windows PDF_load_font( ) – X X X
宿 主 字 体
访 问 Windows、 iSeries、
zSeries 上 的 系 统 编 码
PDF_load_font( ) – X X X
PDFlib
PDFlib+PDI
PDFlib Personalization
Server (PPS)
1.4 不 同 产 品 中 的 功 能 的 可 用 性 15

表 1.2 不 同 产 品 中 的 功 能 的 可 用 性 ( 续 )
功 能
Unicode 编 码 和 ToUnicode
CMaps
带 有 encoding = unicode、 autocidfont 和
unicodemap 参 数 的 PDF_load_font( )
数 字 和 字 符 实 体 引 用 PDF_fit_textline( ) 中 的 charref 选 项 ,
charref 参 数
带 Unicode CMap 的 标 准
CJK 字 体 的 比 例 字 形 宽 度
– X X X
– X X X
带 有 UCS2-compatible CMap 的 PDF_load_font( ) – X X X
字 形 ID 寻 址 带 有 encoding = glyphid 的 PDF_load_font( ) – X X X
基 于 PostScript OpenType PDF_load_font( ) – X X X
字 体 的 扩 展 编 码
Textflow PDF_create_textflow( )、 PDF_delete_textflow( )、
PDF_fit_textflow( )、 PDF_info_textflow( )
– X X X
专 色 PDF_makespotcolor() – X X X
分 色 带 有 separationinfo 选 项 的 PDF_begin_page_ext( ) – X X X
表 域 PDF_create_field( )、 PDF_create_fieldgroup( )、 – X X X
带 有 type=SetOCGState 的 PDF_create_action( )
JavaScript 动 作 带 有 type=JavaScript 的 PDF_create_action( ) – X X X
图 层 PDF_define_layer( )、 PDF_begin_layer( )、
PDF_end_layer( )、 PDF_set_layer_dependency( )、
带 有 type=SetOCGState 的 PDF_create_action( )
– X X X
标 签 PDF PDF_begin_item( )、 PDF_end_item( )、
PDF_activate_item( )、 带 有 tagged 和
lang 选 项 的 PDF_begin_document( )
– X X X
JPEG2000 带 有 imagetype=jpeg2000 的 PDF_load_image( ) – X X X
支 持 PDF/X PDF_process_pdi( )、
带 pdfx 选 项 的 PDF_begin_document( )
支 持 ICC 配 置 文 件
(ICC profile)
PDF_load_iccprofile( )、 带 有 iccbasedgray/rgb/
cmyk 的 PDF_setcolor( )、 带 有 honoriccprofile 选
项 、 honoriccprofile 参 数 的 PDF_load_image( )、
带 有 defaultgray/rgb/cmyk 选 项 的 PDF_begin/
end_page_ext( )
– X X X
– X X X
CIE L*a*b* 色 彩 空 间 带 有 type = lab 的 PDF_ setcolor( ) ; Lab TIFF 图 像 – X X X
支 持 开 放 印 前 作 业 界 面 带 有 OPI-1.3/OPI-2.0 选 项 的 PDF_load_image( ) – X X X
(OPI)
PDF 导 入 (PDI) PDF_open_pdi( )、 PDF_open_pdi_callback( )、
PDF_open_pdi_page( )、 PDF_fit_pdi_page( )、
PDF_process_pdi( )
– – X X
查 询 现 有 PDF 的 信 息 PDF_get_pdi_value( )、
PDF_get_pdi_parameter( )
使 用 块 进 行 变 量 数 据 处 理 和
个 性 化 设 置
API 函 数 和 参 数
PDF_fill_textblock( )、
PDF_fill_imageblock( )、
PDF_fill_pdfblock( )
PDFlib Lite
( 开 放 原 码 )
PDFlib
PDFlib+PDI
– – X X
– – – X
PDFlib Personalization
Server (PPS)
16 第 1 章 : 前 言

表 1.2 不 同 产 品 中 的 功 能 的 可 用 性 ( 续 )
功 能
查 询 标 准 和 自 定 义 块 属 性
用 于 Acrobat 的 PDFlib 块
增 效 工 具
API 函 数 和 参 数
PDF_get_pdi_value( )、 带 有 vdp/Blocks 密 钥 的
PDF_get_pdi_parameter( )
PDFlib Lite
( 开 放 原 码 )
– – – X
交 互 式 创 建 用 于 PPS 的 PDFlib 块 – – – X
PDFlib
PDFlib+PDI
PDFlib Personalization
Server (PPS)
1.4 不 同 产 品 中 的 功 能 的 可 用 性 17

18 第 1 章 : 前 言

2PDFlib 语 言 绑 定
2.1 概 述
可 用 性 和 平 台 所 有 PDFlib 功 能 在 所 有 平 台 上 和 所 有 语 言 绑 定 ( 有 少 数 几 种 例 外 情 况 已 在
本 手 册 中 注 明 ) 中 都 可 用 。 表 2.1 列 出 了 我 们 用 于 测 试 的 语 言 / 平 台 组 合 。
表 2.1 测 试 所 使 用 的 语 言 和 平 台 组 合
IBM eServer
iSeries 和 zSeries
语 言
Unix (Linux、 Solaris、 HP-UX、
Mac OS X、 AIX、 IRIX a.o.) Windows NT4SP2 或 以 上 平 台
Cobol – – ILE Cobol
–
COM – ASP (PWS、 IIS 4、 5、 6)
WSH (VBScript 5、 JScript 5)
Visual Basic 6.0, Borland Delphi 5 – 7
ISO/ANSI C
gcc 3/4、 HP C、 IBM C 6、 Sun
Workshop 6 和 其 他 ISO C 编 译 器
Microsoft Visual C++ 6、 VS .NET
Metrowerks CodeWarrior 8
Borland C++ Builder 6
ISO C++ gcc 3/4 和 其 他 ISO C++ 编 译 器 Microsoft Visual C++ 6、 VS .NET
Metrowerks CodeWarrior 8
Java JDK 1.1.8、 1.2.2、 1.3、 1.4、 1.5 Sun JDK 1.1.8、 1.2.2、 1.3、 1.4、 1.5
ColdFusion MX
.NET – .NET Framework 1.1:
C#、 VB.NET、 ASP.NET 等
( 也 测 试 了 Visual Studio 2005 Beta 2
与 .NET Framework 2.0)
Perl Perl 5.6 – 5.8 Perl 5.6 – 5.8 –
IBM c89
SAS C for MVS
IBM c89
JDK 1.3.1
PHP PHP 4.3.x、 4.4.x、 5.0.x PHP 4.3.x、 4.4.x、 5.0.x –
Python Python 1.6, 2.0 – 2.3 Python 1.6, 2.0 – 2.3 –
REALbasic 适 用 于 Mac OS Classic、 Mac OS X 和 Windows 的 REALbasic 5.5、 2005 或 更 –
高 版 本
RPG – – ILE RPG
Ruby Ruby 1.8 Ruby 1.8 –
Tcl Tcl 8.3.2 和 8.4.4 Tcl 8.3.2 和 8.4.4 –
–
嵌 入 系 统 上 的 PDFlib 应 当 指 出 , 在 嵌 入 系 统 上 也 可 以 使 用 PDFlib, 并 且 PDFlib 已 被 移 植
到 Windows CE、QNX 和 EPOC 环 境 以 及 自 定 义 嵌 入 系 统 中 。 为 了 在 受 限 制 的 环 境 下 使 用 ,
可 以 对 某 些 功 能 进 行 配 置 以 减 少 PDFlib 的 资 源 需 求 。 若 您 对 详 细 信 息 感 兴 趣 , 请 通 过
sales@pdflib.com 与 我 们 联 系 。
2.2 Cobol 绑 定
2.2.1 有 关 Cobol 的 特 别 注 意 事 项
虽 然 用 于 Cobol 的 PDFlib API 函 数 不 可 以 按 照 第 8 章 中 说 明 的 名 称 使 用 , 但 可 以 使 用 缩 写
的 函 数 名 称 。 虽 然 在 此 处 没 有 说 明 相 应 的 缩 写 函 数 名 称 , 但 可 以 在 单 独 的 交 叉 引 用 列 表
(xref.txt) 中 找 到 它 们 。 例 如 , 必 须 使 用 缩 写 形 式 PDLODFNT 来 代 替 PDF_load_font( )。
2.1 概 述 19

将 用 Cobol 编 写 的 PDFlib 客 户 端 静 态 地 链 接 到 PDFLBCOB 对 象 。 此 对 象 然 后 动 态 地 加
载 PDLBDLCB 加 载 模 块 (DLL), 该 模 块 又 将 在 首 次 调 用 PDNEW ( 对 应 于 PDF_new( )) 时 动
态 加 载 PDFlib 加 载 模 块 (DLL)。 新 近 分 配 的 PDFlib 内 部 结 构 的 实 例 句 柄 存 储 在 P 参 数 中 , 随
后 的 每 个 调 用 都 必 须 提 供 该 参 数 。
PDLBDLCB 加 载 模 块 提 供 8 字 符 Cobol 函 数 与 核 心 PDFlib 例 程 之 间 的 接 口 。PDLBDLCB
加 载 模 块 还 提 供 PDFlib 的 异 步 异 常 处 理 与 Cobol 预 期 的 整 体 式 ( 检 查 每 个 函 数 的 返 回 代
码 ) 方 法 之 间 的 映 射 。
注 : 必 须 通 过 STEPLIB 使 得 PDLBDLCB 和 PDFLIB 可 用 于 COBOL 程 序 。
数 据 类 型 PDFlib API 参 考 中 使 用 的 数 据 类 型 必 须 如 下 例 所 示 映 射 到 Cobol 数 据 类 型
(hello 示 例 中 的 部 分 映 射 ):
05 PDFLIB-A4-WIDTH USAGE COMP-1 VALUE 5.95E+2. // float
05 WS-INT PIC S9(9) BINARY. // int
05 WS-FLOAT COMP-1. // float
05 WS-STRING PIC X(128). // const char *
05 P PIC S9(9) BINARY. // long *
05 RETURN-RC PIC S9(9) BINARY. // int *
所 有 将 传 递 给 PDFlib API 的 Cobol 字 符 串 应 为 预 期 的 LOW-VALUES (NULL) 终 结 符 额 外 定
义 多 一 个 字 节 。
返 回 值 通 过 引 用 来 传 递 的 附 加 参 数 ret 将 提 供 PDFlib API 函 数 的 返 回 值 。 它 将 被 赋 予 相 应
的 函 数 调 用 返 回 值 。 返 回 值 为 零 意 味 着 该 函 数 调 用 正 常 执 行 ; 返 回 值 为 其 他 值 则 表 示 一 个
错 误 , 无 法 继 续 生 成 PDF。
对 于 没 有 返 回 值 的 函 数 ( 返 回 类 型 为 void 的 C 函 数 ) 将 不 使 用 此 附 加 参 数 。
错 误 处 理 PDFlib 异 常 处 理 在 Cobol 语 言 绑 定 中 不 适 宜 。 取 而 代 之 , 在 Cobol 语 言 绑 定 中
所 有 API 函 数 都 支 持 一 个 携 带 错 误 信 号 的 (rc) 参 数 。 rc 参 数 按 引 用 传 递 , 并 将 用 来 报 告 问
题 。 若 它 的 值 为 非 零 意 味 着 函 数 调 用 失 败 。
20 第 2 章 : PDFlib 语 言 绑 定

2.2.2 用 Cobol 编 写 的 “Hello world” 示 例
下 面 的 示 例 演 示 一 个 针 对 PDFlib 进 行 链 接 的 简 单 Cobol 程 序 。 请 注 意 , 示 例 中 不 执 行 任 何
错 误 检 查 :
IDENTIFICATION DIVISION.
PROGRAM-ID. HELLO.
ENVIRONMENT DIVISION.
DATA DIVISION.
WORKING-STORAGE SECTION.
01 PDFLIB-PAGE-SIZE-CONSTANTS.
05 PDFLIB-A4-WIDTH USAGE COMP-1 VALUE 5.95E+2.
05 PDFLIB-A4-HEIGHT USAGE COMP-1 VALUE 8.42E+2.
01 PDFLIB-CALL-AREA.
05 P PIC S9(9) BINARY.
05 RC PIC S9(9) BINARY.
05 PDFLIB-RETURN-LONG PIC S9(9) BINARY.
05 PDFLIB-RETURN-CHAR PIC X(64) VALUE SPACES.
05 PDFLIB-ERR-STRING PIC X(128).
01 WS-WORK-FIELDS.
05 WS-INT PIC S9(9) BINARY.
05 WS-FONT PIC S9(9) BINARY.
05 WS-FLOAT COMP-1.
05 WS-FLOAT2 COMP-1.
05 WS-STRING PIC X(128).
05 WS-STRING2 PIC X(128).
05 WS-NULL PIC X(1) VALUE LOW-VALUES.
PROCEDURE DIVISION.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* CREATE A PDF OBJECT *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
CALL "PDNEW" USING P,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* OPEN NEW PDF DOCUMENT *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
MOVE 0 TO WS-INT.
STRING Z'HELLO.PDF'
DELIMITED BY SIZE INTO WS-STRING.
CALL "PDBEGDOC" USING P,
WS-STRING,
WS-INT,
WS-NULL,
PDFLIB-RETURN-LONG,
RC.
IF PDFLIB-RETURN-LONG = -1
CALL "PDERRMSG" USING P,
PDFLIB-ERR-STRING,
RC
DISPLAY PDFLIB-ERR-STRING
2.2 Cobol 绑 定 21

MOVE +8 TO RETURN-CODE
GOBACK.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* SET PDF INFORMATION *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
STRING Z'Creator'
DELIMITED BY SIZE INTO WS-STRING.
STRING Z'Hello.cbl'
DELIMITED BY SIZE INTO WS-STRING2.
CALL "PDSETINF" USING P,
WS-STRING,
WS-STRING2,
RC.
STRING Z'Author'
DELIMITED BY SIZE INTO WS-STRING.
STRING Z'Thomas Merz'
DELIMITED BY SIZE INTO WS-STRING2.
CALL "PDSETINF" USING P,
WS-STRING
WS-STRING2,
RC.
STRING Z'Title'
DELIMITED BY SIZE INTO WS-STRING.
STRING Z'Hello, world (COBOL)!'
DELIMITED BY SIZE INTO WS-STRING2.
CALL "PDSETINF" USING P,
WS-STRING
WS-STRING2,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* BEGIN A NEW PAGE *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
CALL "PDBEGPAG" USING P,
PDFLIB-A4-WIDTH,
PDFLIB-A4-HEIGHT,
WS-NULL,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* LOAD & SET THE CURRENT FONT *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
MOVE 0 TO WS-INT.
STRING Z'Helvetica-Bold'
DELIMITED BY SIZE INTO WS-STRING.
STRING Z'ebcdic'
DELIMITED BY SIZE INTO WS-STRING2.
CALL "PDLODFNT" USING P,
WS-STRING
WS-INT,
WS-STRING2,
WS-NULL,
PDFLIB-RETURN-LONG,
22 第 2 章 : PDFlib 语 言 绑 定

RC.
MOVE PDFLIB-RETURN-LONG
TO WS-FONT.
MOVE 24 TO WS-FLOAT.
CALL "PDSETFNT" USING P,
WS-FONT,
WS-FLOAT,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* WRITE TO THE CURRENT PAGE OF THE PDF DOCUMENT *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
MOVE 50 TO WS-FLOAT.
MOVE 700 TO WS-FLOAT2.
CALL "PDSETTP" USING P,
WS-FLOAT,
WS-FLOAT2,
RC.
STRING Z'Hello, World!'
DELIMITED BY SIZE INTO WS-STRING.
CALL "PDSHOW" USING P,
WS-STRING,
RC.
STRING Z'(says COBOL)'
DELIMITED BY SIZE INTO WS-STRING.
CALL "PDCONT" USING P,
WS-STRING,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* END THIS PAGE *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
CALL "PDENDPAG" USING P,
WS-NULL,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* END THE PDF DOCUMENT *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
CALL "PDENDDOC" USING P,
WS-NULL,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* DELETE THE PDF OBJECT *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
CALL "PDDELETE" USING P,
RC.
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* END THE PROGRAM *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
MOVE ZERO
TO RETURN-CODE.
GOBACK.
END PROGRAM HELLO.
2.2 Cobol 绑 定 23

2.3 COM 绑 定
( 只 有 COM/.NET/REAL 基 本 版 的 PDFlib 手 册 中 包 括 此 小 节 。)
2.4 C 绑 定
2.4.1 有 关 C 的 可 用 性 和 特 别 注 意 事 项
PDFlib 自 身 是 用 ANSI C 语 言 编 写 的 。 为 了 使 用 PDFlib C 绑 定 , 您 可 以 使 用 静 态 或 共 享 库
(Windows 和 MVS 上 的 DLL), 并 且 您 需 要 在 PDFlib 客 户 端 源 模 块 中 包 含 带 有 pdflib.h 的
PDFlib 核 心 文 件 。 另 外 , 可 以 使 用 pdflibdl.h 在 运 行 时 动 态 加 载 PDFlib DLL( 请 参 见 第 25 页
上 的 第 2.4.3 节 “ 使 用 PDFlib 作 为 在 运 行 时 加 载 的 DLL”)。
2.4.2 用 C 编 写 的 “Hello world” 示 例
下 面 的 示 例 演 示 了 一 个 针 对 静 态 或 共 享 / 动 态 PDFlib 库 进 行 链 接 的 简 单 C 程 序 :
#include
#include
#include "pdflib.h"
int
main(void)
{
PDF *p;
int font;
if ((p = PDF_new()) == (PDF *) 0)
{
printf("Couldn't create PDFlib object (out of memory)!\n");
return(2);
}
PDF_TRY(p) {
if (PDF_begin_document(p, "hello.pdf", 0, "") == -1) {
printf("Error: %s\n", PDF_get_errmsg(p));
return(2);
}
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, "");
/* Change "host" encoding to "winansi" or whatever you need! */
font = PDF_load_font(p, "Helvetica-Bold", 0, "host", "");
PDF_setfont(p, font, 24);
PDF_set_text_pos(p, 50, 700);
PDF_show(p, "Hello, world!");
PDF_continue_text(p, "(says C)");
PDF_end_page_ext(p, "");
PDF_end_document(p, "");
24 第 2 章 : PDFlib 语 言 绑 定

}
PDF_CATCH(p) {
printf("PDFlib exception occurred in hello sample:\n");
printf("[%d] %s: %s\n",
PDF_get_errnum(p), PDF_get_apiname(p), PDF_get_errmsg(p));
PDF_delete(p);
return(2);
}
PDF_delete(p);
}
return 0;
2.4.3 使 用 PDFlib 作 为 在 运 行 时 加 载 的 DLL
尽 管 大 多 数 客 户 端 使 用 PDFlib 作 为 静 态 绑 定 库 或 作 为 在 链 接 时 绑 定 的 动 态 库 , 但 您 还 可 以
在 运 行 时 加 载 PDFlib DLL 并 动 态 获 取 指 向 所 有 API 函 数 的 指 针 。 对 于 仅 按 需 加 载 PDFlib
DLL 和 MVS ( 通 常 在 运 行 时 作 为 DLL 加 载 库 而 不 显 式 针 对 PDFlib 进 行 链 接 ), 这 一 点 特 别
有 用 。 PDFlib 支 持 一 种 方 便 此 动 态 用 法 的 特 殊 机 制 。 此 特 殊 机 制 按 照 下 面 的 规 则 工 作 :
> 包 括 pdflibdl.h 而 不 包 括 pdflib.h。
> 使 用 PDF_new_dl( ) 和 PDF_delete_dl( ) 而 不 使 用 PDF_new( ) 和 PDF_delete( )。
> 使 用 PDF_TRY_DL( ) 和 PDF_CATCH_DL( ) 而 不 使 用 PDF_TRY( ) 和 PDF_CATCH( )。
> 使 用 所 有 其 他 PDFlib 调 用 的 函 数 指 针 。
> 禁 止 使 用 PDF_get_opaque( )。
> 编 译 辅 助 模 块 pdflibdl.c 并 针 对 该 模 块 链 接 应 用 程 序 。
注 : 仅 在 选 定 的 平 台 上 支 持 运 行 时 加 载 PDFlib DLL。
下 面 的 示 例 使 用 此 技 术 在 运 行 时 加 载 PDFlib DLL:
#include
#include
#include "pdflibdl.h"
int
main(void)
{
PDF *p;
int font;
PDFlib_api *PDFlib;
/* load the PDFlib dynamic library and create a new PDFlib object*/
if ((PDFlib = PDF_new_dl(&p)) == (PDFlib_api *) NULL)
{
printf("Couldn't create PDFlib object (DLL not found?)\n");
return(2);
}
PDF_TRY_DL(PDFlib, p) {
if (PDFlib->PDF_begin_document(p, "hellodl.pdf", 0, "") == -1) {
printf("Error: %s\n", PDFlib->PDF_get_errmsg(p));
return(2);
}
2.4 C 绑 定 25

PDFlib->PDF_set_info(p, "Creator", "hello.c");
PDFlib->PDF_set_info(p, "Author", "Thomas Merz");
PDFlib->PDF_set_info(p, "Title", "Hello, world (C DLL)!");
PDFlib->PDF_begin_page_ext(p, a4_width, a4_height, "");
/* Change "host" encoding to "winansi" or whatever you need! */
font = PDFlib->PDF_load_font(p, "Helvetica-Bold", 0, "host", "");
PDFlib->PDF_setfont(p, font, 24);
PDFlib->PDF_set_text_pos(p, 50, 700);
PDFlib->PDF_show(p, "Hello, world!");
PDFlib->PDF_continue_text(p, "(says C DLL)");
PDFlib->PDF_end_page_ext(p, "");
}
PDFlib->PDF_end_document(p, "");
PDF_CATCH_DL(PDFlib, p) {
printf("PDFlib exception occurred in hellodl sample:\n");
printf("[%d] %s: %s\n",
PDFlib->PDF_get_errnum(p), PDFlib->PDF_get_apiname(p),
PDFlib->PDF_get_errmsg(p));
PDF_delete_dl(PDFlib, p);
return(2);
}
/* delete the PDFlib object and unload the library */
PDF_delete_dl(PDFlib, p);
}
return 0;
2.4.4 C 的 错 误 处 理
PDFlib 支 持 使 用 try/catch 子 句 的 结 构 化 异 常 处 理 。 这 使 得 C 和 C++ 客 户 端 不 但 可 以 捕 捉 由
PDFlib 引 发 的 异 常 , 还 可 以 用 适 当 的 方 式 对 异 常 做 出 反 应 。 在 catch 子 句 中 , 客 户 端 将 可 以
访 问 一 个 字 符 串 , 其 中 描 述 了 问 题 的 本 质 、 唯 一 的 异 常 号 和 引 发 异 常 的 PDFlib API 函 数 的 名
称 。 带 有 异 常 处 理 功 能 的 PDFlib C 客 户 端 程 序 的 常 规 结 构 如 下 所 示 :
PDF_TRY(p)
{
...some PDFlib instructions...
}
PDF_CATCH(p)
{
printf("PDFlib exception occurred in hello sample:\n");
printf("[%d] %s: %s\n",
PDF_get_errnum(p), PDF_get_apiname(p), PDF_get_errmsg(p));
PDF_delete(p);
return(2);
}
PDF_delete(p);
26 第 2 章 : PDFlib 语 言 绑 定

注 : PDF_TRY/PDF_CATCH 是 用 复 杂 的 预 处 理 器 宏 实 现 的 。 若 不 小 心 忽 略 了 其 中 一 个 , 将 导 致 一 些
可 能 让 人 难 以 理 解 的 编 译 器 错 误 消 息 。 确 保 完 全 按 照 如 上 所 示 的 形 式 使 用 这 些 宏 , 在 TRY 子
句 和 CATCH 子 句 (PDF_CATCH( ) 除 外 ) 之 间 不 要 添 加 任 何 代 码 。
如 果 您 想 在 try 子 句 结 束 之 前 离 开 该 子 句 , 则 必 须 先 使 用 PDF_EXIT_TRY( ) 宏 通 知 异 常 机
制 。 在 此 宏 与 try 块 的 结 尾 之 间 可 以 不 调 用 任 何 其 他 PDFlib 函 数 。
catch 子 句 的 一 个 重 要 任 务 是 通 过 使 用 PDF_delete( ) 和 指 向 PDFlib 对 象 的 指 针 清 理 PDFlib
内 部 变 量 。 必 要 时 PDF_delete( ) 也 将 关 闭 输 出 文 件 。 除 了 PDF_delete( )、 PDF_get_opaque( )
以 及 异 常 函 数 PDF_get_errnum( )、PDF_get_apiname( ) 和 PDF_get_errmsg( ), 其 余 PDFlib 函
数 不 得 在 客 户 端 错 误 处 理 程 序 内 调 用 。 发 生 严 重 异 常 后 ,PDF 文 档 将 不 能 使 用 , 并 将 保 留 为 未
完 成 和 不 一 致 状 态 。 很 显 然 , 异 常 发 生 时 的 合 适 的 操 作 完 全 是 因 应 用 程 序 而 异 的 。
对 于 未 捕 捉 异 常 的 C 和 C++ 客 户 端 , 针 对 异 常 的 默 认 操 作 是 在 标 准 错 误 通 道 上 发 出 适 当
的 消 息 , 并 在 发 生 严 重 错 误 时 退 出 。PDF 输 出 文 件 将 保 留 为 未 完 成 状 态 ! 由 于 默 认 操 作 可 能
无 法 满 足 对 库 的 例 行 要 求 , 因 此 对 于 重 大 的 PDFlib 项 目 , 强 烈 建 议 利 用 PDFlib 的 异 常 处 理
功 能 。 例 如 , 用 户 定 义 的 catch 子 句 可 能 在 GUI 对 话 框 中 显 示 错 误 消 息 , 并 获 取 其 他 度 量 值
而 不 是 中 止 项 目 。
旧 式 错 误 处 理 程 序 PDFlib 除 了 支 持 结 构 化 异 常 处 理 之 外 , 还 支 持 客 户 端 提 供 的 回 调 函 数
的 概 念 ( 回 调 函 数 在 异 常 发 生 时 进 行 调 用 )。 不 过 , 此 方 法 已 过 时 , 之 所 以 提 供 支 持 只 不 过
是 为 了 兼 容 性 。 在 PDF_TRY 部 分 将 忽 略 错 误 处 理 程 序 。
2.4.5 用 C 进 行 内 存 管 理
为 了 获 得 最 大 限 度 的 灵 活 性 , PDFlib 的 内 部 内 存 管 理 例 程 ( 基 于 标 准 C malloc/free) 可 以
由 客 户 端 提 供 的 外 部 程 序 替 换 。 这 些 程 序 将 被 用 于 所 有 PDFlib 内 部 内 存 分 配 或 解 除 分 配 。
可 以 通 过 调 用 PDF_new2( ) 来 安 装 内 存 管 理 例 程 , 并 用 来 代 替 PDFlib 的 内 部 例 程 。 下 面 的 所
有 例 程 必 须 要 么 全 部 提 供 , 要 么 都 不 提 供 :
> 分 配 例 程
> 解 除 分 配 ( 释 放 ) 例 程
> 用 于 扩 大 先 前 已 使 用 分 配 例 程 分 配 的 内 存 块 的 重 新 分 配 例 程 。
可 以 在 第 170 页 上 的 第 8.2 节 “ 常 规 函 数 ” 中 找 到 内 存 例 程 的 签 名 。 虽 然 这 些 例 程 必 须 符 合
标 准 C malloc/free/realloc 语 义 , 但 是 它 们 可 以 选 择 任 意 的 实 现 方 式 。 一 个 指 向 正 被 调 用 的
PDFlib 对 象 的 指 针 将 提 供 给 所 有 例 程 。 此 规 则 唯 一 的 例 外 是 在 第 一 次 调 用 分 配 例 程 时 将 提
供 NULL PDF 指 针 。 因 此 , 客 户 端 提 供 的 内 存 分 配 例 程 必 须 准 备 好 处 理 NULL PDF 指 针 。
使 用 PDF_get_opaque( ) 函 数 , 可 以 从 PDFlib 对 象 检 索 不 透 明 的 应 用 程 序 特 定 指 针 。 不
透 明 指 针 自 身 是 在 PDF_new2( ) 调 用 中 由 客 户 端 提 供 的 。 不 透 明 指 针 对 于 多 线 程 应 用 程 序 很
有 用 。 多 线 程 应 用 程 序 可 能 希 望 在 PDFlib 对 象 中 保 留 一 个 指 向 特 定 于 线 程 或 类 的 数 据 的 指
针 , 以 便 在 内 存 管 理 或 错 误 处 理 中 使 用 。
2.4.6 C 语 言 绑 定 中 的 Unicode
在 文 本 可 能 包 含 嵌 入 的 空 字 符 的 情 况 下 , 必 须 注 意 ,C 语 言 绑 定 的 客 户 端 不 要 使 用 标 准 文 本
输 出 函 数 (PDF_show( )、PDF_show_xy( ) 和 PDF_continue_text( ))。 在 上 述 情 况 下 , 必 须 使
用 替 代 函 数 PDF_show2( ) 等 , 并 且 必 须 分 别 提 供 字 符 串 的 长 度 。 由 于 PDFlib 语 言 包 装 首 先
会 在 内 部 调 用 PDF_show2( ) 等 , 因 此 以 上 情 况 不 会 影 响 到 所 有 其 他 的 语 言 绑 定 。
2.4 C 绑 定 27

2.5 C++ 绑 定
2.5.1 有 关 C++ 的 可 用 性 和 特 别 注 意 事 项
对 于 PDFlib 客 户 端 , 除 了 提 供 pdflib.h C 头 文 件 之 外 , 还 提 供 C++ 的 面 向 对 象 的 包 装 。 这 就
需 要 pdflib.hpp 头 文 件 ( 它 又 包 含 pdflib.h)。 相 应 的 pdflib.cpp 模 块 应 针 对 应 用 程 序 进 行 链
接 , 而 该 应 用 程 序 又 应 针 对 通 用 PDFlib C 库 进 行 链 接 。
通 过 使 用 C++ 对 象 包 装 , 可 用 一 个 更 加 面 向 对 象 的 方 法 替 代 所 有 PDFlib 函 数 名 称 中 的
PDF_ 前 缀 。 在 阅 读 本 手 册 中 用 C 风 格 记 录 的 PDFlib API 说 明 时 , 请 紧 记 这 一 点 。
2.5.2 用 C++ 编 写 的 “Hello world” 示 例
#include
#include "pdflib.hpp"
int
main(void)
{
try {
int font;
PDFlib p;
if (p.begin_document("hello.pdf", "") == -1) {
cerr

2.5.3 C++ 的 错 误 处 理
出 错 时 , PDFlib API 函 数 将 引 发 C++ 异 常 。 必 须 使 用 C++ try/catch 子 句 在 客 户 端 代 码 中 捕
获 这 些 异 常 。 为 了 提 供 扩 展 的 错 误 信 息 ,PDFlib 类 提 供 了 一 个 公 共 PDFlib::Exception 类 , 该
类 公 开 了 用 来 检 索 详 细 的 错 误 信 息 、 异 常 号 和 引 发 异 常 的 PDFlib API 函 数 的 名 称 的 方 法 。
由 PDFlib 例 程 引 发 的 本 地 C++ 异 常 将 按 预 期 的 方 式 运 行 。 以 下 代 码 片 段 将 捕 获 由
PDFlib 引 发 的 异 常 :
try {
...some PDFlib instructions...
catch (PDFlib::Exception &ex) {
cerr

com.pdflib.pdflib
此 包 在 pdflib.jar 文 件 中 提 供 , 并 且 包 含 一 个 名 为 pdflib 的 类 。 利 用 PDFlib Lite 分 发 中 提 供
的 源 文 件 , 您 可 以 使 用 javadoc 实 用 工 具 生 成 HTML 简 化 版 本 的 PDFlib API 参 考 ( 本 手
册 ), 这 是 因 为 PDFlib 类 包 含 必 要 的 javadoc 注 释 。 有 关 在 特 定 Java 环 境 中 使 用 PDFlib 的
注 释 和 限 制 , 可 以 在 与 之 分 发 的 文 本 文 件 中 找 到 。
为 了 将 此 包 提 供 给 应 用 程 序 , 您 必 须 将 pdflib.jar 添 加 到 CLASSPATH 环 境 变 量 中 , 并 在 编
译 和 运 行 时 加 入 -classpath pdflib.jar 选 项 , 或 在 Java IDE 中 执 行 等 同 的 步 骤 。 您 可 以 在 JDK
中 通 过 对 java.library.path 属 性 赋 值 , 从 而 Java VM 可 在 指 定 的 目 录 中 搜 索 本 地 库 , 例 如 :
java -Djava.library.path=. pdfclock
您 可 以 按 照 如 下 方 式 检 查 此 属 性 的 值 :
System.out.println(System.getProperty("java.library.path"));
另 外 , 必 须 执 行 下 面 的 与 平 台 相 关 的 步 骤 :
Unix 必 须 将 libpdf_java.so 库 ( 位 于 Mac OS X:libpdf_java.jnilib 上 ) 置 于 某 一 默 认 存 放 共
享 库 的 目 录 , 或 某 一 合 适 的 配 置 目 录 中 。
Windows 必 须 将 pdf_java.dll 库 置 于 Windows 系 统 目 录 中 , 或 置 于 PATH 环 境 变 量 列 出
的 某 一 目 录 中 。
PDFlib servlet 和 Java 应 用 程 序 服 务 器 PDFlib 完 全 适 合 于 服 务 器 端 Java 应 用 程 序 ( 特 别
是 servlet)。 PDFlib 分 发 包 含 许 多 演 示 基 本 用 法 的 PDFlib Java servlet 示 例 。 将 PDFlib 用
于 特 定 的 servlet 引 擎 时 , 必 须 考 虑 以 下 配 置 问 题 :
> servlet 引 擎 从 中 查 找 本 地 库 的 目 录 会 因 厂 商 而 不 同 。 常 见 的 候 选 位 置 是 系 统 目 录 、 相 应
Java VM 的 特 定 目 录 和 servlet 引 擎 的 本 地 目 录 。 请 查 阅 由 servlet 引 擎 厂 商 提 供 的 文 档 。
> Servlet 通 常 由 一 个 特 殊 的 类 加 载 程 序 进 行 加 载 , 该 加 载 程 序 可 能 受 限 制 或 使 用 专 用 的
classpath。 有 一 些 servlet 引 擎 需 要 定 义 一 个 专 用 引 擎 classpath 以 确 保 找 到 PDFlib 包 。
有 关 将 PDFlib 用 于 特 定 的 servlet 引 擎 和 Java 应 用 程 序 服 务 器 的 更 加 详 细 的 说 明 , 可 以 在
PDFlib 分 发 的 附 加 文 档 中 找 到 。
注 : 由 于 EJB (Enterprise Java Bean) 规 范 不 允 许 使 用 本 地 库 , 因 此 不 能 在 EJB 内 部 使 用 PDFlib。
2.6.2 用 Java 编 写 的 “Hello world” 示 例
import java.io.*;
import com.pdflib.pdflib;
import com.pdflib.PDFlibException;
public class hello
{
public static void main (String argv[])
{
int font;
pdflib p = null;
try{
p = new pdflib();
if (p.begin_document("hello.pdf", "") == -1) {
throw new Exception("Error: " + p.get_errmsg());
30 第 2 章 : PDFlib 语 言 绑 定

}
p.set_info("Creator", "hello.java");
p.set_info("Author", "Thomas Merz");
p.set_info("Title", "Hello world (Java)!");
p.begin_page_ext(595, 842, "");
font = p.load_font("Helvetica-Bold", "unicode", "");
p.setfont(font, 18);
p.set_text_pos(50, 700);
p.show("Hello world!");
p.continue_text("(says Java)");
p.end_page_ext("");
p.end_document("");
}
}
} catch (PDFlibException e) {
System.err.print("PDFlib exception occurred in hello sample:\n");
System.err.print("[" + e.get_errnum() + "] " + e.get_apiname() +
": " + e.get_errmsg() + "\n");
} catch (Exception e) {
System.err.println(e.getMessage());
} finally {
if (p != null) {
p.delete();
}
}
2.6.3 Java 的 错 误 处 理
Java 绑 定 安 装 一 个 特 殊 的 错 误 处 理 程 序 , 该 程 序 会 将 PDFlib 错 误 转 换 成 本 机 Java 异 常 。 发
生 异 常 时 , PDFlib 将 引 发 本 地 Java 异 常 通 过 以 下 类 :
PDFlibException
可 以 用 常 见 的 try/catch 技 术 处 理 Java 异 常 :
try {
...some PDFlib instructions...
} catch (PDFlibException e) {
System.err.print("PDFlib exception occurred in hello sample:\n");
System.err.print("[" + e.get_errnum() + "] " + e.get_apiname() +
": " + e.get_errmsg() + "\n");
} catch (Exception e) {
System.err.println(e.getMessage());
} finally {
if (p != null) {
p.delete(); /* delete the PDFlib object */
2.6 Java 绑 定 31

}
}
由 于 PDFlib 声 明 适 当 的 throws 子 句 , 因 此 客 户 端 代 码 必 须 捕 获 所 有 可 能 发 生 的 PDFlib 异
常 , 或 自 身 声 明 这 些 异 常 。
2.7 .NET 绑 定
( 只 有 COM/.NET/REAL 基 本 版 的 PDFlib 手 册 中 包 括 此 小 节 。)
2.8 Perl 绑 定
Perl 1 支 持 通 过 本 地 C 库 扩 展 语 言 解 释 程 序 的 机 制 。Perl 的 PDFlib 包 装 由 一 个 C 包 装 文 件 和
一 个 Perl 包 模 块 组 成 。 在 一 些 包 文 件 的 帮 助 下 , C 模 块 用 于 构 建 Perl 解 释 程 序 在 运 行 时 加
载 的 共 享 库 。 Perl 脚 本 通 过 use 语 句 引 用 共 享 库 模 块 。
2.8.1 安 装 PDFlib Perl 版 本
Perl 扩 展 机 制 通 过 DynaLoader 模 块 在 运 行 时 加 载 共 享 库 。 在 对 Perl 可 执 行 文 件 进 行 编 译
时 , 必 须 使 其 支 持 共 享 库 ( 对 大 多 数 Perl 配 置 都 是 这 样 )。
为 了 使 PDFlib 绑 定 起 作 用 , Perl 解 释 程 序 必 须 访 问 PDFlib Perl 包 装 和 模 块 文 件
pdflib_pl.pm。 除 了 下 面 描 述 的 特 定 于 平 台 的 方 法 之 外 , 您 还 可 以 使 用 -I 命 令 行 选 项 向
Perl 的 @INC 模 块 搜 索 路 径 中 添 加 目 录 :
perl -I/path/to/pdflib hello.pl
Unix Perl 将 在 当 前 目 录 下 或 由 以 下 Perl 命 令 输 出 的 目 录 下 搜 索 pdflib_pl.so( 位 于 Mac OS
X:pdflib_pl.dylib 上 ) 和 pdflib_pl.pm:
perl -e 'use Config; print $Config{sitearchexp};'
Perl 还 将 搜 索 子 目 录 auto/pdflib_pl。 以 上 命 令 的 典 型 输 出 如 下 所 示 :
/usr/lib/perl5/site_perl/5.8/i686-linux
Windows PDFlib 支 持 Windows ActivePerl ( 又 称 Perl 5 的 ActiveState 端 口 ) 2 将 在 当 前
目 录 下 或 由 以 下 Perl 命 令 输 出 的 目 录 下 搜 索 pdflib_pl.dll 和 pdflib_pl.pm :
perl -e "use Config; print $Config{sitearchexp};"
以 上 命 令 的 典 型 输 出 如 下 所 示 :
C:\Program Files\Perl5.8\site\lib
2.8.2 用 Perl 编 写 的 “Hello world” 示 例
use pdflib_pl 6.0;
$p = PDF_new();
eval {
if (PDF_begin_document($p, "hello.pdf", "") == -1) {
1. 请 参 见 www.perl.com
2. 请 参 见 www.activestate.com
32 第 2 章 : PDFlib 语 言 绑 定

}
printf("Error: %s\n", PDF_get_errmsg($p));
exit;
PDF_set_info($p, "Creator", "hello.pl");
PDF_set_info($p, "Author", "Thomas Merz");
PDF_set_info($p, "Title", "Hello world (Perl)!");
PDF_begin_page_ext($p, 595, 842, "");
$font = PDF_load_font($p, "Helvetica-Bold", "winansi", "");
PDF_setfont($p, $font, 24.0);
PDF_set_text_pos($p, 50, 700);
PDF_show($p, "Hello world!");
PDF_continue_text($p, "(says Perl)");
PDF_end_page_ext($p, "");
};
PDF_end_document($p, "");
if ($@) {
printf("hello: PDFlib Exception occurred:\n");
printf(" $@\n");
exit;
}
PDF_delete($p);
2.8.3 Perl 的 错 误 处 理
Perl 绑 定 安 装 一 个 特 殊 的 错 误 处 理 程 序 , 该 程 序 会 将 PDFlib 错 误 转 换 成 本 地 Perl 异 常 。 可
以 通 过 使 用 适 当 的 语 言 构 造 ( 即 将 关 键 部 分 括 起 来 ) 处 理 Perl 异 常 :
eval {
...some PDFlib instructions...
};
die "Exception caught" if $@;
2.9 PHP 绑 定
2.9.1 安 装 PDFlib PHP 版 本
1
有 关 将 PDFlib 用 于 PHP 的 的 各 种 风 格 和 选 项 的 详 细 信 息 , 包 括 有 关 是 否 使 用 PHP 的 可 加
载 PDFlib 模 块 的 问 题 , 都 可 以 在 PDFlib-in-PHP-HowTo.pdf 文 档 中 找 到 。 此 文 档 包 含 在 分 发
包 中 , 也 可 以 在 PDFlib 网 站 上 找 到 。
必 须 对 PHP 进 行 配 置 , 以 便 让 其 了 解 外 部 的 PDFlib 库 。 您 有 两 种 选 择 :
> 在 php.ini 中 添 加 以 下 行 之 一 :
extension=libpdf_php.so
extension=libpdf_php.dll
; for Unix
; for Windows
1. 请 参 见 www.php.net
2.9 PHP 绑 定 33

对 于 Unix, PHP 将 在 由 php.ini 中 的 extension_dir 变 量 指 定 的 目 录 下 搜 索 库 ; 对 于
Windows, PHP 除 在 extension_dir 变 量 指 定 的 目 录 下 搜 索 库 外 , 还 在 标 准 系 统 目 录 下
搜 索 库 。 您 可 以 使 用 下 面 的 单 行 PHP 脚 本 测 试 已 安 装 哪 一 个 版 本 的 PHP PDFlib 绑 定 :
这 将 显 示 有 关 当 前 PHP 配 置 的 很 长 的 信 息 页 。 在 此 页 上 , 检 查 标 题 为 pdf 的 部 分 。 若 这
一 部 分 包 含 PDFlib GmbH Binary Version ( 以 及 PDFlib 版 本 号 ), 则 表 明 您 正 在 使 用 受
支 持 的 新 的 PDFlib 包 装 。 而 不 受 支 持 的 旧 包 装 将 显 示 PDFlib GmbH Version。
> 在 您 的 脚 本 的 开 头 处 添 加 以 下 行 之 一 以 在 运 行 时 加 载 PDFlib:
dl("libpdf_php.so");
dl("libpdf_php.dll");
# for Unix
# for Windows
PHP 5 功 能 PDFlib 利 用 以 下 PHP 5 中 的 新 功 能 :
> 新 的 对 象 模 型 : 将 PDFlib 函 数 封 装 到 PDFlib 对 象 内 。
> 异 常 :PDFlib 异 常 将 作 为 PHP 5 异 常 进 行 传 播 , 并 且 可 以 使 用 常 见 try/catch 技 术 捕 获 。
新 式 异 常 处 理 可 以 与 新 的 面 向 对 象 的 方 法 以 及 旧 的 API 函 数 一 同 使 用 。
以 下 将 更 具 体 地 介 绍 这 些 PHP 5 功 能 。
PHP 中 经 修 改 的 PDFlib 函 数 错 误 返 回 值 由 于 PHP 遵 从 函 数 内 发 生 错 误 时 返 回 值 为 0
(FALSE) 的 约 定 , 因 此 已 对 所 有 PDFlib 函 数 进 行 了 调 整 , 使 之 在 出 现 错 误 时 返 回 0 而 不 是 -1。
此 差 异 已 经 在 第 8 章 中 的 函 数 说 明 中 注 明 。 不 过 , 在 阅 读 第 45 页 上 的 第 3 节 “PDFlib 编 程 ”
中 的 代 码 片 段 示 例 时 要 多 加 注 意 , 因 为 这 些 示 例 遵 从 的 是 常 见 的 PDFlib 约 定 , 即 在 出 现 错 误
时 返 回 -1。
PHP 中 的 文 件 名 处 理 在 PHP 的 Unix 和 Windows 版 本 中 , 对 于 PDF、 图 像 、 字 体 和 其 他
磁 盘 文 件 的 未 经 限 定 的 文 件 名 称 ( 没 有 任 何 路 径 部 分 ) 和 相 对 文 件 名 称 的 处 理 方 式 将 有 所
不 同 :
> Unix 系 统 上 的 PHP 将 在 脚 本 所 在 的 目 录 中 查 找 没 有 任 何 路 径 部 分 的 文 件 。
> Windows 上 的 PHP 将 只 在 PHP DLL 所 在 的 目 录 中 查 找 没 有 任 何 路 径 部 分 的 文 件 。
为 了 提 供 与 平 台 无 关 的 文 件 名 称 处 理 , 强 烈 建 议 使 用 PDFlib 的 SearchPath 实 用 工 具 ( 请 参
见 第 49 页 上 的 第 3.1.5 节 “ 资 源 配 置 和 文 件 搜 索 ”)。
2.9.2 用 PHP 编 写 的 “Hello world” 示 例
PHP 4 的 示 例 以 下 示 例 使 用 PHP 4:

$font = PDF_load_font($p, "Helvetica-Bold", "winansi", "");
PDF_setfont($p, $font, 24.0);
PDF_set_text_pos($p, 50, 700);
PDF_show($p, "Hello world!");
PDF_continue_text($p, "(says PHP)");
PDF_end_page_ext($p, "");
PDF_end_document($p, "");
$buf = PDF_get_buffer($p);
$len = strlen($buf);
header("Content-type: application/pdf");
header("Content-Length: $len");
header("Content-Disposition: inline; filename=hello.pdf");
print $buf;
PDF_delete($p);
?>
PHP 5 的 示 例 以 下 示 例 使 用 PHP 5 中 提 供 的 新 的 异 常 处 理 和 对 象 封 装 功 能 :

die("PDFlib exception occurred in hello sample:\n" .
"[" . $e->get_errnum() . "] " . $e->get_apiname() . ": " .
$e->get_errmsg() . "\n");
}
catch (Exception $e) {
die($e);
}
$p = 0;
?>
2.9.3 PHP 的 错 误 处 理
利 用 PHP 4 进 行 错 误 处 理 当 出 现 一 个 PDFlib 异 常 时 , 将 引 发 一 个 PHP 异 常 。 由 于 PHP 4
不 支 持 结 构 化 异 常 处 理 , 所 以 无 法 捕 获 异 常 和 进 行 适 当 的 操 作 。 使 用 PDFlib 时 , 不 要 禁 用
PHP 警 告 , 否 则 将 会 遇 到 真 正 的 麻 烦 。
PDFlib 警 告 ( 非 严 重 错 误 ) 将 被 映 射 到 PHP 警 告 , 这 些 警 告 可 以 在 php.ini 中 禁 用 。 另
外 , 如 同 在 任 何 其 他 语 言 绑 定 中 一 样 , 在 运 行 时 可 以 使 用 一 个 PDFlib 函 数 调 用 禁 止 警 告 :
PDF_set_parameter($p, "warning", "false");
用 PHP 5 进 行 异 常 处 理 由 于 PHP 5 支 持 结 构 化 异 常 处 理 , 因 此 PDFlib 异 常 将 作 为 PHP 异
常 进 行 传 播 。 PDFlib 将 引 发 一 个 派 生 自 PHP 的 标 准 Exception 类 的 PDFlibException 类 异
常 。 您 可 以 使 用 标 准 try/catch 技 术 处 理 PDFlib 异 常 :
try {
...some PDFlib instructions...
} catch (PDFlibException $e) {
print "PDFlib exception occurred:\n";
print "[" . $e->get_errnum() . "] " . $e->get_apiname() . ": "
$e->get_errmsg() . "\n";
}
catch (Exception $e) {
print $e;
}
请 注 意 , 无 论 您 使 用 的 是 旧 的 基 于 函 数 的 PDFlib 接 口 还 是 新 的 面 向 对 象 的 PDFlib 接 口 , 都
可 以 使 用 PHP 5 风 格 的 异 常 处 理 。
2.10 Python 绑 定
2.10.1 安 装 PDFlib Python 版 本
Python 1 扩 展 机 制 通 过 在 运 行 时 加 载 共 享 库 的 方 式 工 作 。 为 了 使 PDFlib 绑 定 运 作 , Python
解 释 程 序 必 须 能 够 访 问 PDFlib Python 包 装 :
Unix 将 在 PYTHONPATH 环 境 变 量 中 列 出 的 目 录 中 搜 索 库 pdflib_py.so ( 位 于 Mac OS
X:pdflib_py.dylib 上 )。
Windows 将 在 PYTHONPATH 环 境 变 量 中 列 出 的 目 录 中 搜 索 库 pdflib_py.dll 。
1. 请 参 见 www.python.org
36 第 2 章 : PDFlib 语 言 绑 定

2.10.2 用 Python 编 写 的 “Hello world” 示 例
from sys import *
from pdflib_py import *
p = PDF_new()
if PDF_begin_document(p, "hello.pdf", "") == -1:
print "Error: " + PDF_get_errmsg(p) + "\n"
exit(2)
PDF_set_info(p, "Author", "Thomas Merz")
PDF_set_info(p, "Creator", "hello.py")
PDF_set_info(p, "Title", "Hello world (Python)")
PDF_begin_page_ext(p, 595, 842, "")
font = PDF_load_font(p, "Helvetica-Bold", "winansi", "")
PDF_setfont(p, font, 24)
PDF_set_text_pos(p, 50, 700)
PDF_show(p, "Hello world!")
PDF_continue_text(p, "(says Python)")
PDF_end_page_ext(p, "")
PDF_end_document(p, "")
PDF_delete(p)
2.10.3 Python 的 错 误 处 理
Python 绑 定 安 装 一 个 特 殊 的 错 误 处 理 程 序 , 该 程 序 会 将 PDFlib 错 误 转 换 成 本 地 Python 异
常 。 可 以 用 常 见 的 try/catch 技 术 处 理 Python 异 常 :
try:
...some PDFlib instructions...
except:
print 'Exception caught!'
1
2.11 REALbasic 绑 定
( 只 有 COM/.NET/REAL 基 本 版 的 PDFlib 手 册 中 包 括 此 小 节 。)
2.12 Ruby 绑 定
2.12.1 安 装 PDFlib Ruby 版 本
Ruby 2 扩 展 机 制 是 通 过 在 运 行 时 调 用 共 享 库 实 现 的 。 为 了 使 PDFlib 绑 定 工 作 , Ruby 编 译
器 须 能 访 问 Ruby 的 PDFlib 扩 展 库 。 这 个 库 ( Windows/Linux/Unix: PDFlib.so; Mac OS X:
PDFlib.dylib) 通 常 被 安 装 在 Ruby 本 地 安 装 目 录 的 site_ruby 分 支 下 , 也 就 是 与 以 下 名 字 相 类
似 的 路 径 :
/usr/local/lib/ruby/site_ruby//
1. 请 参 见 www.realbasic.com
2. See www.ruby-lang.org/en
2.11 REALbasic 绑 定 37

除 此 之 外 , Ruby 还 将 在 其 他 目 录 下 搜 索 扩 展 库 。 用 户 可 用 以 下 Ruby 命 令 取 得 搜 索 目 录
列 表 :
ruby -e "puts $:"
这 个 列 表 通 常 都 包 括 当 前 目 录 。 因 此 为 了 测 试 的 方 便 , 用 户 可 以 直 接 将 PDFlib 扩 展 库 和 程
序 放 入 当 前 目 录 。
2.12.2 用 Ruby 编 写 的 “Hello world” 示 例
require 'PDFlib'
begin
p = PDFlib.new
if (p.begin_document("hello.pdf", "") == -1)
raise "Error: " + p.get_errmsg
end
p.set_info("Creator", "hello.rb")
p.set_info("Author", "Thomas Merz")
p.set_info("Title", "Hello world (Ruby)!")
p.begin_page_ext(595, 842, "")
font = p.load_font("Helvetica-Bold", "winansi", "")
p.setfont(font, 24)
p.set_text_pos(50, 700)
p.show("Hello world!")
p.continue_text("(says Ruby)")
p.end_page_ext("")
p.end_document("")
rescue PDFlibException => pe
print "PDFlib exception occurred in hello sample:\n"
print "[" + pe.get_errnum.to_s + "] " + pe.get_apiname + \
": " + pe.get_errmsg + "\n"
rescue Exception => e
print e.backtrace.join("\n") + "\n" + e.to_s
end
2.12.3 Ruby 的 错 误 处 理
Ruby 绑 定 安 装 了 一 个 将 PDFlib 异 常 转 为 Ruby 异 常 的 特 殊 错 误 处 理 器 。 Ruby 异 常 可 通 过
rescue 技 术 来 处 理 :
begin
...some PDFlib instructions...
rescue PDFlibException => pe
print "PDFlib exception occurred in hello sample:\n"
print "[" + pe.get_errnum.to_s + "] " + pe.get_apiname + ": " + pe.get_errmsg + "\n"
38 第 2 章 : PDFlib 语 言 绑 定

2.12.4 Ruby on Rails
Ruby on Rails 1 是 一 个 推 广 Ruby 用 于 Web 开 发 的 开 放 原 码 框 架 。PDFlib 的 Ruby 扩 展 库 可 用
于 Ruby on Rails; 软 件 包 中 将 有 相 应 示 例 。 运 行 PDFlib 的 Ruby on Rails 示 例 , 需 遵 循 下
列 步 骤 :
> 安 装 Ruby
> 安 装 Ruby on Rails
> 安 装 含 有 Ruby on Rails 示 例 的 PDFlib Ruby 软 件 包
> 将 bind/ruby/RubyOnRails 设 为 当 前 目 录 并 启 动 Ruby 网 络 服 务 器 :
ruby script/server
> 将 浏 览 器 指 向 http://localhost:3000
app/controllers/pdflib_controller.rb 是 PDFlib 的 示 例 程 序 。
本 地 PDFlib 安 装 如 果 您 只 打 算 在 Ruby on Rails 中 使 用 PDFlib , 但 不 能 将 其 全 面 安 装 以
被 Ruby 通 用 。 您 可 以 在 Rails 树 目 录 的 vendors 目 录 里 本 地 安 装 PDFlib。 这 特 别 适 用 于 用
户 没 有 安 装 Ruby 扩 展 库 的 通 用 权 限 但 想 在 Rails 里 使 用 PDFlib 的 情 形 。
2.13 RPG 绑 定
PDFlib 提 供 一 个 /copy 模 块 , 其 中 定 义 了 所 有 原 型 和 使 用 嵌 入 的 PDFlib 函 数 编 译 ILE-RPG
程 序 时 必 需 的 一 些 有 用 的 常 量 。
由 于 PDFlib 提 供 的 所 有 函 数 是 用 C 语 言 实 现 的 , 因 此 您 必 须 将 x'00' 添 加 到 已 传 递 给
PDFlib 函 数 的 每 一 个 字 符 串 值 的 结 尾 。 从 PDFlib 返 回 的 所 有 字 符 串 也 将 具 有 终 止 符 x'00'。
2.13.1 为 PDFlib 对 RPG 程 序 进 行 编 译 和 绑 定
若 要 从 RPG 使 用 PDFlib 函 数 , 需 要 经 过 编 译 的 PDFlib 服 务 程 序 。 若 要 在 编 译 时 包 含 PDFlib
定 义 , 则 必 须 在 ILE-RPG 程 序 的 D 规 范 中 指 定 相 应 的 名 称 :
d/copy QRPGLESRC,PDFLIB
若 PDFlib 源 文 件 库 未 在 库 列 表 的 顶 部 , 则 您 还 必 须 指 定 库 :
d/copy PDFsrclib/QRPGLESRC,PDFLIB
在 开 始 编 译 ILE-RPG 程 序 之 前 , 您 必 须 创 建 一 个 绑 定 目 录 , 在 其 中 包 含 PDFlib 附 带 的
PDFLIB 服 务 程 序 。 下 面 的 示 例 假 定 您 要 在 PDFLIB 库 中 创 建 一 个 名 为 PDFLIB 的 绑 定 目 录 :
CRTBNDDIR BNDDIR(PDFLIB/PDFLIB) TEXT('PDFlib Binding Directory')
创 建 绑 定 目 录 后 , 您 需 要 将 PDFLIB 服 务 程 序 添 加 到 该 绑 定 目 录 中 。 下 面 的 示 例 假 定 您 要 将
库 PDFLIB 中 的 服 务 程 序 PDFLIB 添 加 到 先 前 已 创 建 的 绑 定 目 录 中 。
ADDBNDDIRE BNDDIR(PDFLIB/PDFLIB) OBJ((PDFLIB/PDFLIB *SRVPGM))
现 在 您 可 以 使 用 CRTBNDRPG 命 令 ( 或 PDM 中 的 选 项 14) 编 译 程 序 :
CRTBNDRPG PGM(PDFLIB/HELLO) SRCFILE(PDFLIB/QRPGLESRC) SRCMBR(*PGM) DFTACTGRP(*NO)
BNDDIR(PDFLIB/PDFLIB)
1. See www.rubyonrails.org
2.13 RPG 绑 定 39

2.13.2 用 RPG 编 写 的 “Hello world” 示 例
*****************************************************************************************
d/copy QRPGLESRC,PDFLIB
*****************************************************************************************
d p S *
d font s 10i 0
*
d error s 50
d errmsg_p s *
d errmsg s 200 based(errmsg_p)
*
d filename s 256
d fontname s 50
d fontenc s 50
d infokey s 50
d infoval s 200
d text s 200
d n s 1 inz(x'00')
d empty s 1 inz(x'00')
*****************************************************************************************
c clear error
*
* Init on PDFlib
c eval p=pdf_new
c if p=*null
c eval error='Couldn''t create PDFlib object '+
c
'(out of memory)!'
c exsr exit
c
endif
*
* Open new pdf file
c eval filename='hello.pdf'+x'00'
c if PDF_begin_document(p:filename:0:empty) = -1
c exsr geterrmsg
c exsr exit
c
endif
* This is required to avoid problems on Japanese systems
c eval infokey='hypertextencoding'+x'00'
c eval infoval='ebcdic'+x'00'
c callp PDF_set_parameter(p:infokey:infoval)
* Set info "Creator"
c eval infokey='Creator'+x'00'
c eval infoval='hello.rpg'+x'00'
c callp PDF_set_info(p:infokey:infoval)
* Set info "Author"
c eval infokey='Author'+x'00'
c eval infoval='Thomas Merz'+x'00'
c callp PDF_set_info(p:infokey:infoval)
* Set info "Title"
c eval infokey='Title'+x'00'
c eval infoval='Hello, world (RPG)!'+x'00'
c callp PDF_set_info(p:infokey:infoval)
c callp PDF_begin_page_ext(p:a4_width:a4_height:
c
empty)
*
c eval fontname='Helvetica-Bold'+x'00'
c eval fontenc='ebcdic'+x'00'
c eval font=PDF_load_font(p:fontname:0:fontenc:n)
40 第 2 章 : PDFlib 语 言 绑 定

*
c callp PDF_setfont(p:font:24)
c callp PDF_set_text_pos(p:50:700)
*
c eval text='Hello world!'+x'00'
c callp PDF_show(p:text)
c eval text='(says ILE RPG)'+x'00'
c callp PDF_continue_text(p:text)
c callp PDF_end_page_ext(p:empty)
c callp PDF_end_document(p:empty)
c callp PDF_delete(p)
*
c exsr exit
*****************************************************************************************
c geterrmsg begsr
c eval errmsg_p=PDF_get_errmsg(p)
c if errmsg_p*NULL
c eval error=%subst(errmsg:1:%scan(x'00':errmsg)-1)
c
endif
c
endsr
*****************************************************************************************
c exit begsr
c if error*blanks
c eval error='Error: '+error
c error dsply
c
endif
c seton lr
c
return
c
endsr
可 以 按 如 下 方 式 编 译 此 程 序 :
CRTBNDDIR BNDDIR(PDFLIB/PDFLIB) TEXT('PDFlib Binding Directory')
ADDBNDDIRE BNDDIR(PDFLIB/PDFLIB) OBJ((PDFLIB/PDFLIB *SRVPGM))
CRTBNDRPG PGM(PDFLIB/HELLO) SRCFILE(PDFLIB/QRPGLESRC) SRCMBR(*PGM) DFTACTGRP(*NO) +
BNDDIR(PDFLIB/PDFLIB)
2.13.3 RPG 的 错 误 处 理
用 ILE-RPG 编 写 的 PDFlib 客 户 端 可 以 在 PDFlib 中 安 装 一 个 错 误 处 理 程 序 , 该 程 序 将 在 发 生
异 常 时 被 激 活 。 由 于 ILE-RPG 将 所 有 程 序 名 称 都 转 换 成 大 写 形 式 , 因 此 应 将 错 误 处 理 程 序 的
名 称 以 大 写 形 式 指 定 。 下 面 的 主 干 代 码 演 示 了 此 技 术 :
*****************************************************************************************
d/copy QRPGLESRC,PDFLIB
*****************************************************************************************
d p S *
d font s 10i 0
*
d error s 50
*
d errhdl s * procptr
*
* Prototype for exception handling procedure
*
d errhandler PR
d p * value
d type
10i 0 value
2.13 RPG 绑 定 41

d shortmsg 2048
*****************************************************************************************
c clear error
*
* Set the procedure pointer to the ERRHANDLER procedure.
*
c eval errhdl=%paddr('ERRHANDLER')
*
c eval p=pdf_new2(errhdl:*null:*null:*null:*null)
...PDFlib instructions...
c callp PDF_delete(p)
*
c exsr exit
*****************************************************************************************
c exit begsr
c if error*blanks
c error dsply
c
endif
c seton lr
c
return
c
endsr
*****************************************************************************************
* If any of the PDFlib functions will cause an exception, first the error handler
* will be called and after that we will get a regular RPG exception.
c *pssr begsr
c exsr exit
c
endsr
*****************************************************************************************
* Exception Handler Procedure
* This procedure will be linked to PDFlib by passing the procedure pointer to
* PDF_new2. This procedure will be called when a PDFlib exception occurs.
*
*****************************************************************************************
p errhandler B
d errhandler PI
d p * value
d type
10i 0 value
d c_message 2048
*
d length s 10i 0
*
* Chop off the trailing x'00' (we are called by a C program)
* and set the error (global) string
c clear error
c x'00' scan c_message length 50
c sub 1 length
c if *in50 and length>0
c if length>%size(error)
c eval error=c_message
c
else
c eval error=%subst(c_message:1:length)
c
endif
c
endif
*
* Always call PDF_delete to clean up PDFlib
c callp PDF_delete(p)
42 第 2 章 : PDFlib 语 言 绑 定

*
c
*
p errhandler
E
return
2.14 Tcl 绑 定
2.14.1 安 装 PDFlib Tcl 版 本
通 过 在 运 行 时 加 载 共 享 库 实 现 Tcl 1 扩 展 机 制 。 为 了 使 PDFlib 绑 定 起 作 用 , Tcl 外 壳 程 序 必
须 能 访 问 PDFlib Tcl 包 装 共 享 库 和 程 序 包 索 引 文 件 pkgIndex.tcl 。 您 可 以 在 脚 本 中 使 用 以 下
命 令 , 以 便 可 以 从 某 个 目 录 中 使 用 库 ( 如 果 您 想 在 您 没 有 安 装 PDFlib 的 根 权 限 的 计 算 机 上
部 署 PDFlib, 这 将 会 很 有 用 ):
lappend auto_path /path/to/pdflib
Unix 库 pdflib_tcl.so( 位 于 Mac OS X:pdflib_tcl.dylib 上 ) 必 须 被 放 置 在 某 一 个 存 放 共 享 库
的 默 认 目 录 或 一 个 经 过 恰 当 配 置 的 目 录 中 。 通 常 , 将 pkgIndex.tcl 和 pdflib_tcl.so 都 放 置 在 该
目 录 中
/usr/lib/tcl8.3/pdflib
Windows
将 在 以 下 目 录 中 搜 索 pkgIndex.tcl 和 pdflib_tcl.dll 文 件
C:\Program Files\Tcl\lib\pdflib
C:\Program Files\Tcl\lib\tcl8.3\pdflib
2.14.2 用 Tcl 编 写 的 “Hello world” 示 例
package require pdflib 6.0
set p [PDF_new]
if {[PDF_begin_document $p "hello.pdf" ""] == -1} {
puts stderr "Error: [PDF_get_errmsg $p]"
exit
}
PDF_set_info $p "Creator" "hello.tcl"
PDF_set_info $p "Author" "Thomas Merz"
PDF_set_info $p "Title" "Hello world (Tcl)"
PDF_begin_page_ext $p 595 842 ""
set font [PDF_load_font $p "Helvetica-Bold" "unicode" ""]
PDF_setfont $p $font 24.0
PDF_set_text_pos $p 50 700
PDF_show $p "Hello world!"
PDF_continue_text $p "(says Tcl)"
PDF_end_page_ext $p ""
PDF_end_document $p ""
1. 请 参 见 www.tcl.tk
2.14 Tcl 绑 定 43

PDF_delete $p
2.14.3 Tcl 的 错 误 处 理
Tcl 绑 定 安 装 一 个 特 殊 的 错 误 处 理 程 序 , 该 程 序 将 PDFlib 错 误 转 换 成 本 地 Tcl 异 常 。 可 以 用
常 见 的 try/catch 技 术 处 理 Tcl 异 常 :
if [ catch { ...some PDFlib instructions... } result ] {
puts stderr "Exception caught!"
puts stderr $result
}
44 第 2 章 : PDFlib 语 言 绑 定

3PDFlib 编 程
3.1 常 规 编 程
3.1.1 PDFlib 程 序 结 构 和 函 数 范 围
PDFlib 应 用 程 序 必 须 遵 守 某 些 非 常 易 于 理 解 的 结 构 规 则 。 按 照 这 些 限 制 编 写 应 用 程 序 可 做
到 简 单 明 了 。 例 如 , 在 关 闭 一 个 文 档 前 , 您 不 需 要 考 虑 先 打 开 该 文 档 。 由 于 PDFlib API 几 乎
是 完 全 仿 效 文 档 / 页 范 例 , 所 以 用 自 然 方 式 生 成 文 档 通 常 可 得 到 标 准 格 式 的 PDFlib 客 户 端
程 序 。
PDFlib 使 用 严 格 的 作 用 界 定 范 围 系 统 强 制 推 行 正 确 的 函 数 调 用 顺 序 。 函 数 说 明 指 定 一 个
函 数 的 允 许 范 围 。 从 不 同 范 围 调 用 函 数 将 触 发 PDFlib 异 常 。 若 库 客 户 端 提 供 错 误 的 参 数 ,
则 PDFlib 也 将 引 发 异 常 。
第 8 章 中 的 函 数 说 明 引 用 到 这 些 范 围 ; 范 围 定 义 可 以 在 表 3.1 中 找 到 。 图 3.1 说 明 范 围 的
嵌 套 。 若 在 允 许 的 范 围 之 外 调 用 函 数 , 则 PDFlib 将 引 发 异 常 。 您 可 以 使 用 scope 参 数 查 询 当
前 范 围 。
表 3.1 函 数 范 围 定 义
范 围 名 称 定 义
路 径 由 PDF_moveto( )、 PDF_circle( )、 PDF_arc( )、 PDF_arcn( ) 或 PDF_rect( ) 中 的 一 个 函 数 开 始 ;
由 第 216 页 上 的 第 8.4.6 节 “ 路 径 绘 制 和 剪 切 ” 中 的 任 何 函 数 终 止 。
页
模 板
图 案
字 体
字 形
文 档
在 PDF_begin_page( ) 和 PDF_end_page( ) 之 间 , 但 是 在 路 径 范 围 之 外
在 PDF_begin_template( ) 和 PDF_end_template( ) 之 间 , 但 是 在 路 径 范 围 之 外
在 PDF_begin_pattern( ) 和 PDF_end_pattern( ) 之 间 , 但 是 在 路 径 范 围 之 外
在 PDF_begin_font( ) 和 PDF_end_font( ) 之 间 , 但 是 在 字 形 范 围 之 外
在 PDF_begin_glyph( ) 和 PDF_end_glyph( ) 之 间 , 但 是 在 路 径 范 围 之 外
在 PDF_begin_document( ) 和 PDF_end_document( ) 之 间 , 但 是 在 页 、 模 板 、 图 案 和 字 体 范 围
之 外
对 象 在 Java 中 : 等 同 于 pdflib 对 象 的 生 存 时 间 , 但 是 在 文 档 范 围 之 外 ;
在 PDF_new( ) 和 PDF_delete( ) 之 间 的 其 他 绑 定 中 , 但 是 在 文 档 范 围 之 外
空
任 意
对 象 范 围 之 外
由 于 PDFlib 对 象 甚 至 不 存 在 于 空 范 围 内 , 因 此 当 函 数 说 明 提 及 “ 任 何 ” 范 围 时 , 实 际 上 是 指
除 空 范 围 以 外 的 任 何 范 围 。
3.1.2 参 数
PDFlib 的 操 作 可 以 被 各 种 全 局 参 数 控 制 。 这 些 参 数 将 在 PDFlib 对 象 的 整 个 生 存 期 内 保 留 其
设 置 , 或 者 直 到 设 置 被 客 户 端 明 确 地 更 改 。 以 下 函 数 可 以 用 于 处 理 参 数 :
> PDF_set_parameter( ) 可 以 用 于 为 字 符 串 类 型 参 数 赋 值 。
> PDF_set_value( ) 可 以 用 于 为 参 数 设 置 数 值 。
> PDF_get_parameter( ) 可 以 用 于 查 询 字 符 串 类 型 的 参 数 。
> PDF_get_value( ) 可 以 用 于 查 询 数 值 参 数 的 值 。
3.1 常 规 编 程 45

null
object
document
page page page page
path
path
. . .
template
path
pattern
path
font
glyph glyph glyph
document
page page page page
path
path
. . .
template
path
pattern
path
font
glyph
图 3.1
范 围 的 嵌 套
. . .
有 关 参 数 名 称 和 可 能 值 的 详 细 信 息 , 见 第 8 章 。
3.1.3 异 常 处 理
有 一 类 型 的 错 误 在 许 多 语 言 中 有 很 好 的 理 由 被 称 作 异 常 ― 它 们 仅 仅 是 异 常 , 并 且 在 程 序 的
生 存 期 间 不 会 经 常 发 生 。 一 般 策 略 是 对 可 能 时 常 出 错 的 函 数 调 用 使 用 常 规 的 错 误 报 告 机 制
( 读 取 : 特 殊 错 误 返 回 代 码 ), 而 对 那 些 极 少 出 现 的 且 在 一 定 条 件 下 会 弄 乱 代 码 的 情 况 使 用
特 殊 异 常 机 制 。 这 正 是 PDFlib 遵 循 的 处 理 方 法 : 可 预 期 一 些 操 作 将 相 当 频 繁 地 出 错 , 例 如 :
> 试 图 打 开 对 其 没 有 相 应 权 限 的 输 出 文 件
> 试 图 用 错 误 的 文 件 名 打 开 输 入 PDF 文 件
> 试 图 打 开 损 坏 的 图 像 文 件
如 API 参 考 中 所 述 ,PDFlib 通 过 返 回 一 个 特 殊 的 值 ( 此 值 通 常 为 –1, 但 是 在 PHP 绑 定 中 为 0)
来 指 示 类 似 错 误 。 其 他 事 件 可 能 被 认 为 是 有 害 的 , 但 是 它 们 将 很 少 发 生 , 例 如 :
> 虚 拟 内 存 不 足
> 范 围 冲 突 ( 例 如 , 打 开 某 一 文 档 前 关 闭 该 文 档 )
> 提 供 PDFlib API 函 数 的 错 误 参 数 ( 例 如 , 试 图 使 用 负 半 径 绘 制 圆 形 )
当 PDFlib 检 测 到 这 种 情 形 时 , 将 引 发 一 个 异 常 而 不 是 将 一 个 特 殊 的 错 误 返 回 值 传 递 给 调 用
方 。 在 本 来 不 支 持 异 常 的 C 编 程 语 言 中 , 客 户 端 可 以 安 装 一 个 自 定 义 例 程 ( 称 作 错 误 处 理
程 序 ); 以 便 在 异 常 出 现 时 调 用 该 例 程 。 不 过 , 建 议 的 方 法 是 按 第 26 页 上 的 第 2.4.4 节 “C
的 错 误 处 理 ” 中 所 述 使 用 PDF_TRY( )/PDF_CATCH( ) 块 。
必 须 懂 得 一 点 , 即 在 发 生 异 常 后 无 法 完 成 生 成 的 PDF 文 档 。 发 生 异 常 后 , 只 可 以 安 全 调 用 以
下 方 法 之 一 :PDF_delete( )、PDF_get_apiname( )、PDF_get_errnum( ) 和 PDF_get_errmsg( )。
发 生 异 常 后 , 调 用 任 何 其 他 PDFlib 方 法 可 能 导 致 意 外 结 果 。 异 常 ( 或 传 递 给 C 错 误 处 理 程 序 的
数 据 ) 将 包 含 以 下 信 息 :
> 唯 一 的 错 误 号 ( 请 参 见 表 3.2);
> 引 发 异 常 的 PDFlib API 函 数 的 名 称 ;
> 包 含 问 题 的 详 细 信 息 的 描 述 性 文 本 ;
46 第 3 章 : PDFlib 编 程

表 3.2 PDFlib 异 常 号 的 范 围
错 误 范 围 原 因
1000 – 1999 (PDCORE 库 ): 内 存 、 I/O、 变 量 、 参 数 / 值 、 选 项
2000 – 3999 (PDFlib 库 ): 配 置 、 范 围 、 图 形 和 文 本 、 颜 色 、 图 像 、 字 体 、 编 码 、 PDF/X、 超 文 本 、
标 签 PDF、 图 层
4000 – 4999 (PDF 导 入 库 PDI): 配 置 和 参 数 , 损 坏 的 PDF ( 文 件 、 对 象 或 流 级 别 )
禁 用 异 常 可 以 禁 用 一 些 异 常 。 这 些 异 常 分 为 两 类 : 非 致 命 错 误 ( 警 告 ) 以 及 根 据 客 户 端
首 选 项 设 置 可 能 会 也 可 能 不 会 认 定 为 异 常 的 错 误 。
警 告 通 常 是 指 PDFlib 代 码 中 需 要 您 密 切 关 注 和 调 查 的 一 些 问 题 。 若 出 现 的 错 误 是 非 致 命
的 时 , 程 序 可 继 续 运 行 。 为 此 , 您 可 以 使 用 以 下 函 数 调 用 取 消 显 示 警 告 :
PDF_set_parameter(p, "warning", "false");
除 全 局 warning 参 数 以 外 , 一 些 函 数 也 支 持 一 些 专 用 选 项 来 启 用 或 禁 用 各 个 函 数 调 用 的 警
告 。 建 议 的 策 略 是 在 开 发 周 期 内 启 用 警 告 ( 同 时 密 切 关 注 可 能 的 警 告 ), 而 在 生 产 系 统 中 禁
用 警 告 。
某 些 操 作 对 于 一 些 客 户 端 可 能 是 严 重 的 , 而 其 他 的 客 户 端 可 能 已 准 备 好 处 理 这 种 情 况 。
在 这 种 情 况 下 , 相 应 的 PDFlib API 函 数 的 行 为 会 根 据 参 数 发 生 更 改 。 对 于 加 载 字 体 、 图 像 、
导 入 的 PDF 文 档 和 ICC 配 置 文 件 , 此 差 别 已 经 得 到 实 现 。 例 如 , 如 果 由 于 某 个 配 置 问 题 无 法
加 载 某 一 字 体 , 一 个 客 户 端 可 能 会 完 全 放 弃 加 载 , 而 另 外 一 个 客 户 端 可 能 会 选 择 加 载 其 他 的
字 体 。 在 参 数 或 选 项 fontwarning 设 置 为 true 的 情 况 下 , 当 无 法 加 载 字 体 时 , 将 引 发 异 常 。
否 则 , 函 数 将 返 回 一 个 错 误 代 码 。 可 以 按 如 下 所 示 设 置 参 数 :
PDF_set_parameter(p, "fontwarning", "false");
查 询 函 数 调 用 失 败 的 原 因 正 如 以 上 提 到 的 那 样 , 发 生 异 常 时 , 必 须 总 是 放 弃 生 成 的 PDF
输 出 文 档 。 不 过 , 有 些 客 户 端 可 能 更 愿 意 通 过 调 整 一 些 参 数 继 续 处 理 文 档 。 例 如 , 当 不 能
加 载 某 一 特 别 的 字 体 时 , 大 多 数 客 户 端 将 放 弃 文 档 , 而 其 他 的 客 户 端 可 能 更 愿 意 使 用 不 同
的 字 体 。 可 以 使 用 fontwarning 等 参 数 实 现 此 差 别 。 在 这 种 情 况 下 , 可 能 需 要 检 索 已 作 为 异
常 的 一 部 分 的 错 误 消 息 。 一 旦 某 个 函 数 调 用 失 败 , 则 可 能 立 即 调 用 函 数 PDF_get_errnum( )、
PDF_get_errmsg( ) 和 PDF_get_apiname( )。 例 如 , 当 函 数 调 用 返 回 -1 (PHP:0) 错 误 值 。
以 下 代 码 片 段 总 结 了 有 关 异 常 处 理 的 不 同 策 略 。 示 例 试 图 加 载 并 嵌 入 某 一 字 体 , 但 假 定
该 字 体 不 可 用 。
若 fontwarning 参 数 或 选 项 为 true ( 默 认 设 置 ), 则 必 须 放 弃 文 档 :
font = PDF_load_font(p, "MyFontName", 0, "winansi", "fontwarning=true");
/* unless an exception was thrown the font handle is valid;
* when an exception occurred the PDF output cannot be continued
*/
若 fontwarning 参 数 或 选 项 为 false, 则 必 须 检 查 返 回 值 的 有 效 性 。 若 返 回 值 指 示 失 败 , 则 查
询 失 败 的 原 因 以 便 对 这 种 情 况 进 行 正 确 地 处 理 :
font = PDF_load_font(p, "MyFontName", 0, "winansi", "fontwarning=false";
if (font == -1) {
/* font handle is invalid; find out what happened. */
errmsg = PDF_get_errmsg(p);
/* Log error message */
/* Try a different font or give up */
...
3.1 常 规 编 程 47

}
/* font handle is valid; continue as usual */
3.1.4 PDFlib 虚 拟 文 件 系 统 (PVF)
除 磁 盘 文 件 以 外 , 一 种 名 为 “PDFlib 虚 拟 文 件 系 统 ”(PDFlib Virtual File System, PVF) 的 工 具
允 许 客 户 端 直 接 在 内 存 中 提 供 数 据 而 不 需 要 任 何 磁 盘 文 件 参 与 。 这 种 方 式 带 来 了 性 能 上 的
优 势 , 可 用 于 从 数 据 库 捕 获 的 数 据 ( 这 些 数 据 甚 至 不 存 在 于 单 独 的 磁 盘 文 件 上 ) 以 及 其 他
一 些 客 户 端 在 内 存 中 已 具 有 所 需 的 数 据 ( 作 为 处 理 的 结 果 ) 的 情 况 。
PVF 基 于 命 名 的 虚 拟 只 读 文 件 的 概 念 , 这 类 文 件 与 常 规 文 件 名 称 一 样 , 可 以 与 任 何 API
函 数 一 起 使 用 。 PVF 甚 至 可 以 在 UPR 配 置 文 件 中 使 用 。 客 户 端 可 以 使 用 任 意 方 法 生 成 虚 拟
文 件 名 称 。 显 然 , 必 须 选 择 虚 拟 文 件 名 称 以 避 免 与 常 规 磁 盘 文 件 发 生 名 称 冲 突 。 为 此 , 建 议
遵 循 以 下 的 虚 拟 文 件 名 称 的 分 层 命 名 约 定 (filename 是 指 客 户 端 选 择 的 在 相 应 类 别 中 唯 一
的 名 称 )。 还 建 议 保 留 标 准 文 件 名 称 后 缀 :
> 光 栅 图 像 文 件 :/pvf/image/filename
> 字 型 和 规 格 文 件 ( 建 议 将 实 际 字 体 名 称 用 作 文 件 名 称 的 基 础 部 分 ):/pvf/font/filename
> ICC 配 置 文 件 :/pvf/iccprofile/filename
> 编 码 和 代 码 页 :/pvf/codepage/filename
> PDF 文 档 :/pvf/pdf/filename
当 搜 索 一 个 命 名 的 文 件 时 ,PDFlib 将 首 先 检 查 提 供 的 文 件 名 称 是 否 引 用 已 知 的 虚 拟 文 件 , 然
后 试 图 打 开 磁 盘 上 相 应 的 命 名 文 件 。
虚 拟 文 件 的 生 存 时 间 一 些 函 数 将 立 即 使 用 虚 拟 文 件 中 提 供 的 数 据 , 而 其 他 函 数 将 仅 读 取
文 件 的 部 分 内 容 , 并 在 稍 后 使 用 其 他 数 据 片 段 。 为 此 , 必 须 密 切 关 注 虚 拟 文 件 的 生 存 时 间 。
PDFlib 将 在 每 个 虚 拟 文 件 上 放 置 一 个 内 部 锁 , 并 仅 在 不 再 需 要 相 应 内 容 时 移 除 该 锁 。 除 非 客
户 端 请 求 PDFlib 立 即 复 制 数 据 ( 使 用 PDF_create_pvf( ) 中 的 copy 选 项 ) , 否 则 , 只 有 当
PDFlib 不 再 锁 定 虚 拟 文 件 内 容 时 , 客 户 端 才 能 对 虚 拟 文 件 内 容 进 行 修 改 、 删 除 或 释 放 。
PDFlib 将 使 用 PDF_delete( ) 自 动 删 除 所 有 虚 拟 文 件 。 不 过 , 必 须 总 是 由 客 户 端 释 放 实 际 文 件
内 容 ( 包 含 虚 拟 文 件 的 数 据 )。
不 同 的 策 略 PVF 支 持 不 同 的 管 理 虚 拟 文 件 内 存 的 方 法 。 这 是 由 于 : 在 接 受 虚 拟 文 件 名 称 的
API 调 用 之 后 , PDFlib 可 能 需 要 访 问 虚 拟 文 件 的 内 容 , 但 从 不 在 PDF_close( ) 之 后 需 要 访 问
内 容 。 记 住 , 调 用 PDF_delete_pvf( ) 不 会 释 放 实 际 的 文 件 内 容 ( 除 非 使 用 了 copy 选 项 ), 而
只 是 释 放 用 于 PVF 文 件 名 称 管 理 的 相 应 的 数 据 结 构 。 这 就 产 生 了 以 下 策 略 :
> 最 小 化 内 存 使 用 : 建 议 在 接 受 虚 拟 文 件 名 称 的 API 调 用 之 后 立 即 调 用 PDF_delete_pvf( ),
并 在 PDF_close( ) 之 后 再 次 调 用 。 第 二 次 调 用 是 必 需 的 , 因 为 有 可 能 在 第 一 次 调 用 时
PDFlib 未 完 成 数 据 访 问 , 故 拒 绝 对 虚 拟 文 件 解 除 锁 定 。 当 然 , 在 有 些 情 况 下 , 第 一 次 调 用
就 已 将 数 据 释 放 , 即 使 如 此 第 二 次 调 用 也 不 会 有 任 何 害 处 。 客 户 端 仅 在 PDF_delete_pvf( )
成 功 的 情 况 下 , 才 可 能 释 放 文 件 内 容 。
> 通 过 重 用 虚 拟 文 件 优 化 性 能 : 有 些 客 户 端 可 能 希 望 重 用 各 种 输 出 文 档 中 的 一 些 数 据 ( 例
如 , 字 体 定 义 ), 和 避 免 多 次 重 复 创 建 / 删 除 相 同 的 文 件 内 容 。 在 这 种 情 况 下 , 如 果 更 多
PDF 输 出 文 档 将 使 用 此 虚 拟 文 件 , 建 议 不 要 调 用 PDF_delete_pvf( )。
> 简 化 编 程 : 如 果 不 需 要 考 虑 内 存 的 使 用 情 况 , 则 客 户 端 可 选 择 不 调 用 PDF_delete_pvf( )。
在 这 种 情 况 下 , PDFlib 将 在 PDF_delete( ) 中 内 部 删 除 所 有 挂 起 的 虚 拟 文 件 。
在 所 有 情 况 下 , 客 户 端 仅 当 PDF_delete_pvf( ) 成 功 返 回 时 , 或 在 PDF_delete( ) 之 后 释 放 相 应
的 数 据 。
48 第 3 章 : PDFlib 编 程

3.1.5 资 源 配 置 和 文 件 搜 索
在 大 多 数 高 级 应 用 程 序 中 ,PDFlib 需 要 访 问 字 体 文 件 、 编 码 定 义 、ICC 配 置 文 件 等 资 源 。 为
了 使 PDFlib 的 资 源 处 理 功 能 与 平 台 无 关 并 实 现 自 定 义 , 可 以 提 供 一 个 配 置 文 件 用 于 描 述 可
用 资 源 以 及 相 应 的 磁 盘 文 件 的 名 称 。 除 了 静 态 配 置 文 件 之 外 , 可 以 利 用 PDF_set_
parameter( ) 在 运 行 时 添 加 资 源 从 而 实 现 动 态 配 置 。 对 于 配 置 文 件 , 我 们 挖 掘 出 在 Display
PostScript 时 代 问 世 并 仍 被 几 个 系 统 使 用 的 简 单 文 本 格 式 (Unix PostScript Resource, UPR)。
不 过 , 我 们 已 经 根 据 自 己 的 需 要 扩 展 了 原 始 的 UPR 格 式 。 下 面 将 描 述 PDFlib 使 用 的 UPR 文
件 格 式 。 有 一 种 名 为 makepsres ( 经 常 作 为 X Window 系 统 的 一 部 分 进 行 分 发 ) 的 实 用 工
具 , 此 工 具 可 用 于 从 PostScript 字 库 外 形 和 量 度 文 件 自 动 生 成 UPR 文 件 。
资 源 类 别 在 表 3.3 中 已 列 出 PDFlib 支 持 的 资 源 类 别 。 其 他 资 源 类 别 将 被 忽 略 。 这 些 值 被 视
为 名 称 字 符 串 ; 可 以 用 ASCII 或 UTF-8 ( 带 BOM) 对 其 进 行 编 码 。 Unicode 值 可 能 对 带 有
HostFont 资 源 的 本 地 化 的 字 体 名 称 很 有 用 。
表 3.3 PDFlib 支 持 的 资 源 类 别
种 类 格 式 说 明
SearchPath value 包 含 数 据 文 件 的 目 录 的 相 对 或 绝 对 路 径 名 称
FontAFM key=value 用 AFM 格 式 编 写 的 PostScript 字 库 量 度 文 件
FontPFM key=value 用 PFM 格 式 编 写 的 PostScript 字 库 量 度 文 件
FontOutline key=value PostScript、 TrueType 或 OpenType 字 库 外 形 文 件
Encoding key=value 包 含 8 位 编 码 或 代 码 页 表 的 文 本 文 件
HostFont key=value 系 统 上 安 装 的 字 体 的 名 称
ICCProfile key=value ICC 配 置 文 件 的 名 称
StandardOutputIntent key=value PDF/X 的 标 准 输 出 条 件 的 名 称
应 避 免 冗 余 的 资 源 项 。 例 如 , 一 个 字 体 的 量 度 数 据 不 应 包 含 多 个 项 。 另 外 , 在 UPR 文 件 中
配 置 的 字 体 名 称 应 与 实 际 的 字 体 名 称 完 全 相 同 以 避 免 混 淆 ( 尽 管 PDFlib 不 强 制 此 限 制 )。
在 Mac OS Classic 中 , 冒 号 字 符 “:” 必 须 作 为 目 录 分 隔 符 使 用 。 必 须 使 用 完 整 路 径
( 包 括 卷 名 ) 指 定 基 于 资 源 的 PostScript Type 1 字 体 (LWFN 字 体 ) 的 字 体 名 称 , 例 如 :
Foo-Italic=Classic:Data:Fonts:FooIta
UPR 文 件 格 式 UPR 文 件 是 结 构 非 常 简 单 的 文 本 文 件 , 可 以 用 文 本 编 辑 器 轻 松 编 写 或 自 动
生 成 。 首 先 , 让 我 们 来 了 解 一 下 句 法 问 题 :
> 每 行 最 多 有 255 个 字 符 。
> 反 斜 线 符 号 “\” 转 义 换 行 符 。 它 可 能 用 于 扩 展 行 。
> 单 独 的 句 点 字 符 “ . ” 用 作 节 终 结 符 。
> 所 有 项 都 要 区 分 大 小 写 。
> 可 以 用 百 分 比 “%” 字 符 引 入 注 释 行 并 在 行 的 结 尾 终 止 。
> 除 了 资 源 名 称 和 文 件 名 称 中 的 空 白 字 符 外 , 其 余 的 将 被 忽 略 。
UPR 文 件 由 以 下 各 部 分 组 成 :
> 用 于 标 识 文 件 的 特 殊 行 。 它 具 备 以 下 形 式 :
PS-Resources-1.0
> 列 出 文 件 中 描 述 的 所 有 资 源 类 别 的 可 选 节 。 每 行 描 述 一 种 资 源 类 别 。 该 列 表 由 带 有 单 个
句 点 字 符 的 行 终 止 。 稍 后 将 描 述 可 用 的 资 源 类 别 。
3.1 常 规 编 程 49

在 文 件 的 开 头 列 出 的 针 对 每 一 个 资 源 类 别 的 节 。 每 一 节 由 显 示 资 源 类 别 的 行 开 始 , 后 跟
任 意 数 量 的 描 述 可 用 资 源 的 行 。 该 列 表 由 带 有 单 个 句 点 字 符 的 行 终 止 。 每 个 资 源 数 据 行
都 包 含 资 源 的 名 称 ( 必 须 用 引 号 将 等 号 引 起 来 )。 若 资 源 需 要 一 个 文 件 名 称 , 则 必 须 在
等 号 后 面 添 加 此 名 称 。 当 PDFlib 搜 索 资 源 项 中 列 出 的 文 件 时 , 将 应 用 SearchPath( 请 参
见 以 下 内 容 )。
文 件 搜 索 和 SearchPath 资 源 类 别 PDFlib 从 磁 盘 文 件 中 读 取 各 种 数 据 项 , 例 如 光 栅 图 像 、
字 型 和 规 格 信 息 、 编 码 定 义 、PDF 文 档 和 ICC 配 置 文 件 。 除 了 相 对 或 绝 对 路 径 名 称 之 外 , 您
还 可 以 使 用 不 带 任 何 路 径 说 明 的 文 件 名 称 。 SearchPath 资 源 类 别 可 以 用 于 为 包 含 必 需 的 数
据 文 件 的 目 录 指 定 路 径 名 称 的 列 表 。 当 PDFlib 必 须 打 开 一 个 文 件 时 , 它 先 会 完 全 按 照 所 提
供 的 文 件 名 称 试 图 打 开 该 文 件 。 若 此 尝 试 失 败 , PDFlib 将 接 连 尝 试 打 开 SearchPath 资 源 类
别 中 指 定 的 目 录 下 的 文 件 , 直 到 成 功 为 止 。SearchPath 项 可 以 进 行 累 积 , 并 且 将 按 相 反 的 顺
序 对 其 进 行 搜 索 ( 即 , 先 搜 索 后 来 设 置 的 路 径 , 再 搜 索 早 先 设 置 的 路 径 )。 此 功 能 可 以 用 于
让 PDFlib 应 用 程 序 不 再 依 赖 特 定 于 平 台 的 文 件 系 统 架 构 。 为 了 禁 用 搜 索 , 您 可 以 在 PDFlib
函 数 中 使 用 指 定 完 整 的 路 径 名 称 。 请 注 意 SearchPath 资 源 类 别 的 下 列 特 定 于 平 台 的 功 能 :
> 在 Windows 上 , PDFlib 将 使 用 注 册 表 中 的 项 初 始 化 SearchPath。 以 下 注 册 表 项 可 能 包
含 一 个 包 含 路 径 名 称 的 列 表 , 其 中 的 路 径 名 称 由 分 号 “;” 字 符 隔 开 :
HKLM\SOFTWARE\PDFlib\PDFlib\6.0.3\SearchPath
> 在 IBM iSeries 上 , 将 使 用 以 下 值 初 始 化 SearchPath 资 源 类 别 :
/pdflib/6.0.3/fonts
/pdflib/6.0.3/bind/data
> 在 带 有 MVS 的 IBM zSeries 系 统 上 , 不 支 持 SearchPath 功 能 。
> 在 OpenVMS 上 , 可 以 将 逻 辑 名 称 作 为 SearchPath 提 供 。
示 例 UPR 文 件 以 下 列 表 提 供 了 一 个 UPR 配 置 文 件 示 例 :
PS-Resources-1.0
SearchPath
/usr/local/lib/fonts
C:/psfonts/pfm
C:/psfonts
/users/kurt/my_images
.
FontAFM
Code-128=Code_128.afm
.
FontPFM
Corporate-Bold=corpb___.pfm
.
Mistral=c:/psfonts/pfm/mist____.pfm
.
FontOutline
Code-128=Code_128.pfa
ArialMT=Arial.ttf
.
Encoding
myencoding=myencoding.enc
.
ICCProfile
highspeedprinter=cmykhighspeed.icc
.
50 第 3 章 : PDFlib 编 程

搜 索 UPR 资 源 文 件 若 仅 要 使 用 内 建 资 源 ( 例 如 ,PDF 核 心 字 体 、 内 置 编 码 、sRGB ICC 配
置 文 件 ) 和 系 统 资 源 ( 宿 主 字 体 ), 则 不 需 要 UPR 配 置 文 件 , 这 是 因 为 PDFlib 在 不 使 用 任
何 附 加 配 置 的 情 况 下 , 也 可 以 找 到 所 有 必 需 的 资 源 。
若 要 使 用 其 他 资 源 , 您 可 以 通 过 调 用 PDF_set_parameter( ) 指 定 这 些 资 源 ( 请 参 见 以 下
内 容 ), 或 者 在 UPR 资 源 文 件 中 指 定 这 些 资 源 。 当 请 求 第 一 个 资 源 时 , PDFlib 自 动 读 取 此
文 件 。 详 细 过 程 如 下 所 示 :
> 若 定 义 环 境 变 量 PDFLIBRESOURCE, 则 PDFlib 将 其 值 作 为 要 读 取 的 UPR 文 件 的 名 称 。 若
无 法 读 取 此 文 件 , 则 将 引 发 异 常 。
> 若 未 定 义 环 境 变 量 PDFLIBRESOURCE, 则 PDFlib 尝 试 打 开 带 有 以 下 名 称 的 文 件 :
upr ( 在 MVS 上 ; 预 期 为 数 据 集 )
pdflib//fonts/pdflib.upr ( 在 IBM eServer iSeries 上 )
pdflib.upr ( 在 Windows、 Unix 以 及 所 有 其 他 系 统 上 )
即 使 无 法 读 取 此 文 件 , 也 不 会 引 发 异 常 。
> 在 Windows 上 , PDFlib 将 额 外 尝 试 读 取 注 册 表 项
HKLM\SOFTWARE\PDFlib\PDFlib\6.0.3\resourcefile
此 项 的 值 ( 将 由 PDFlib 安 装 程 序 创 建 , 但 也 可 以 通 过 其 他 方 式 创 建 ) 将 作 为 要 使 用 的
资 源 文 件 的 名 称 。 若 无 法 读 取 此 文 件 , 则 将 引 发 异 常 。
> 通 过 明 确 地 设 置 resourcefile 参 数 , 客 户 端 可 以 在 运 行 时 强 制 PDFlib 读 取 资 源 文 件 :
PDF_set_parameter(p, "resourcefile", "/path/to/pdflib.upr");
可 以 时 常 任 意 重 复 此 调 用 ; 资 源 项 将 进 行 累 积 。
运 行 时 对 资 源 进 行 配 置 除 了 使 用 UPR 文 件 进 行 配 置 以 外 , 还 能 够 通 过 PDF_set_parameter( )
函 数 在 源 代 码 内 直 接 配 置 各 个 资 源 。 此 函 数 采 用 一 个 类 别 名 称 和 相 应 的 资 源 项 作 为 参 数 , 这
正 如 同 它 出 现 在 UPR 资 源 文 件 中 此 类 别 的 相 关 节 中 一 样 , 例 如 :
PDF_set_parameter(p, "FontAFM", "Foobar-Bold=foobb___.afm")
PDF_set_parameter(p, "FontOutline", "Foobar-Bold=foobb___.pfa")
3.1.6 在 内 存 中 生 成 PDF 文 档
除 了 在 文 件 上 生 成 PDF 文 档 之 外 , 也 可 以 指 示 PDFlib 在 内 存 中 直 接 生 成 PDF 文 档 ( 输 出 到
内 存 )。 由 于 不 需 要 涉 及 到 基 于 磁 盘 的 I/O, 并 且 PDF 文 档 可 以 直 接 通 过 HTTP 进 行 传 输 ,
因 此 此 技 术 提 供 了 性 能 上 的 优 势 。 网 站 管 理 员 将 高 兴 地 知 道 其 服 务 器 将 可 不 再 被 临 时 PDF
文 件 弄 得 一 团 糟 。
您 可 以 选 择 定 时 收 集 部 分 数 据 ( 例 如 , 每 次 完 成 一 页 时 ), 或 者 最 后 在 一 个 大 的 块 区 中
获 取 完 整 的 PDF 文 档 ( 在 PDF_end_document( ) 之 后 )。 交 错 进 行 PDF 数 据 的 生 产 和 消 耗
有 几 个 好 处 。 首 先 , 由 于 不 是 所 有 数 据 都 必 须 保 存 在 内 存 中 , 从 而 降 低 了 内 存 要 求 。 其 次 ,
此 方 案 可 以 增 强 性 能 , 这 是 因 为 当 下 一 个 块 区 还 在 生 成 中 时 , 第 一 个 数 据 块 区 可 以 通 过 一 个
慢 速 链 接 传 输 。 不 过 , 只 有 当 整 个 文 档 完 成 后 , 才 能 知 道 生 成 数 据 的 总 长 度 。
主 动 的 PDF 文 件 输 出 到 内 存 的 生 成 的 接 口 为 了 在 内 存 中 生 成 PDF 数 据 , 只 需 对 PDF_
begin_document( ) 提 供 一 个 空 文 件 名 称 , 并 用 PDF_get_buffer( ) 提 取 数 据 :
PDF_begin_document(p, "", 0, "")
...create document...
PDF_end_document(p);
buf = PDF_get_buffer(p, &size);
3.1 常 规 编 程 51

... use the PDF data contained in the buffer ...
PDF_delete(p);
注 : 缓 冲 区 中 的 PDF 数 据 必 须 作 为 二 进 制 数 据 进 行 处 理 。
以 上 程 序 是 由 客 户 端 决 定 何 时 获 取 缓 冲 区 内 容 , 故 被 认 为 是 “ 主 动 ” 模 式 。 此 模 式 可 用 于
所 有 受 支 持 的 语 言 绑 定 。
注 : C 和 C++ 客 户 端 不 得 释 放 返 回 的 缓 冲 区 。
被 动 的 PDF 文 件 输 出 到 内 存 的 生 成 的 接 口 在 “ 被 动 ” 模 式 下 ( 此 模 式 仅 在 C 和 C++ 语
言 绑 定 中 可 用 ), 用 户 安 装 ( 通 过 PDF_open_document_callback( )) 一 个 回 调 函 数 ,PDFlib
将 在 PDF 数 据 等 待 使 用 时 的 无 法 预 知 的 任 何 时 间 调 用 该 函 数 。 客 户 端 可 以 配 置 与 刷 新 ( 将
PDF 数 据 从 库 转 换 到 客 户 端 ) 相 关 的 计 时 和 缓 冲 区 大 小 约 束 以 便 提 供 最 大 灵 活 性 。 根 据 环 境
的 不 同 , 以 下 做 法 各 有 千 秋 : 一 次 使 用 几 大 块 内 存 缓 冲 区 获 取 整 个 PDF 文 档 ; 或 分 为 许 多
小 段 来 获 取 PDF 文 档 以 阻 止 PDFlib 增 加 内 部 文 档 缓 冲 区 。 可 以 使 用 PDF_open_document_
callback( ) 的 flush 选 项 设 置 刷 新 策 略 。
3.1.7 在 基 于 EBCDIC 的 平 台 上 使 用 PDFlib
PDF 文 件 格 式 中 的 运 算 符 和 结 构 元 素 都 基 于 ASCII, 这 样 就 使 得 在 基 于 EBCDIC 的 平 台 ( 例
如 IBM eServer iSeries 400 和 zSeries S/390) 上 难 以 混 合 文 本 输 出 和 PDF 运 算 符 。 不 过 ,
我 们 已 精 心 制 作 了 一 个 特 殊 的 PDFlib 大 型 机 版 本 , 以 便 使 基 于 ASCII 的 PDF 运 算 符 和
EBCDIC ( 或 其 他 ) 文 本 输 出 能 够 混 合 。 EBCDIC 安 全 版 本 的 PDFlib 可 用 于 多 种 操 作 系 统 和
计 算 机 架 构 。
为 了 在 基 于 EBCDIC 的 平 台 上 利 用 PDFlib 的 功 能 , 应 使 用 EBCDIC 文 本 格 式 提 供 以 下 项
( 更 具 体 而 言 , 对 于 iSeries 是 在 代 码 页 037 中 , 而 对 于 zSeries 是 在 代 码 页 1047 中 ):
> PFA 字 体 文 件 、 UPR 配 置 文 件 、 AFM 字 库 量 度 文 件
> 编 码 和 代 码 页 文 件
> 用 于 PDFlib 函 数 的 字 符 串 参 数
> 输 入 和 输 出 文 件 名 称
> 环 境 变 量 ( 如 果 受 运 行 库 环 境 支 持 )
> PDFlib 错 误 消 息 ( 除 Java 之 外 ) 也 将 用 EBCDIC 格 式 生 成 。
若 您 更 愿 意 按 ASCII 格 式 使 用 输 入 文 本 文 件 (PFA、UPR、AFM、 编 码 ), 则 您 可 以 将 asciifile
参 数 设 置 为 true( 默 认 值 为 false)。 这 样 PDFlib 将 期 望 用 ASCII 编 码 编 写 这 些 文 件 。 不 过 ,
字 符 串 参 数 仍 将 期 望 用 EBCDIC 编 码 编 写 。
与 此 相 反 , 以 下 项 必 须 以 二 进 制 模 式 处 理 ( 例 如 , 必 须 避 免 任 何 转 换 ):
> PDF 输 入 和 输 出 文 件
> PFB 字 库 外 形 和 PFM 字 库 量 度 文 件
> TrueType 和 OpenType 字 体 文 件
> 图 像 文 件 和 ICC 配 置 文 件
3.1.8 大 文 件 支 持
在 本 节 中 , 术 语 “ 大 文 件 ” 是 指 大 小 超 过 2GB 的 文 件 。 虽 然 对 于 普 通 用 户 来 说 似 乎 不 需 要
如 此 大 的 文 件 , 但 是 实 际 上 有 些 企 业 应 用 程 序 需 要 创 建 或 处 理 如 包 含 大 量 发 票 或 结 算 单 的
单 个 大 文 件 。 在 这 类 情 况 下 , 文 件 大 小 可 能 会 超 过 2GB 的 限 制 。
PDFlib 支 持 输 出 大 文 件 , 也 就 是 说 , 它 可 以 创 建 大 于 2GB 的 PDF 输 出 。PDI 也 支 持 处 理
大 输 入 文 件 。 不 过 , 对 大 文 件 的 支 持 仅 适 用 于 操 作 系 统 其 本 身 支 持 大 文 件 。 显 然 , 所 使 用 的
文 件 系 统 也 必 须 支 持 大 文 件 。 请 注 意 , Acrobat 6 及 更 早 的 版 本 不 能 处 理 大 文 件 。 不 过 ,
Acrobat 7 完 全 可 以 处 理 大 文 件 。
52 第 3 章 : PDFlib 编 程

注 : 除 PDF 以 外 的 导 入 文 件 ( 例 如 字 体 和 图 像 ) 不 能 超 过 2GB 限 制 。 用 PDF_get_buffer( ) 接 口
获 取 的 PDF 输 出 片 段 也 需 要 遵 从 此 限 制 。 最 终 ,PDF 输 出 文 件 通 常 限 于 10 10 个 字 节 , 即 大 约
9.3 GB。
3.2 页 面 说 明
3.2.1 坐 标 系 统
在 PDFlib 中 使 用 PDF 的 默 认 坐 标 系 统 。 默 认 坐 标 系 统 ( 或 默 认 用 户 空 间 ) 的 原 点 位 于 页 面
的 左 下 角 , 并 使 用 DTP 点 作 为 单 位 :
1 pt = 1/72 inch = 25.4/72 mm = 0.3528 mm
第 一 个 坐 标 向 右 增 加 , 第 二 个 坐 标 向 上 增 加 。 PDFlib 客 户 端 程 序 可 以 通 过 旋 转 、 缩 放 、
平 移 或 斜 移 更 改 默 认 用 户 空 间 , 从 而 产 生 新 的 用 户 坐 标 。 这 些 转 换 对 应 的 函 数 分 别 为
PDF_rotate( )、 PDF_scale( )、 PDF_translate( ) 和 PDF_skew( )。 若 已 转 换 用 户 空 间 , 则 必 须
根 据 新 的 坐 标 系 统 提 供 图 形 和 文 本 函 数 中 的 所 有 坐 标 。 在 每 一 页 的 开 头 , 坐 标 系 统 都 会 重
置 为 默 认 坐 标 系 统 。
使 用 公 制 坐 标
的 定 义 派 生 :
PDF_scale(p, 28.3465, 28.3465);
通 过 缩 放 坐 标 系 统 可 以 轻 松 使 用 公 制 坐 标 。 缩 放 因 子 从 上 面 给 定 的 DTP 点
完 成 此 调 用 后 , PDFlib 将 以 厘 米 为 单 位 解 释 所 有 坐 标 ( 超 文 本 功 能 除 外 , 具 体 请 参 见 以 下
内 容 ), 这 是 由 于 72/2.54 = 28.3465。
用 于 超 文 本 元 素 的 坐 标 PDF 总 是 需 要 用 于 超 文 本 函 数 的 坐 标 , 例 如 在 默 认 坐 标 系 统 而 不
是 在 ( 可 能 已 经 过 转 换 的 ) 用 户 坐 标 系 统 中 用 于 创 建 文 本 注 释 、 链 接 和 文 件 注 释 的 矩 形 坐
标 。 由 于 这 样 非 常 麻 烦 , 因 此 PDFlib 对 PDF 需 要 的 格 式 提 供 了 用 户 坐 标 的 自 动 转 换 。 通 过
将 usercoordinates 参 数 设 置 为 true 可 以 激 活 此 自 动 转 换 :
PDF_set_parameter(p, "usercoordinates", "true");
由 于 PDF 仅 支 持 其 边 缘 平 行 于 页 边 缘 的 超 文 本 矩 形 , 因 此 , 当 坐 标 系 统 已 经 通 过 缩 放 、 旋
转 、 平 移 或 斜 移 完 成 转 换 后 , 必 须 修 改 所 提 供 的 矩 形 。 在 这 种 情 况 下 ,PDFlib 将 计 算 其 边 缘
平 行 于 页 边 缘 的 最 小 包 容 矩 形 , 将 其 转 换 到 默 认 坐 标 , 并 使 用 得 到 的 值 替 换 提 供 的 坐 标 。
总 体 而 言 , 当 usercoordinates 参 数 已 设 置 为 true 时 , 您 可 以 对 页 面 内 容 和 超 文 本 元 素 使
用 同 一 坐 标 系 统 。
使 坐 标 可 视 化 为 了 帮 助 PDFlib 用 户 使 用 PDF 的 坐 标 系 统 , PDFlib 分 发 中 包 含 PDF 文 件
grid.pdf, 此 文 件 可 让 一 些 普 通 页 面 大 小 的 坐 标 可 视 化 。 在 透 明 的 材 料 上 打 印 适 当 大 小 的 页
可 能 会 为 准 备 PDFlib 开 发 提 供 有 用 的 工 具 。
Acrobat 6 或 7( 仅 限 完 全 版 本 , 而 不 是 免 费 的 Reader) 也 带 有 一 个 有 用 的 实 用 工 具 。 在
Acrobat 7.0 ( 标 准 版 ) 中 , 只 需 选 择 “ 视 图 ” -> “ 导 览 标 签 ” -> “ 信 息 ”, 即 可 显 示 测 量
调 板 。 请 注 意 , 显 示 的 坐 标 参 照 页 面 左 上 角 的 原 点 , 而 不 是 PDF 默 认 的 左 下 角 的 原 点 。 若
想 改 变 显 示 单 位 , 选 择 “ 编 辑 ” -> “ 首 选 项 ” -> “ 单 位 ”, 在 pica、 点 、 毫 米 、 厘 米 和 英
寸 中 选 择 单 位 。 您 也 可 以 到 “ 视 图 ” -> “ 导 览 标 签 ” ->“ 信 息 ”, 在 “ 选 项 ” 中 选 择 单 位 。
3.2 页 面 说 明 53

不 要 被 看 起 来 好 像 页 面 尺 寸 存 在 错 误 的 PDF 打 印 输 出 误 导 。 由 于 以 下 一 些 常 见 原 因 , 这
些 打 印 输 出 可 能 是 错 误 的 :
> 已 经 在 Acrobat 的 打 印 对 话 框 中 选 中 “ 缩 小 以 适 合 打 印 机 页 边 距 ” 选 项 , 此 设 置 将 导 致
对 打 印 输 出 进 行 缩 放 。
> 非 PostScript 打 印 机 驱 动 程 序 并 不 总 是 能 够 保 留 所 打 印 对 象 的 精 确 大 小 。
旋 转 对 象 必 须 懂 得 一 点 , 即 一 旦 对 象 已 经 被 绘 制 在 页 面 上 , 就 不 能 修 改 。 尽 管 PDFlib
提 供 了 用 于 旋 转 、 平 移 、 缩 放 和 斜 移 坐 标 系 统 的 函 数 , 这 些 函 数 也 不 能 影 响 页 面 上 现 有 的
对 象 , 而 只 可 以 影 响 随 后 绘 制 的 对 象 。 可 以 使 用 PDF_fit_textline( )、 PDF_fit_image( ) 和
PDF_fit_pdi_page( ) 函 数 中 的 orientate 选 项 , 轻 松 地 将 文 本 、 图 像 和 导 入 的 PDF 页 旋 转
90 度 的 整 数 倍 角 度 。
通 过 提 供 常 规 的 坐 标 转 换 函 数 , 可 以 完 成 任 意 角 度 的 旋 转 。 以 下 示 例 生 成 一 些 水 平 文 本
并 旋 转 坐 标 系 统 以 便 显 示 旋 转 的 文 本 。 保 存 / 还 原 嵌 套 功 能 使 得 在 完 成 垂 直 文 本 输 出 后 能 轻
松 地 在 原 坐 标 系 统 中 继 续 水 平 文 本 的 输 出 :
PDF_set_text_pos(p, 50, 600);
PDF_show(p, "This is horizontal text");
textx = PDF_get_value(p, "textx", 0); /* determine text position*/
texty = PDF_get_value(p, "texty", 0); /* determine text position */
PDF_save(p);
PDF_translate(p, textx, texty); /* move origin to end of text */
PDF_rotate(p, 45); /* rotate coordinates */
PDF_set_text_pos(p, 18, 0); /* provide for distance from horiz. text */
PDF_show(p, "rotated text");
PDF_restore(p);
PDF_continue_text(p, "horizontal text continues");
使 用 自 上 而 下 的 坐 标 与 PDF 的 自 下 而 上 的 坐 标 系 统 不 同 , 一 些 图 形 环 境 使 用 自 上 而 下 的
坐 标 系 统 , 有 些 开 发 人 员 也 偏 爱 这 一 坐 标 系 统 。 可 以 使 用 PDFlib 的 转 换 函 数 轻 松 地 建 立 这
样 的 坐 标 系 统 。 不 过 , 由 于 转 换 也 将 影 响 文 本 输 出 , 因 此 需 要 附 加 的 调 用 以 避 免 文 本 显 示 时
出 现 镜 像 效 果 。
为 了 便 于 使 用 自 上 而 下 的 坐 标 , PDFlib 支 持 一 个 特 殊 的 模 式 , 在 这 种 模 式 下 将 对 所 有 相
关 的 坐 标 进 行 不 同 的 解 释 : 从 原 有 的 以 页 面 左 小 角 为 原 点 (0, 0), y 坐 标 向 上 增 加 的 PDF 默
认 坐 标 系 统 ; 改 为 以 页 面 左 上 角 为 原 点 (0, 0), y 坐 标 向 下 增 加 的 PDF 默 认 坐 标 系 统 。 使 用
topdown 参 数 可 以 激 活 此 自 上 而 下 的 坐 标 系 统 :
PDF_set_parameter(p, "topdown", "true")
每 页 可 以 建 立 不 同 的 坐 标 系 统 , 但 对 topdown 参 数 的 设 置 不 能 在 页 描 述 内 进 行 ( 仅 可 以 在
页 与 页 之 间 )。 topdown 功 能 是 为 了 让 PDFlib 用 户 在 自 上 而 下 的 坐 标 系 统 中 自 如 地 工 作 而
设 计 的 。 为 了 完 整 性 , 下 面 将 列 出 建 立 自 上 而 下 的 坐 标 系 统 对 不 同 坐 标 值 的 影 响 。
绝 对 坐 标 在 未 经 任 何 修 改 的 情 况 下 在 用 户 坐 标 系 统 中 使 用 :
> 这 包 括 在 函 数 说 明 中 指 定 为 坐 标 的 所 有 函 数 参 数 。 一 些 示 例 :PDF_moveto() 中 的 x, y ;
PDF_circle() 中 的 x, y ; PDF_rect() 中 的 x, y ( 但 不 是 width 和 height!); PDF_create_
annotation() 中 的 llx, lly, urx, ury。
以 下 的 相 对 坐 标 值 将 在 内 部 修 改 以 匹 配 自 上 而 下 系 统 :
> 文 本 ( 字 体 大 小 为 正 数 ) 将 面 向 页 面 顶 端 ;
> 当 手 册 中 谈 论 到 矩 形 、 方 框 等 的 左 下 角 时 , 这 将 被 解 释 为 您 在 页 面 上 实 际 看 到 的 图 形 的
左 下 角 ;
> 当 指 定 一 个 旋 转 角 度 时 , 旋 转 中 心 仍 是 用 户 坐 标 系 统 的 原 点 (0, 0)。 顺 时 针 方 向 旋 转 的 可
视 化 结 果 将 仍 是 顺 时 针 方 向 的 。
54 第 3 章 : PDFlib 编 程

3.2.2 页 面 大 小 和 坐 标 限 制
标 准 页 格 式 为 了 方 便 PDFlib 用 户 , 表 3.4 列 出 了 常 见 的 标 准 页 面 大 小 1 。 页 面 大 小 的 格 式 名
可 以 被 用 于 PDF_begin/end_page_ext( ) 中 的 width 和 height 选 项 。 它 们 称 作 .width
和 .height, 此 处 的 是 表 3.4 中 列 出 的 格 式 之 一 ( 用 小 写 字 母 表 示 , 例 如
a4.width)。
表 3.4 以 点 为 单 位 的 常 见 页 面 大 小 尺 寸
格 式 宽 度 高 度 格 式 宽 度 高 度 格 式 宽 度 高 度
a0 2380 3368 a4 595 842 letter 612 792
a1 1684 2380 a5 421 595 legal 612 1008
a2 1190 1684 a6 297 421 ledger 1224 792
a3 842 1190 a5 501 709 11x17 792 1224
页 面 大 小 限 制 虽 然 PDF 和 PDFlib 没 有 对 可 用 的 页 面 大 小 作 任 何 的 限 制 , 但 是 Acrobat 在
页 面 大 小 方 面 却 受 到 设 计 结 构 的 限 制 。 请 注 意 , 其 他 PDF 解 释 程 序 也 许 能 够 处 理 更 大 或 更
小 的 文 档 格 式 。 若 超 出 Acrobat 的 页 面 大 小 极 限 , 则 PDFlib 将 引 发 一 个 非 致 命 的 异 常 。
Acrobat 的 页 面 大 小 极 限 显 示 在 表 3.5 中 。
表 3.5 Acrobat 的 最 大 页 面 尺 寸 和 最 小 页 面 尺 寸
PDF 浏 览 器 最 小 页 面 尺 寸 最 大 页 面 尺 寸
Acrobat 4 及 以 上 版 本 1/24" = 3 pt = 0.106 cm 200" = 14400 pt = 508 cm
不 同 的 页 面 大 小 方 框 尽 管 许 多 PDFlib 开 发 人 员 仅 指 定 页 面 的 宽 度 和 高 度 , 但 是 一 些 高 级
应 用 程 序 ( 特 别 是 用 于 印 前 工 作 的 应 用 程 序 ) 可 能 需 要 指 定 一 个 或 多 个 额 外 的 PDF 的 方 框
项 。PDFlib 支 持 所 有 PDF 的 方 框 项 。 下 面 的 项 ( 在 某 些 环 境 下 可 能 有 用 ) 可 以 由 PDFlib 客
户 端 指 定 ( 从 PDF reference 中 获 取 定 义 ):
> MediaBox: 用 于 指 定 页 面 的 宽 度 和 高 度 , 即 我 们 通 常 所 说 的 页 面 大 小 。
> CropBox: 页 面 内 容 中 要 被 裁 剪 下 的 区 域 ; Acrobat 使 用 此 尺 寸 进 行 屏 幕 显 示 和 打 印 。
> TrimBox: 已 完 成 的 ( 可 能 是 已 裁 剪 下 的 ) 页 面 的 预 期 尺 寸 ;
> ArtBox: 页 面 中 有 意 义 内 容 的 范 围 。 应 用 程 序 软 件 很 少 使 用 它 ;
> BleedBox: 当 在 生 产 环 境 中 输 出 时 , 页 面 内 容 中 要 被 裁 剪 下 的 区 域 。 它 可 能 包 括 附 加 的
出 血 区 域 以 处 理 生 成 过 程 中 的 不 精 确 之 处 。
PDFlib 除 了 在 输 出 文 件 中 记 录 这 些 值 以 外 , 将 不 会 使 用 其 中 的 任 何 值 。 默 认 情 况 下 ,PDFlib
根 据 指 定 的 页 面 宽 度 和 高 度 生 成 MediaBox, 而 不 会 生 成 任 何 其 他 项 。 以 下 代 码 片 段 将 启 动
一 个 新 页 , 并 设 置 裁 剪 框 的 四 个 值 :
/* start a new page with custom CropBox */
PDF_begin_page_ext(p, 595, 842, "cropbox {10 10 500 800}");
文 档 中 页 面 的 数 目 在 PDFlib 中 , 对 于 文 档 中 生 成 的 页 面 的 数 目 没 有 限 制 。PDFlib 生 成 的
PDF 结 构 可 让 Acrobat 在 带 有 数 以 万 计 的 页 面 的 文 档 中 高 效 地 导 航 。
1. 有 关 ISO、 日 本 和 美 国 标 准 格 式 的 更 多 信 息 可 以 在 下 面 的 URL 上 找 到 :
home.inter.net/eds/paper/papersize.html、 www.cl.cam.ac.uk/~mgk25/iso-paper.html
3.2 页 面 说 明 55

输 出 准 确 性 和 坐 标 范 围 PDFlib 的 数 字 输 出 精 确 度 是 根 据 PDF 和 其 支 持 的 环 境 的 要 求 , 并
结 合 对 优 化 文 件 输 出 大 小 的 考 虑 而 仔 细 挑 选 的 。 正 如 表 3.6 中 详 细 描 述 的 一 样 ,PDFlib 的 精
确 度 取 决 于 坐 标 的 绝 对 值 。 虽 然 大 多 数 开 发 人 员 无 需 为 此 担 心 , 但 要 求 苛 刻 的 应 用 程 序 在 缩
放 操 作 中 应 当 注 意 不 要 超 出 PDF 的 内 置 坐 标 极 限 。
表 3.6 输 出 准 确 性 和 坐 标 范 围
绝 对 值
输 出
0 ... 0.000015 0
0.000015 ... 32767.999999 四 舍 五 入 为 四 位 小 数 位 数
32768 ... 2 31 - 1 四 舍 五 入 为 下 一 个 整 数
>= 2 31
将 引 发 异 常
3.2.3 路 径
路 径 是 由 任 意 数 目 的 直 线 、 矩 形 或 曲 线 构 成 的 一 种 形 状 。 路 径 可 以 包 含 一 些 断 开 的 部 分 ( 称
作 子 路 径 )。 有 一 些 操 作 可 用 于 路 径 处 理 ( 请 参 见 第 216 页 上 的 第 8.4.6 节 “ 路 径 绘 制 和 剪
切 ”):
> 描 边 就 是 使 用 客 户 端 提 供 的 绘 制 参 数 ( 例 如 颜 色 、 线 宽 ) 沿 着 路 径 绘 制 线 条 。
> 填 充 就 是 使 用 客 户 端 提 供 的 填 充 参 数 对 路 径 包 围 的 整 个 区 域 涂 色 。
> 剪 切 就 是 以 当 前 剪 切 区 域 ( 默 认 情 况 下 为 页 面 大 小 ) 与 路 径 包 围 区 域 的 相 交 区 域 替 换 当
前 剪 切 区 域 , 从 而 减 少 用 于 后 续 绘 制 操 作 的 成 像 区 域 。
> 断 然 终 止 路 径 将 导 致 不 可 见 的 路 径 , 不 过 该 路 径 仍 存 在 于 PDF 文 件 中 。 这 种 需 求 极 少 。
在 没 有 应 用 任 何 上 述 操 作 的 情 况 下 构 造 路 径 是 错 误 的 。 PDFlib 的 范 围 界 定 系 统 确 保 客 户 端
遵 从 此 限 制 。 如 果 您 需 要 设 置 路 径 的 任 何 外 观 属 性 ( 例 如 , 颜 色 、 线 宽 ), 则 必 须 在 开 始 执
行 任 何 绘 图 操 作 之 前 进 行 设 置 。 这 些 规 则 可 以 总 结 为 “ 不 要 在 更 改 路 径 描 述 内 改 变 外 观 ”。
仅 仅 构 造 路 径 不 会 在 页 面 上 显 示 任 何 内 容 ; 您 必 须 填 充 或 描 边 路 径 才 能 获 取 可 视 结 果 :
PDF_moveto(p, 100, 100);
PDF_lineto(p, 200, 100);
PDF_stroke(p);
3.2.4 模 板
大 多 数 图 形 函 数 都 利 用 了 当 前 点 的 概 念 , 当 前 点 可 看 作 是 用 于 绘 图 的 笔 的 位 置 。
PDF 中 的 模 板 PDFlib 支 持 一 种 在 技 术 上 称 为 “form XObjects” 的 PDF 功 能 。 不 过 , 由 于
此 术 语 与 交 互 式 表 格 存 在 冲 突 , 因 此 我 们 将 此 功 能 称 为 “ 模 板 ”。 可 以 将 PDFlib 模 板 看 作
一 个 离 页 缓 冲 区 , 文 本 、 矢 量 和 图 像 操 作 将 被 重 定 向 到 此 离 页 缓 冲 区 中 ( 而 不 在 常 规 页 上
操 作 )。 模 板 完 成 后 , 就 可 以 像 光 栅 图 像 一 样 使 用 , 并 可 以 在 任 意 页 上 放 置 任 意 次 数 。 与 图
像 一 样 , 模 板 也 可 以 被 几 何 转 换 ( 例 如 缩 放 或 斜 移 ) 。 当 在 多 个 页 面 上 ( 或 在 同 一 页 面 上
多 次 ) 使 用 同 一 模 板 时 , 用 于 构 造 模 板 的 实 际 PDF 运 算 符 只 需 在 PDF 文 件 中 包 含 一 次 , 因
此 可 减 小 PDF 输 出 文 件 的 大 小 。 模 板 适 用 于 在 一 些 页 面 上 反 复 出 现 的 元 素 , 例 如 保 持 不 变
的 背 景 、 公 司 徽 标 或 由 CAD 和 地 理 绘 图 软 件 绘 制 的 图 形 元 素 。 使 用 模 板 的 其 他 典 型 示 例 包
括 裁 剪 和 注 册 标 志 或 自 定 义 亚 洲 字 形 。
在 PDFlib 中 使 用 模 板 模 板 仅 可 以 在 页 面 描 述 以 外 被 定 义 , 但 可 以 在 页 面 描 述 内 使 用 。 不
过 , 模 板 也 可 以 包 含 其 他 模 板 。 但 不 能 包 含 自 身 。 可 以 通 过 使 用 PDF_fit_image( ) 函 数 在 页
面 上 引 用 已 定 义 的 模 板 , 如 同 在 页 面 上 放 置 图 像 一 样 ( 请 参 见 第 123 页 上 的 第 5.3 节 “ 放 置
图 像 和 导 入 的 PDF 页 ”)。 PDFlib 中 的 常 规 模 板 惯 用 法 如 下 所 示 :
56 第 3 章 : PDFlib 编 程

* define the template */
template = PDF_begin_template(p, template_width, template_height);
...place marks on the template using text, vector, and image functions...
PDF_end_template(p);
...
PDF_begin_page(p, page_width, page_height);
/* use the template */
PDF_fit_image(p, template, (float) 0.0, (float) 0.0, "");
...more page marking operations...
PDF_end_page(p);
...
PDF_close_image(p, template);
可 以 在 模 板 上 使 用 所 有 文 本 、 图 形 和 颜 色 函 数 。 不 过 , 构 造 模 板 下 列 函 数 禁 止 使 用 :
> 第 227 页 上 的 第 8.6 节 “ 图 像 和 模 板 函 数 ” 中 的 函 数 , 但 PDF_fit_image( ) 和 PDF_close_
image( ) 除 外 。 由 于 图 像 可 以 在 模 板 定 义 之 外 打 开 , 并 可 以 在 模 板 ( 但 是 未 打 开 ) 内 自 由
使 用 , 故 这 并 不 是 一 个 很 大 的 限 制 。
> 第 246 页 上 的 第 表 8.50 节 “PDF_add_nameddest( ) 的 目 标 选 项 以 及 PDF_create_
action( )、 PDF_create_annotation( )、 PDF_create_bookmark( ) 和 PDF_begin/end_
document( ) 中 的 目 标 选 项 ” 中 的 函 数 。 超 文 本 元 素 必 须 总 是 在 所 出 现 的 文 档 页 上 进 行 定
义 , 而 不 能 作 为 模 板 的 一 部 分 生 成 。
第 三 方 软 件 中 的 模 板 支 持 模 板 (form XObjects) 是 PDF 规 范 的 一 个 不 可 分 的 部 分 , 可
以 使 用 Acrobat 完 全 查 看 和 打 印 。 不 过 , 不 是 所 有 的 PDF 用 户 都 准 备 好 处 理 此 构 造 。 例 如 ,
Acrobat 增 效 工 具 Enfocus PitStop 5.0 只 能 移 动 模 板 , 而 不 能 访 问 模 板 内 的 单 个 元 素 。 另 一
方 面 , Adobe Illustrator 9 和 10 完 全 支 持 模 板 。
3.3 使 用 颜 色
3.3.1 颜 色 和 色 彩 空 间
PDFlib 客 户 端 可 以 指 定 用 于 填 充 和 描 边 路 径 内 部 和 文 本 字 符 的 颜 色 。 可 以 使 用 几 个 色 彩 空
间 指 定 颜 色 :
> 介 于 0 ( 表 示 黑 色 ) 和 1 ( 表 示 白 色 ) 之 间 的 灰 度 值 ;
> RGB 三 原 色 组 合 , 即 用 于 指 定 红 色 (red)、 绿 色 (green) 和 蓝 色 (blue) 的 百 分 比 的 介 于 0
和 1 之 间 的 三 个 值 ; 其 中 , (0, 0, 0) 表 示 黑 色 , (1, 1, 1) 表 示 白 色 。
> 介 于 0( 表 示 无 颜 色 ) 和 1( 表 示 完 全 色 ) 之 间 的 四 个 CMYK 值 , 分 别 表 示 青 色 (cyan)、
洋 红 色 (magenta)、 黄 色 (yellow) 和 黑 色 (black) 值 ; 其 中 ,(0, 0, 0, 0) 表 示 白 色 ,(0, 0,
0, 1) 表 示 黑 色 。 请 注 意 , 这 不 同 于 RGB 规 范 。
> CIE L*a*b* 色 彩 空 间 内 独 立 于 设 备 的 颜 色 由 一 个 在 0-100 范 围 内 的 亮 度 值 和 两 个 在 -127
到 128 范 围 内 的 颜 色 值 指 定 ( 请 参 见 第 60 页 上 的 第 3.3.4 节 “ 色 彩 管 理 和 ICC 配 置 文
件 ”)。
> 在 ICC 配 置 文 件 的 帮 助 下 , 指 定 基 于 ICC 的 颜 色 ( 请 参 见 第 60 页 上 的 第 3.3.4 节 “ 色 彩
管 理 和 ICC 配 置 文 件 ”)。
> 专 色 ( 分 色 色 彩 空 间 ): 一 个 预 定 义 或 任 意 命 名 的 自 定 义 颜 色 表 示 以 上 色 彩 空 间 的 某 一
颜 色 ; 通 常 用 于 为 打 算 在 使 用 一 种 或 多 种 自 定 义 颜 色 的 胶 印 机 上 印 刷 文 档 作 准 备 。 色 调
值 ( 百 分 比 ) 范 围 是 从 0 ( 表 示 无 颜 色 ) 到 1 ( 表 示 专 色 最 大 亮 度 )。 有 关 专 色 名 称 的
列 表 , 请 参 见 第 58 页 上 的 第 3.3.3 节 “ 专 色 ”。
> 图 案 : 平 铺 由 任 意 文 本 、 矢 量 或 图 像 图 形 组 成 的 对 象 ( 请 参 见 第 58 页 上 的 第 3.3.2 节
“ 图 案 和 平 滑 着 色 ”)。
3.3 使 用 颜 色 57

着 色 ( 平 滑 混 合 ) 提 供 基 于 另 一 色 彩 空 间 的 两 种 颜 色 之 间 的 逐 渐 过 渡 ( 请 参 见 第 58 页
上 的 第 3.3.2 节 “ 图 案 和 平 滑 着 色 ”)。
> 索 引 色 彩 空 间 本 身 不 是 真 正 的 色 彩 色 空 间 , 而 是 其 他 色 彩 空 间 的 有 效 编 码 。 当 导 入 索 引
( 基 于 调 色 板 ) 图 像 时 , 将 自 动 生 成 索 引 色 彩 空 间 。
描 边 和 填 充 操 作 的 默 认 颜 色 是 黑 色 。
3.3.2 图 案 和 平 滑 着 色
作 为 对 纯 色 的 补 充 , 图 案 和 着 色 是 可 以 用 于 填 充 或 描 边 任 意 对 象 的 特 殊 种 类 的 颜 色 。
图 案 图 案 是 任 意 数 目 的 绘 图 操 作 组 合 成 的 单 一 实 体 。 这 组 对 象 可 以 被 任 意 的 复 制 ( 或 平
铺 ) 直 至 整 个 区 域 被 填 充 或 描 边 。 使 用 图 案 涉 及 以 下 步 骤 :
> 首 先 , 必 须 在 PDF_begin_pattern( ) 和 PDF_end_pattern( ) 之 间 定 义 图 案 。 大 多 数 图 形 运
算 符 都 可 以 用 于 定 义 图 案 。
> 由 PDF_begin_pattern( ) 返 回 的 图 案 句 柄 可 以 通 过 使 用 PDF_setcolor( ) 将 图 案 设 置 为 当 前
颜 色 。
图 案 定 义 可 能 会 也 可 能 不 会 包 含 其 自 身 的 颜 色 规 范 , 这 取 决 于 PDF_begin_pattern( ) 的
painttype 参 数 。 若 painttype 为 1, 则 图 案 定 义 包 含 其 自 身 的 颜 色 规 范 并 且 外 观 总 是 保 持 相
同 ; 若 painttype 为 2, 则 图 案 定 义 禁 止 包 含 任 何 颜 色 规 范 。 反 之 , 用 当 前 填 充 或 描 边 颜 色
进 行 填 充 和 描 边 。
注 : 也 可 以 基 于 平 滑 着 色 定 义 图 案 ( 请 参 见 以 下 内 容 )。
平 滑 着 色 平 滑 着 色 也 称 作 “ 颜 色 混 合 ” 或 “ 渐 变 ”, 提 供 从 一 种 颜 色 到 另 一 种 颜 色 的 连
续 过 渡 。 且 这 两 种 颜 色 必 须 属 于 同 一 色 彩 空 间 。PDFlib 支 持 用 于 平 滑 着 色 的 两 种 不 同 种 类 的
几 何 形 状 :
> 轴 向 着 色 沿 直 线 定 义 ;
> 辐 射 着 色 在 两 个 圆 形 之 间 定 义 。
着 色 是 两 种 颜 色 之 间 的 过 渡 。 总 是 将 第 一 种 颜 色 作 为 当 前 填 充 颜 色 ; 第 二 种 颜 色 在
PDF_shading( ) 的 c1、 c2、 c3 和 c4 参 数 中 提 供 。 这 些 数 值 将 根 据 第 一 种 颜 色 的 色 彩 空 间
PDF_setcolor( ) 的 描 边 做 解 释 。
调 用 PDF_shading( ) 将 返 回 处 理 某 个 着 色 对 象 的 句 柄 , 可 以 按 以 下 两 种 方 式 使 用 该 句 柄 :
> 使 用 PDF_shfill( ) 填 充 一 个 区 域 。 当 要 填 充 的 对 象 的 几 何 形 状 与 着 色 的 几 何 形 状 相 同 时 ,
可 以 使 用 此 方 法 。 与 其 名 称 相 反 , 此 函 数 不 仅 将 填 充 对 象 内 部 , 而 且 还 会 影 响 外 部 。 使
用 PDF_clip( ) 可 以 修 改 此 行 为 。
> 定 义 一 个 可 用 于 填 充 更 多 复 杂 对 象 的 着 色 图 案 。 这 就 需 要 调 用 PDF_shading_pattern( ) 以
创 建 基 于 着 色 的 图 案 , 并 用 该 图 案 填 充 或 描 边 任 意 对 象 。
3.3.3 专 色
PDFlib 支 持 专 色 ( 技 术 上 称 为 PDF 中 的 分 色 色 彩 空 间 , 尽 管 “ 分 色 ” 这 个 术 语 通 常 也 与 印
刷 色 一 起 使 用 ), 专 色 可 以 用 于 印 刷 超 出 印 刷 混 合 色 范 围 之 外 的 自 定 义 颜 色 。 专 色 是 根 据 名
称 指 定 的 , 在 PDF 中 , 总 是 附 有 一 种 与 专 色 接 近 但 不 完 全 类 似 的 替 代 颜 色 。Acrobat 将 使 用
此 替 代 颜 色 进 行 屏 幕 显 示 和 输 出 到 不 支 持 专 色 的 设 备 ( 例 如 办 公 用 的 普 通 打 印 机 )。 在 印 刷
时 , 除 了 文 档 中 可 能 使 用 的 任 何 印 刷 色 之 外 , 还 将 应 用 要 求 的 专 色 。 这 就 需 要 通 过 一 种 称 作
“ 分 色 ” 的 过 程 对 PDF 文 件 进 行 后 处 理 。
注 : 在 已 打 开 “ 叠 印 预 览 ” 的 情 况 下 , 使 用 Acrobat 5 在 屏 幕 上 无 法 正 确 显 示 一 些 专 色 。 但 这 些
专 色 可 以 正 确 地 分 色 和 打 印 。
58 第 3 章 : PDFlib 编 程

PDFlib 支 持 各 种 内 置 专 色 库 , 也 支 持 自 定 义 ( 用 户 定 义 的 ) 专 色 。 当 使 用 PDF_makespotcolor( )
请 求 一 个 专 色 名 称 时 ,PDFlib 首 先 将 检 查 在 其 内 置 库 中 是 否 可 以 找 到 请 求 的 专 色 。 如 果 能 够
找 到 ,PDFlib 将 对 替 代 颜 色 使 用 内 置 值 。 否 则 , 将 假 定 该 专 色 为 用 户 定 义 的 颜 色 , 客 户 端 必
须 提 供 适 当 的 替 代 颜 色 值 ( 通 过 当 前 颜 色 )。 专 色 可 以 减 淡 , 即 可 以 与 0 和 1 之 间 的 百 分 比
一 起 使 用 。
默 认 情 况 下 , 不 能 使 用 自 定 义 替 代 值 重 新 定 义 内 置 专 色 。 不 过 , 可 以 使 用 spotcolorlookup
参 数 更 改 此 行 为 。 这 对 实 现 与 早 期 应 用 程 序 ( 可 能 使 用 了 不 同 的 颜 色 定 义 ) 的 兼 容 性 , 以
及 对 于 无 法 处 理 Pantone 颜 色 的 PDFlib 的 Lab 替 代 值 的 工 作 流 来 说 , 会 很 有 用 。
当 选 定 PDF/X 规 范 等 级 后 , PDFlib 将 为 内 置 专 色 自 动 生 成 适 合 的 替 代 颜 色 ( 请 参 见
第 155 页 上 的 第 7.4 节 “PDF/X”)。 对 于 自 定 义 专 色 , 用 户 需 要 负 责 提 供 与 选 定 的 PDF/
X 规 范 等 级 兼 容 的 替 代 颜 色 。
注 : 内 置 专 色 数 据 和 相 应 的 商 标 已 经 由 PDFlib GmbH 从 各 自 的 商 标 所 有 者 那 里 得 到 了 授 权 , 可
以 在 PDFlib 软 件 中 使 用 。
PANTONE® 专 色 PANTONE 专 色 很 有 名 , 并 在 全 世 界 范 围 内 被
广 泛 使 用 。 PDFlib 完 全 支 持 PANTONE MATCHING SYSTEM®
( 总 计 有 20 000 个 色 板 )。 可 以 使 用 以 下 数 字 颜 色 库 中 的 所 有
色 板 名 称 ( 括 号 中 提 供 了 一 些 示 例 色 板 名 称 ):
> PANTONE solid coated (PANTONE 185 C)
> PANTONE solid uncoated (PANTONE 185 U)
> PANTONE solid matte (PANTONE 185 M)
> PANTONE process coated (PANTONE DS 35-1 C)
> PANTONE process uncoated (PANTONE DS 35-1 U)
> PANTONE process coated EURO (PANTONE DE 35-1 C)
> PANTONE pastel coated (PANTONE 9461 C)
> PANTONE pastel uncoated (PANTONE 9461 U)
> PANTONE metallic coated (PANTONE 871 C)
> PANTONE solid to process coated (PANTONE 185 PC)
> PANTONE solid to process coated EURO (PANTONE 185 EC)
> PANTONE hexachrome® coated (PANTONE H 305-1 C)
> PANTONE hexachrome® uncoated (PANTONE H 305-1 U)
> PANTONE solid in hexachrome coated (PANTONE 185 HC)
PDFlib 商 业 用 户 可 以 向 我 们 请 求 一 个 列 出 了 全 部 Pantone 专 色 名 称 的 文 本 文 件 。
专 色 名 称 区 分 大 小 写 ; 如 示 例 中 所 示 , 使 用 大 写 字 母 。 也 将 接 受 旧 式 颜 色 名 称 前 缀 CV、
CVV、CVU、CVC 和 CVP, 并 将 其 更 改 为 相 应 的 新 颜 色 名 称 , 除 非 preserveoldpantonenames
参 数 为 true。 如 示 例 中 所 示 , 必 须 总 是 在 色 板 名 称 中 提 供 PANTONE 前 缀 。 通 常 , 必 须 根 据
以 下 方 案 构 造 PANTONE 颜 色 名 称 :
PANTONE
此 处 , 是 颜 色 的 标 识 符 ( 例 如 185), 是 使 用 的 纸 张 的 缩 写 ( 例 如 , C 表
示 涂 层 纸 ) 。 在 构 成 色 板 名 称 的 各 个 部 分 之 间 必 须 使 用 一 个 空 格 字 符 。 在 请 求 一 个 以
PANTONE 前 缀 开 头 的 专 色 名 称 时 , 如 果 该 名 称 不 代 表 一 个 有 效 PANTONE 颜 色 , 则 将 导 致
一 个 非 致 命 的 异 常 ( 通 过 将 warning 参 数 设 置 为 false 可 以 禁 止 此 异 常 )。 以 下 代 码 片 段 演
示 如 何 使 用 色 调 值 为 70% 的 PANTONE 专 色 :
spot = PDF_makespotcolor(p, "PANTONE 281 U", 0);
PDF_setcolor(p, "fill", "spot", spot, 0.7, 0, 0);
3.3 使 用 颜 色 59

注 : 此 处 显 示 的 PANTONE® 专 色 可 能 与 PANTONE 标 识 的 标 准 不 符 。 请 参 考 最 新 的 PANTONE 专 色
出 版 物 获 取 准 确 的 颜 色 。 PANTONE® 以 及 其 他 Pantone, Inc. 商 标 为 Pantone, Inc. 所 有 。 版 权
所 有 © Pantone, Inc., 2003。
注 : PANTONE® 专 色 在 PDF/X-1:2001、 PDF/X-1a:2001 和 PDF/X-1a:2003 标 准 模 式 下 不 受 支 持 。
HKS® 专 色 HKS 专 色 系 统 在 德 国 和 其 他 欧 洲 国 家 被 广 泛 使 用 。
PDFlib 完 全 支 持 HKS 专 色 。 可 以 使 用 以 下 数 字 颜 色 库 (Farbfächer)
中 的 所 有 色 板 名 称 ( 括 号 中 提 供 了 一 些 示 例 色 板 名 称 ):
> HKS K (Kunstdruckpapier) 用 于 光 面 艺 术 纸 , 88 种 专 色
(HKS 43 K)
> HKS N (Naturpapier) 用 于 天 然 纸 , 86 种 专 色 (HKS 43 N)
> HKS E (Endlospapier) 用 于 连 续 静 物 , 88 种 专 色 (HKS 43 E)
> HKS Z (Zeitungspapier) 用 于 新 闻 纸 , 50 种 专 色 (HKS 43 Z)
PDFlib 商 业 用 户 可 以 向 我 们 索 取 一 个 列 出 了 全 部 HKS 专 色 名 称 的 文 本 文 件 。
专 色 名 称 区 分 大 小 写 ; 如 示 例 中 所 示 , 使 用 大 写 字 母 。 如 示 例 中 所 示 , 必 须 总 是 在 色 板
名 称 中 提 供 HKS 前 缀 。 通 常 , 必 须 根 据 以 下 方 案 构 造 HKS 专 色 名 称 :
HKS
此 处 , 是 颜 色 的 标 识 符 ( 例 如 43), 是 使 用 的 纸 张 的 缩 写 ( 例 如 , N 表
示 天 然 纸 )。 在 构 成 色 板 名 称 的 HKS、 和 各 个 部 分 之 间 必 须 使 用 一 个 空 格
字 符 。 在 请 求 一 个 以 HKS 前 缀 开 头 的 专 色 名 称 时 , 如 果 该 名 称 不 代 表 一 个 有 效 HKS 专 色 ,
则 将 导 致 一 个 非 致 命 的 异 常 ( 通 过 将 warning 参 数 设 置 为 false 可 以 禁 用 此 异 常 )。 以 下 代
码 片 段 演 示 如 何 使 用 色 调 值 为 70% 的 HKS 颜 色 :
spot = PDF_makespotcolor(p, "HKS 38 E", 0);
PDF_setcolor(p, "fill", "spot", spot, 0.7, 0, 0);
用 户 定 义 的 专 色 除 了 以 上 详 细 介 绍 的 内 置 专 色 之 外 , PDFlib 还 支 持 自 定 义 专 色 。 可 以 为
这 些 自 定 义 专 色 指 定 一 个 任 意 名 称 ( 此 名 称 不 得 与 任 何 内 置 颜 色 的 名 称 发 生 冲 突 ) 和 一 个
替 代 颜 色 。 替 代 颜 色 将 用 于 屏 幕 预 览 或 低 质 量 打 印 , 但 是 不 能 用 于 高 质 量 分 色 。 客 户 端 需 要
负 责 为 自 定 义 专 色 提 供 合 适 的 替 代 颜 色 。
PDFlib 没 有 提 供 单 独 的 为 新 的 专 色 设 置 替 代 颜 色 的 PDFlib 函 数 , 但 可 使 用 当 前 填 充 颜
色 完 成 。 除 了 使 用 附 加 调 用 设 置 替 代 颜 色 以 外 , 定 义 和 使 用 自 定 义 专 色 与 使 用 内 置 专 色 的 方
法 类 似 :
PDF_setcolor(p, "fill", "cmyk", 0.2, 1.0, 0.2, 0); /* define alternate CMYK values */
spot = PDF_makespotcolor(p, "CompanyLogo", 0); /* derive a spot color from it */
PDF_setcolor(p, "fill", "spot", spot, 1, 0, 0); /* set the spot color */
3.3.4 色 彩 管 理 和 ICC 配 置 文 件
PDFlib 支 持 一 些 色 彩 管 理 概 念 , 包 括 独 立 于 设 备 的 颜 色 、 渲 染 方 法 和 ICC 配 置 文 件 。
独 立 于 设 备 的 CIE L*a*b* 颜 色 通 过 对 PDF_setcolor( ) 提 供 色 彩 空 间 名 称 lab, 可 以 在
CIE 1976 L*a*b* 色 彩 空 间 中 指 定 独 立 于 设 备 的 颜 色 值 。 可 以 用 范 围 在 0-100 的 亮 度 值 和 两 个
范 围 在 -127 到 128 之 间 的 颜 色 值 指 定 L*a*b* 色 彩 空 间 中 的 颜 色 。 用 于 lab 色 彩 空 间 的 光 源 将
为 D50 ( 日 光 5000K, 2˚ 观 察 者 )
60 第 3 章 : PDFlib 编 程

渲 染 方 法 虽 然 PDFlib 客 户 端 可 以 指 定 独 立 于 设 备 的 颜 色 值 , 但 是 特 定 的 输 出 设 备 不 一 定
能 够 准 确 地 再 现 所 需 的 颜 色 。 在 这 种 情 况 下 , 必 须 通 过 一 个 称 作 “ 色 域 压 缩 ” 的 过 程 针 对 折
衷 方 案 做 出 一 些 妥 协 , 即 将 颜 色 的 范 围 减 少 到 特 定 设 备 可 以 再 现 的 一 个 较 小 的 范 围 。 渲 染 方
法 可 以 用 于 管 理 这 个 过 程 。 通 过 将 renderingintent 参 数 或 选 项 提 供 给 PDF_load_image( ), 可
以 指 定 各 个 图 像 的 渲 染 方 法 。 另 外 , 通 过 将 renderingintent 选 项 提 供 给 PDF_create_
gstate( ), 可 以 为 文 本 和 矢 量 图 形 指 定 渲 染 方 法 。 表 3.7 列 出 了 可 用 的 渲 染 方 法 及 其 含 义 。
表 3.7 渲 染 方 法
渲 染 方 法 说 明 典 型 使 用
Auto
不 在 PDF 文 件 中 指 定 任 何 渲 染 方 法 , 而 改 为 使 用 设 备 的 未 知 或 非 特 定 的 使 用
默 认 渲 染 方 法 。 这 是 默 认 设 置 。
AbsoluteColorimetric 未 对 设 备 的 白 点 ( 例 如 白 纸 ) 做 出 任 何 校 正 。 色 域 外 的
颜 色 都 将 映 射 为 设 备 的 色 域 内 最 接 近 的 值 。
RelativeColorimetric 颜 色 数 据 缩 放 到 设 备 的 色 域 内 , 当 轻 微 地 移 位 颜 色 时 ,
映 射 到 另 外 一 个 白 点 。
纯 色 的 准 确 再 现 ; 不 建 议 作
其 他 使 用 。
矢 量 图 形
Saturation 当 颜 色 值 可 能 被 移 位 时 , 将 保 存 颜 色 的 饱 和 度 。 商 业 图 形
Perceptual
通 过 修 改 色 域 内 和 色 域 外 的 颜 色 保 留 颜 色 关 系 , 以 提 供 扫 描 的 图 像
愉 悦 的 外 观 。
ICC 配 置 文 件 International Color Consortium (ICC) 1 定 义 了 一 种 用 来 指 定 输 入 和 输 出 设
备 的 颜 色 特 征 的 文 件 格 式 。 这 些 ICC 配 置 文 件 已 被 作 为 产 业 标 准 , 受 到 所 有 主 要 的 色 彩 管 理
系 统 和 应 用 程 序 厂 商 的 支 持 。 在 以 下 一 些 领 域 , PDFlib 支 持 带 ICC 配 置 文 件 的 颜 色 管 理 :
> 为 页 面 上 文 本 和 矢 量 图 形 定 义 基 于 ICC 的 色 彩 空 间 。
> 处 理 嵌 入 到 导 入 的 图 像 文 件 中 的 ICC 配 置 文 件 。
> 将 一 ICC 配 置 文 件 用 于 导 入 的 图 像 ( 可 能 会 覆 盖 已 嵌 入 图 像 中 的 ICC 配 置 文 件 )。
> 定 义 默 认 色 彩 空 间 以 便 将 灰 度 、 RGB 或 CMYK 数 据 映 射 到 基 于 ICC 的 色 彩 空 间 。
> 通 过 外 部 ICC 配 置 文 件 定 义 PDF/X 输 出 方 法 。
色 彩 管 理 不 会 更 改 色 彩 规 范 中 色 彩 成 分 的 数 目 ( 例 如 从 RGB 到 CMYK)。
搜 索 ICC 配 置 文 件 PDFlib 将 使 用 提 供 给 PDF_load_iccprofile( ) 的 profilename 参 数 , 按 照
以 下 步 骤 搜 索 ICC 配 置 文 件 :
> 若 profilename = sRGB,PDFlib 将 使 用 其 内 部 的 sRGB 描 述 文 件 ( 请 参 见 以 下 内 容 ) 并 终
止 搜 索 。
> 检 查 在 ICCProfile 资 源 类 别 中 是 否 有 一 个 名 为 profilename 的 资 源 。 如 果 有 , 则 在 以 下 步
骤 中 , 将 其 值 用 作 文 件 名 称 。 如 果 没 有 此 类 资 源 , 则 直 接 使 用 profilename 作 为 文 件 名 称 。
> 使 用 在 前 一 步 骤 中 确 定 的 文 件 名 称 结 合 以 下 组 合 来 查 找 磁 盘 文 件 :
.icc
.icm
/
/.icc
/.icm
在 Windows 2000/XP 上 ,colordir 指 定 操 作 系 统 用 来 存 储 特 定 于 设 备 的 ICC 配 置 文 件 的
目 录 ( 通 常 是 C:\WINNT\system32\spool\drivers\ color)。 在 Mac OS X 上 , 将 对
colordir 尝 试 以 下 路 径 :
1. 请 参 见 www.color.org
3.3 使 用 颜 色 61

System/Library/ColorSync/Profiles
/Library/ColorSync/Profiles
/Network/Library/ColorSync/Profiles
~/Library/ColorSync/Profiles
在 其 他 系 统 上 , 将 省 略 与 colordir 有 关 的 步 骤 。
可 接 受 的 ICC 配 置 文 件 可 接 受 的 ICC 配 置 文 件 的 类 型 取 决 于 提 供 给 PDF_load_iccprofile( )
的 usage 参 数 :
> 若 usage = outputintent, 则 仅 接 受 输 出 设 备 ( 打 印 机 ) 配 置 文 件 。
> 若 usage = iccbased, 则 接 受 输 入 设 备 、 显 示 设 备 和 输 出 设 备 ( 扫 描 仪 、 显 示 器 和 打 印
机 ) 配 置 文 件 以 及 色 彩 空 间 转 换 配 置 文 件 。 可 以 在 灰 色 、 RGB、 CMYK 或 Lab 色 彩 空 间
中 指 定 这 些 配 置 文 件 。
sRGB 色 彩 空 间 和 sRGB ICC 配 置 文 件 PDFlib 支 持 称 作 “sRGB”( 正 式 名 称 为 IEC 61966-
2-1) 的 产 业 标 准 RGB 色 彩 空 间 。sRGB 受 到 各 种 软 件 和 硬 件 厂 商 的 支 持 , 并 被 广 泛 用 于 消 费
型 RGB 设 备 的 简 化 颜 色 管 理 。 这 些 设 备 的 示 例 有 数 码 相 机 和 办 公 设 备 ( 如 彩 色 打 印 机 和 显
示 器 )。 PDFlib 支 持 sRGB 色 彩 空 间 , 并 且 在 内 部 包 含 必 需 的 ICC 配 置 文 件 数 据 。 因 此 , 客
户 端 在 使 用 sRGB 描 述 文 件 时 无 需 且 不 可 加 入 任 何 其 他 附 加 配 置 。 该 文 件 可 通 过 PDF_load_
iccprofile( ), 并 设 置 profilename = sRGB 而 调 用 。
在 图 像 中 使 用 嵌 入 的 配 置 文 件 (ICC 标 记 的 图 像 ) 有 些 图 像 可 能 包 含 嵌 入 的 ICC 配 置 文
件 , 用 于 说 明 图 像 的 颜 色 值 的 本 质 。 例 如 , 嵌 入 的 ICC 配 置 文 件 可 以 说 明 用 于 产 生 图 像 数 据
的 扫 描 仪 的 颜 色 特 征 。PDFlib 可 以 处 理 PNG、JPEG 和 TIFF 图 像 文 件 格 式 中 嵌 入 的 ICC 配 置
文 件 。 若 honoriccprofile 选 项 或 参 数 设 置 为 true ( 此 为 默 认 情 况 ), 则 图 像 中 嵌 入 的 ICC 配
置 文 件 将 从 该 图 像 中 被 提 取 , 并 嵌 入 到 PDF 输 出 中 , 以 便 Acrobat 将 其 应 用 到 该 图 像 。 有
时 , 此 过 程 称 为 标 记 着 ICC 配 置 文 件 的 图 像 ”。 PDFlib 将 不 会 改 变 图 像 的 像 素 值 。
使 用 image:iccprofile 参 数 可 获 得 嵌 于 图 像 中 的 ICC 配 置 文 件 句 柄 。 这 对 于 多 个 图 像 应 用
同 一 个 描 述 文 件 的 情 况 会 有 用 。
为 了 检 查 未 知 ICC 配 置 文 件 中 色 彩 成 分 的 数 目 , 请 使 用 icccomponents 参 数 。
对 图 像 应 用 外 部 ICC 配 置 文 件 ( 标 记 ) 作 为 使 用 图 像 中 嵌 入 的 ICC 配 置 文 件 的 一 种 替 代
方 式 , 也 可 以 通 过 提 供 一 个 配 置 文 件 句 柄 和 PDF_load_image( ) 的 iccprofile 选 项 对 单 个 图 像
使 用 外 部 配 置 文 件 。
用 于 页 面 说 明 的 基 于 ICC 的 色 彩 空 间 文 本 和 矢 量 图 像 基 于 ICC 的 色 彩 空 间 的 颜 色 值 可 直
接 通 过 配 置 文 件 指 定 。 配 置 ICC 配 置 文 件 句 柄 提 供 给 setcolor: iccprofilegray、 setcolor:
iccprofilergb 或 setcolor: iccprofilecmyk 参 数 来 设 置 色 彩 空 间 。 紧 接 着 , 可 以 将 基 于 ICC 的
颜 色 值 连 同 色 彩 空 间 关 键 字 iccbasedgray、 iccbasedrgb 或 iccbasedcmyk 提 供 给 PDF_
setcolor( ) :
icchandle = PDF_load_iccprofile(...)
if (icchandle == -1) {
return;
}
PDF_set_value(p, "setcolor:iccprofilecmyk", icchandle);
PDF_setcolor(p, "fill", "iccbasedcmyk", 0, 1, 0, 0);
将 设 备 颜 色 映 射 到 基 于 ICC 的 默 认 色 彩 空 间 PDF 提 供 了 一 个 功 能 , 可 以 将 页 面 说 明 中 的 设
备 相 关 的 灰 色 、 RGB 或 CMYK 颜 色 映 射 到 与 设 备 无 关 的 颜 色 。 即 对 与 设 备 相 关 的 颜 色 附 加 精
确 的 比 色 规 范 。 这 一 颜 色 值 映 射 可 通 过 提 供 DefaultGray、DefaultRGB 或 DefaultCMYK 色 彩
62 第 3 章 : PDFlib 编 程

空 间 定 义 来 实 现 。 在 PDFlib 中 , 可 以 通 过 设 置 defaultgray、 defaultrgb 或 defaultcmyk 参 数 并
提 供 ICC 配 置 文 件 句 柄 作 为 相 应 的 值 , 完 成 此 操 作 。 以 下 示 例 将 sRGB 色 彩 空 间 设 置 为 文 本 、
图 像 和 矢 量 图 形 的 默 认 RGB 色 彩 空 间 :
icchandle = PDF_load_iccprofile(p, "sRGB", 0, "usage=iccbased");
if (icchandle == -1) {
return;
}
PDF_set_value(p, "defaultrgb", icchandle);
定 义 PDF/X 输 出 方 法 输 出 设 备 ( 打 印 机 ) 配 置 文 件 可 以 用 于 指 定 PDF/X 的 输 出 条 件 。 这
可 以 在 对 PDF_load_iccprofile( ) 的 调 用 中 提 供 usage = outputintent 来 实 现 。 有 关 详 细 信 息 ,
请 参 见 第 155 页 上 的 第 7.4.2 节 “ 生 成 符 合 PDF/X 标 准 的 输 出 ”。
3.4 超 文 本 元 素
3.4.1 创 建 超 文 本 元 素 的 示 例
本 节 解 释 如 何 创 建 超 文 本 元 素 ( 如 书 签 、 表 单 域 和 注 释 )。 图 3.2 显 示 了 包 含 我 们 将 在 本 节
中 创 建 的 所 有 超 文 本 元 素 的 结 果 文 档 。 该 文 档 包 含 以 下 超 文 本 元 素 :
> 在 页 面 的 右 上 角 , 文 本 www.pdflib.com 处 有 一 个 不 可 见 的 Web 链 接 。 单 击 此 区 域 将 打
开 一 个 相 关 网 页 。
> Web 链 接 之 下 有 一 个 文 本 类 型 的 灰 色 表 单 域 。 通 过 使 用 JavaScript 代 码 , 将 自 动 使 用 当
前 日 期 填 充 该 表 单 域 。
> 红 色 图 钉 包 含 带 有 一 个 附 件 的 注 释 。 单 击 此 图 钉 将 打 开 附 加 的 文 件 。
> 在 页 面 的 左 下 角 , 有 一 个 带 有 打 印 机 符 号 的 按 钮 类 型 的 表 单 域 。 单 击 此 按 钮 将 执 行
Acrobat 的 菜 单 项 “ 文 件 ” -> “ 打 印 ”。
> 该 导 航 页 包 含 书 签 “Our Paper Planes Catalog”。 单 击 此 书 签 将 打 开 另 一 页 PDF 文 档 。
在 下 一 个 段 落 中 , 我 们 将 详 细 说 明 如 何 使 用 PDFlib 创 建 这 些 超 文 本 元 素 。
Web 链 接 让 我 们 从 网 站 www.pdflib.com 的 链 接 开 始 。 此 操 作 分 为 两 步 完 成 。 第 一 步 , 我
们 创 建 URI 类 型 的 操 作 ( 在 Acrobat 中 : 打 开 一 个 Web 链 接 )。 这 将 为 我 们 提 供 一 个 操 作
句 柄 , 随 后 可 将 该 句 柄 指 定 给 一 个 或 多 个 超 文 本 元 素 :
web_action = PDF_create_action(p, "URI", "url http://www.pdflib.com");
图 3.2
包 含 超 文 本 元 素 的 文 档
3.4 超 文 本 元 素 63

第 二 步 , 我 们 创 建 实 际 的 链 接 。 PDF 中 的 链 接 是 一 个 Link 类 型 的 注 释 。 该 链 接 的 action 选
项 包 含 将 触 发 操 作 的 事 件 名 称 activate 以 及 上 面 为 操 作 自 身 创 建 的 web_action 句 柄 :
sprintf(optlist, "linewidth=0 action {activate %d}", web_action);
PDF_create_annotation (p, left_x, left_y, right_x, right_y, "Link", optlist);
默 认 情 况 下 , 将 使 用 一 个 细 的 黑 色 边 框 显 示 该 链 接 。 最 初 , 准 确 定 位 非 常 方 便 , 但 是 我 们 使
用 linewidth=0 禁 用 边 框 。
作 为 一 种 选 择 方 式 , 您 可 以 按 如 下 方 式 使 用 weblink 选 项 调 用 PDF_fit_textline( ) 来 创 建
文 本 输 出 和 链 接 注 释 :
PDF_fit_textline(p, "http://www.pdflib.com", x, y, "position=50 underline"
"weblink {linewidth=1 annotcolor={rgb 1 0 0 }} fillcolor={rgb 0 0 1}");
用 于 跳 转 到 另 一 文 件 的 书 签 现 在 我 们 来 创 建 书 签 “Our Paper Planes Catalog”, 该 书 签
可 跳 转 到 另 一 个 名 为 paper_planes_catalog.pdf 的 PDF 文 件 。 首 先 我 们 创 建 一 个 GoToR 类 型
的 操 作 。 在 此 操 作 的 选 项 列 表 中 , 我 们 使 用 filename 选 项 定 义 目 标 文 档 的 名 称 ; destination
选 项 指 定 将 要 扩 大 的 页 面 的 某 个 部 分 。 更 准 确 地 说 , 文 档 将 使 用 固 定 视 图 (type fixed) 显 示
在 第 二 页 (page 2) 上 , 在 此 视 图 中 , 页 面 的 中 间 部 分 可 见 (left 50 top 200) 并 且 缩 放 因 子 为
200% (zoom 2):
char optlist[256] =
"filename paper_planes_catalog.pdf "
"destination {page 2 type fixed left 50 top 200 zoom 2}"
goto_action = PDF_create_action(p, "GoToR", optlist);
在 下 一 个 步 骤 中 , 我 们 创 建 实 际 的 书 签 。 书 签 的 action 选 项 包 含 将 触 发 操 作 的 activate 事
件 , 以 及 上 面 为 所 需 操 作 创 建 的 goto_action 句 柄 。 选 项 fontstyle bold 指 定 粗 体 文 本 ,
textcolor {rgb 0 0 1} 使 书 签 成 为 蓝 色 的 。 提 供 书 签 文 本 “Our Paper Planes Catalog” 作 为 函
数 参 数 :
sprintf(optlist, "action {activate %d} fontstyle bold textcolor {rgb 0 0 1}",
goto_action);
catalog_bookmark = PDF_create_bookmark(p, "Our Paper Planes Catalog", 0, optlist);
单 击 书 签 将 显 示 目 标 文 档 中 的 页 面 的 指 定 部 分 。
带 有 文 件 附 件 的 注 释 在 下 一 个 示 例 中 , 我 们 创 建 一 个 文 件 附 件 。 我 们 先 创 建 一 个
FileAttachment 类 型 的 注 释 。filename 选 项 指 定 附 件 的 名 称 , 选 项 mimetype image/gif 指 定
附 件 的 类 型 (MIME 是 一 种 用 于 给 文 件 内 容 分 类 的 常 用 约 定 ) 。 注 释 将 显 示 为 一 个 红 色
(annotcolor {rgb 1 0 0}) 的 图 钉 (iconname pushpin), 并 带 有 一 个 工 具 提 示 (contents {Get the
Kraxi Paper Plane!})。 注 释 不 进 行 打 印 (display noprint):
char optlist[256] =
"filename kraxi_logo.gif mimetype image/gif iconname pushpin "
"annotcolor {rgb 1 0 0} contents {Get the Kraxi Paper Plane!} display noprint"
PDF_create_annotation(p, left_x, left_y, right_x, right_y, "FileAttachment", optlist);
请 注 意 , 使 用 iconname 定 义 的 符 号 的 大 小 不 会 变 化 ; 图 标 将 按 其 标 准 尺 寸 显 示 在 指 定 矩 形
的 左 上 角 。
64 第 3 章 : PDFlib 编 程

用 于 打 印 的 按 钮 表 单 域 下 一 个 示 例 创 建 可 用 于 打 印 文 档 的 按 钮 表 单 域 。 在 第 一 个 版 本
中 , 我 们 将 对 按 钮 添 加 一 个 标 题 ; 在 以 后 的 版 本 中 , 我 们 将 使 用 打 印 机 符 号 , 而 不 用 标 题 。
我 们 先 创 建 一 个 Named 类 型 的 操 作 ( 在 Acrobat 中 : 执 行 菜 单 项 )。 同 样 , 我 们 必 须 指 定
标 题 的 字 体 :
print_action = PDF_create_action(p, "Named", "menuname Print");
button_font = PDF_load_font(p, "Helvetica-Bold", 0, "winansi", "");
按 钮 表 单 域 的 action 选 项 包 含 作 为 执 行 操 作 的 触 发 器 的 up 事 件 ( 在 Acrobat 中 : 鼠 标 松
开 ), 以 及 上 面 为 操 作 本 身 创 建 的 print_action 句 柄 。backgroundcolor {rgb 1 1 0} 选 项 指 定 黄
色 背 景 , bordercolor {rgb 0 0 0} 指 定 黑 色 边 框 。 选 项 caption Print 将 文 本 Print 添 加 到 按 钮
上 , tooltip {Print the document} 为 用 户 创 建 附 加 说 明 。 font 选 项 通 过 使 用 上 面 创 建 的
button_font 句 柄 指 定 字 体 。 默 认 情 况 下 , 将 调 整 标 题 的 尺 寸 以 使 其 完 全 适 合 按 钮 的 区 域 。
最 后 , 使 用 适 当 的 坐 标 、 名 称 print_button、 类 型 pushbutton 和 合 适 的 选 项 创 建 实 际 的 按 钮
表 单 域 :
sprintf(optlist, "action {up %d} backgroundcolor {rgb 1 1 0} bordercolor {rgb 0 0 0} "
"caption Print tooltip {Print the document} font %d",
print_action, button_font);
PDF_create_field(p, left_x, left_y, right_x, right_y, "print_button", 0,
"pushbutton", optlist);
现 在 我 们 通 过 用 一 个 小 的 打 印 机 图 标 替 换 文 本 Print 的 方 式 扩 展 第 一 个 版 本 的 按 钮 。 为 了 完
成 此 操 作 , 在 创 建 页 之 前 , 我 们 加 载 相 应 的 图 像 文 件 print_icon.jpg 作 为 模 板 。 使 用 icon 选
项 , 我 们 可 以 对 按 钮 域 指 定 模 板 句 柄 print_icon, 并 创 建 类 似 于 以 上 代 码 的 表 单 域 :
print_icon = PDF_load_image(p, "auto", "print_icon.jpg", "template");
if (print_icon == -1)
{
/* Error handling */
return;
}
PDF_begin_page_ext(p, pagewidth, pageheight, "");
...
sprintf(optlist, "action {up %d} icon %d tooltip {Print the document} font %d",
print_action, print_icon, button_font);
PDF_create_field(p, left_x, left_y, right_x, right_y, "print_button", 0,
"pushbutton", optlist);
简 单 文 本 域 现 在 我 们 在 页 面 的 右 上 角 附 近 创 建 一 个 文 本 域 。 用 户 将 能 够 在 此 域 中 输 入 当
前 日 期 。 我 们 获 取 一 个 字 体 句 柄 , 并 创 建 一 个 名 为 date 且 带 有 灰 色 背 景 的 textfield 类 型 的
表 单 域 :
textfield_font = PDF_load_font(p, "Helvetica-Bold", "winansi", "");
sprintf(optlist, "backgroundcolor {gray 0.8} font %d", textfield_font);
PDF_create_field(p, left_x, left_y, right_x, right_y, "date", 0, "textfield", optlist);
默 认 情 况 下 , 字 体 大 小 是 auto, 这 意 味 着 域 高 度 最 初 将 用 作 为 字 体 大 小 。 当 输 入 文 本 达 到
域 的 末 尾 时 , 将 减 少 字 体 大 小 以 便 使 文 本 总 是 适 合 域 大 小 。
3.4 超 文 本 元 素 65

带 有 JavaScript 的 文 本 域 为 了 改 进 上 面 创 建 的 文 本 表 单 域 , 在 页 面 打 开 的 情 况 下 , 我 们
使 用 当 前 日 期 自 动 填 充 此 文 本 表 单 域 。 首 先 , 我 们 创 建 JavaScript 类 型 的 操 作 ( 在 Acrobat
中 : 运 行 JavaScript)。 此 操 作 的 选 项 列 表 中 的 script 选 项 定 义 一 个 JavaScript 片 段 , 该 片 段
在 date 文 本 域 中 按 照 “ 月 - 日 - 年 ” 的 格 式 显 示 当 前 日 期 :
char optlist[256] =
"script {var d = util.printd('mmm dd yyyy', new Date()); "
"var date = this.getField('date'); date.value = d;}"
show_date = PDF_create_action(p, "JavaScript", optlist);
在 第 二 个 步 骤 中 , 我 们 创 建 页 面 。 在 选 项 列 表 中 , 我 们 提 供 action 选 项 将 上 面 创 建 的
show_date 操 作 附 加 到 触 发 器 事 件 open ( 在 Acrobat 中 : 进 入 页 面 ):
sprintf(optlist, "action {open %d}", show_date);
PDF_begin_page_ext(p, pagewidth, pageheight, optlist);
最 后 , 我 们 按 照 上 面 的 操 作 创 建 文 本 域 。 只 要 页 面 处 于 打 开 状 态 , 就 将 用 当 前 日 期 自 动 填 充
该 页 面 :
textfield_font = PDF_load_font(p, "Helvetica-Bold", "winansi", "");
sprintf(optlist, "backgroundcolor {gray 0.8} font %d", textfield_font);
PDF_create_field(p, left_x, left_y, right_x, right_y, "date", 0, "textfield", optlist);
3.4.2 文 本 域 的 格 式 化 选 项
在 Acrobat 中 , 可 以 指 定 用 于 格 式 化 文 本 域 内 容 ( 例 如 货 币 金 额 、 日 期 或 百 分 比 ) 的 各 种
选 项 。 此 操 作 可 以 通 过 由 Acrobat 使 用 的 自 定 义 JavaScript 代 码 完 成 。PDFlib 不 直 接 支 持 这
些 格 式 化 功 能 , 因 为 在 PDF 参 考 中 未 指 定 这 些 功 能 。 不 过 , 为 了 PDFlib 用 户 的 利 益 , 我 们
在 下 面 提 供 了 一 些 信 息 , 让 您 能 够 通 过 使 用 PDF_create_field( ) 的 action 选 项 提 供 简 单
JavaSscript 代 码 片 段 实 现 文 本 域 的 格 式 化 选 项 。
为 了 对 文 本 域 应 用 格 式 化 设 置 , JavaScript 片 段 将 被 附 加 到 文 本 域 作 为 keystroke 和
format 操 作 。JavaScript 代 码 调 用 一 些 内 部 Acrobat 函 数 , 这 些 函 数 的 参 数 可 控 制 格 式 化 设
置 的 细 节 。
以 下 示 例 创 建 两 个 keystroke 和 format 操 作 , 并 将 它 们 附 加 到 一 个 表 单 域 , 以 便 用 两 个
小 数 位 数 和 EUR 货 币 标 识 符 设 置 域 内 容 的 格 式 :
keystroke_action = PDF_create_action(p, "JavaScript",
"script {AFNumber_Keystroke(2, 0, 3, 0, \"EUR \", true); }");
format_action = PDF_create_action(p, "JavaScript",
"script {AFNumber_Format(2, 0, 0, 0, \"EUR \", true); }");
sprintf(optlist, "font = %d action = {keystroke %d format %d}",
font, keystroke_action, format_action);
PDF_create_field(p, 50, 500, 250, 600, "price", 0, "textfield", optlist);
为 了 指 定 Acrobat 中 支 持 的 各 种 格 式 , 您 必 须 在 JavaScript 代 码 中 使 用 适 当 的 函 数 。 表 3.8
列 出 了 所 有 支 持 的 格 式 的 keystroke 和 format 操 作 的 JavaSscript 函 数 名 称 ; 相 应 的 函 数 参
数 在 表 3.9 中 进 行 了 说 明 。 必 须 按 照 以 上 示 例 的 类 似 方 式 使 用 这 些 函 数 。
表 单 域 激 活 文 档 的 脏 标 志 当 在 Acrobat 中 关 闭 包 含 表 单 域 的 PDF 文 档 时 , 将 会 询 问 您 是
否 需 要 保 存 该 文 件 , 即 使 您 未 动 过 任 何 域 也 是 如 此 。 从 技 术 上 讲 , 打 开 一 个 带 有 表 单 域 的
PDFlib 生 成 的 PDF 将 会 导 致 设 置 文 档 的 脏 标 志 , 即 Acrobat 将 该 文 档 视 为 已 更 改 。 尽 管 这
66 第 3 章 : PDFlib 编 程

表 3.8 文 本 域 的 JavaScript 格 式 化 函 数
格 式
数 字
百 分 比
日 期
时 间
特 殊
要 用 于 keystroke 和 format 操 作 的 JavaScript 函 数
AFNumber_Keystroke(nDec, sepStyle, negStyle, currStyle, strCurrency, bCurrencyPrepend)
AFNumber_Format(nDec, sepStyle, negStyle, currStyle, strCurrency, bCurrencyPrepend)
AFPercent_Keystroke(ndec, sepStyle)
AFPercent_Format(ndec, sepStyle)
AFDate_KeystrokeEx(cFormat)
AFDate_FormatEx(cFormat)
AFTime_Keystroke(tFormat)
AFTime_FormatEx(cFormat)
AFSpecial_Keystroke(psf)
AFSpecial_Format(psf)
表 3.9 JavaScript 格 式 化 函 数 的 参 数
参 数
nDec
说 明 和 可 能 的 值
小 数 位 数
sepStyle 小 数 分 隔 符 样 式 :
0 1,234.56
1 1234.56
2 1.234,56
3 1234,56
negStyle 突 出 负 数 的 方 式 :
0 正 常
1 使 用 红 色 文 本
2 显 示 括 号
3 显 示 括 号 并 使 用 红 色 文 本
strCurrency
bCurrency-
Prepend
要 使 用 的 货 币 字 符 串 , 例 如 表 示 欧 元 符 号 的 “\u20AC”
false
true
不 预 置 货 币 符 号
预 置 货 币 符 号
cFormat 日 期 格 式 字 符 串 。 它 可 能 包 含 以 下 格 式 占 位 符 或 下 面 为 tFormat 列 出 的 时 间 格 式 :
d 日
dd 带 有 前 导 零 的 日
ddd 缩 写 的 星 期
m 用 数 字 表 示 的 月 份
mm 用 数 字 表 示 的 带 有 前 导 零 的 月 份
mmm 缩 写 的 月 份 名 称
mmmm 完 整 的 月 份 名 称
yyyy 用 四 位 数 字 表 示 的 年 份
yy 年 份 的 后 两 位 数 字
tFormat 时 间 格 式 字 符 串 。 它 可 能 包 含 以 下 格 式 占 位 符 :
h 小 时 (0-12)
hh 带 有 前 导 零 的 小 时 (0-12)
H 小 时 (0-24)
HH 带 有 前 导 零 的 小 时 (0-24)
M 分 钟
MM 带 有 前 导 零 的 分 钟
s 秒
ss 带 有 前 导 零 的 秒
t
'a' 或 'p'
tt 'am' 或 'pm'
3.4 超 文 本 元 素 67

表 3.9 JavaScript 格 式 化 函 数 的 参 数 ( 续 )
参 数 说 明 和 可 能 的 值
psf 描 述 几 种 附 加 格 式 :
0 邮 政 编 码
1 邮 政 编 码 + 4
2 电 话 号 码
3 身 份 证 号 码
通 常 是 无 关 紧 要 的 , 因 为 用 户 反 正 需 要 填 充 表 单 域 , 但 是 , 有 一 些 用 户 可 能 会 认 为 这 一 行 为
不 正 常 , 有 点 烦 人 。 您 可 以 使 用 一 小 段 JavaScript 代 码 在 加 载 文 件 后 重 置 文 档 的 脏 标 记 , 从
而 解 决 这 个 问 题 。 使 用 以 下 代 码 可 以 完 成 这 一 操 作 :
/* ...create some form fields... */
PDF_create_field(p, "100, 500, 300, 600, "field1", 0, "textfield", "..."
/* Create a JavaScript action which will be hooked up in the document */
action = PDF_create_action(p, "JavaScript", "script={this.dirty=false;}");
...
sprintf(optlist, "action={open %d}", action);
PDF_end_document(p, optlist);
68 第 3 章 : PDFlib 编 程

4 文 本 处 理
4.1 字 体 和 编 码 概 述
字 体 处 理 是 类 似 于 PDF 这 样 的 页 面 描 述 和 文 档 格 式 的 一 个 最 复 杂 的 方 面 。 在 本 节 中 , 我 们 将
总 结 PDFlib 的 有 关 字 体 和 编 码 处 理 的 主 要 特 征 ( 编 码 是 指 各 个 字 节 或 字 节 组 合 与 其 实 际 表
示 的 字 符 之 间 的 映 射 )。 除 了 另 有 说 明 之 外 , PDFlib 在 所 有 平 台 上 都 支 持 相 同 的 字 体 格 式 。
4.1.1 支 持 的 字 体 格 式
PDFlib 支 持 多 种 字 体 类 型 。 本 节 总 结 PDFlib 支 持 的 字 体 类 型 , 并 对 这 些 格 式 中 的 一 些 最 重
要 的 方 面 加 以 说 明 。
PostScript Type 1 字 体 PostScript 字 体 可 以 按 照 多 种 文 件 格 式 打 包 , 并 通 常 附 有 一 个 单
独 的 文 件 , 在 其 中 包 含 字 体 规 格 和 其 他 字 体 相 关 信 息 。 PDFlib 支 持 Mac 和 Windows
PostScript 字 体 , 以 及 用 于 PostScript 字 型 和 规 格 数 据 的 所 有 常 见 文 件 格 式 。
TrueType 字 体 PDFlib 支 持 基 于 矢 量 的 TrueType 字 体 , 但 是 不 支 持 基 于 位 图 的 TrueType
字 体 。 TrueType 字 体 文 件 必 须 用 Windows TTF 或 TTC 格 式 提 供 , 或 必 须 安 装 在 Mac 或
Windows 操 作 系 统 上 。 与 PostScript Type 1 字 体 不 同 的 是 , TrueType 和 OpenType 字 体
不 需 要 任 何 附 加 的 规 格 文 件 , 这 是 因 为 相 应 的 字 体 文 件 中 自 身 已 包 含 规 格 信 息 。
OpenType 字 体 OpenType 是 一 种 现 代 字 体 格 式 , 融 合 了 PostScript 和 TrueType 这 两 种
技 术 , 并 使 用 独 立 于 平 台 的 文 件 格 式 。OpenType 字 体 有 两 种 风 格 , 且 均 受 到 PDFlib 的 支 持 :
> 具 有 TrueType 字 型 的 OpenType 字 体 (*.ttf) 的 外 观 与 常 见 的 TrueType 字 体 一 样 。
> 具 有 PostScript 字 型 的 OpenType 字 体 (*.otf) 包 含 类 似 于 TrueType 的 文 件 格 式 的
PostScript 数 据 。 此 风 格 也 称 作 CFF (Compact Font Format)。
中 文 、 日 文 和 韩 文 (CJK) 字 体 除 了 Acrobat 的 标 准 CJK 字 体 之 外 ( 请 参 见 第 93 页 上 的 第
4.7 节 “ 中 文 、 日 文 和 韩 文 文 本 ”),PDFlib 还 支 持 TrueType 和 OpenType 格 式 的 自 定 义
CJK 字 体 。 通 常 , 这 些 字 体 的 处 理 方 式 类 似 于 西 文 字 体 。 不 过 , 存 在 某 些 限 制 。
Type 3 字 体 除 了 PostScript、TrueType 和 OpenType 字 体 之 外 ,PDFlib 还 支 持 用 户 定 义
的 (Type 3) PDF 字 体 概 念 。 与 常 见 字 体 格 式 不 同 , 用 户 定 义 的 字 体 不 是 从 某 个 外 部 源 ( 字
体 文 件 或 操 作 系 统 服 务 ) 获 取 的 , 而 是 必 须 借 助 于 PDFlib 的 本 机 文 本 、 图 形 和 图 像 函 数 由
客 户 端 完 全 定 义 。 Type 3 字 体 可 用 于 以 下 目 的 :
> 位 图 字 体 。
> 自 定 义 图 形 , 例 如 可 以 使 用 简 单 的 文 本 运 算 符 轻 松 打 印 徽 标 。
> 在 任 何 预 定 义 的 字 体 或 编 码 中 都 不 包 含 日 文 gaiji ( 用 户 定 义 的 字 符 )。
4.1.2 编 码
编 码 定 义 PDFlib 和 Acrobat 将 如 何 解 释 字 符 串 中 的 实 际 字 节 , 以 及 如 何 将 这 些 字 节 转 换 成
页 面 上 的 文 本 。 PDFlib 支 持 多 种 编 码 方 法 。
所 有 受 支 持 的 编 码 都 可 以 在 一 个 文 档 中 任 意 混 合 。 您 甚 至 可 以 对 单 个 字 体 使 用 不 同 的 编
码 , 尽 管 这 种 情 况 很 少 出 现 。
注 : 并 非 所 有 编 码 都 可 以 用 于 某 一 给 定 的 字 体 。 用 户 需 要 负 责 确 保 该 字 体 包 含 某 一 特 定 编 码 所
需 的 所 有 字 符 。 这 甚 至 对 Acrobat 的 核 心 字 体 都 是 一 个 问 题 ( 请 参 见 表 4.2)。
4.1 字 体 和 编 码 概 述 69

标 识 字 形 有 三 种 不 同 的 基 本 方 法 用 于 标 识 某 一 字 体 中 的 各 个 字 形 ( 字 符 的 表 现 方 式 ):
> PostScript Type 1 字 体 都 基 于 字 型 名 称 的 概 念 : 每 个 字 形 都 使 用 可 用 来 标 识 字 符 的 唯 一
名 称 进 行 标 记 , 并 构 造 适 合 某 个 环 境 的 代 码 映 射 。 尽 管 字 形 名 称 在 相 当 一 段 时 间 内 达 到
了 其 目 的 , 但 是 由 于 其 空 间 要 求 以 及 没 有 真 正 符 合 国 际 使 用 要 求 ( 在 特 殊 的 CJK 字 体
中 ), 它 们 给 现 代 计 算 带 来 了 很 大 的 限 制 。
> TrueType 和 OpenType 字 体 标 识 基 于 其 Unicode 值 的 各 个 字 形 。 这 样 就 可 以 对 文 本 字
体 中 的 所 有 字 形 轻 松 地 添 加 清 晰 的 语 义 。 不 过 , 没 有 用 于 pi 或 符 号 字 体 的 标 准 Unicode
分 配 。 当 在 Unicode 环 境 中 使 用 符 号 字 体 时 , 这 预 示 着 会 有 一 些 困 难 。
> 中 文 、 日 文 和 韩 文 OpenType 字 体 都 基 于 字 符 ID (CID) 的 概 念 。 这 些 是 为 相 应 的 语 言 引
用 标 准 知 识 库 ( 称 作 字 符 补 集 ) 的 基 本 数 字 。
这 些 概 念 之 间 存 在 相 当 大 的 重 叠 。 例 如 , 由 于 一 些 兼 容 性 原 因 , TrueType 字 体 可 能 包 含
PostScript 字 形 名 称 的 辅 助 表 。 另 一 方 面 , 一 些 标 准 PostScript 字 形 名 称 的 Unicode 语 义 可
在 Adobe Glyph List (AGL) 中 找 到 。 PDFlib 支 持 所 有 三 种 方 法 ( 基 于 名 称 的 、 Unicode、
CID)。
8 位 编 码 8 位 编 码 ( 也 称 作 单 字 节 编 码 ) 将 文 本 字 符 串 中 的 每 个 字 节 映 射 到 单 个 字 符 , 因
此 每 次 最 多 256 个 不 同 字 符 。 在 PDFlib 中 使 用 的 8 位 编 码 基 于 字 形 名 称 或 Unicode 值 , 并
可 以 从 各 种 源 提 取 :
> 表 4.2 中 列 出 的 大 量 预 定 义 的 编 码 。 这 些 编 码 涵 盖 了 目 前 在 多 种 系 统 上 和 多 个 区 域 中 使
用 的 最 重 要 的 编 码 。
> 可 以 在 外 部 文 件 中 提 供 或 使 用 PDF_encoding_set_char( ) 在 运 行 时 动 态 构 造 的 用 户 定 义 的
编 码 。 这 些 编 码 可 以 基 于 字 形 名 称 或 Unicode 值 。
> 源 自 操 作 系 统 的 编 码 , 也 称 作 “ 系 统 编 码 ”。 此 功 能 仅 在 Windows、IBM eServer iSeries
和 zSeries 上 可 用 。
> 简 写 的 基 于 Unicode 的 编 码 , 可 以 用 于 方 便 地 使 用 8 位 值 对 任 何 256 个 连 续 字 符 的
Unicode 范 围 进 行 寻 址 。
> 与 某 一 特 殊 字 体 相 关 的 编 码 。 这 些 编 码 也 称 作 font-specific 或 builtin 编 码 。
宽 字 符 寻 址 除 了 8 位 编 码 之 外 , 也 支 持 其 他 各 种 功 能 更 为 强 大 且 不 需 遵 从 256 个 字 符 限
制 的 寻 址 方 案 。
> 通 过 unicode 编 码 关 键 字 可 以 完 全 基 于 Unicode 的 寻 址 。 在 这 种 情 况 下 , 客 户 端 直 接 为
PDFlib 提 供 Unicode 字 符 串 。 可 以 根 据 一 些 标 准 方 法 ( 例 如 UTF-16,UTF-8) 和 字 节 顺
序 (little-endian 或 big-endian) 格 式 化 Unicode 字 符 串 。
> 各 种 中 文 、 日 文 和 韩 文 标 准 的 基 于 CMap 的 寻 址 。 通 过 与 标 准 CJK 字 体 结 合 ,PDFlib 支
持 Acrobat 所 支 持 的 所 有 CMap。 这 包 括 基 于 Unicode 的 CMap 和 其 他 CMap ( 请 参 见
第 93 页 上 的 第 4.7 节 “ 中 文 、 日 文 和 韩 文 文 本 ”)。
> 通 过 glyphid 编 码 关 键 字 的 TrueType 和 OpenType 字 体 的 字 形 ID 寻 址 。 这 对 高 级 文 本 处
理 应 用 程 序 非 常 有 用 , 因 为 这 类 应 用 程 序 需 要 不 通 过 参 考 任 何 特 殊 编 码 方 案 即 可 访 问 字
体 的 各 个 字 形 , 或 必 须 对 没 有 任 何 Unicode 映 射 的 字 形 进 行 寻 址 。 可 以 使 用 fontmaxcode
参 数 查 询 字 体 中 的 有 效 字 形 ID 的 数 目 。
4.1.3 支 持 Unicode 标 准
Unicode 是 一 个 大 的 字 符 集 , 涵 盖 了 世 界 上 所 有 现 行 语 言 和 脚 本 以 及 许 多 早 期 的 语 言 和 脚
本 , 并 对 许 多 应 用 程 序 、 操 作 系 统 和 编 程 语 言 提 供 有 效 支 持 。 PDFlib 在 很 大 范 围 上 支 持
Unicode 标 准 。 PDFlib 中 的 下 面 一 些 功 能 是 支 持 Unicode 的 :
> 可 以 直 接 在 页 面 说 明 中 提 供 Unicode。
> 可 以 为 多 种 超 文 本 元 素 提 供 Unicode。
70 第 4 章 : 文 本 处 理

可 以 使 用 带 任 何 字 节 顺 序 的 UTF-8 或 UTF-16 格 式 提 供 页 面 上 的 文 本 或 超 文 本 元 素 的
Unicode 字 符 串 。
> PDFlib 将 在 PDF 输 出 中 包 括 其 他 信 息 (ToUnicode CMap), 以 便 帮 助 Acrobat 为 导 出 文 本
( 例 如 通 过 剪 贴 板 ) 和 搜 索 Unicode 文 本 指 定 适 当 的 Unicode 值 。
4.2 字 体 格 式 详 细 信 息
4.2.1 Windows 和 Mac 上 的 宿 主 字 体 支 持
在 Mac 和 Windows 系 统 上 , PDFlib 可 以 访 问 已 经 安 装 在 操 作 系 统 上 的 TrueType、
OpenType 和 PostScript 字 体 。 我 们 将 这 样 的 字 体 称 为 “ 宿 主 字 体 ”。 只 需 在 系 统 中 安 装 字
体 ( 通 常 是 将 字 体 放 入 适 当 的 目 录 中 ), 而 不 用 手 动 配 置 字 体 文 件 ,PDFlib 就 可 使 用 相 应 的
字 体 了 。
当 使 用 宿 主 字 体 时 , 使 用 准 确 的 ( 区 分 大 小 写 ) 字 体 名 称 很 重 要 。 由 于 字 体 名 称 非 常 重
要 , 以 下 我 们 会 提 及 一 些 用 于 不 同 平 台 的 确 定 字 体 名 称 的 特 有 方 法 。 有 关 字 体 名 称 的 更 多 信
息 可 以 在 第 72 页 上 的 第 4.2.2 节 “PostScript 字 体 ” 和 第 73 页 上 的 第 4.2.3 节 “TrueType
和 OpenType 字 体 ” 中 找 到 。
查 找 Windows 上 的 宿 主 字 体 名 称 可 以 通 过 如 下 方 法 轻 松 找 到 已 安 装 的 字 体 的 名 称 : 双 击
字 体 文 件 , 然 后 在 显 示 的 窗 口 的 第 一 行 中 显 示 即 可 留 意 到 字 体 全 名 。 一 些 字 体 的 名 称 的 部 分
内 容 已 根 据 所 使 用 的 相 应 的 Windows 版 本 进 行 了 本 地 化 。 例 如 , 常 见 字 体 名 称 部 分 Bold 可
能 在 德 语 系 统 上 作 为 转 换 后 的 单 词 Fett 出 现 。 为 了 检 索 Windows 系 统 中 的 宿 主 字 体 数 据 ,
必 须 使 用 PDFlib 中 字 体 名 称 的 已 转 换 的 形 式 ( 如 :Arial Fett), 或 使 用 字 体 样 式 名 称 ( 请 参
见 第 73 页 上 的 “TrueType 和 OpenType 字 体 的 Windows 字 体 样 式 名 称 ”)。 不 过 , 为 了
直 接 从 文 件 中 检 索 字 体 数 据 , 必 须 使 用 字 体 名 称 的 一 般 形 式 ( 未 本 地 化 , 如 :Arial Bold)。
若 需 要 更 加 详 细 地 检 查 TrueType 字 体 , 可 以 参 考 Microsoft 免 费 的 “ 字 体 属 性 扩 展 ” 1 ,
其 中 将 按 照 用 户 可 读 的 形 式 显 示 字 体 的 TrueType 表 的 许 多 项 。
查 找 Mac 上 的 宿 主 字 体 名 称 使 用 Font Book 实 用 工 具 (Mac OS X 的 一 部 分 ), 可 以 找 到
已 安 装 的 宿 主 字 体 的 名 称 。 不 过 , 在 某 些 情 况 下 , Font Book 不 会 显 示 PDFlib 所 需 的 字 体
的 正 确 的 QuickDraw 名 称 。
为 此 , 我 们 推 荐 Apple 的 可 免 费 获 得 的 Font Tools 2 。 此 命 令 行 实 用 工 具 套 件 包 含 一 个 称
作 ftxinstalledfonts 的 程 序 , 该 程 序 用 于 确 定 所 有 已 安 装 的 字 体 的 确 切 的 QuickDraw 名 称 。
为 了 确 定 PDFlib 需 要 的 字 体 名 称 , 请 安 装 Font Tols 并 在 终 端 窗 口 中 发 出 以 下 命 令 语 句 :
ftxinstalledfonts -q
Windows 上 有 关 宿 主 字 体 访 问 的 潜 在 问 题 我 们 提 请 用 户 注 意 一 个 与 在 Windows 上 安 装
字 体 有 关 的 潜 在 问 题 。 若 您 通 过 “ 文 件 ” -> “ 安 装 新 字 体 ” 菜 单 项 ( 另 一 种 对 应 的 方 法 是
将 字 体 拖 动 到 Fonts 目 录 中 ) 安 装 字 体 , 将 出 现 一 个 复 选 框 “ 复 制 字 体 到 Fonts 文 件 夹 ” 。
若 未 选 中 此 框 , Windows 将 在 字 体 文 件 夹 中 仅 放 置 一 个 指 向 原 始 字 体 文 件 的 快 捷 方 式 ( 链
接 )。 在 这 种 情 况 下 , 原 始 字 体 文 件 必 须 位 于 一 个 应 用 程 序 可 使 用 PDFlib 访 问 的 目 录 中 。 具
体 而 言 , 位 于 Windows 的 Fonts 目 录 之 外 的 字 体 文 件 对 于 使 用 默 认 安 全 设 置 的 IIS 可 能 是 不
可 访 问 的 。 解 决 方 案 : 将 字 体 文 件 复 制 到 Fonts 目 录 下 , 或 将 原 始 字 体 文 件 放 置 到 IIS 对 其
具 有 read 权 限 的 目 录 中 。
在 使 用 Adobe Type Manager (ATM) 时 , 如 果 在 安 装 字 体 时 选 中 了 “ 添 加 时 不 复 制 字 体 ”
选 项 , 则 会 出 现 类 似 的 问 题 。
1. 请 参 见 www.microsoft.com/typography/TrueTypeProperty21.mspx
2. 请 参 见 developer.apple.com/fonts/OSXTools.html
4.2 字 体 格 式 详 细 信 息 71

Mac 上 有 关 宿 主 字 体 访 问 的 潜 在 问 题 在 测 试 中 我 们 发 现 , 对 于 无 用 户 界 面 的 应 用 程 序
( 例 如 PDFlib) 而 言 , 新 安 装 的 字 体 有 时 无 法 访 问 ; 用 户 需 从 控 制 台 中 注 销 然 后 重 新 登 录 方
可 正 常 使 用 。
4.2.2 PostScript 字 体
PostScript 字 体 文 件 格 式 PostScript Type 1 字 体 总 是 分 为 两 个 部 分 : 实 际 字 型 数 据 和 规 格
信 息 。PDFlib 在 所 有 平 台 上 都 支 持 以 下 用 于 PostScript Type 1 字 型 和 规 格 数 据 的 文 件 格 式 :
> 用 于 规 格 信 息 的 独 立 于 平 台 的 AFM(Adobe 字 体 规 格 ) 和 特 定 于 Windows 的 PFM( 打
印 机 字 体 规 格 ) 格 式 。 虽 然 基 于 AFM 的 字 体 规 格 可 以 对 字 体 支 持 的 任 何 编 码 重 新 安 排 ,
但 是 一 般 的 西 文 PFM 字 体 规 格 文 件 ( 代 码 页 1252) 仅 可 以 与 以 下 编 码 一 起 使 用 :auto、
winansi、iso8859-1、unicode 和 ebcdic。 符 号 字 体 的 PFM 文 件 可 使 用 builtin 编 码 。 其 他
代 码 页 的 PFM 文 件 可 使 用 与 PFM 代 码 页 ( 或 其 任 何 子 集 ) 相 匹 配 的 编 码 , 也 可 选 择 FM
的 内 部 代 码 页 或 unicode 作 为 builtin 编 码 。 例 如 , 一 个 西 里 尔 字 体 的 PFM 可 使 用 cp1250,
builtin 或 unicode 编 码 。
> 用 于 PostScript Type 1 格 式 ( 有 时 也 称 作 “ATM 字 体 ”) 的 字 型 信 息 的 、 独 立 于 平 台 的
PFA ( 打 印 机 字 体 ASCII) 和 特 定 于 Windows 的 PFB ( 打 印 机 字 体 二 进 制 ) 格 式 。
> 在 Mac 上 , 也 支 持 基 于 资 源 的 PostScript Type 1 字 体 , 即 LWFN (LaserWriter 字 体 )
字 型 字 体 。 这 些 字 体 附 有 一 个 字 体 包 (FOND 资 源 或 FFIL), 其 中 包 含 了 规 格 数 据 ( 以
及 PDFlib 将 忽 略 的 屏 幕 字 体 ) 。 PostScript 宿 主 字 体 可 以 与 以 下 一 些 编 码 一 起 使 用 :
auto、macroman、macroman_apple、unicode 和 builtin。 不 过 , 对 于 一 些 需 要 字 形 补 充
的 字 体 , 可 能 不 可 以 接 受 macroman 和 macroman_apple。
当 使 用 PostScript 宿 主 字 体 时 , LWFN 文 件 必 须 放 置 在 与 字 体 包 相 同 的 目 录 中 , 并 且 必
须 按 照 5+3+3 的 规 则 进 行 命 名 。 请 注 意 , 在 PDFlib 的 无 CarbonLib 支 持 的 OS 9 版 本 中 不
支 持 PostScript 宿 主 字 体 。
> 使 用 PostScript 字 型 (*.otf) 的 OpenType 字 体 。
PostScript 字 体 名 称 若 正 在 使 用 基 于 磁 盘 的 字 体 文 件 , 则 可 以 使 用 任 意 别 名 ( 请 参 见
第 75 页 上 的 第 4.3.1 节 “PDFlib 搜 索 字 体 的 方 法 ” ) 。 可 以 使 用 以 下 几 种 方 法 查 找
PostScript 字 体 的 准 确 名 称 :
> 打 开 字 型 文 件 (*.pfa 或 *.pfb), 并 查 找 项 /FontName 后 面 的 字 符 串 。 忽 略 此 项 的 最 前 面
的 / 字 符 , 然 后 使 用 其 余 部 分 作 为 字 体 名 称 。
> 若 正 在 使 用 Windows 2000/XP 或 Mac OS X 10.4, 可 以 双 击 字 体 文 件 , 即 可 显 示 字 体 的
PostScript 名 称 以 及 相 应 的 字 体 示 例 。
> 打 开 AFM 规 格 文 件 并 查 找 项 FontName 后 面 的 字 符 串 。
注 : PostScript 字 体 名 称 可 能 与 Windows 字 体 菜 单 名 称 完 全 不 同 , 例 如 “AvantGarde-Demi”
(PostScript 名 称 ) 与 “AvantGarde, Bold”( Windows 字 体 菜 单 名 称 ) 。 另 外 , 任 何
Windows .inf 文 件 中 给 定 的 字 体 名 称 与 使 用 PDF 无 关 。
PostScript 字 形 名 称 为 了 编 写 自 定 义 编 码 文 件 或 查 找 可 以 与 某 一 提 供 的 编 码 一 同 使 用 的
字 体 , 将 必 须 查 找 有 关 编 码 定 义 的 字 符 集 的 准 确 定 义 , 以 及 字 体 文 件 中 使 用 的 准 确 的 字 形 名
称 。 还 必 须 确 保 选 择 的 字 体 提 供 了 用 于 编 码 的 所 有 必 需 的 字 符 。 例 如 , 与 Acrobat 4/5 一 起
提 供 的 核 心 字 体 不 支 持 ISO 8859-2 (Latin 2), 也 不 支 持 Windows 代 码 页 1250。 若 您 正 巧 有
FontLab 1 字 体 编 辑 器 ( 顺 便 说 一 下 , 此 编 辑 器 是 用 于 处 理 所 有 种 类 的 字 体 和 编 码 问 题 的 有
效 工 具 ), 则 可 以 使 用 此 编 辑 器 查 找 有 关 某 一 给 定 字 体 所 支 持 的 编 码 的 信 息 ( 在 FontLab 文
档 中 查 找 代 码 页 )。 2
1. 请 参 见 www.fontlab.com
72 第 4 章 : 文 本 处 理

为 了 方 便 PDFlib 用 户 , 分 发 文 件 集 中 的 PostScript 程 序 print_glyphs.ps 可 以 用 于 查 找
PostScript 字 体 中 包 含 的 所 有 字 符 的 名 称 。 为 了 使 用 该 程 序 , 可 在 PostScript 文 件 的 末 尾 输
入 字 体 的 名 称 并 将 其 ( 连 同 字 体 一 起 ) 发 送 到 PostScript 打 印 机 , 然 后 使 用 Acrobat
Distiller 转 换 此 名 称 , 或 者 使 用 PostScript 查 看 器 查 看 此 名 称 。 该 程 序 将 打 印 字 体 中 的 所 有
字 形 , 并 按 照 字 形 名 称 的 字 母 顺 序 排 序 。
若 字 体 不 包 含 自 定 义 编 码 必 需 的 字 形 , 则 相 应 的 字 符 将 从 PDF 文 档 缺 失 。
4.2.3 TrueType 和 OpenType 字 体
TrueType 和 OpenType 文 件 格 式 TT 和 OT 字 体 文 件 都 是 自 我 包 含 的 : 它 们 在 单 个 文 件 中
包 含 所 有 必 需 的 文 件 。 PDFlib 支 持 TrueType 和 OpenType 字 体 的 以 下 文 件 格 式 :
> Windows TrueType 字 体 (*.ttf), 包 括 CJK 字 体 。
> 使 用 TrueType (*.ttf) 或 PostScript 字 型 (*.otf) 的 独 立 于 平 台 的 OpenType 字 体 , 包 括 CJK
字 体 。
> 在 单 个 文 件 中 带 有 多 个 字 体 的 TrueType 集 合 (*.ttc) ( 主 要 用 于 CJK 字 体 )。
> 终 端 用 户 定 义 的 字 符 (EUDC) 字 体 (*.tte), 由 Microsoft 的 eudcedit.exe 工 具 创 建 。
> 在 Mac 上 , 系 统 上 安 装 的 任 何 TrueType 字 体 ( 包 括 .dfont) 也 可 在 PDFlib 中 使 用 。
TrueType 和 OpenType 字 体 名 称 若 正 在 使 用 基 于 磁 盘 的 字 体 文 件 , 则 可 以 使 用 任 意 别 名
( 请 参 见 第 75 页 上 的 第 4.3.1 节 “PDFlib 搜 索 字 体 的 方 法 ”)。 在 生 成 的 PDF 中 ,TrueType
字 体 的 名 称 可 能 与 在 PDFlib ( 或 Windows) 中 使 用 的 名 称 不 同 。 这 种 情 况 很 正 常 , 这 是 由
于 PDF 使 用 TrueType 字 体 的 PostScript 名 称 导 致 的 , PostScript 名 称 与 其 原 来 的
TrueType 名 称 不 同 ( 例 如 TimesNewRomanPSMT 与 Times New Roman)。
注 : 与 PostScript 字 体 相 反 , TrueType 和 OpenType 字 体 名 称 可 能 包 含 空 字 符 。
TrueType 和 OpenType 字 体 的 Windows 字 体 样 式 名 称 加 载 Windows 操 作 系 统 的 宿 主
字 体 时 , PDFlib 用 户 可 以 访 问 Windows 字 体 选 择 机 制 提 供 的 功 能 : 可 以 为 TrueType 或
OpenType 字 体 的 粗 细 度 或 倾 斜 度 提 供 样 式 名 称 , 例 如
Georgia,Bold
这 将 指 示 Windows 搜 索 特 殊 的 粗 体 、 斜 体 或 基 本 字 体 的 其 他 变 体 。 根 据 可 用 的 字 体 ,
Windows 将 选 择 与 所 请 求 的 样 式 最 为 接 近 的 字 体 (Windows 将 不 会 创 建 新 的 字 体 变 体 )。
Windows 找 到 的 字 体 可 能 与 所 请 求 的 字 体 不 同 , 生 成 的 PDF 中 的 字 体 名 称 也 可 能 与 请 求 的
名 称 不 同 ; PDFlib 在 Windows 的 字 体 选 择 上 没 有 任 何 控 制 权 。 另 外 , 字 体 样 式 名 称 仅 可 用
于 TrueType 和 OpenType 宿 主 字 体 , 而 不 可 用 于 PostScript 宿 主 字 体 或 通 过 基 于 磁 盘 的 字
体 文 件 配 置 的 字 体 。
以 下 关 键 字 ( 与 字 体 名 称 之 间 用 逗 号 分 隔 ) 可 以 附 加 到 提 供 给 PDF_load_font( ) 的 基 字
体 名 称 以 指 定 字 体 粗 细 度 :
none, thin, extralight, ultralight, light, normal, regular, medium,
semibold, demibold, bold, extrabold, ultrabold, heavy, black
可 以 使 用 以 下 关 键 字 替 换 上 述 关 键 字 或 附 加 到 它 们 后 面 :
italic
这 些 关 键 字 不 区 分 大 小 写 。 若 使 用 两 种 样 式 名 称 , 则 两 者 必 须 用 逗 号 分 开 , 例 如 :
2. 有 关 PostScript 字 体 中 使 用 的 字 形 名 称 的 信 息 可 以 在 partners.adobe.com/asn/tech/type/unicodegn.jsp 网 页 上 找 到
( 并 不 要 求 字 体 供 应 商 遵 从 这 些 字 形 命 名 建 议 )。
4.2 字 体 格 式 详 细 信 息 73

Georgia,Bold,Italic
注 : 若 必 须 处 理 经 过 本 地 化 的 字 体 名 称 , 则 字 体 的 Windows 样 式 名 称 可 能 会 有 用 , 因 为 这 些
Windows 样 式 名 称 提 供 了 访 问 字 体 变 体 的 通 用 方 法 , 而 不 需 要 考 虑 其 本 地 化 的 名 称 。
4.2.4 用 户 定 义 的 (Type 3) 字 体
PDF 中 的 Type 3 字 体 ( 与 PostScript Type 3 字 体 相 对 ) 实 际 上 不 是 一 种 文 件 格 式 。 Type 3
字 体 中 的 字 形 必 须 在 运 行 时 使 用 标 准 PDFlib 图 形 函 数 进 行 定 义 。 由 于 矢 量 图 形 、 光 栅 图 像
甚 至 文 本 输 出 的 所 有 PDFlib 功 能 都 可 以 在 Type 3 字 体 定 义 中 使 用 , 所 以 对 于 使 用 Type 3
字 体 的 字 符 内 容 没 有 任 何 限 制 。 通 过 与 PDF 导 入 库 PDI 配 合 使 用 , 甚 至 可 以 导 入 复 杂 的 绘
图 作 为 PDF 页 , 并 使 用 这 些 绘 图 定 义 Type 3 字 体 的 字 符 。
注 : PostScript Type 3 字 体 不 支 持 。
必 须 完 全 在 任 何 页 面 的 外 部 定 义 Type 3 字 体 ( 更 确 切 地 说 , 字 体 定 义 必 须 在 “ 文 档 ” 范 围
中 进 行 )。 以 下 示 例 演 示 简 单 的 Type 3 字 体 的 定 义 :
PDF_begin_font(p, "Fuzzyfont", 0, 0.001, 0.0, 0.0, 0.001, 0.0, 0.0, "");
PDF_begin_glyph(p, "circle", 1000, 0, 0, 1000, 1000);
PDF_arc(p, 500, 500, 500, 0, 360);
PDF_fill(p);
PDF_end_glyph(p);
PDF_begin_glyph(p, "ring", 400, 0, 0, 400, 400);
PDF_arc(p, 200, 200, 200, 0, 360);
PDF_stroke(p);
PDF_end_glyph(p);
PDF_end_font(p);
字 体 将 在 PDFlib 中 注 册 , 并 且 字 体 的 名 称 可 以 连 同 一 个 编 码 ( 包 含 Type 3 字 体 中 字 形 的 名
称 ) 一 起 提 供 给 PDF_load_font( )。 在 使 用 Type 3 字 体 时 , 请 注 意 以 下 内 容 :
> 与 模 式 和 模 板 类 似 , 图 像 不 能 够 在 字 形 说 明 内 打 开 。 不 过 , 在 启 动 字 形 说 明 之 前 , 可 以
打 开 图 像 并 将 其 置 于 字 形 说 明 内 。 作 为 一 种 选 择 , 内 嵌 图 像 可 以 用 于 小 的 位 图 以 克 服 此
限 制 。
> 由 于 PDF 使 用 者 方 面 的 限 制 , 所 有 在 文 本 输 出 的 字 符 必 须 确 切 地 被 定 义 在 字 体 中 : 若 字
符 代 码 x 要 使 用 PDF_show( ) 或 一 个 相 似 函 数 显 示 , 并 且 编 码 包 含 位 置 x 处 的
glyphname, 则 必 须 通 过 PDF_begin_glyph( ) 定 义 glyphname。 此 限 制 仅 影 响 Type 3 字
体 ; 将 完 全 忽 略 PostScript Type 1、 TrueType 或 OpenType 字 体 中 的 缺 失 字 形 。
> 如 果 要 对 字 体 中 没 有 定 义 的 相 应 字 形 名 称 使 用 代 码 , 则 一 些 PDF 使 用 者 ( 不 包 括 Acrobat)
会 要 求 一 个 名 为 .notdef 的 字 形 。 .notdef 字 形 必 须 存 在 , 但 是 它 可 以 包 含 一 个 空 的 字 形
说 明 。
> 当 用 普 通 位 图 数 据 定 义 字 符 时 , 位 图 中 未 使 用 的 像 素 将 不 管 背 景 如 何 都 会 用 白 色 输 出 。
为 了 避 免 上 述 情 况 发 生 , 显 示 原 始 的 背 景 色 , 可 使 用 mask 参 数 构 造 位 图 图 像 。
> 图 像 的 interpolate 选 项 可 能 对 增 强 Type 3 位 图 字 体 的 屏 幕 和 打 印 外 观 很 有 用 。
74 第 4 章 : 文 本 处 理

4.3 字 体 嵌 入 和 子 集 化
4.3.1 PDFlib 搜 索 字 体 的 方 法
字 体 数 据 源 PDFlib 可 以 访 问 多 种 源 中 的 字 体 数 据 :
> 基 于 磁 盘 的 字 体 文 件 可 通 过 UPR 配 置 文 件 ( 请 参 见 第 49 页 上 的 第 3.1.5 节 “ 资 源 配 置 和
文 件 搜 索 ”) 静 态 配 置 的 或 通 过 PDF_set_parameter( ) 和 FontOutline 资 源 类 别 动 态 配 置 。
> 尽 管 不 需 要 任 何 配 置 就 可 以 使 用 宿 主 字 体 ( 请 参 见 第 71 页 上 的 第 4.2.1 节 “Windows 和
Mac 上 的 宿 主 字 体 支 持 ”), 但 还 是 可 以 使 用 HostFont UPR 资 源 类 别 明 确 配 置 宿 主 字 体
来 管 理 搜 索 顺 序 。 例 如 , 此 功 能 可 以 用 于 指 定 搜 索 宿 主 字 体 优 先 于 内 建 核 心 字 体 。
> 客 户 端 通 过 PDFlib 虚 拟 文 件 (PVF) 直 接 在 内 存 中 传 递 的 字 体 数 据 。 对 于 已 在 内 存 中 加
载 字 体 数 据 并 希 望 避 免 不 必 要 的 PDFlib 磁 盘 访 问 ( 有 关 虚 拟 文 件 的 详 细 信 息 , 请 参 见
第 48 页 上 的 第 3.1.4 节 “PDFlib 虚 拟 文 件 系 统 (PVF)”) 的 高 级 应 用 程 序 , 这 一 点 很 有 用 。
字 体 名 称 的 别 名 使 用 由 于 字 体 的 准 确 内 部 名 称 难 于 查 找 , PDFlib 支 持 对 PostScript、
TrueType 和 OpenType 字 体 的 字 体 名 称 使 用 别 名 。 通 过 使 用 字 体 名 称 的 别 名 , 可 以 为 某 个
字 体 指 定 任 意 名 称 作 为 别 名 。 在 UPR 文 件 中 或 在 运 行 时 , 均 可 以 为 HostFont、FontOutline、
FontAFM 和 FontPFM 类 型 的 资 源 指 定 别 名 。 以 下 示 例 为 基 于 磁 盘 的 字 体 定 义 一 个 别 名 :
PDF_set_parameter(p, "FontOutline", "x=DFHSMincho-W3.ttf");
font = PDF_load_font(p, "x", 0, "winansi", "");
搜 索 字 体 提 供 给 PDF_load_font( ) 的 字 体 名 称 是 一 个 名 称 字 符 串 ( 请 参 见 第 84 页 上 的
第 4.5.2 节 “ 内 容 字 符 串 、 超 文 本 字 符 串 和 名 称 字 符 串 ”)。 然 而 , 不 是 所 有 编 码 都 支 持
任 何 字 体 源 。 根 据 以 下 方 案 搜 索 字 体 :
> 若 名 称 是 一 个 别 名 ( 通 过 UPR 文 件 或 调 用 PDF_set_parameter( ) 进 行 配 置 ) , 则 可 用
ASCII 或 UTF-8 编 码 。 别 名 所 引 用 的 名 称 在 后 面 的 步 骤 中 将 用 来 查 找 字 体 文 件 ( 基 于 磁
盘 的 字 体 ) 或 宿 主 字 体 。
> 若 名 称 指 定 一 个 宿 主 字 体 , 则 可 以 用 ASCII 对 其 编 码 。 在 Windows 上 , 也 可 以 使 用
Unicode。
> 若 发 现 字 体 不 是 ( 可 能 已 本 地 化 ) 宿 主 字 体 , 并 且 未 用 Unicode 编 码 , 则 将 通 过 应 用 下
面 说 明 的 基 于 扩 展 名 的 搜 索 方 式 搜 索 相 应 的 字 体 文 件 。
> 对 于 TTC (TrueType 集 合 ) 字 体 , 可 以 使 用 ASCII 或 Unicode 对 名 称 进 行 编 码 , 并 将
对 照 TTC 文 件 中 的 所 有 字 体 的 所 有 名 称 匹 配 这 一 名 称 。
基 于 磁 盘 的 字 体 文 件 的 基 于 扩 展 名 的 搜 索 当 PDFlib 搜 索 磁 盘 上 字 体 的 字 型 或 规 格 文 件
时 ( 与 从 操 作 系 统 直 接 获 取 宿 主 字 体 不 同 ), 如 果 字 体 名 称 由 纯 ASCII 字 符 组 成 , 则 PDFlib
使 用 以 下 搜 索 算 法 :
> 当 通 过 UPR 文 件 或 在 运 行 时 已 经 将 字 体 配 置 为 FontAFM、 FontPFM 或 FontOutline 资 源
时 , 将 使 用 已 配 置 的 文 件 名 称 。
> 若 无 法 找 到 文 件 , 则 将 以 下 后 缀 添 加 到 字 体 名 称 , 然 后 尝 试 利 用 得 到 的 文 件 名 称 一 个 一
个 地 查 找 字 体 规 格 ( 对 于 TrueType 和 OpenType 字 体 则 查 找 字 型 ):
.ttf .otf .afm .pfm .ttc .tte
.TTF .OTF .AFM .PFM .TTC .TTE
> 若 PostScript 字 体 要 求 嵌 入 , 则 将 以 下 后 缀 添 加 到 字 体 名 称 , 然 后 尝 试 利 用 得 到 的 文 件
名 称 一 个 一 个 地 查 找 字 型 文 件 :
.pfa .pfb
.PFA .PFB
4.3 字 体 嵌 入 和 子 集 化 75

以 上 所 有 的 尝 试 文 件 名 都 会 按 原 样 搜 索 , 并 预 先 考 虑 SearchPath 资 源 类 别 中 配 置 的 所 有
目 录 名 称 。
这 意 味 着 , 只 要 相 应 的 字 体 文 件 中 包 含 字 体 名 称 和 对 应 于 字 体 类 型 的 标 准 文 件 名 后 缀 , 并
且 该 文 件 位 于 任 一 个 SearchPath 目 录 中 , 则 不 需 要 任 何 手 动 配 置 , PDFlib 就 将 查 找 相 应 的
字 体 。
4.3.2 字 体 嵌 入
PDF 核 心 字 体 PDF 浏 览 器 支 持 含 有 14 种 字 体 的 核 心 集 ( 假 定 这 些 字 体 永 远 可 用 )。 核 心
字 体 的 完 整 规 格 信 息 已 经 构 建 到 PDFlib 二 进 制 文 件 中 , 因 此 不 再 需 要 其 他 字 体 文 件 ( 除 非
要 嵌 入 字 体 )。 核 心 字 体 如 下 所 示 :
Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique,
Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique,
Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic,
Symbol, ZapfDingbats
注 : PDFlib 当 前 只 包 含 Acrobat 4 和 5 中 使 用 的 传 统 核 心 字 体 的 规 格 。 Acrobat 6 以 及 更 高 版 本 在
核 心 字 体 中 支 持 更 多 字 符 ( 例 如 一 些 波 兰 语 字 符 ), 而 PDFlib 不 包 含 这 些 字 符 的 正 确 字 形 宽
度 。
为 了 使 用 系 统 上 已 安 装 的 宿 主 字 体 替 换 一 种 核 心 字 体 , 必 须 在 HostFont 资 源 类 别 中 配 置 相
应 的 字 体 。 例 如 , 以 下 代 码 行 确 保 将 使 用 主 机 系 统 上 的 Symbol 字 体 , 而 不 使 用 内 建 核 心 字
体 数 据 :
PDF_set_parameter(p, "HostFont", "Symbol=Symbol");
PDF 通 过 一 些 方 法 支 持 除 14 种 核 心 字 体 之 外 的 字 体 。 PDFlib 能 够 将 字 型 嵌 入 到 生 成 的 PDF
输 出 中 。 通 过 PDF_load_font( ) 的 embedding 选 项 可 以 控 制 字 体 嵌 入 ( 尽 管 在 某 些 情 况 下 ,
PDFlib 将 强 制 实 施 字 体 嵌 入 ):
另 外 , 也 可 以 嵌 入 仅 包 含 字 符 规 格 和 有 关 字 体 的 常 规 信 息 ( 不 带 实 际 字 型 ) 的 字 体 说 明
符 。 若 某 种 字 体 未 嵌 入 到 PDF 文 档 中 ,Acrobat 将 从 目 标 系 统 获 取 相 应 的 字 体 ( 如 果 存 在 ),
或 者 根 据 字 体 说 明 符 构 造 替 代 字 体 。 表 4.1 列 出 有 关 字 体 用 法 的 不 同 情 况 , 每 种 用 法 都 对
PDFlib 必 需 的 字 体 和 规 格 文 件 提 出 了 不 同 的 要 求 。
PDF_set_parameter(p, "HostFont", "Symbol=Symbol");
当 字 体 带 有 局 限 于 该 字 体 的 编 码 ( 符 号 字 体 ) 或 包 含 Adobe 的 标 准 拉 丁 字 符 集 之 外 的 字
形 的 字 体 时 , 但 在 PDF 输 出 中 没 有 嵌 入 这 种 字 体 , 则 只 有 当 该 字 体 已 经 安 装 在 目 标 系 统 上
产 生 的 PDF 才 将 可 用 ( 因 为 Acrobat 只 能 模 拟 拉 丁 文 字 体 )。 这 类 PDF 文 件 天 生 就 不 可 移
植 , 不 过 可 以 在 受 控 环 境 下 使 用 ( 例 如 , 公 司 内 部 文 档 交 换 )。
表 4.1 不 同 的 字 体 用 法 情 况 以 及 要 求 的 规 格 和 字 型 文 件
字 体 用 法 必 须 明 确 配 置 字 体 规 格 文 件 吗 ? 必 须 明 确 配 置 字 型 文 件 吗 ?
14 种 核 心 字 体 之 一 否 仅 在 要 求 嵌 入 的 情 况 下 需 要
安 装 在 Mac 或 Windows 系 统 上 的
TrueType、 OpenType 或 PostScript
Type 1 宿 主 字 体 。
否
非 核 心 PostScript 字 体 是 仅 在 要 求 嵌 入 的 情 况 下 需 要
否
76 第 4 章 : 文 本 处 理

表 4.1 不 同 的 字 体 用 法 情 况 以 及 要 求 的 规 格 和 字 型 文 件
字 体 用 法 必 须 明 确 配 置 字 体 规 格 文 件 吗 ? 必 须 明 确 配 置 字 型 文 件 吗 ?
TrueType 字 体 不 适 用 是
OpenType 字 体 , 包 括 CJK 不 适 用
是
TrueType 和 OpenType 字 体
1
标 准 CJK 字 体
否
否
1. 有 关 CJK 字 体 的 更 多 信 息 , 请 参 见 第 93 页 上 的 第 4.7 节 “ 中 文 、 日 文 和 韩 文 文 本 ”。
强 制 的 字 体 嵌 入 PDF 需 要 为 某 些 字 体 和 编 码 的 组 合 进 行 字 体 嵌 入 。 因 此 , 在 以 下 情 况 下
PDFlib 将 强 制 字 体 嵌 入 ( 与 embedding 选 项 无 关 ):
> 与 具 有 TT 字 型 的 TrueType 或 OpenType 字 体 一 起 使 用 glyphid 或 unicode 编 码 。
> 与 不 同 于 winansi、macroman 和 ebcdic 的 编 码 一 起 使 用 具 有 TrueType 字 型 的 TrueType
字 体 或 OpenType 字 体 。
请 注 意 , 对 于 具 有 PostScript 字 型 的 OpenType 字 体 , 将 不 会 强 制 实 施 字 体 嵌 入 。 字 体 嵌 入
的 需 求 是 由 针 对 CID 字 体 的 内 部 转 换 引 起 的 , 可 以 通 过 将 autocidfont 参 数 设 置 为 false 来 禁
用 此 转 换 。 这 样 做 也 将 禁 用 强 制 嵌 入 。 请 注 意 , 在 这 种 情 况 下 , 并 非 所 有 拉 丁 字 符 都 将 可 以
访 问 , Adobe 字 形 列 表 (AGL) 之 外 的 字 符 根 本 不 会 起 作 用 。
有 关 字 体 嵌 入 的 法 律 事 宜 请 注 意 , 仅 拥 有 字 体 文 件 也 许 没 有 资 格 在 PDF 中 嵌 入 字 体 , 即
使 对 于 合 法 的 字 体 许 可 的 所 有 者 也 是 一 样 。 许 多 字 体 供 应 商 都 会 限 制 他 人 嵌 入 其 字 体 。 一 些
字 体 厂 商 完 全 禁 止 PDF 字 体 嵌 入 , 其 他 厂 商 对 于 其 字 体 提 供 特 殊 的 在 线 或 嵌 入 许 可 , 同 时
仍 有 其 他 一 些 厂 商 在 对 字 体 应 用 子 集 化 的 前 提 下 允 许 字 体 嵌 入 。 在 试 图 使 用 PDFlib 嵌 入 字
体 之 前 , 请 检 查 字 体 嵌 入 是 否 合 法 。PDFlib 将 遵 从 在 TrueType 或 OpenType 字 体 中 可 能 指
定 的 嵌 入 限 制 。 若 TrueType 字 体 中 的 嵌 入 标 记 设 置 为 no embedding 1 , 则 PDFlib 将 尊 重 字
体 供 应 商 的 要 求 , 从 而 拒 绝 有 关 嵌 入 相 应 字 体 的 任 何 尝 试 。
4.3.3 字 体 子 集 化
为 了 减 少 PDF 输 出 的 大 小 , PDFlib 可 以 仅 嵌 入 字 体 中 的 那 些 在 文 档 中 实 际 使 用 的 字 符 。 这
个 过 程 称 作 “ 字 体 子 集 化 ”。 此 过 程 将 创 建 一 个 新 的 字 体 , 其 中 包 含 的 字 形 比 原 始 字 体 包 含
的 字 形 要 少 一 些 , 并 将 省 略 PDF 查 看 不 需 要 的 字 体 信 息 。 不 过 , 请 注 意 , Acrobat 的
TouchUp 工 具 将 拒 绝 处 理 使 用 子 集 字 体 的 文 本 。 字 体 子 集 化 对 于 CJK 字 体 特 别 重 要 。
PDFlib 支 持 以 下 类 型 的 字 体 的 子 集 化 :
> TrueType 字 体 。
> 具 有 PostScript 或 TrueType 字 型 的 OpenType 字 体 。
当 已 请 求 子 集 化 的 字 体 在 文 档 中 使 用 时 ,PDFlib 将 记 录 实 际 用 于 文 本 输 出 的 字 符 。 对 于 子 集
化 行 为 有 一 些 控 制 方 式 :
> 默 认 的 子 集 化 行 为 由 autosubsetting 参 数 控 制 。 若 该 参 数 为 true, 则 将 对 所 有 可 能 发 生
子 集 化 的 字 体 启 用 子 集 化 。 默 认 值 为 true。
> 若 autosubsetting 参 数 为 false, 而 某 一 特 殊 字 体 需 要 子 集 化 , 则 subsetting 选 项 仍 必 须
提 供 给 PDF_load_font( ):
font = PDF_load_font(p, "WarnockPro", 0, "winansi", "subsetting");
> subsetlimit 参 数 包 含 一 个 百 分 比 值 。 若 文 档 使 用 的 值 大 于 字 体 中 的 此 字 形 百 分 比 值 , 则
将 对 此 特 殊 字 体 禁 用 子 集 化 , 而 改 为 嵌 入 完 整 字 体 。 这 将 节 省 一 些 处 理 时 间 , 不 过 输 出
文 件 会 较 大 :
1. 更 具 体 而 言 : 若 字 体 的 OS/2 表 中 的 fsType 标 记 的 值 为 2。
4.3 字 体 嵌 入 和 子 集 化 77

PDF_set_value(p, "subsetlimit", 75); /* set subset limit to 75% */
subsetlimit 的 默 认 值 是 100%。 换 言 之 , 将 遵 从 PDF_load_font( ) 请 求 的 subsetting 选
项 , 除 非 客 户 端 显 式 请 求 一 个 低 于 100% 的 限 制 。
> subsetminsize 参 数 可 以 用 于 对 小 型 字 体 完 全 禁 用 子 集 化 。 若 原 始 字 体 文 件 小 于
subsetminsize 的 值 ( 以 KB 为 单 位 ), 则 将 禁 用 此 字 体 的 子 集 化 。 默 认 值 是 100 KB。
嵌 入 和 子 集 化 TrueType 字 体 由 于 PDF 中 的 某 些 要 求 , 导 致 用 于 TrueType 处 理 的 依 赖 项
有 点 混 乱 。 以 下 是 前 面 几 个 段 落 中 的 信 息 的 小 结 。
若 将 TrueType 字 体 与 不 同 于 winansi 和 macroman 的 编 码 一 同 使 用 , 默 认 情 况 下 , 该 字
体 将 转 换 为 用 于 PDF 输 出 的 CID 字 体 。 对 于 仅 包 含 Adobe 字 形 列 表 (AGL) 中 的 字 符 的 编
码 , 可 以 通 过 将 autocidfont 参 数 设 置 为 false 阻 止 此 转 换 。 若 字 体 转 换 为 CID 字 体 , 它 将 总
是 嵌 入 的 。 默 认 情 况 下 , 将 应 用 子 集 化 , 除 非 autosubsetting 参 数 设 置 为 false, 或 使 用 的 字
形 的 百 分 比 高 于 subsetlimit 参 数 , 或 字 体 文 件 大 小 ( 以 KB 为 单 位 ) 小 于 subsetminsize 参
数 的 值 。
4.4 编 码 详 细 信 息
4.4.1 8 位 编 码
表 4.2 列 出 了 PDFlib 中 预 定 义 的 编 码 , 并 详 细 介 绍 了 如 何 将 这 些 编 码 与 一 些 重 要 类 别 的 字 体
一 起 使 用 。 某 些 脚 本 或 语 言 有 一 些 普 通 字 体 无 法 满 足 的 要 求 , 认 识 到 这 一 点 很 重 要 。 例 如 ,
Acrobat 的 核 心 字 体 未 包 含 ISO 8859-2 必 需 的 所 有 字 符 ( 例 如 波 兰 语 ) , 而 PostScript 3、
OpenType Pro 和 TrueType 的 大 字 体 中 包 含 了 所 有 这 些 字 符 。
注 : PDFlib 分 发 中 包 含 的 chartab 示 例 可 以 用 于 轻 松 打 印 任 意 字 体 / 编 码 组 合 的 字 符 表 。
有 关 macroman 编 码 的 批 注 此 编 码 反 映 Mac OS 字 符 集 , 尽 管 在 219 = 0xDB 位 置 处 带 有
旧 的 货 币 符 号 , 而 不 是 由 Apple 重 新 定 义 的 欧 元 符 号 字 形 (PDF 规 范 指 出 此 不 兼 容 性 )。 除
了 以 下 一 些 差 异 之 外 , macroman_apple 编 码 与 macroman 一 致 :
> macroman_apple 中 的 219 = 0xDB 位 置 处 保 留 欧 元 符 号 字 形 , 而 不 是 货 币 符 号 。
> macroman_apple 编 码 包 括 Mac OS 字 符 集 中 定 义 的 希 腊 / 数 学 符 号 。 虽 然 这 些 符 号 在
macroman_apple 编 码 中 可 用 , 但 只 是 在 少 数 字 体 中 包 含 所 需 的 字 形 。
宿 主 编 码 尽 管 此 特 殊 的 “ 宿 主 ” 编 码 没 有 任 何 固 定 的 含 意 , 但 是 将 按 如 下 方 式 根 据 当 前
平 台 映 射 为 其 他 8 位 编 码 :
> 在 Mac OS Classic 上 , 它 将 映 射 为 macroman ;
> 在 带 有 MVS 或 USS 的 IBM eServer zSeries 上 , 它 将 映 射 为 ebcdic ;
> 在 IBM eServer iSeries 上 , 它 将 映 射 为 ebcdic_37 ;
> 在 Windows 上 , 它 将 映 射 为 winansi ;
> 在 所 有 其 他 系 统 上 ( 包 括 Mac OS X), 它 将 映 射 为 iso8859-1 ;
宿 主 编 码 主 要 用 于 编 写 独 立 于 平 台 的 测 试 程 序 ( 如 PDFlib 分 发 中 包 含 的 程 序 和 其 他 简 单 应
用 程 序 )。 建 议 不 要 在 生 产 中 使 用 宿 主 编 码 , 而 应 使 用 任 何 适 当 的 编 码 进 行 替 代 。
自 动 编 码 PDFlib 支 持 可 用 于 为 某 些 环 境 指 定 最 自 然 的 编 码 的 机 制 , 而 不 用 再 费 周 折 。 提
供 关 键 字 auto 作 为 编 码 名 称 , 可 以 为 以 下 文 本 字 体 指 定 特 定 于 平 台 和 环 境 的 8 位 编 码 :
> 在 Windows 上 : 当 前 系 统 代 码 页 ( 有 关 详 细 信 息 , 请 参 见 以 下 内 容 )
> 在 Unix 和 Mac OS X 上 :iso8859-1 (Mac 上 的 LWFN PostScript 字 体 除 外 , 此 处 auto
将 映 射 为 macroman)
78 第 4 章 : 文 本 处 理

表 4.2 用 于 预 定 义 编 码 的 字 形 在 一 些 类 别 的 字 体 中 的 可 用 性 : 一 些 语 言 无 法 用 Acrobat 的 核 心 字 体 表 示
代 码 页
受 支 持 的 语 言
PS Level 1/2,
Acrobat 4/5 1
Acrobat 6/7 2
核 心 字 体
PostScript 3
3
字 体
OpenType
4
Pro 字 体
TrueType
5
大 字 体
winansi 与 cp1252 相 同 (iso8859-1 的 超 集 ) 是 是 是 是 是
macroman Mac Roman 编 码 , 原 始 Macintosh 字 符 集 是 是 是 是 是
macroman_
apple
类 似 于 macroman, 但 替 换 了 欧 元 货 币 符 号 ,
并 包 括 其 他 数 字 / 希 腊 符 号
– – – 是 是
ebcdic EBCDIC 代 码 页 1047 是 是 是 是 是
ebcdic_37 EBCDIC 代 码 页 037 是 是 是 是 是
pdfdoc PDFDocEncoding 是 是 是 是 是
iso8859-1 (Latin-1) 西 欧 语 言 是 是 是 是 是
iso8859-2 (Latin-2) 中 欧 斯 拉 夫 语 – – 是 是 是
iso8859-3 (Latin-3) 世 界 语 、 马 耳 他 语 – – – 是 是
iso8859-4 (Latin-4) 爱 沙 尼 亚 语 、 波 罗 的 语 、 格 陵 兰 语 – – – 是 是
iso8859-5 保 加 利 亚 语 、 俄 语 、 塞 尔 维 亚 语 – – – 是 是
iso8859-6 阿 拉 伯 语 – – – – 是
iso8859-7 现 代 希 腊 语 – – – 1 缺 失 。 是
iso8859-8 希 伯 来 语 和 依 地 语 – – – – 是
iso8859-9 (Latin-5) 西 欧 语 言 、 土 耳 其 语 5 缺 失 。 5 缺 失 。 是 是 是
iso8859-10 (Latin-6) 北 欧 语 言 – – – 1 缺 失 。 是
iso8859-13 (Latin-7) 波 罗 的 语 – – 是 是 是
iso8859-14 (Latin-8) 凯 尔 特 语 – – – – –
iso8859-15 (Latin-9) 将 欧 元 符 号 、 法 语 和 芬 兰 语 字 符
添 加 到 Latin-1
欧 元
符 号
缺 失 。
是 是 是 是
iso8859-16 (Latin-10) 匈 牙 利 语 、 波 兰 语 、 罗 马 尼 亚 语 、 – – 是 是 是
斯 洛 文 尼 亚 语
cp1250 中 欧 语 言 – – 是 是 是
cp1251 古 斯 拉 夫 语 – – – 是 是
cp1252 西 欧 语 言 ( 与 winansi 相 同 ) 是 是 是 是 是
cp1253 希 腊 语 – – – 1 缺 失 。 是
cp1254 土 耳 其 语 5 缺 失 。 – 是 是 是
cp1255 希 伯 来 语 – – – – 是
cp1256 阿 拉 伯 语 – – – – 5 缺 失 。
cp1257 波 罗 的 语 – – 是 是 是
cp1258 越 南 语 – – – – 是
1. 随 Acrobat 4/5 附 带 的 核 心 字 体 ( 原 始 的 Adobe 拉 丁 字 符 集 ; 自 1982 年 起 通 常 为 Type 1 字 体 )。
2. Acrobat 6 和 7 依 赖 在 系 统 上 可 用 的 字 体 以 显 示 Times 和 Helvetica。 因 此 , 结 果 会 根 据 已 安 装 的 字 体 的 数 目 和 种 类 改 变 。
例 如 , 随 Windows XP 附 带 的 系 统 字 体 包 含 的 字 形 比 早 期 版 本 的 Windows 中 可 用 的 字 形 多 。
3. 扩 展 的 Adobe 拉 丁 字 符 集 (CE-Fonts), 通 常 是 随 PostScript 3 设 备 附 带 的 Type 1 字 体 。
4. Adobe OpenType Pro 字 体 包 含 的 字 形 比 常 规 OpenType 字 体 包 含 的 字 形 多 。
5. Windows TrueType 字 体 包 含 大 字 形 增 补 集 , 例 如 Tahoma。
> 在 Mac OS Classic 上 :macroman
4.4 编 码 详 细 信 息 79

在 IBM eServer iSeries 上 : 当 前 的 工 作 代 码 (IBMCCSID000000000000)
> 在 IBM eServer zSeries 上 :ebcdic (= 代 码 页 1047)
对 于 符 号 字 体 , 关 键 字 auto 将 映 射 为 builtin 编 码 。 虽 然 自 动 编 码 在 许 多 环 境 下 使 用 起 来 很
方 便 , 但 是 使 用 这 种 方 法 将 使 您 的 PDFlib 客 户 端 程 序 天 生 不 可 移 植 。
分 支 系 统 代 码 页 可 以 指 示 PDFlib 从 系 统 中 获 取 代 码 页 定 义 并 将 其 适 当 转 换 以 供 内 部 使
用 。 由 于 这 种 方 法 将 使 您 不 必 亲 自 需 要 实 现 代 码 页 定 义 , 因 而 使 用 上 很 方 便 。 这 种 方 法 不 必
再 向 PDF_load_font( ) 提 供 内 建 编 码 或 用 户 定 义 的 编 码 的 名 称 , 只 需 使 用 系 统 已 知 的 编 码 名
称 即 可 。 此 功 能 仅 在 选 定 的 平 台 上 可 用 , 并 且 编 码 字 符 串 的 语 法 是 特 定 于 平 台 的 :
> 在 Windows 上 , 编 码 名 称 是 cp, 此 处 是 指 系 统 上 安 装 的 任 何 单 字 节
代 码 页 的 数 目 ( 有 关 多 字 节 Windows 代 码 页 的 更 多 信 息 , 请 参 见 第 97 页 上 的 第 4.7.3 节
“ 自 定 义 CJK 字 体 ”):
PDF_load_font(p, "Helvetica", 0, "cp1250", "");
单 字 节 代 码 页 将 转 换 为 内 部 8 位 编 码 , 而 多 字 节 代 码 页 将 映 射 为 unicode。 必 须 按 照 与
选 定 的 代 码 页 兼 容 的 格 式 提 供 文 本 ( 例 如 , 用 于 cp932 的 SJIS)。
> 在 IBM eServer iSeries 上 , 可 以 使 用 任 何 编 码 的 字 符 集 标 识 符 (CCSID)。 必 须 提 供 CCSID
作 为 字 符 串 , 并 且 PDFlib 将 对 提 供 的 代 码 页 号 应 用 前 缀 IBMCCSID。 若 代 码 页 号 使 用 的 字
符 少 于 5 个 字 符 , PDFlib 还 将 在 前 面 添 加 0 字 符 。 提 供 0 ( 零 ) 作 为 代 码 页 号 将 导 致 使
用 当 前 工 作 的 编 码 :
PDF_load_font(p, "Helvetica", 0, "273", "");
> 在 带 有 USS 或 MVS 的 IBM eServer zSeries 上 , 可 以 使 用 任 何 Coded Character Set
Identifier (CCSID)。 必 须 提 供 CCSID 作 为 字 符 串 , 并 且 PDFlib 将 提 供 的 代 码 页 名 称 完 全
传 递 给 系 统 ( 对 名 称 不 作 任 何 更 改 ):
PDF_load_font(p, "Helvetica", 0, "IBM-273", "");
用 户 定 义 的 8 位 编 码 除 了 预 定 义 编 码 之 外 , PDFlib 支 持 用 户 定 义 的 8 位 编 码 。 若 需 要 处
理 在 PDFlib 内 部 不 可 用 的 字 符 集 ( 例 如 , 与 PDFlib 内 部 支 持 的 字 符 集 不 同 的 EBCDIC 字 符
集 ), 则 可 以 使 用 这 些 方 法 。PDFlib 既 支 持 按 照 PostScript 字 形 名 称 定 义 的 编 码 表 , 也 支 持
按 照 Unicode 值 定 义 的 表 。
在 用 户 定 义 的 编 码 可 以 在 PDFlib 程 序 中 使 用 之 前 , 必 须 完 成 以 下 任 务 ( 或 者 , 也 可 以 使
用 PDF_encoding_set_char( ) 在 运 行 时 构 造 编 码 ):
> 用 简 单 的 文 本 格 式 生 成 编 码 的 说 明 。
> 在 PDFlib 资 源 文 件 中 配 置 编 码 ( 请 参 见 第 49 页 上 的 第 3.1.5 节 “ 资 源 配 置 和 文 件 搜 索 ”)
或 通 过 PDF_set_parameter( ) 配 置 编 码 。
> 提 供 一 种 支 持 编 码 中 使 用 的 所 有 字 符 的 字 体 ( 规 格 和 可 能 的 字 型 文 件 )。
编 码 文 件 只 是 逐 行 列 出 字 形 名 称 和 编 号 。 以 下 节 选 显 示 了 编 码 定 义 的 开 头 部 分 :
% Encoding definition for PDFlib, based on glyph names
% name code Unicode (optional)
space 32 0x0020
exclam 33 0x0021
...
下 面 的 示 例 显 示 了 Unicode 代 码 页 的 一 个 片 段 :
% Code page definition for PDFlib, based on Unicode values
% Unicode code
0x0020 32
80 第 4 章 : 文 本 处 理

0x0021 33
...
更 合 乎 规 范 的 做 法 是 按 照 以 下 规 则 管 理 编 码 或 代 码 页 文 件 的 内 容 :
> 注 释 由 百 分 比 “%” 字 符 引 入 , 并 在 行 的 末 尾 终 止 。
> 每 一 行 的 第 一 项 是 PostScript 字 形 名 称 , 或 是 一 个 由 0x 前 缀 和 四 位 数 的 十 六 进 制 数 字
( 大 写 或 小 写 ) 组 成 的 十 六 进 制 Unicode 值 。 其 后 紧 跟 空 白 和 一 个 十 六 进 制 (0xoo–0xFF)
或 十 进 制 (0–255) 字 符 代 码 。 有 时 , 基 于 名 称 的 编 码 文 件 可 能 包 含 带 有 相 应 Unicode 值 的
第 三 列 。
> 编 码 文 件 中 未 提 及 的 字 符 代 码 假 定 为 未 定 义 的 代 码 。 或 者 , 可 以 将 Unicode 值 0x0000
或 字 符 名 称 .notdef 提 供 给 未 使 用 的 插 槽 。
按 照 命 名 约 定 , 我 们 将 基 于 名 称 的 表 称 为 编 码 文 件 (*.enc), 而 将 基 于 Unicode 的 表 称 为 代 码
页 文 件 (*.cpg), 但 PDFlib 会 以 相 同 的 方 式 处 理 这 两 种 文 件 , 并 不 在 意 文 件 名 称 。 实 际 上 ,
PDFlib 将 在 基 于 名 称 的 代 码 页 文 件 和 基 于 Unicode 的 代 码 页 文 件 之 间 自 动 转 换 ( 必 要 时 )。
此 转 换 基 于 Adobe 的 PostScript 字 形 名 称 标 准 列 表 (Adobe 字 形 列 表 或 AGL 1 ), 但 是 也 可
以 使 用 非 AGL 名 称 。PDFlib 将 为 非 AGL 名 称 分 配 可 用 的 Unicode 值 , 并 在 读 取 包 含 从 字 形
名 称 到 Unicode 值 的 映 射 的 OpenType 字 体 文 件 时 , 调 整 这 些 值 。
AGL 已 被 构 建 到 PDFlib 中 , 其 中 包 含 1000 多 种 字 形 名 称 。 带 有 非 标 准 字 形 名 称 的
PostScript 字 体 需 要 编 码 文 件 , 而 在 处 理 基 于 Unicode 的 TrueType 或 OpenType 字 体 时 ,
使 用 代 码 页 更 为 方 便 。
4.4.2 符 号 字 体 和 特 定 于 字 体 的 编 码
由 于 符 号 或 徽 标 字 体 ( 也 称 作 Pi 字 体 ) 通 常 未 包 含 标 准 字 符 , 因 此 它 们 必 须 使 用 与 文 本 字
体 不 同 的 编 码 方 案 。
PostScript 字 体 的 builtin 编 码 。 编 码 名 称 builtin 不 是 指 特 殊 的 字 符 顺 序 , 而 是 指 按 原 样
使 用 此 字 体 , 而 不 要 与 字 符 集 混 在 一 起 。 这 个 概 念 有 时 也 称 作 “ 特 定 于 字 体 的 编 码 ”, 这 对
于 非 文 本 字 体 ( 例 如 , 徽 标 和 符 号 字 体 ) 非 常 重 要 。 它 也 广 泛 地 用 于 ( 有 点 不 适 当 地 ) 非
拉 丁 文 本 字 体 ( 例 如 希 腊 语 和 古 斯 拉 夫 语 )。 由 于 这 些 字 符 名 称 与 这 些 编 码 中 的 字 符 名 称 不
匹 配 , 因 此 使 用 任 一 种 标 准 编 码 都 无 法 重 新 编 码 这 些 字 体 。 因 此 ,builtin 必 须 用 于 所 有 符 号
性 或 非 文 本 PostScript 字 体 。 在 AFM 文 件 中 , 以 下 项 可 以 识 别 非 文 本 字 体 :
EncodingScheme FontSpecific
可 以 对 文 本 字 体 重 新 编 码 ( 调 整 到 某 个 代 码 页 或 字 符 集 ), 但 不 可 以 对 符 号 字 体 重 新 编 码 ,
而 必 须 改 用 builtin 编 码 。 不 过 , 广 泛 使 用 的 Symbol 和 ZapfDingbats 字 体 也 可 以 与 unicode
编 码 一 起 使 用 。
builtin 编 码 无 法 用 于 用 户 定 义 的 (Type 3) 字 体 , 因 为 这 些 字 体 未 包 含 任 何 默 认 编 码 。
注 : 不 幸 的 是 , 过 去 许 多 印 刷 商 和 字 体 供 应 商 没 有 完 全 理 解 特 定 于 字 体 的 编 码 的 概 念 ( 这 可 能
是 由 于 一 些 不 甚 完 美 的 生 产 工 具 导 致 的 ) 。 为 此 , 产 生 了 许 多 标 记 为 FontSpecific 编 码 的 拉
丁 文 本 字 体 以 及 许 多 错 误 地 标 记 为 文 本 字 体 的 符 号 字 体 。
TrueType 字 体 的 builtin 编 码 带 有 非 文 本 字 符 的 TrueType 字 体 ( 例 如 Wingdings 字 体 )
必 须 与 builtin 编 码 一 起 使 用 。 若 字 体 要 求 builtin 编 码 , 但 客 户 端 请 求 不 同 的 编 码 , PDFlib
仍 将 强 制 执 行 builtin 编 码 。
1. AGL 可 以 在 partners.adobe.com/public/developer/en/opentype/glyphlist.txt 上 找 到
4.4 编 码 详 细 信 息 81

具 有 PostScript 字 型 (*.otf) 的 OpenType 字 体 的 builtin 编 码 带 有 非 文 本 字 符 的 OTF 字
体 必 须 与 builtin 编 码 一 起 使 用 。 一 些 OTF 字 体 包 含 一 个 内 部 默 认 编 码 。PDFlib 将 检 测 这 种 情
况 , 并 动 态 构 建 适 合 此 特 殊 的 字 体 的 编 码 。 编 码 名 称 builtin 将 被 修 改 为 builtin_。
虽 然 此 新 的 编 码 名 称 可 以 在 将 来 对 PDF_load_font( ) 的 调 用 中 使 用 , 但 只 有 与 相 同 的 字 体 使
用 才 合 理 。
4.4.3 TrueType 和 OpenType 字 体 的 字 形 ID 寻 址
除 了 8 位 编 码 、 Unicode 和 CMap 之 外 , PDFlib 还 支 持 一 种 在 字 体 内 针 对 各 个 字 符 进 行 寻
址 的 方 法 , 此 方 法 称 作 “ 字 形 ID 寻 址 ”。 为 了 使 用 此 技 术 , 必 须 满 足 以 下 所 有 要 求 :
> 字 体 在 TrueType 或 OpenType 格 式 中 可 用 。
> 字 体 必 须 嵌 入 到 PDF 文 档 中 ( 使 用 或 不 使 用 子 集 化 )。
> 开 发 人 员 熟 悉 字 体 内 的 字 形 的 内 部 编 号 。
字 形 ID (GID) 在 TrueType 和 OpenType 字 体 中 内 部 使 用 , 并 唯 一 地 在 字 体 中 确 定 各 个 字 形
的 地 址 。GID 寻 址 功 能 使 开 发 人 员 免 受 给 定 的 编 码 方 案 中 的 任 何 限 制 , 并 提 供 对 已 被 字 体 设
计 人 员 放 入 到 字 体 文 件 中 的 所 有 字 形 的 访 问 权 。 不 过 , 通 常 在 GID 和 许 多 常 见 寻 址 方 案 之
间 根 本 没 有 任 何 关 系 , 例 如 Windows 编 码 或 Unicode。PDFlib 用 户 负 责 将 特 定 于 应 用 程 序
的 代 码 转 换 为 GID。
通 过 提 供 关 键 字 glyphid 作 为 PDF_load_font( ) 的 encoding 参 数 , 调 用 GID 寻 址 。 可 以 使
用 从 0 到 最 后 的 字 形 ID 值 之 间 的 值 为 GID 连 续 编 号 , 最 后 的 字 形 ID 值 可 以 使 用
fontmaxcode 参 数 进 行 查 询 。
4.4.4 欧 元 符 号 字 形
此 符 号 表 示 欧 洲 货 币 , 当 需 要 正 确 显 示 和 打 印 符 号 时 , 欧 元 符 号 会 引 发 许 多
问 题 。 在 本 节 中 , 我 们 将 提 供 一 些 提 示 以 便 您 可 以 成 功 处 理 欧 元 字 符 。 首 先 ,
您 将 必 须 选 择 包 含 欧 元 字 符 的 编 码 并 检 查 欧 元 字 符 的 位 置 。 请 看 一 些 示 例 :
> 在 unicode 编 码 中 使 用 字 符 U+20AC。
> 在 winansi 编 码 中 , 位 置 是 0x80 ( 十 六 进 制 ) 或 128 ( 十 进 制 )。
> 普 通 iso8859-1 编 码 不 包 含 欧 元 字 符 。 不 过 ,iso8859-15 编 码 是 iso8859-1 的
扩 展 , 其 中 在 0xA4 ( 十 六 进 制 ) 或 164 ( 十 进 制 ) 处 添 加 了 欧 元 字 符 。
> 原 始 的 macroman 编 码 不 包 含 欧 元 字 符 。 不 过 ,Apple 修 改 了 此 编 码 并 用 位 于 0xDB( 十
六 进 制 ) 或 219 ( 十 进 制 ) 处 的 欧 元 字 形 替 换 旧 的 货 币 字 形 。 为 了 使 用 此 已 修 改 的 Mac
编 码 , 请 使 用 macroman_apple, 而 不 使 用 macroman。
下 一 步 , 您 必 须 选 择 包 含 欧 元 字 形 的 字 体 。 许 多 现 代 字 体 包 含 欧 元 字 形 , 但 是 并 不 是 所 有 字
体 都 包 含 。 同 样 , 请 看 一 些 示 例 :
> PostScript Level 1 和 Level 2 设 备 中 的 内 建 字 体 不 包 含 欧 元 字 符 , 而 PostScript 3 设 备 中
的 内 建 字 体 通 常 包 含 欧 元 字 符 。
> 若 字 体 未 包 含 欧 元 字 符 , 则 可 以 使 用 Symbol 核 心 字 体 的 欧 元 符 号 , 此 欧 元 符 号 位 于
0xA0 ( 十 六 进 制 ) 或 160 ( 十 进 制 ) 。 在 Acrobat 4.0 及 更 高 版 本 的 软 件 附 带 的
Symbol 字 体 的 版 本 中 带 有 该 字 符 , 并 构 建 到 PostScript 3 设 备 内 部 。
82 第 4 章 : 文 本 处 理

4.5 Unicode 支 持
PDFlib 支 持 Unicode 标 准 1 ( 几 乎 与 ISO 10646 相 同 ) 这 包 括 对 页
面 内 容 和 超 文 本 元 素 相 关 的 多 种 功 能 的 支 持 。
4.5.1 页 面 内 容 和 超 文 本 的 Unicode
可 以 在 页 面 说 明 中 直 接 提 供 Unicode 字 符 串 以 便 使 用 以 下 种 类 的
字 体 :
> 带 有 unicode 编 码 的 PostScript 字 体 。 最 多 有 255 个 不 同 的 Unicode 值 可 供 使 用 。 若 请 求
更 多 的 值 , 则 它 们 将 被 空 格 字 符 替 换 。 若 字 体 带 有 PFM 规 格 文 件 或 编 码 unicode 将 总 是
映 射 为 winansi( 若 使 用 的 字 体 ) 和 macroman( 若 使 用 Mac 上 的 PostScript 宿 主 字 体 )。
> 带 有 unicode 编 码 的 TrueType 和 OpenType 字 体 。 对 于 TrueType 和 OpenType 字 体 ,
将 强 制 执 行 字 体 嵌 入 。
> 带 有 基 于 Unicode 的 CMap 的 标 准 CJK 字 体 。Unicode 兼 容 的 CMap 可 以 根 据 其 名 称 中
的 Uni 前 缀 轻 松 地 进 行 识 别 ( 请 参 见 表 4.7)。
> 带 有 unicode 编 码 的 自 定 义 CJK 字 体 。
> 在 Windows 系 统 上 , 可 以 使 用 Unicode 文 件 名 称 。
除 了 unicode 编 码 之 外 , PDFlib 支 持 用 于 选 择 Unicode 字 符 的 一 些 其 他 方 法 。
PostScript 字 体 和 TrueType 字 体 的 Unicode 代 码 页 PDFlib 支 持 对 Adobe 字 形 列 表 (AGL)
内 的 字 符 进 行 Unicode 寻 址 。 此 类 Unicode 支 持 可 用 于 带 有 AGL 中 的 字 形 名 称 的 、 基 于
Unicode 的 TrueType 字 体 和 PostScript 字 体 。
可 以 通 过 使 用 任 一 PDFlib 的 内 部 代 码 页 或 通 过 提 供 合 适 的 自 定 义 编 码 或 代 码 页 文 件 激
活 此 功 能 ( 请 参 见 第 78 页 上 的 第 4.4.1 节 “8 位 编 码 ”)。
用 于 为 Unicode 片 段 寻 址 的 8 位 字 符 串 PDFlib 支 持 一 种 缩 写 格 式 , 该 格 式 可 用 于 为 256 个
连 续 Unicode 字 符 寻 址 ( 在 U+0000 和 U+FFFF 之 间 的 任 意 偏 移 量 处 开 始 )。 这 可 以 用 于 轻 松
访 问 小 范 围 的 Unicode 字 符 , 而 且 仍 使 用 8 位 字 符 。
可 以 通 过 使 用 字 符 串 U+XXXX 作 为 PDF_load_font( ) 的 encoding 参 数 激 活 此 功 能 , 此 处
XXXX 表 示 一 个 十 六 进 制 的 偏 移 量 。 将 8 位 字 符 添 加 到 提 供 的 偏 移 量 。 例 如 , 使 用 编 码
U+0400
将 选 择 古 斯 拉 夫 语 Unicode 节 , 提 供 给 文 本 函 数 的 8 位 字 符 串 将 选 择 Unicode 字 符
U+0400、 U+0401 等 。
用 于 剪 贴 和 查 找 操 作 的 Unicode 值 PDFlib 将 在 PDF 输 出 中 包 含 额 外 信 息 (ToUnicode
CMap), 以 便 帮 助 Acrobat 为 导 出 文 本 ( 例 如 , 通 过 剪 贴 板 ) 和 搜 索 文 本 指 定 合 适 的
Unicode 值 。 默 认 情 况 下 , 将 为 所 有 支 持 的 字 体 类 型 生 成 ToUnicode CMap, 其 前 提 是
Unicode 信 息 可 用 于 给 定 的 字 体 / 编 码 组 合 。 尽 管 对 大 多 数 字 体 / 编 码 组 合 都 是 这 样 , 但
是 有 些 字 体 ( 例 如 , 用 户 定 义 的 Type 3 字 体 ) 可 能 会 缺 失 Unicode 信 息 。 在 这 种 情 况
下 , PDFlib 将 不 能 够 生 成 ToUnicode CMap, 文 本 导 出 或 搜 索 将 在 Acrobat 中 不 起 作
用 。 使 用 unicodemap 参 数 可 以 全 局 禁 用 ToUnicode CMap 的 生 成 , 或 者 在 每 个 字 体 的 基
础 上 使 用 相 同 名 称 的 PDF_load_font( ) 选 项 禁 用 ToUnicode CMap 的 生 成 。 此 参 数 / 选 项 的
默 认 值 为 true。 将 此 值 设 置 为 false 将 减 少 输 出 文 件 的 大 小 , 但 在 Acrobat 中 可 能 会 禁 用 剪
切 / 粘 贴 支 持 。
1. 请 参 见 www.unicode.org
4.5 Unicode 支 持 83

超 文 本 字 符 串 的 Unicode 可 以 为 各 种 超 文 本 元 素 提 供 Unicode, 例 如 书 签 、 注 释 的 内 容 和
标 题 ( 请 参 见 图 4.1)、 标 准 的 和 用 户 定 义 的 文 档 信 息 域 内 容 、 文 件 附 件 的 说 明 和 作 者 。
虽 然 PDF 只 支 持 big-endian UTF-16 格 式 和 PDFDocEncoding ( 是 用 于 超 文 本 元 素 的
ISO 8859-1 的 超 集 ) 中 的 Unicode, 但 是 PDFlib 支 持 所 有 8 位 的 和 基 于 Unicode 的 编 码 以
及 可 用 于 PDF_load_font( ) 的 系 统 安 装 的 代 码 页 , 并 将 自 动 应 用 任 何 必 需 的 转 换 。
4.5.2 内 容 字 符 串 、 超 文 本 字 符 串 和 名 称 字 符 串
根 据 字 符 串 用 法 的 不 同 , PDFlib API 中 字 符 串 分 为 不 同 的 类 型 :
> 内 容 字 符 串 : 这 些 字 符 串 将 用 于 根 据 用 户 为 特 定 的 字 体 选 定 的 编 码 创 建 真 正 的 页 内 容 ( 页
面 说 明 )。 第 191 页 上 的 第 8.3.4 节 “ 简 单 文 本 输 出 ” 和 第 198 页 上 的 第 8.3.5 节 “ 使 用
文 本 流 的 多 行 文 本 ” 中 的 页 面 内 容 函 数 的 所 有 text 参 数 都 归 为 此 类 。
> 超 文 本 字 符 串 : 这 些 字 符 串 多 数 用 于 超 文 本 函 数 , 例 如 书 签 和 注 释 , 并 在 函 数 说 明 中 明
确 标 记 为 Hypertext string。 第 243 页 上 的 第 8.9 节 “ 超 文 本 函 数 ” 中 的 许 多 函 数 的 参 数
和 选 项 与 一 些 其 他 项 都 归 为 此 类 。
> 名 称 字 符 串 : 这 些 字 符 串 用 于 外 部 文 件 名 称 、 字 体 名 称 、 块 名 称 等 , 并 在 函 数 说 明 中 标
记 为 name string。 它 们 与 超 文 本 字 符 串 稍 微 有 点 不 同 , 但 是 差 异 仅 存 在 于 无 法 识 别
Unicode 的 语 言 中 。 有 关 详 细 信 息 , 请 参 见 第 85 页 上 的 第 4.5.4 节 “ 不 支 持 Unicode 的
语 言 中 的 字 符 串 处 理 ”。
带 有 不 可 用 字 形 的 Unicode 码 位 的 替 换 机 制 内 容 字 符 串 将 用 特 定 的 字 体 显 现 在 页 面 上 。
不 过 , 不 存 在 包 含 所 有 最 新 Unicode 标 准 中 包 含 的 字 符 的 字 体 。 尽 管 获 取 合 适 的 字 体 显 然
是 PDFlib 用 户 的 任 务 , 但 是 , 如 果 原 始 字 形 在 字 体 中 不 可 用 , 且 glyphwarning 选 项 设 置 为
false, 则 PDFlib 会 尝 试 通 过 使 用 可 见 的 相 似 字 形 替 换 某 些 字 符 来 解 决 一 些 常 见 问 题 。 以 下
列 表 ( 不 完 整 ) 包 含 一 些 字 形 映 射 。 若 列 表 中 的 第 一 个 字 符 在 字 体 中 不 可 用 , 则 使 用 第 二
个 字 符 自 动 替 换 它 :
U+00A0 ( 非 分 行 空 格 ) U+0020 ( 空 格 )
U+00AD ( 自 动 连 字 符 ) U+002D ( 减 号 连 字 符 )
U+2010 ( 连 字 符 ) U+002D ( 减 号 连 字 符 )
U+03BC ( 希 腊 小 写 字 母 MU) U+00C5 ( 微 符 号 )
U+212B ( 埃 符 号 ) U+00B5 ( 上 部 带 有 一 个 圆 圈 的 拉 丁 大 写 字 母 A Å)
图 4.1
Unicode 书 签 ( 左 侧 ) 和
Unicode 文 本 批 注 ( 右 侧 )
84 第 4 章 : 文 本 处 理

U+220F ( 元 积 )
U+03A0 ( 希 腊 大 写 字 母 PI)
U+2126 ( 欧 姆 符 号 ) U+03A9 ( 希 腊 大 写 字 母 OMEGA)
除 了 内 建 表 之 外 , 若 全 宽 变 体 在 字 体 中 不 可 用 , 则 使 用 相 应 的 ISO 8859-1 字 符 ( 即 U+0021
到 U+007E) 替 换 从 U+FF01 到 U+FF5E 区 间 的 全 宽 字 符 。
4.5.3 支 持 Unicode 的 语 言 中 的 字 符 串 处 理
以 下 PDFlib 语 言 绑 定 支 持 Unicode:
> COM
> .NET
> Java
> REALbasic
> Tcl
在 这 些 环 境 中 将 直 接 处 理 字 符 串 : 所 有 字 符 串 都 将 作 为 UTF-16 格 式 的 Unicode 字 符 串 自 动
提 供 给 PDFlib 内 核 。 语 言 包 装 程 序 将 正 确 处 理 由 客 户 端 提 供 的 Unicode 字 符 串 , 并 自 动 设
置 某 些 PDFlib 参 数 。 这 将 产 生 以 下 结 果 :
> 由 于 语 言 包 装 程 序 自 动 设 置 textformat、hypertextformat 和 hypertextencoding 参 数 , 所
以 客 户 端 无 法 访 问 这 些 包 装 程 序 , 并 禁 止 使 用 这 些 包 装 程 序 。 PDFlib 语 言 包 装 程 序 使 用
所 有 必 需 的 转 换 , 以 便 客 户 端 提 供 的 超 文 本 字 符 串 将 按 照 utf16 格 式 和 unicode 编 码 传 递
给 PDFlib。
> 由 于 语 言 环 境 总 是 按 照 UTF-16 格 式 将 字 符 串 传 递 给 PDFlib, 所 以 UTF-8 无 法 与 支 持
Unicode 的 语 言 一 起 使 用 。 在 使 用 环 境 提 供 的 本 地 方 法 之 前 , 必 须 将 其 转 换 为 UTF-16。
> 处 理 识 别 Unicode 的 语 言 中 的 编 码 有 一 个 最 简 单 的 方 法 , 就 是 对 页 面 内 容 使 用 unicode
编 码 。
> 在 页 面 说 明 中 必 须 避 免 对 标 准 CJK 字 体 使 用 非 Unicode CMap, 这 是 因 为 包 装 程 序 总 是
将 Unicode 提 供 给 PDFlib 核 心 ; 只 可 以 使 用 Unicode CMap。
总 的 效 果 是 , 客 户 端 可 以 将 纯 Unicode 字 符 串 提 供 给 PDFlib 函 数 , 而 不 需 要 任 何 其 他 配 置
或 参 数 设 置 。
4.5.4 不 支 持 Unicode 的 语 言 中 的 字 符 串 处 理
注 : 此 节 内 容 不 适 用 于 支 持 Unicode 的 语 言 Java 和 Tcl。
以 下 PDFlib 语 言 绑 定 不 支 持 Unicode:
> C ( 无 本 地 字 符 串 数 据 类 型 )
> C++
> Cobol ( 无 本 地 字 符 串 数 据 类 型 )
> Perl
> PHP
> Python
> Ruby
> RPG ( 无 本 地 字 符 串 数 据 类 型 )
在 不 支 持 本 地 字 符 串 数 据 类 型 的 语 言 绑 定 中 ( 即 C、 Cobol 和 RPG), 必 须 在 单 独 的 length
参 数 中 提 供 UTF-16 字 符 串 的 长 度 。 尽 管 Unicode 文 本 可 以 在 这 些 语 言 中 使 用 , 但 是 处 理 多
种 字 符 串 类 型 仍 有 点 复 杂 :
> 内 容 字 符 串 : 这 些 字 符 串 用 于 创 建 真 正 的 页 面 内 容 。 这 些 字 符 串 的 解 释 由 textformat
参 数 ( 以 下 内 容 将 详 细 说 明 ) 和 PDF_load_font( ) 的 encoding 参 数 进 行 控 制 。 若
textformat=auto ( 此 为 默 认 设 置 ), 则 utf16 格 式 将 用 于 unicode 和 glyphid 编 码 以 及
4.5 Unicode 支 持 85

UCS-2 CMap。 对 于 所 有 其 他 编 码 , 采 用 的 格 式 将 是 bytes。 在 没 有 本 地 字 符 串 数 据 类 型
的 语 言 中 ( 请 参 见 以 上 列 表 ), 必 须 在 单 独 的 长 度 参 数 中 提 供 UTF-16 字 符 串 的 长 度 。
> 超 文 本 字 符 串 : 字 符 串 解 释 由 hypertextformat 和 hypertextencoding 参 数 进 行 控 制 ( 以
下 将 详 细 说 明 )。 若 hypertextformat=auto( 此 为 默 认 设 置 ), 且 hypertextencoding=unicode
则 使 用 utf16 格 式 ; 否 则 使 用 bytes。 在 没 有 本 地 字 符 串 数 据 类 型 的 语 言 中 ( 请 参 见 以 上 列
表 ), 必 须 在 单 独 的 长 度 参 数 中 提 供 UTF-16 字 符 串 的 长 度 。
> 名 称 字 符 串 : 这 些 字 符 串 的 解 释 与 页 面 说 明 字 符 串 的 解 释 稍 微 不 同 。 通 常 , 使 用 宿 主 编
码 ( 请 参 见 第 78 页 上 的 “ 宿 主 编 码 ”) 解 释 名 称 字 符 串 。 不 过 , 若 它 是 以 UTF-8 BOM
开 始 的 , 则 将 其 解 释 为 UTF-8 ( 或 者 , 若 它 是 以 EBCDIC UTF- BOM 开 始 , 则 将 其 解 释
为 EBCDIC UTF-8)。 在 没 有 本 地 字 符 串 数 据 类 型 的 语 言 中 , 对 于 UTF-8 字 符 串 ,length
参 数 必 须 是 0。 若 此 参 数 不 等 于 0, 则 字 符 串 将 被 解 释 为 UTF-16。 在 不 支 持 Unicode 但
支 持 本 地 字 符 串 数 据 类 型 的 语 言 中 , 在 API 函 数 中 没 有 length 参 数 。 为 了 创 建 Unicode
名 称 字 符 串 , 可 以 使 用 PDF_utf16_to_utf8( ) 实 用 工 具 函 数 以 创 建 UTF-8。
选 项 列 表 中 的 字 符 串 选 项 列 表 内 的 字 符 串 需 要 特 别 注 意 , 因 为 这 些 字 符 串 不 能 表 示 为
UTF-16 格 式 的 Unicode 字 符 串 , 而 只 能 表 示 为 字 节 字 符 串 。 为 此 , UTF-8 用 于 Unicode 选
项 。PDFlib 通 过 在 选 项 开 始 处 寻 找 BOM 来 决 定 解 释 方 式 。BOM 将 用 于 确 定 字 符 串 的 格 式 ,
而 字 符 串 的 类 型 ( 前 面 定 义 的 内 容 字 符 串 、 超 文 本 字 符 串 或 名 称 字 符 串 ) 将 用 于 确 定 适 当
的 编 码 。 更 加 确 切 地 说 , 将 按 如 下 所 示 解 释 字 符 串 选 项 :
> 若 选 项 以 UTF-8 BOM (\xEF\xBB\xBF) 开 始 , 则 将 其 解 释 为 UTF-8。 若 选 项 以 EBCDIC
UTF-8 BOM (\x57\x8B\xAB) 开 始 , 则 将 其 解 释 为 EBCDIC UTF-8。
> 若 未 找 到 BOM, 则 字 符 串 将 按 照 在 hypertextencoding 参 数 或 选 项 中 指 定 的 编 码 进 行 处
理 。 若 字 符 串 是 一 个 名 称 字 符 串 , 则 将 使 用 宿 主 编 码 对 其 进 行 解 释 。
注 : PDF_utf16_to_utf8( ) 实 用 工 具 函 数 可 以 用 于 从 UTF-16 字 符 串 创 建 UTF-8 字 符 串 , 后 者 可 用
于 创 建 带 有 Unicode 值 的 选 项 列 表 。
Unicode 字 符 串 的 文 本 格 式 Unicode 标 准 支 持 一 些 转 换 格 式 以 便 存 储 包 含 Unicode 字 符 串
的 实 际 字 节 值 。 这 些 转 换 格 式 在 每 个 字 母 的 字 节 数 以 及 字 符 中 的 字 节 顺 序 方 面 有 一 些 不 同 。
PDFlib 中 的 Unicode 字 符 串 可 以 用 UTF-8 或 UTF-16 格 式 按 照 任 意 字 节 顺 序 提 供 。 可 以 使 用 页
面 说 明 上 的 适 用 于 所 有 文 本 的 textformat 参 数 和 适 用 于 所 有 超 文 本 元 素 的 hypertextformat
参 数 控 制 此 操 作 。 表 4.3 列 出 了 这 两 个 参 数 支 持 的 值 。
表 4.3 文 本 格 式
textformat 说 明
bytes 字 符 串 中 的 一 个 字 节 对 应 于 一 个 字 符 。 这 主 要 用 于 8 位 编 码 。
utf8 应 使 用 UTF-8 格 式 的 字 符 串 。
ebcdicutf8 应 使 用 EBCDIC 编 码 的 UTF-8 格 式 的 字 符 串 ( 仅 在 iSeries 和 zSeries 上 )。
utf16 应 使 用 UTF-16 格 式 的 字 符 串 。 将 评 估 字 符 串 开 头 的 Unicode 字 节 顺 序 标 记 (BOM), 然 后 移 除
该 标 记 。 若 不 存 在 BOM, 则 字 符 串 应 使 用 计 算 机 的 本 地 字 节 顺 序 ( 在 Intel x86 结 构 中 , 本 地
字 节 顺 序 是 little-endian, 而 在 Sparc 和 PowerPC 系 统 上 , 本 地 字 节 顺 序 是 big-endian)。
utf16be 应 按 big-endian 字 节 顺 序 使 用 UTF-16 格 式 的 字 符 串 。 对 字 节 顺 序 标 记 没 有 特 殊 的 处 理 。
utf16le 应 按 little-endian 字 节 顺 序 使 用 UTF-16 格 式 的 字 符 串 。 对 字 节 顺 序 标 记 没 有 特 殊 的 处 理 。
auto 等 同 于 8 位 编 码 的 字 节 和 宽 字 符 寻 址 的 utf16 (unicode、 glyphid 或 UCS2 或 UTF16 CMap)。
此 设 置 将 在 未 在 本 地 使 用 Unicode 的 多 数 环 境 下 提 供 适 当 的 文 本 解 释 。
对 textformat 参 数 的 默 认 设 置 对 于 支 持 Unicode 的 语 言 为 utf16 , 而 对 于 其 他 语 言 则 为
auto。
86 第 4 章 : 文 本 处 理

尽 管 textformat 设 置 对 所 有 编 码 都 起 作 用 , 但 它 将 对 unicode 编 码 最 有 用 。 表 4.4 详 细 记
录 了 针 对 字 体 编 码 和 textformat 设 置 的 多 种 组 合 的 文 本 字 符 串 解 释 。
表 4.4 字 体 编 码 和 文 本 格 式 的 关 系
字 体 编 码 textformat = bytes textformat = utf8, utf16, utf16be, or utf16le
TTF/OTF 的 8 位 编 码
或 内 建 编 码
PostScript 的 内 建
编 码
U+XXXX
1
8 位 代 码 根 据 选 定 的 编 码 将 Unicode 值 转 换 为 8 位 代 码
8 位 代 码 仅 在 支 持 Unicode 的 语 言 绑 定 中 使 用 , 否 则
PDFlib 将 引 发 异 常
8 位 代 码 将 添 加 到 偏 移 量 XXXX 处
以 对 Unicode 值 寻 址
glyphid 8 位 代 码 对 字 形 ID ( 从 0 到 255)
进 行 寻 址
unicode 和 UCS2 或
UTF16 CMap
任 何 其 他 CMap
( 未 基 于 Unicode)
8 位 代 码 对 Unicode 值 ( 从
U+0000 到 U+00FF) 进 行 寻 址
基 于 选 定 的 CMap 的 任 何 单 个 或
多 个 代 码
根 据 选 定 的 Unicode 偏 移 量 将 Unicode 值 转 换
为 8 位 代 码
Unicode 值 将 被 解 释 为 字 形 ID 2
1
根 据 选 定 的 文 本 格 式 编 码 的 任 何 Unicode 值
仅 在 支 持 Unicode 的 语 言 绑 定 中 使 用 , 否 则
PDFlib 将 引 发 异 常
1. 若 Unicode 字 符 在 字 体 中 不 可 用 , 则 PDFlib 将 发 出 警 告 并 用 空 格 字 符 替 换 此 Unicode 字 符 ( 可 以 通 过 glyphwarning 参
数 控 制 此 操 作 )。
2. 若 字 形 ID 在 字 体 中 不 可 用 , PDFlib 将 发 出 警 告 并 使 用 字 形 ID 0 替 换 它 。
超 文 本 编 码 hypertextencoding 参 数 与 PDF_load_font( ) 的 encoding 参 数 作 用 类 似 , 用 于
控 制 超 文 本 字 符 串 的 8 位 编 码 。 它 可 以 包 含 PDFlib 已 知 的 大 多 数 编 码 名 称 , 包 括 auto ( 请
参 见 第 78 页 上 的 第 4.4 节 “ 编 码 详 细 信 息 ”)。 请 注 意 , 此 参 数 不 能 使 用 glyphid、 builtin
和 CMap 名 称 。 hypertextencoding 参 数 的 默 认 设 置 是 auto。
超 文 本 格 式 与 textformat 参 数 类 似 , 可 以 使 用 hypertextformat 参 数 控 制 超 文 本 字 符 串 的
格 式 。 不 过 , 它 对 允 许 的 值 的 解 释 与 hypertextformat 参 数 稍 微 有 点 不 同 。 虽 然 utf8、utf16、
utf16be 和 utf16le 对 于 textformat 参 数 的 含 意 相 同 , 但 是 bytes 和 auto 的 行 为 稍 微 不 同 :
> auto: 将 检 测 带 有 big-endian BOM 的 UTF-16 字 符 串 ( 在 C 中 , 必 须 使 用 双 Null 终 止
此 字 符 串 ) , 并 生 成 Unicode 输 出 。 若 字 符 串 不 是 以 big-endian BOM 开 始 , 则 根 据
hypertextencoding 参 数 将 其 解 释 为 8 位 编 码 的 字 符 串 ( 请 参 见 以 上 内 容 )。 若 它 至 少 包
含 一 个 在 PDFDocEncoding 中 未 包 含 的 字 符 , 则 整 个 字 符 串 将 被 转 换 为 big-endian
UTF-16 字 符 串 , 并 作 为 Unicode 编 写 到 PDF 输 出 中 。 否 则 , 它 将 作 为 8 位 编 码 的
PDFDocEncoding 文 本 编 写 到 PDF 输 出 中 。
> bytes: 字 符 串 中 的 一 个 字 节 对 应 于 一 个 字 符 , 输 出 字 符 串 时 不 进 行 任 何 解 释 。 这 主 要 用
于 8 位 编 码 。 另 外 , 将 自 动 检 测 带 有 big-endian BOM 的 UTF-16 字 符 串 。 在 C 中 , 必 须
用 双 Null 终 止 此 字 符 串 , 除 非 在 相 应 的 函 数 调 用 中 已 显 式 提 供 字 节 长 度 。
hypertextformat 参 数 的 默 认 设 置 为 auto。
4.5.5 字 符 引 用
一 些 环 境 要 求 程 序 员 使 用 8 位 编 码 编 写 源 代 码 ( 例 如 winansi、 macroman 或 ebcdic)。 在
没 有 将 文 本 中 的 所 有 字 符 更 改 为 多 字 节 编 码 的 情 况 下 , 这 使 得 很 难 在 8 位 编 码 的 文 本 中 包
含 独 立 的 Unicode 字 符 。 在 这 种 情 况 下 为 了 给 开 发 人 员 提 供 帮 助 , PDFlib 支 持 字 符 引 用 ,
这 是 标 记 语 言 ( 例 如 , SGML 和 HTML) 中 已 知 的 一 种 方 法 。
4.5 Unicode 支 持 87

HTML 样 式 字 符 引 用 PDFlib 支 持 HTML 4.0 1 中 定 义 的 所 有 数 字 字 符 引 用 和 字 符 实 体 引
用 。 可 以 用 十 进 制 或 十 六 进 制 表 示 法 为 字 符 的 Unicode 值 提 供 数 字 字 符 引 用 。
注 : 码 位 128-159 ( 十 进 制 ) 或 0x80-0x9F ( 十 六 进 制 ) 不 引 用 winansi 码 位 。 在 Unicode 中 ,
它 们 不 引 用 可 打 印 字 符 , 而 仅 引 用 控 制 字 符 。
以 下 是 有 效 的 字 符 引 用 以 及 对 得 到 的 字 符 的 说 明 的 示 例 :
­
自 动 连 字 符
­
自 动 连 字 符
­
自 动 连 字 符
å 上 方 带 有 一 个 小 圆 圈 的 字 母 a ( 十 进 制 )
å 上 方 带 有 一 个 小 圆 圈 的 字 母 a ( 十 六 进 制 , 小 写 x)
å 上 方 带 有 一 个 小 圆 圈 的 字 母 a ( 十 六 进 制 , 大 写 X)
€ 欧 元 字 形 ( 十 六 进 制 )
€ 欧 元 字 形 ( 十 进 制 )
€ 欧 元 字 形 ( 实 体 名 )
<
小 于 号
>
大 于 号
&
& 符 号
Α
希 腊 字 母 Alpha
注 : 尽 管 可 以 使 用 字 符 引 用 来 引 用 任 何 Unicode 字 符 ( 例 如 希 腊 字 符 和 数 学 字 符 ), 但 是 字 体 不
会 自 动 转 换 。 若 当 前 字 体 中 未 包 含 指 定 的 字 符 , 为 了 实 际 使 用 这 些 字 符 , 必 须 明 确 选 择 合 适
的 字 体 。
Textflow 中 用 于 控 制 字 符 的 附 加 引 用 除 了 以 上 的 HTML 样 式 引 用 之 外 ,PDFlib 还 支 持 自
定 义 字 符 实 体 引 用 , 用 以 指 定 textflow 的 控 制 字 符 。 表 4.5 列 出 了 这 些 附 加 的 字 符 引 用 。
表 4.5 Textflow 中 的 控 制 字 符 及 其 含 意
Unicode 字 符 实 体 名 称 相 当 于 textflow 在 使 用 Unicode 兼 容 字 体 的 textflow 中 的 含 意
选 项
U+0020 SP, space space 对 齐 单 词 并 分 行
U+00A0 NBSP, nbsp (none) ( 非 分 行 空 格 ) 将 不 分 行 的 空 格 字 符
U+0009 HT, hortab (none) 水 平 制 表 位 : 将 根 据 ruler、 tabalignchar 和
tabalignment 选 项 进 行 处 理
U+002D HY, hyphen (none) 用 于 断 词 的 分 隔 符 字 符
U+00AD SHY, shy (none) ( 自 动 连 字 符 ) 提 供 断 词 的 机 会 , 仅 在 分 行 符
处 可 见
U+000B
U+2028
VT, verttab
LS, linesep
nextline ( 新 行 ) 强 制 一 个 新 行
U+000A
U+000D
U+000D and
U+000A
U+0085
U+2029
LF, linefeed
CR, return
CRLF
NEL, newline
PS, parasep
nextparagraph ( 新 段 落 ) 与 “ 新 行 ” 效 果 相 同 ; 另 外 ,
parindent 选 项 将 影 响 新 行 。
U+000C FF, formfeed return PDF_fit_textflow( ) 将 停 止 , 然 后 返 回 字 符 串
_nextpage。
1. 请 参 见 www.w3.org/TR/REC-html40/charset.html#h-5.3
88 第 4 章 : 文 本 处 理

使 用 字 符 引 用 字 符 引 用 可 以 在 所 有 的 内 容 字 符 串 、 超 文 本 字 符 串 和 名 称 字 符 串 中 使 用 , 例
如 在 使 用 show 或 textflow 函 数 放 置 在 页 上 的 文 本 中 使 用 , 以 及 在 提 供 给 超 文 本 函 数 的 文 本
中 使 用 。 注 意 , 在 使 用 builtin 编 码 的 文 本 中 将 不 会 处 理 字 符 引 用 , 这 一 点 很 重 要 。
默 认 情 况 下 , 将 不 会 转 换 字 符 引 用 ; 如 果 需 要 在 所 有 内 容 字 符 串 中 使 用 字 符 引 用 , 则 必
须 将 charref 参 数 明 确 设 置 为 true:
PDF_set_parameter(p, "charref", "true");
通 过 将 charref 选 项 提 供 给 PDF_create_textflow( ) ( 直 接 提 供 或 作 为 内 嵌 选 项 提 供 )、
PDF_fit_textline( ) 或 PDF_fill_textblock( ), 也 可 以 为 textflow 处 理 启 用 字 符 引 用 。
当 启 用 字 符 引 用 时 , 可 以 在 8 位 编 码 的 文 本 中 提 供 数 字 引 用 或 实 体 引 用 :
PDF_set_parameter(p, "charref", "true");
PDF_set_parameter(p, "textformat", "bytes");
font = PDF_load_font(p, "Helvetica", 0, "unicode", "");
PDF_setfont(p, font, 24);
PDF_show_xy(p, "Price: 500€", 50, 500);
在 选 项 列 表 中 将 不 会 替 换 字 符 引 用 , 但 是 将 在 选 项 中 使 用 Unichar 数 据 类 型 识 别 字 符 引 用
( 请 参 见 第 168 页 上 的 第 8.1.2 节 “ 选 项 列 表 ”)。 此 识 别 将 总 是 活 动 的 ; 它 不 由 charref 参
数 控 制 。
当 在 未 引 入 数 字 引 用 或 字 符 引 用 的 文 本 中 找 到 & 字 符 时 , 若 glyphwarning=true, 将 引 发
异 常 。 换 言 之 , 通 过 将 glyphwarning 设 置 为 false, 可 以 在 同 一 文 本 中 使 用 字 符 引 用 和 独 立
的 & 字 符 。
4.5.6 Unicode 兼 容 的 字 体
精 确 的 Unicode 语 义 对 于 PDFlib 的 内 部 处 理 很 重 要 , 而 且 对 从 PDF 文 档 中 正 确 提 取 文 本 或
以 其 他 方 式 重 用 文 档 ( 例 如 将 内 容 转 换 成 其 他 格 式 ) 至 关 紧 要 。 这 在 创 建 标 签 PDF 时 尤 为 重
要 , 因 为 标 签 PDF 对 于 Unicode 规 范 具 有 严 格 的 要 求 ( 请 参 见 第 159 页 上 的 第 7.5.1 节 “ 用
PDFlib 生 成 标 签 PDF”)。 除 了 标 签 PDF 之 外 , Unicode 兼 容 性 还 与 textflow 功 能 有 关 。
Unicode 兼 容 的 字 体 对 于 使 用 PDF_load_font( ) 加 载 的 字 体 ( 更 准 确 地 说 , 应 为 字 体 和 编
码 的 组 合 ), 如 果 在 加 载 字 体 时 使 用 的 编 码 符 合 以 下 条 件 , 则 被 认 为 是 Unicode 兼 容 的 :
> 仅 Symbol 和 ZapfDingbats 字 体 以 及 基 于 PostScript 的 OpenType 字 体 允 许 builtin 编 码 。
> 编 码 不 是 glyphid。
> 若 编 码 是 表 4.7 中 预 定 义 的 CMap 之 一 , 则 它 必 须 是 UCS2 或 UTF16 CMap 中 的 一 种 。
Unicode 兼 容 的 输 出 若 想 确 保 从 生 成 的 PDF 中 能 够 可 靠 地 提 取 文 本 , 则 对 于 生 成 标 签
PDF, 输 出 必 须 是 Unicode 兼 容 的 。 如 果 以 下 条 件 都 成 立 , 则 使 用 PDFlib 创 建 的 PDF 输 出
将 是 Unicode 兼 容 的 :
> 文 档 中 使 用 的 所 有 字 体 都 必 须 是 如 上 所 定 义 的 Unicode 兼 容 的 字 体 , 或 者 使 用 表 4.7 中
预 定 义 的 CMap 之 一 。
> 如 果 编 码 是 使 用 PDF_encoding_set_char( ) 和 字 形 名 称 ( 不 带 相 应 的 Unicode 值 ) 构 造
的 , 或 者 是 从 一 个 编 码 文 件 加 载 的 , 则 所 有 字 形 名 称 必 须 包 含 在 Adobe 字 形 列 表 中 或
Symbol 字 体 中 已 知 的 字 形 名 称 的 列 表 中 。
> unicodemap 参 数 或 选 项 为 true。
> 所 有 文 本 字 符 串 都 必 须 根 据 Unicode 标 准 清 楚 地 定 义 语 义 , 即 不 允 许 Unicode 私 人 使 用
区 域 (PUA) 的 字 符 。
> 使 用 PDI 导 入 的 PDF 页 必 须 与 Unicode 兼 容 。 PDI 不 会 更 改 导 入 的 页 的 Unicode 兼 容
性 状 态 : 它 既 不 会 移 除 也 不 会 添 加 Unicode 信 息 。
4.5 Unicode 支 持 89

当 创 建 标 签 PDF 输 出 时 , 通 过 PDF_begin_item( ) 中 的 ActualText 选 项 提 供 合 适 的 Unicode
文 本 , 违 背 这 些 规 则 的 文 本 部 分 仍 可 以 与 Unicode 兼 容 。
4.6 文 本 规 格 和 文 本 变 体
4.6.1 字 体 和 字 符 规 格
文 本 位 置 PDFlib 可 以 让 文 本 位 置 不 需 要 依 赖 当 前 点 来 绘 制 图 形 。 文 本 位 置 可 以 通 过
textx/texty 参 数 查 询 , 而 当 前 点 可 以 通 过 currentx/currenty 查 询 。
字 符 规 格 PDFlib 使 用 由 PostScript 和 PDF 使 用 的 字 符 和 字 体 规 格 系 统 , 下 面 将 对 此 进 行
简 单 的 讨 论 。
字 体 大 小 ( 必 须 由 PDFlib 用 户 指 定 的 ) 是 相 邻 两 文 本 行 之 间 可 避 免 字 符 重 叠 的 最 小 距
离 。 字 体 大 小 通 常 大 于 字 体 中 的 各 个 字 符 , 因 为 它 跨 越 了 字 母 上 伸 部 分 ( ascender ) 和 字
母 下 伸 部 分 ( descender ), 以 及 行 与 行 之 间 可 能 的 其 他 空 间 。
leading ( 行 间 距 ) 指 定 文 本 的 相 邻 行 的 基 线 之 间 的 垂 直 距 离 。 默 认 情 况 下 , 它 设 置 为 字
体 大 小 的 值 。 capheight 在 多 数 拉 丁 字 体 中 是 指 大 写 字 母 如 T 或 H 的 高 度 。xheight 在 多 数
拉 丁 字 体 中 是 指 小 写 字 母 如 x 高 度 。 ascender 是 指 小 写 字 母 ( 例 如 多 数 拉 丁 字 体 中 的 f 或
d) 的 高 度 。 descender 是 指 从 基 线 到 小 写 字 母 ( 例 如 多 数 拉 丁 字 体 中 的 j 或 p) 的 底 部 的 距
离 。descender 通 常 是 负 值 。xheight、capheight、ascender 和 descender 的 值 作 为 字 体 大 小
的 一 部 分 进 行 计 算 , 在 使 用 这 些 值 之 前 , 必 须 乘 以 所 需 的 字 体 大 小 。
有 些 字 体 或 规 格 文 件 并 不 包 含 这 些 参 数 , 这 时 PDFlib 不 得 不 估 算 其 相 应 值 。 若 想 查 出 所
使 用 的 是 真 实 值 还 是 估 算 值 , 可 查 询 xheightfaked 等 参 数 值 。 查 询 特 定 字 体 的 规 格 信 息 , 如
下 所 示 :
float capheight, ascender, descender, fontsize;
...
font = PDF_load_font(p, "Times-Roman", 0, "winansi", "");
PDF_setfont(p, font, fontsize);
capheight = PDF_get_value(p, "capheight", font) * fontsize;
ascender = PDF_get_value(p, "ascender", font) * fontsize;
descender = PDF_get_value(p, "descender", font) * fontsize;
注 : 无 法 从 PDFlib 查 询 上 标 和 下 标 的 位 置 和 大 小 。
图 4.2 字 体 和 字 符 规 格
ascender
font size
capheight
baseline
descender
90 第 4 章 : 文 本 处 理

CPI 计 算 虽 然 多 数 字 体 都 具 有 变 化 的 字 符 宽 度 , 但 是 所 谓 的 等 宽 字 体 对 所 有 字 符 都 使 用 相
同 的 宽 度 。 为 了 将 PDF 字 体 规 格 与 高 速 度 打 印 环 境 下 经 常 使 用 的 每 英 寸 字 符 数 (CPI) 测 量 单
位 联 系 起 来 , 等 宽 的 Courier 字 体 的 一 些 计 算 示 例 可 能 会 有 帮 助 。 在 Courier 中 , 所 有 字 符
的 宽 度 均 为 600 个 单 位 , 与 此 对 应 的 是 , 整 个 字 符 单 元 为 每 点 1000 个 单 位 ( 可 以 从 相 应
的 AFM 规 格 文 件 检 索 此 值 )。 例 如 , 对 于 12 点 的 文 本 , 所 有 字 符 的 绝 对 宽 度 应 为
12 点 * 600/1000 = 7.2 点
最 佳 行 间 距 为 12 点 。 由 于 每 英 寸 有 72 点 , 因 此 1 英 寸 正 好 放 下 10 个 Courier 12 点 字 符 。
换 言 之 ,12 点 Courier 就 是 10 cpi 字 体 。 对 于 10 点 文 本 , 字 符 宽 度 是 6 点 , 经 过 计 算 应 为
72/6 = 12 cpi 字 体 。 同 样 , 8 点 Courier 对 应 于 15 cpi。
4.6.2 字 距 调 整
一 些 字 符 组 合 会 导 致 难 看 的 外 观 。 例 如 , 紧 邻 的 两 个 V 看 起 来 就 像 一 个 W, 而 T 和 e 之 间 的
距 离 必 须 减 少 以 避 免 不 协 调 的 空 白 。 这 种 调 整 通 常 称 为 “ 字 距 调 整 ”。 许 多 字 体 都 包 含 有 全
面 的 字 距 调 整 表 , 提 供 了 用 于 某 些 关 键 字 母 对 的 间 距 调 整 值 。PDFlib 提 供 了 两 种 控 制 字 距 调
整 行 为 的 方 式 :
> 默 认 情 况 下 , 加 载 字 体 时 不 会 读 取 字 体 中 的 字 距 调 整 信 息 。 若 要 求 进 行 字 距 调 整 , 则 在
对 PDF_load_font( ) 的 相 应 的 调 用 中 必 须 设 置 kerning 选 项 。 这 将 指 示 PDFlib 读 取 字 体 的
字 距 调 整 数 据 ( 如 果 可 用 )。
> 当 已 读 取 了 字 距 调 整 数 据 的 字 体 与 任 何 文 本 输 出 函 数 一 起 使 用 时 , 将 应 用 字 距 调 整 数 据
提 供 的 位 置 修 正 。 不 过 , 也 可 以 通 过 将 kerning 参 数 设 置 为 false 禁 用 字 距 调 整 :
PDF_set_parameter(p, "kerning", "false"); /* disable kerning */
有 时 可 能 需 要 临 时 禁 用 字 距 调 整 , 例 如 , 由 于 经 过 字 距 调 整 的 数 字 在 表 中 无 法 对 齐 , 因
此 对 于 在 字 距 调 整 表 中 具 有 对 应 的 数 字 对 的 表 中 数 字 , 应 临 时 禁 用 字 距 调 整 。
除 了 可 能 激 活 的 任 何 字 符 间 距 、 单 词 间 距 和 水 平 缩 放 之 外 , 还 应 用 字 距 调 整 。PDFlib 对 字 体
中 的 字 距 调 整 对 的 数 目 没 有 任 何 限 制 。
图 4.3 字 距 调 整
No kerning
Kerning applied
Character movement caused by kerning
4.6 文 本 规 格 和 文 本 变 体 91

4.6.3 文 本 变 体
伪 字 体 样 式 字 体 的 粗 体 和 斜 体 变 体 通 常 应 通 过 选 择 适 合 的 字 体 来 创 建 。 此 外 , PDFlib 也
支 持 伪 字 体 样 式 : 在 常 规 字 体 的 基 础 上 , Acrobat 将 通 过 增 强 或 倾 斜 基 本 字 体 模 拟 粗 体 、 斜
体 或 粗 斜 体 样 式 。 伪 字 体 样 式 的 美 感 质 量 比 不 上 由 字 体 设 计 器 精 心 调 配 出 的 实 际 粗 体 或 斜
体 字 体 。 不 过 , 在 不 能 直 接 使 用 特 殊 字 体 样 式 的 情 况 下 , 可 以 使 用 伪 样 式 作 为 一 种 变 通 方
式 。 伪 字 体 样 式 对 于 标 准 CJK 字 体 尤 其 有 用 , 因 为 该 字 体 仅 支 持 常 规 字 体 , 而 不 支 持 任 何 粗
体 或 斜 体 变 体 。
注 : 不 建 议 对 标 准 标 准 CJK 字 体 以 外 的 字 体 使 用 fontstyle 功 能 。 还 请 注 意 , fontstyle 功 能 在
Adobe Acrobat 之 外 的 PDF 浏 览 器 中 可 能 不 起 作 用 。
由 于 Adobe Acrobat 中 的 限 制 , 仅 在 以 下 所 有 条 件 都 满 足 的 情 况 下 , 伪 字 体 样 式 才 起 作 用 :
> 基 字 体 是 TrueType 或 OpenType 字 体 , 包 括 标 准 和 自 定 义 CJK 字 体 。 基 字 体 不 得 为
PDF 核 心 字 体 ( 请 参 见 第 76 页 上 的 第 4.3.2 节 “ 字 体 嵌 入 ” ) 。 字 体 样 式 不 能 应 用 于
TrueType 集 合 (TTC)。
> 编 码 是 winansi、macroman 或 表 4.7 中 列 出 的 预 定 义 CJK CMaps 之 一 ( 因 为 如 果 不 是 这
样 的 话 , PDFlib 将 强 制 执 行 字 体 嵌 入 )。
> embedding 选 项 必 须 设 置 为 false。
> 基 字 体 必 须 安 装 在 查 看 PDF 所 使 用 的 目 标 系 统 上 。
虽 然 PDFlib 将 检 查 最 初 三 个 条 件 , 但 是 用 户 需 要 负 责 确 保 最 后 一 个 条 件 。
通 过 对 PDF_load_font( ) 的 fontstyle 选 项 使 用 normal( 对 基 字 体 不 做 任 何 更 改 )、 bold、
italic 或 bolditalic 关 键 字 , 可 以 请 求 伪 字 体 样 式 :
PDF_load_font(p, "HeiseiKakuGo-W5", 0, "UniJIS-UCS2-H", "fontstyle bold");
fontstyle 功 能 不 应 与 Windows 字 体 样 式 名 称 的 类 似 概 念 混 淆 。fontstyle 仅 在 以 上 条 件 下 才
起 作 用 , 并 需 要 Acrobat 来 模 拟 伪 字 体 样 式 , 而 Windows 样 式 名 称 完 全 基 于 Windows 字
体 选 择 引 擎 , 并 且 不 能 用 于 模 拟 不 存 在 的 样 式 。
模 拟 的 斜 体 字 体 作 为 fontstyle 的 一 种 替 代 方 式 , italicangle 参 数 或 选 项 可 用 于 在 只 提 供
有 常 规 字 体 的 情 况 下 模 拟 斜 体 字 体 。 此 方 法 通 过 将 常 规 字 体 倾 斜 用 户 提 供 的 角 度 来 创 建 伪
斜 体 字 体 , 并 且 不 受 以 上 提 到 的 fontstyle 限 制 。 负 值 将 顺 时 针 倾 斜 文 本 。 注 意 , 使 用 实 际
斜 体 或 倾 斜 的 字 体 将 会 得 到 更 加 满 意 的 输 出 。 不 过 , 若 没 有 可 用 的 斜 体 字 体 , 则 可 以 使 用
italicangle 参 数 轻 松 地 模 拟 一 款 斜 体 字 体 。 此 功 能 可 能 对 CJK 字 体 特 别 有 用 。 italicangle 参
数 的 典 型 值 的 范 围 是 -12 到 -15 度 之 间 :
PDF_set_value(p, "italicangle", -12); /* create fake italic font */
注 : 垂 直 书 写 模 式 不 支 持 italicangle 参 数 。
下 划 线 、 上 划 线 和 删 除 线 文 本 可 以 指 示 PDFlib 将 文 本 的 下 方 、 上 方 或 中 间 放 置 直 线 。 横
线 的 粗 细 以 及 它 与 基 线 的 距 离 将 基 于 字 体 的 规 格 信 息 进 行 计 算 。 另 外 , 当 计 算 横 线 的 宽 度
时 , 需 要 考 虑 水 平 缩 放 因 素 和 文 本 字 模 的 当 前 值 。 PDF_set_parameter( ) 可 用 于 开 启 或 关 闭
下 划 线 、 上 划 线 和 删 除 线 功 能 , 如 下 所 示 :
PDF_set_parameter(p, "underline", "true"); /* enable underlines */
使 用 当 前 的 笔 触 颜 色 绘 制 横 线 。 不 过 , 将 忽 略 当 前 的 linecap 和 dash 参 数 。 审 美 学 上 的 提 示 :
在 大 多 数 字 体 中 , 下 划 线 将 接 触 到 下 行 字 母 , 而 上 划 线 将 接 触 到 上 行 字 母 顶 部 的 发 音 标 记 。
注 : 除 非 使 用 Unicode CMap, 否 则 标 准 CJK 字 体 不 支 持 下 划 线 、 上 划 线 和 删 除 线 功 能 。
92 第 4 章 : 文 本 处 理

文 本 渲 染 模 式 PDFlib 支 持 一 些 将 影 响 文 本 外 观 的 渲 染 模 式 。 其 中 包 括 空 心 文 本 和 将 文 本
用 作 剪 贴 路 径 的 能 力 。 文 本 也 可 以 通 过 不 可 见 的 方 式 渲 染 , 这 样 可 能 有 助 于 在 扫 描 的 图 像 上
放 置 文 本 , 从 而 可 以 搜 索 文 本 和 构 建 文 本 索 引 , 同 时 确 保 文 本 将 不 会 直 接 可 见 。 在 表 8.18 中
说 明 了 渲 染 模 式 。 可 以 使 用 PDF_set_value( ) 和 textrendering 参 数 设 置 这 些 模 式 。
PDF_set_value(p, "textrendering", 1); /* set stroked text rendering (outline text) */
当 对 文 本 描 边 时 , 将 对 字 形 轮 廓 使 用 图 形 状 态 参 数 , 例 如 linewidth 和 color 参 数 。 渲 染 模
式 对 使 用 Type 3 字 体 显 示 的 文 本 没 有 影 响 。
注 : 文 本 渲 染 模 式 7 ( 用 文 本 作 为 剪 贴 路 径 ) 当 使 用 PDF_fit_textline( ) 或 PDF_fit_textflow( ) 创 建
文 本 输 出 时 , 将 没 有 任 何 影 响 。
文 本 颜 色 通 常 文 本 将 使 用 当 前 填 充 色 显 示 , 填 充 色 可 以 使 用 PDF_setcolor( ) 进 行 设 置 。 不
过 , 若 选 定 的 是 除 0 之 外 的 渲 染 模 式 , 则 描 边 和 填 充 色 对 文 本 的 影 响 可 能 会 因 选 定 的 渲 染 模
式 而 异 。
4.7 中 文 、 日 文 和 韩 文 文 本
4.7.1 Acrobat 和 PDF 中 支 持 的 CJK
Acrobat/PDF 支 持 一 组 没 有 字 体 嵌 入 的 标 准 CJK 字 体 , 以 及 自 定 义 的 嵌 入 式 CJK 字 体 。 尽 管
嵌 入 的 CJK 字 体 在 所 有 版 本 的 Acrobat 中 都 可 以 起 作 用 而 无 需 再 费 周 折 , 但 是 在 Acrobat 中
使 用 任 何 标 准 CJK 字 体 都 要 求 用 户 执 行 以 下 操 作 之 一
1 :
> 使 用 本 地 化 的 CJK 版 本 的 Acrobat。
> 若 使 用 任 何 非 CJK 版 本 的 完 全 版 Acrobat 产 品 , 请 选 择 Acrobat 安 装 程 序 中 的 选 项 “ 亚
洲 语 言 支 持 ” (Windows) 或 “ 语 言 工 具 包 ” (Mac)。 将 从 Acrobat 产 品 光 盘 中 安 装 必 需
的 支 持 文 件 ( 字 体 和 CMap)。
> 若 使 用 Acrobat Reader, 则 安 装 在 Web 上 可 用 的 亚 洲 字 体 包 之 一 。 2
打 印 带 有 CJK 文 本 的 PDF 文 档 打 印 CJK 文 档 会 引 起 许 多 超 出 本 手 册 讨 论 范 围 的 问 题 。 不
过 , 为 了 方 便 PDFlib 用 户 , 我 们 将 提 供 一 些 有 用 的 提 示 。 若 您 在 使 用 Acrobat 打 印 CJK 文
档 ( 特 别 是 那 些 使 用 了 标 准 字 体 的 CJK 文 档 ) 时 遇 到 麻 烦 , 则 请 考 虑 以 下 内 容 :
> 由 于 字 符 数 量 巨 大 , CJK 字 体 会 消 耗 大 量 打 印 机 内 存 , 除 非 已 应 用 字 体 子 集 化 功 能 。 不
是 所 有 的 打 印 机 都 具 备 打 印 此 类 字 体 所 需 的 足 够 内 存 。
> 非 日 文 PostScript 打 印 机 没 有 安 装 任 何 日 文 字 体 。 为 此 , 您 必 须 在 Acrobat 的 打 印 对 话
框 中 选 中 “ 下 载 亚 洲 字 体 ”。
> 若 您 无 法 使 用 下 载 的 字 体 成 功 打 印 , 则 请 在 Acrobat 的 打 印 对 话 框 中 选 中 “ 作 为 图 像 打
印 ”。 这 样 会 指 示 Acrobat 将 页 面 的 位 图 版 本 发 送 到 打 印 机 ( 但 分 辨 率 只 有 300 dpi)。
4.7.2 标 准 CJK 字 体 和 CMap
在 历 史 上 , 不 同 的 标 准 化 团 体 、 公 司 和 其 他 组 织 已 开 发 出 大 量 CJK 编 码 方 案 。 幸 运 地 是 , 默
认 情 况 下 ,Acrobat 和 PDF 支 持 所 有 现 行 编 码 。 由 于 编 码 的 概 念 对 于 CJK 文 本 相 对 于 拉 丁 文
本 来 说 复 杂 很 多 , 所 以 仅 使 用 简 单 的 8 位 编 码 已 不 够 。PostScript 和 PDF 使 用 字 符 集 合 和 字
符 映 射 (CMap) 的 概 念 来 组 织 字 体 中 的 字 符 。
1. 这 里 需 要 感 谢 Ken Lunde 的 开 创 性 著 作 《CJKV 信 息 处 理 – 中 文 、 日 文 、 韩 文 和 越 南 文 计 算 》 (CJKV information
processing – Chinese, Japanese, Korean & Vietnamese Computing, O’Reilly 1999, ISBN 1-56592-224-7), 以 及 他 本 人 在
Adobe 的 工 作 。 他 与 其 他 人 一 道 推 动 了 PostScript 和 PDF 中 的 CJK 支 持 工 作 。
2. 请 参 见 www.adobe.com/products/acrobat/acrrasianfontpack.html
4.7 中 文 、 日 文 和 韩 文 文 本 93

Acrobat 支 持 许 多 用 于 CJK 文 本 的 标 准 字 体 。 这 些 字 体 通 过 Acrobat 安 装 ( 或 亚 洲 字 体
包 ) 提 供 , 因 此 不 必 在 PDF 文 件 中 嵌 入 。 这 些 字 体 包 含 常 用 编 码 所 需 的 所 有 字 符 , 并 且 支
持 水 平 书 写 和 垂 直 书 写 两 种 模 式 。 在 表 4.6 中 列 出 了 这 些 标 准 字 体 和 CMaps。 Acrobat 4 字
体 也 可 以 与 Acrobat 5 一 起 使 用 , 如 果 系 统 上 未 安 装 所 需 的 字 体 , 则 使 用 相 应 的 Acrobat 5
字 体 进 行 显 示 和 打 印 。
注 : Acrobat 的 标 准 CJK 字 体 不 支 持 粗 体 和 斜 体 变 体 。 不 过 , 可 以 使 用 伪 字 体 样 式 功 能 模 拟 这 些
字 体 ( 请 参 见 第 92 页 上 的 第 4.6.3 节 “ 文 本 变 体 ”)。
正 如 表 中 显 示 的 一 样 , 默 认 CMap 支 持 在 Mac、Windows 和 Unix 系 统 上 使 用 的 大 多 数 CJK
编 码 , 以 及 一 些 其 他 的 特 定 于 供 应 商 的 编 码 。 具 体 而 言 , 如 支 持 主 要 的 日 文 编 码 方 案 Shift-
JIS、 EUC、 ISO 2022 和 Unicode (UCS-2 和 UTF-16) 。 包 含 所 有 支 持 的 字 符 的 表 可 以 从
Adobe 1 获 得 ; 在 表 4.7 中 可 以 找 到 CMap 说 明 。
注 : 支 持 Unicode 的 语 言 绑 定 必 须 仅 使 用 Unicode 兼 容 的 CMap (UCS2 或 UTF16)。 不 支 持 其 他
的 CMap。
表 4.6 Acrobat 的 用 于 日 文 、 中 文 和 韩 文 文 本 的 标 准 字 体 和 CMap ( 编 码 )
区 域 字 体 名 称 示 例 支 持 的 CMap ( 编 码 )
简 体 中 文 STSong-Light 1
STSongStd-Light-Acro 2
AdobeSongStd-Light-Acro 3
繁 体 中 文 MHei-Medium 1
MSung-Light 1
MSungStd-Light-Acro 2
AdobeMingStd-Light-Acro 3
日 文 HeiseiKakuGo-W5 1
HeiseiMin-W3 1
KozMinPro-Regular-Acro 2, 6
KozGoPro-Medium-Acro 3, 6
韩 文 HYGoThic-Medium 1
HYSMyeongJo-Medium 1
HYSMyeongJoStd-Medium-
Acro 2
AdobeMyungjoStd-
Medium-Acro 3
GB-EUC-H, GB-EUC-V, GBpc-EUC-H, GBpc-EUC-V,
GBK-EUC-H, GBK-EUC-V, GBKp-EUC-H 4 , GBKp-EUC-V 2 ,
GBK2K-H 2 , GBK2K-V 2 , UniGB-UCS2-H, UniGB-UCS2-V,
UniGB-UTF16-H 5 , UniGB-UTF16-V 5
B5pc-H, B5pc-V, HKscs-B5-H 4 , HKscs-B5-V 4 , ETen-B5-H,
ETen-B5-V, ETenms-B5-H, ETenms-B5-V, CNS-EUC-H,
CNS-EUC-V, UniCNS-UCS2-H, UniCNS-UCS2-V,
UniCNS-UTF16-H 5 , UniCNS-UTF16-V 5
83pv-RKSJ-H, 90ms-RKSJ-H, 90ms-RKSJ-V,
90msp-RKSJ-H, 90msp-RKSJ-V, 90pv-RKSJ-H,
Add-RKSJ-H, Add-RKSJ-V, EUC-H, EUC-V, Ext-RKSJ-H,
Ext-RKSJ-V, H, V, UniJIS-UCS2-H, UniJIS-UCS2-V,
UniJIS-UCS2-HW-H 6 , UniJIS-UCS2-HW-V 6 ,
UniJIS-UTF16-H 5 , UniJIS-UTF16-V 5
KSC-EUC-H, KSC-EUC-V, KSCms-UHC-H, KSCms-UHC-V,
KSCms-UHC-HW-H, KSCms-UHC-HW-V, KSCpc-EUC-H,
UniKS-UCS2-H, UniKS-UCS2-V, UniKS-UTF16-H 5 , UniKS-
UTF16-V 5
1. 在 Acrobat 4 中 可 用 ; Acrobat 5 和 6 将 使 用 不 同 的 字 体 替 换 这 些 字 体 。
2. 仅 在 Acrobat 5 中 可 用 。
3. 仅 在 Acrobat 6 中 可 用 。
4. 仅 当 生 成 PDF 1.4 或 更 高 版 本 时 可 用 。
5. 仅 当 生 成 PDF 1.5 或 更 高 版 本 时 可 用 。
6. KozMinPro-Regular-Acro 和 KozGoPro-Medium-Acro 字 体 不 允 许 HW CMap, 因 为 这 些 字 体 仅 包 含 比 例 ASCII 字 符 , 而 不
包 含 任 何 半 宽 字 符 。
1. 有 关 与 CID 字 体 相 关 的 资 源 宝 库 , 包 括 列 出 了 所 有 支 持 的 字 形 的 表 ( 搜 索 “character collection”),
请 参 见 partners.adobe.com/asn/tech/type/cidfonts.jsp。
94 第 4 章 : 文 本 处 理

水 平 书 写 和 垂 直 书 写 模 式 PDFlib 支 持 对 标 准 CJK 字 体 和 CMap 使 用 水 平 书 写 和 垂 直 书 写
模 式 。 通 过 选 择 适 当 的 CMap 名 称 , 可 连 同 编 码 一 起 选 定 模 式 。 其 名 称 结 尾 为 -H 的 CMap
选 择 水 平 书 写 模 式 , 而 -V 后 缀 选 择 垂 直 书 写 模 式 。
注 : 一 些 PDFlib 函 数 可 根 据 书 写 模 式 更 改 它 们 的 语 义 。 例 如 , 不 应 在 垂 直 书 写 模 式 中 使 用
PDF_continue_text( ), 并 且 必 须 将 字 符 间 距 设 置 为 负 值 以 便 在 垂 直 书 写 模 式 中 将 字 符 分 开 。
用 于 标 准 CMap 的 CJK 文 本 编 码 客 户 负 责 提 供 与 请 求 的 CMap 匹 配 的 编 码 文 本 。 PDFlib
对 提 供 的 文 本 是 否 符 合 请 求 的 CMap 不 作 检 查 。
对 于 多 字 节 编 码 , 字 符 的 高 位 字 节 必 须 首 先 出 现 。 另 外 , 可 以 使 用 textformat 参 数 选 定
字 节 顺 序 和 文 本 格 式 ( 请 参 见 第 83 页 上 的 第 4.5.1 节 “ 页 面 内 容 和 超 文 本 的 Unicode”),
前 提 是 使 用 Unicode CMap (UCS-2 或 UTF-16)。
因 为 一 些 受 支 持 的 编 码 可 能 会 在 文 本 字 符 串 中 包 含 Null 字 符 , C 开 发 人 员 必 须 注 意 不
要 使 用 PDF_show( ) 等 函 数 , 而 应 改 用 PDF_show2( ) 等 函 数 , 后 者 允 许 提 供 任 意 二 进 制 字 符
串 和 一 个 长 度 参 数 。 对 于 所 有 其 他 语 言 绑 定 , 文 本 函 数 支 持 二 进 制 字 符 串 , 并 且 不 需 要
PDF_show2( ) 等 函 数 。
标 准 CJK 字 体 和 CMap 的 限 制 与 非 Unicode CMap 组 合 的 标 准 CJK 字 体 不 支 持 以 下 功 能
(Unicode CMap 在 其 名 称 中 带 有 UCS2 或 UTF16):
> 使 用 PDF_stringwidth( ) 计 算 文 本 的 宽 度 ( 请 参 见 第 95 页 上 的 “ 强 制 等 宽 字 体 ”)
> 使 用 PDF_fit_textline( )、 PDF_create_textflow( ) 和 相 关 的 Textflow 函 数
> 激 活 下 划 线 / 上 划 线 / 删 除 线 模 式
> 检 索 textx/texty 位 置
这 些 限 制 适 用 于 标 准 CJK 字 体 。 请 注 意 , 尽 管 在 这 些 情 况 下 无 法 查 询 CJK 文 本 的 宽 度 , 但 在
PDF 输 出 中 将 正 确 地 生 成 此 宽 度 。 还 请 注 意 , 自 定 义 CJK 字 体 完 全 支 持 以 上 所 有 功 能 。
标 准 CJK 字 体 示 例 通 过 使 用 PDF_load_font( ) 接 口 并 提 供 CMap 名 称 作 为 encoding 参
数 , 可 选 择 标 准 CJK 字 体 。 不 过 , 必 须 考 虑 到 一 点 : 给 定 的 CJK 字 体 仅 支 持 一 组 CMap
( 请 参 见 表 4.6), 并 且 识 别 Unicode 的 语 言 绑 定 仅 支 持 UCS2 兼 容 的 CMap。 表 4.6 中 的
KozMinPro-Regular-Acro 示 例 可 以 使 用 以 下 代 码 生 成 :
font = PDF_load_font(p, "KozMinPro-Regular-Acro", 0, "UniJIS-UCS2-H", "");
PDF_setfont(p, font, 24);
PDF_set_text_pos(p, 50, 500);
/* We use UTF-16 format with little-endian (LE) byte ordering */
PDF_set_parameter(p, "textformat", "utf16le");
PDF_show(p, "\xE5\x65\x2C\x67\x9E\x8A");
上 述 语 句 查 找 一 种 日 文 标 准 字 体 , 并 且 选 择 Shift-JIS 兼 容 的 CMap (Ext-RKSJ) 和 水 平 书 写
模 式 (H)。 fontname 参 数 必 须 是 字 体 的 准 确 名 称 , 并 且 不 带 任 何 编 码 或 书 写 模 式 后 缀 。
encoding 参 数 是 一 种 受 支 持 的 CMap 的 名 称 ( 根 据 字 体 选 择 ) , 并 且 还 将 指 示 书 写 模 式
( 请 参 见 前 面 的 内 容 )。 PDFlib 支 持 Acrobat 的 所 有 默 认 CMap, 并 且 会 在 检 测 到 请 求 的
字 体 和 CMap 不 匹 配 时 做 出 反 应 。 例 如 ,PDFlib 将 拒 绝 对 韩 文 字 体 使 用 日 文 编 码 的 请 求 。
强 制 等 宽 字 体 一 些 应 用 程 序 没 有 能 力 处 理 比 例 CJK 字 体 和 根 据 字 形 宽 度 和 字 形 数 量 来 计
算 文 本 的 宽 度 。 可 以 指 示 PDFlib 甚 至 对 通 常 具 有 宽 度 不 定 的 字 形 的 字 体 强 制 使 用 等 宽 字
形 。 使 用 PDF_load_font( ) 的 monospace 选 项 可 以 指 定 所 有 字 形 所 需 的 宽 度 。 对 于 标 准 CJK
字 体 , 值 1000 将 产 生 满 意 的 结 果 :
font = PDF_load_font(p, "KozMinPro-Regular-Acro", 0, "UniJIS-UCS2-H", "monospace 1000");
4.7 中 文 、 日 文 和 韩 文 文 本 95

表 4.7 用 于 日 文 、 中 文 和 韩 文 文 本 的 预 定 义 CMap ( 摘 自 PDF Reference)
区 域 CMap 名 称 字 符 集 和 文 本 格 式
简 体 中 文 UniGB-UCS2-H 用 于 Adobe-GB1 字 符 集 合 的 Unicode (UCS-2) 编 码
UniGB-UCS2-V
繁 体 中 文
UniGB-UTF16-H
UniGB-UTF16-V
GB-EUC-H
GB-EUC-V
GBpc-EUC-H
GBpc-EUC-V
GBK-EUC-H, -V
GBKp-EUC-H
GBKp-EUC-V
GBK2K-H, -V
UniCNS-UCS2-H
UniCNS-UCS2-V
UniCNS-UTF16-H
UniCNS-UTF16-V
用 于 Adobe-GB1 字 符 集 合 的 Unicode (UTF-16BE) 编 码 。 包 含 对
GB18030-2000 字 符 集 中 所 有 字 符 的 映 射 。
Microsoft 代 码 页 936 ( 字 符 集 134), GB 2312-80 字 符 集 , EUC-CN 编 码
Macintosh, GB 2312-80 字 符 集 , EUC-CN 编 码 , Script Manager 代 码 2
Microsoft 代 码 页 936 ( 字 符 集 134), GBK 字 符 集 , GBK 编 码
与 GBK-EUC-H 一 样 , 但 将 半 宽 拉 丁 字 符 替 换 为 比 例 字 符 , 并 将 代 码
0x24 映 射 为 美 元 符 号 ($) 而 非 人 民 币 元 符 号 (¥)。
GB 18030-2000 字 符 集 , 混 合 的 1 字 节 、 2 字 节 和 4 字 节 编 码
用 于 Adobe-CNS1 字 符 集 合 的 Unicode (UCS-2) 编 码
用 于 Adobe-CNS1 字 符 集 合 的 Unicode (UTF-16BE) 编 码 。 包 含 对
HKSCS-2001 的 所 有 字 符 (2 字 节 和 4 字 节 字 符 代 码 ) 的 映 射
B5pc-H, -V Macintosh, Big 5 字 符 集 , Big 5 编 码 , Script Manager 代 码 2
HKscs-B5-H 香 港 SCS ( 增 补 字 符 集 ), 对 Big 5 字 符 集 和 编 码 的 扩 充
HKscs-B5-V
ETen-B5-H, -V Microsoft 代 码 页 950 ( 字 符 集 136), 带 ETen 扩 展 名 的 Big 5
ETenms-B5-H 与 ETen-B5-H 一 样 , 但 将 半 宽 拉 丁 字 符 替 换 为 比 例 字 符
ETenms-B5-V
CNS-EUC-H, -V CNS 11643-1992 字 符 集 , EUC-TW 编 码
日 文 UniJIS-UCS2-H, -V 用 于 Adobe-Japan1 字 符 集 合 的 Unicode (UCS-2) 编 码
UniJIS-UCS2-HW-H
UniJIS-UCS2-HW-V
与 UniJIS-UCS2-H 一 样 , 但 是 用 半 宽 窗 体 替 换 成 比 例 的 拉 丁 字 符
UniJIS-UTF16-H
UniJIS-UTF16-V
用 于 Adobe-Japan1 字 符 集 合 的 Unicode (UTF-16BE) 编 码 。
在 JIS X 0213:1000 字 符 集 中 包 含 所 有 字 符 的 映 射 。
83pv-RKSJ-H Mac, 带 KanjiTalk6 扩 展 名 的 JIS X 0208, Shift-JIS, 脚 本 管 理 器 代 码 1
90ms-RKSJ-H
90ms-RKSJ-V
90msp-RKSJ-H
90msp-RKSJ-V
Microsoft 代 码 页 932( 字 符 集 128), 带 NEC 和 IBM 扩 展 名 的 JIS X 0208
字 符 集
与 90ms-RKSJ-H 一 样 , 但 是 用 成 比 例 的 窗 体 替 换 半 宽 拉 丁 字 符
90pv-RKSJ-H Mac, 带 KanjiTalk7 扩 展 名 的 JIS X 0208, Shift-JIS, 脚 本 管 理 器 代 码 1
Add-RKSJ-H, -V
EUC-H, -V
带 Fujitsu FMR 扩 展 名 、 Shift-JIS 编 码 的 JIS X 0208 字 符 集
JIS X 0208 字 符 集 , EUC-JP 编 码
Ext-RKSJ-H, -V 带 NEC 扩 展 名 、 Shift-JIS 编 码 的 JIS C 6226 (JIS78) 字 符 集
H, V JIS X 0208 字 符 集 , ISO-2022-JP 编 码
韩 文 UniKS-UCS2-H, -V 用 于 Adobe-Korea1 字 符 集 合 的 Unicode (UCS-2) 编 码
UniKS-UTF16-H, -V 用 于 Adobe-Korea1 字 符 集 合 的 Unicode (UTF-16BE) 编 码
KSC-EUC-H, -V
KSCms-UHC-H
KSCms-UHC-V
KSCms-UHC-HW-H
KSCms-UHC-HW-V
KS X 1001:1992 字 符 集 , EUC-KR 编 码
Microsoft 代 码 页 949 ( 字 符 集 129), KS X 1001:1992 字 符 集 加 上 8822
附 加 hangul, 统 一 Hangul 代 码 (UHC) 编 码
与 KSCms-UHC-H 一 样 , 但 是 用 半 宽 窗 体 替 换 成 比 例 的 拉 丁 字 符
KSCpc-EUC-H Mac, 具 有 Mac OS KH 扩 展 的 KS X 1001:1992, Script Manager 代 码 3
96 第 4 章 : 文 本 处 理

仅 对 标 准 CJK 字 体 推 荐 使 用 monospace 选 项 。
4.7.3 自 定 义 CJK 字 体
除 了 Acrobat 的 标 准 CJK 字 体 之 外 ,PDFlib 还 支 持 TrueType( 包 括 TrueType 集 合 (TTC))
中 的 自 定 义 CJK 字 体 ( 表 4.6 中 的 列 表 之 外 的 字 体 ) 和 OpenType 格 式 。 将 按 如 下 方 式 处
理 自 定 义 CJK 字 体 :
> 不 管 客 户 端 提 供 的 嵌 入 设 置 如 何 , 字 体 将 转 换 为 CID 字 体 并 嵌 入 到 PDF 输 出 中 。 因 为
PDFlib 遵 从 可 能 在 字 体 中 定 义 的 字 体 嵌 入 限 制 , 所 以 不 允 许 嵌 入 的 字 体 不 能 用 作 自 定 义
CJK 字 体 。
> 默 认 情 况 下 , 将 对 嵌 入 的 自 定 义 CJK 字 体 使 用 字 体 子 集 化 , 除 非 该 字 体 与 标 准 CMap 一
起 使 用 。 可 以 使 用 多 个 参 数 控 制 上 述 行 为 , 请 参 见 第 75 页 上 的 第 4.3 节 “ 字 体 嵌 入 和 子
集 化 ”。
> 自 定 义 CJK 字 体 和 一 些 编 码 支 持 比 例 拉 丁 字 符 和 半 宽 字 符 ( 请 参 见 表 8.15)。
> Windows 上 的 日 文 宿 主 字 体 名 称 可 以 提 供 给 PDF_load_font( ) 作 为 带 初 始 BOM 的 UTF-8
或 UCS-2, 但 在 Mac 上 不 支 持 非 拉 丁 宿 主 字 体 名 称 。
注 : 虽 然 支 持 Windows EUDC 字 体 ( 终 端 用 户 定 义 的 字 符 ), 但 是 不 支 持 将 单 个 最 终 用 户 定 义 的
字 符 链 接 到 所 有 字 体 中 ( 请 参 见 以 下 内 容 )。
注 : TrueType CJK 字 体 不 支 持 垂 直 书 写 模 式 。
自 定 义 CJK 字 体 支 持 的 编 码 自 定 义 CJK 字 体 可 以 与 以 下 编 码 一 起 使 用 ( 另 请 参 见 表 8.15):
> 在 Windows 上 , 在 系 统 上 安 装 的 任 何 代 码 页 都 可 以 使 用 。 必 须 使 用 cp 作 为 代 码 页 号 的
前 缀 ( 有 关 示 例 , 请 参 见 表 4.8)。textformat 参 数 必 须 设 置 为 auto, 并 且 必 须 使 用 与 选
定 的 代 码 页 兼 容 的 格 式 提 供 文 本 。
> 使 用 PostScript 字 型 的 OpenType CJK 字 体 (CID 字 体 ) 可 以 与 相 应 区 域 的 所 有 CMap
一 起 使 用 ( 例 如 , 日 文 字 体 仅 可 以 与 日 文 CMap 一 起 使 用 )。
> unicode 编 码 。
> glyphid 寻 址 ( 请 参 见 第 82 页 上 的 第 4.4.3 节 “TrueType 和 OpenType 字 体 的 字 形 ID
寻 址 ”)。
将 为 自 定 义 CJK 字 体 计 算 textformat 参 数 。
表 4.8 Windows 上 的 CJK 代 码 页 示 例 ( 必 须 与 textformat=auto 一 起 使 用 )
区 域 代 码 页 格 式 字 符 集
简 体 中 文 cp936 GBK GBK
繁 体 中 文 cp950 Big 5 带 有 Microsoft 扩 展 的 Big 5
日 文 cp932 Shift-JIS 带 有 Microsoft 扩 展 的 JIS X 0208:1997
韩 文 cp949 UHC KS X 1001:1992, 保 留 8822 hangul 作 为 扩 展
cp1361 Johab Johab
用 于 日 文 Shift-JIS 文 本 的 自 定 义 CJK 字 体 示 例 以 下 示 例 使 用 MS Mincho 字 体 来 显 示 一
些 日 文 文 本 , 这 些 文 本 是 根 据 Windows 代 码 页 932 按 照 Shift-JIS 格 式 提 供 的 :
font = PDF_load_font(p, "MS Mincho", 0, "cp932", "");
PDF_setfont(p, font, 24);
PDF_set_text_pos(p, 50, 500);
PDF_show2(p, "\x82\xA9\x82\xC8\x8A\xBF\x8E\x9A", 8);
4.7 中 文 、 日 文 和 韩 文 文 本 97

用 于 中 文 Unicode 文 本 的 自 定 义 CJK 字 体 示 例 以 下 示 例 使 用 ArialUnicodeMS 字 体 以 显 示
一 些 中 文 文 本 。 该 字 体 必 须 安 装 在 系 统 上 或 者 必 须 根 据 第 75 页 上 的 第 4.3.1 节 “PDFlib 搜
索 字 体 的 方 法 ” 进 行 配 置 :
/* This is not required if the font is installed on the system */
PDF_set_parameter(p, "FontOutline", "Arial Unicode MS=ARIALUNI.TTF");
font = PDF_load_font(p, "Arial Unicode MS", 0, "unicode", "");
PDF_setfont(p, font, 24);
PDF_set_text_pos(p, 50, 500);
/* We use UTF-16 format with big-endian (BE) byte ordering */
PDF_set_parameter(p, "textformat", "utf16be");
PDF_show2(p, "\x4e\x00\x50\x0b\x4e\xba", 6);
在 访 问 TrueType 集 合 (TTC) 中 的 各 个 字 体 TTC 文 件 包 含 多 个 单 独 的 字 体 。 可 以 通 过 提 供
正 确 的 名 称 来 访 问 相 应 的 字 体 。 不 过 , 若 不 知 道 TTC 文 件 中 包 含 了 哪 些 字 体 , 则 可 以 通 过 在
TTC 文 件 内 追 加 一 个 冒 号 字 符 和 字 体 编 号 ( 以 0 开 始 ) 来 以 数 字 方 式 对 每 个 字 体 寻 址 。 若
索 引 为 0, 则 它 可 以 被 省 略 。 例 如 , TTC 文 件 msgothic.ttc 包 含 多 个 字 体 , 这 些 字 体 可 以 通
过 如 下 方 式 用 PDF_load_font( ) 进 行 寻 址 ( 每 一 行 包 含 相 当 的 字 体 名 称 ):
msgothic:0 MS Gothic msgothic:
msgothic:1 MS PGothic
msgothic:2 MS UI Gothic
请 注 意 ,msgothic( 不 带 任 何 后 缀 ) 将 不 能 用 作 字 体 名 , 因 为 它 不 能 唯 一 地 识 别 字 体 。 字 体
名 称 别 名 ( 请 参 见 第 75 页 上 的 第 4.3.1 节 “PDFlib 搜 索 字 体 的 方 法 ”) 可 以 与 TTC 索 引 结
合 使 用 。 若 无 法 找 到 具 有 指 定 索 引 的 字 体 , 并 且 fontwarning=true, 将 引 发 异 常 。
TTC 字 体 文 件 仅 需 要 配 置 一 次 ; TTC 文 件 中 所 有 编 入 索 引 的 字 体 都 将 自 动 找 到 。 以 下 代
码 足 以 配 置 msgothic.ttc 中 的 所 有 编 入 索 引 的 字 体 :
PDF_set_parameter(p, "FontOutline", "msgothic=msgothic.ttc")
终 端 用 户 定 义 的 字 符 (EUDC) PDFlib 不 支 持 将 终 端 用 户 定 义 的 字 符 链 接 到 字 体 中 , 但 是 可
以 使 用 Windows 中 可 用 的 EUDC 编 辑 器 创 建 自 定 义 字 符 , 以 便 与 PDFlib 一 起 使 用 。 按 如 下
所 示 操 作 :
> 使 用 eudcedit.exe 在 所 需 的 Unicode 位 置 创 建 一 个 或 多 个 自 定 义 字 符 。
> 在 目 录 \Windows\fonts 中 查 找 EUDC.TTE 文 件 , 并 将 该 文 件 复 制 到 另 外 的 目 录 。 由 于 此
文 件 在 Windows 资 源 管 理 器 中 不 可 见 , 因 此 需 要 在 DOS 对 话 框 中 使 用 dir 和 copy 命 令
来 查 找 这 个 文 件 。 现 在 使 用 第 75 页 上 的 第 4.3.1 节 “PDFlib 搜 索 字 体 的 方 法 ” 中 讨 论 的
方 法 之 一 配 置 字 体 以 便 用 于 PDFlib:
PDF_set_parameter(p, "FontOutline", "EUDC=EUDC.TTE")
PDF_set_parameter(p, "SearchPath", "...directory name...")
或 在 当 前 目 录 下 放 置 EUDC.TTE。
> 作 为 前 一 步 骤 的 替 代 方 式 , 可 以 使 用 以 下 函 数 调 用 以 从 Windows 目 录 直 接 配 置 字 体 文
件 。 这 样 能 总 是 访 问 在 Windows 中 使 用 的 当 前 EUDC 字 体 :
PDF_set_parameter(p, "FontOutline", "EUDC=C:\Windows\fonts\EUDC.TTE")
> 使 用 以 下 调 用 来 加 载 字 体 :
font = PDF_load_font(p, "EUDC", 0, "unicode", "")
并 提 供 在 第 一 个 步 骤 中 选 定 的 Unicode 字 符 代 码 以 输 出 字 符 。
98 第 4 章 : 文 本 处 理

4.8 放 置 并 调 整 单 行 文 本
用 于 在 页 上 放 置 单 行 文 本 的 函 数 PDF_fit_textline( ) 提 供 了 许 多 格 式 化 选 项 。 在 本 节 中 , 我 们
使 用 一 些 常 见 的 应 用 程 序 示 例 来 讨 论 最 重 要 的 选 项 。 在 表 8.19 中 可 以 找 到 这 些 选 项 的 完 整
说 明 。 PDF_fit_textline( ) 的 大 多 数 选 项 都 与 PDF_fit_image( ) 的 选 项 相 同 。 因 此 , 在 这 里 我
们 仅 使 用 文 本 相 关 的 示 例 ; 建 议 查 看 第 123 页 上 的 第 5.3 节 “ 放 置 图 像 和 导 入 的 PDF 页 ” 中
的 示 例 以 获 得 初 步 的 了 解 。
以 下 示 例 仅 演 示 函 数 PDF_fit_textline( ) 的 相 关 调 用 , 并 假 定 已 加 载 必 需 的 字 体 并 设 置 了
所 需 的 字 体 大 小 。
PDF_fit_textline( ) 使 用 所 谓 的 文 本 框 来 确 定 文 本 的 位 置 : 文 本 框 宽 度 与 文 本 的 宽 度 一 致 ,
而 文 本 框 的 高 度 与 字 体 中 大 写 字 母 的 高 度 一 致 。 使 用 margin 选 项 可 以 左 右 扩 展 或 上 下 扩 展
文 本 框 。 页 边 距 将 随 同 文 本 行 一 起 缩 放 。
图 4.4
将 文 本 放 置 在
底 部 中 央 位 置
Kraxi
图 4.5
将 文 本 放 置 在 右 上 角
4.8.1 简 单 的 文 本 放 置
Kraxi
将 文 本 放 置 在 底 部 中 央 位 置 。
点 对 齐 ( 请 参 见 图 4.4):
我 们 将 文 本 与 参 考 点 对 齐 , 即 将 文 本 框 底 边 的 中 心 与 参 考
PDF_fit_textline(p, text, 297, 0, "position {50 0}");
此 代 码 片 段 将 文 本 框 的 底 边 中 心 (position {50 0}) 与 参 考 点 (297, 0) 对 齐 。
将 文 本 放 置 在 右 上 角
( 请 参 见 图 4.5):
现 在 我 们 将 文 本 与 参 考 点 对 齐 , 即 将 文 本 框 的 右 上 角 与 参 考 点 对 齐
PDF_fit_textline(p, text, 595, 842, "position 100");
此 代 码 片 段 将 文 本 框 的 右 上 角 (position 100) 参 考 点 (595, 842) 对 齐 。
在 页 边 距 中 放 置 文 本 为 了 扩 展 上 一 示 例 , 我 们 可 以 对 文 本 添 加 水 平 页 边 距 以 向 右 扩 展
一 段 距 离 。 这 可 能 有 助 于 在 表 格 列 中 放 置 文 本 :
PDF_fit_textline(p, text, 595, 842, "position 100 margin {20 0}");
4.8 放 置 并 调 整 单 行 文 本 99

图 4.6
在 文 本 框 中 居 中 放 置 文 本
图 4.7
按 比 例 调 整 文 本 以 使 其 适 合
文 本 框
图 4.8
完 全 调 整 文 本 以 使 其 适 合
文 本 框
Kraxi
Kraxi
Kraxi
4.8.2 在 文 本 框 中 放 置 文 本
在 框 中 居 中 放 置 文 本 我 们 定 义 一 个 框 , 并 在 该 框 内 居 中 放 置 文 本 ( 请 参 见 图 4.6):
PDF_fit_textline(p, text, 10, 200, "boxsize {500 220} position 50");
此 代 码 片 段 将 文 本 在 一 个 文 本 框 中 居 中 放 置 , 其 中 , 文 本 框 的 中 心 位 置 为 (position 50), 左
下 角 位 置 为 (10, 200), 文 本 框 的 宽 度 和 长 度 分 别 为 500 个 单 位 和 220 个 单 位 (boxsize {500
220})。
按 比 例 调 整 文 本 以 使 其 适 合 文 本 框
图 4.7):
我 们 扩 展 上 一 示 例 并 使 文 本 完 全 适 合 文 本 框 ( 请 参 见
PDF_fit_textline(p, text, 10, 200, "boxsize {500 220} position 50 fitmethod meet");
请 注 意 , 当 使 用 fitmethod meet 使 文 本 适 合 文 本 框 时 , 字 体 大 小 将 发 生 更 改 。 为 了 防 止 文 本
变 大 , 请 使 用 auto 而 不 要 使 用 meet。
完 全 调 整 文 本 以 使 其 适 合 文 本 框 我 们 可 以 进 一 步 修 改 上 一 示 例 , 使 文 本 不 能 按 比 例 适 合
文 本 框 , 而 是 完 全 覆 盖 文 本 框 。 不 过 , 此 组 合 将 很 少 使 用 , 因 为 文 本 可 能 会 扭 曲 ( 请 参 见
图 4.8):
PDF_fit_textline(p, text, 10, 200, "boxsize {500 220} position 50 fitmethod entire");
4.8.3 对 齐 文 本
简 单 对 齐 我 们 的 下 一 个 目 标 是 旋 转 文 本 , 使 其 原 始 左 下 角 与 给 定 的 参 考 点 对 齐 ( 请 参 见
图 4.9)。 这 可 能 很 有 用 , 例 如 , 在 表 头 中 放 置 经 过 旋 转 的 列 标 题 :
PDF_fit_textline(p, text, 5, 5, "orientate west");
100 第 4 章 : 文 本 处 理

此 代 码 片 段 将 文 本 的 方 向 调 整 为 朝 西 ( 逆 时 针 旋 转 90 度 ), 然 后 将 旋 转 文 本 的 左 下 角 对 准
参 考 点 (5, 5)。
沿 垂 直 线 对 齐 文 本 沿 垂 直 线 ( 即 , 宽 度 为 零 的 文 本 框 ) 放 置 文 本 是 一 种 有 点 极 端 的 情 况 ,
不 过 它 可 能 很 有 用 ( 请 参 见 图 4.10):
PDF_fit_textline(p, text, 0, 0, "boxsize {0 600} position {0 50} orientate west");
此 代 码 片 段 旋 转 文 本 , 并 沿 线 的 中 心 从 (0, 0) 到 (0, 600) 放 置 文 本 。
4.9 多 行 textflow
除 了 在 页 上 放 置 单 行 文 本 之 外 , PDFlib 支 持 一 种 称 作 “Textflow” 的 功 能 , 可 用 于 放 置 任
意 长 度 的 文 本 部 分 。 文 本 可 能 会 延 伸 到 任 意 数 量 的 行 或 页 , 文 本 的 外 观 可 以 使 用 多 个 选 项 进
行 控 制 。 字 符 属 性 ( 例 如 字 体 、 大 小 和 颜 色 ) 可 以 适 用 于 文 本 的 任 何 部 分 。 可 以 指 定
textflow 属 性 ( 例 如 分 散 对 齐 的 文 本 或 锯 齿 形 的 文 本 、 段 落 缩 排 和 制 表 位 等 ); 将 考 虑 文
本 中 由 自 动 连 字 符 指 定 的 换 行 机 会 。 图 4.11 和 图 4.12 演 示 如 何 使 用 textflow 功 能 在 页 面 上
放 置 发 票 的 不 同 的 部 分 。 在 以 下 的 部 分 , 我 们 将 更 加 详 细 地 讨 论 用 于 控 制 输 出 的 选 项 。
多 行 textflow 可 以 放 置 在 一 个 或 多 个 页 上 的 一 个 或 多 个 矩 形 ( 所 谓 的 “ 限 定 框 ”) 中 。
以 下 步 骤 是 在 页 上 放 置 textflow 所 必 需 的 步 骤 :
> 函 数 PDF_create_textflow( ) 分 析 文 本 , 创 建 一 个 textflow 对 象 并 返 回 一 个 句 柄 。 它 不 会
在 页 上 放 置 任 何 文 本 。
> 函 数 PDF_fit_textflow( ) 在 提 供 的 限 定 框 中 放 置 部 分 textflow 或 全 部 textflow。 为 了 完
全 放 置 文 本 , 可 能 必 须 重 复 执 行 几 次 此 步 骤 , 其 中 的 每 个 函 数 调 用 都 会 提 供 一 个 新 的 限
定 框 ( 可 能 位 于 同 一 页 或 其 他 页 上 )。
> PDF_delete_textflow( ) 函 数 可 删 除 已 放 置 在 文 档 中 的 textflow 对 象 。
用 于 创 建 textflow 的 函 数 PDF_create_textflow( ) 支 持 多 种 用 于 控 制 格 式 化 过 程 的 选 项 。 这
些 选 项 可 以 在 函 数 的 列 表 中 提 供 , 也 可 作 为 inline 选 项 在 文 本 中 嵌 入 。 我 们 将 使 用 一 些 常 见
的 应 用 程 序 示 例 来 讨 论 textflow 的 放 置 。 可 以 在 表 8.24 中 找 到 textflow 选 项 的 完 整 列 表 。
PDF_create_textflow( ) 中 支 持 的 许 多 选 项 都 与 PDF_fit_textline( ) 的 选 项 一 致 。 因 此 建 议
您 自 己 熟 悉 第 99 页 上 的 第 4.8 节 “ 放 置 并 调 整 单 行 文 本 ” 中 的 示 例 。 在 下 面 的 部 分 , 我 们
将 重 点 介 绍 与 多 行 文 本 有 关 的 选 项 。
图 4.9
简 单 对 齐
图 4.10
沿 垂 直 线 对 齐 文 本
Kraxi
Kraxi
4.9 多 行 textflow 101

4.9.1 在 限 定 框 中 放 置 textflow
在 单 个 限 定 框 中 放 置 文 本 让 我 们 从 简 单 的 示 例 开 始 。 以 下 代 码 片 段 使 用 默 认 的 格 式 化 选
项 在 页 上 的 单 个 限 定 框 中 放 置 textflow。 字 体 、 字 体 大 小 和 编 码 都 已 明 确 指 定 ( 可 在 图 4.13
中 查 看 结 果 ):
textflow =
PDF_create_textflow(p, text, 0, "fontname=Helvetica fontsize=9 encoding=winansi");
PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
PDF_delete_textflow(p, textflow);
在 两 个 限 定 框 中 放 置 文 本 若 使 用 PDF_fit_textflow( ) 放 置 在 页 上 的 文 本 在 限 定 框 中 放 不
下 , 则 输 出 将 中 断 , 该 函 数 将 返 回 字 符 串 _boxfull。PDFlib 将 会 记 住 已 经 放 置 在 页 上 的 文 本
Kraxi Systems, Inc.
Paper Planes
17, Aviation Road
Paperfield
Phone 7079-4301
Fax 7079-4302
info@kraxi.com
www.kraxi.com
Kraxi Systems, Inc. 17, Aviation Road Paperfield
John Q. Doe
255 Customer Lane
Suite B
12345 User Town
Everland
INVOICE 14.03.2004
hortabmethod ruler
tabalignment right left right right right
ruler 30 45 275
375
475
图 4.11
格 式 化
textflow
ITEM DESCRIPTION QUANTITY PRICE AMOUNT
1 Super Kite 2 20,00 40,00
2 Turbo Flyer 5 40,00 200,00
3 Giga Trash 1 180,00 180,00
4 Bare Bone Kit 3 50,00 150,00
5 Nitty Gritty 10 20,00 200,00
6 Pretty Dark Flyer 1 75,00 75,00
7 Free Gift 1 0,00 0,00
845,00
leftindent
=55
parindent
=7%
leading
= 140%
leftindent = 75
leftindent = 105
Terms of payment: 30 days net. 30 days warranty starting at the day of sale. This
warranty covers defects in workmanship only. Kraxi Systems, Inc., at its option, repairs or
replaces the product under warranty. This warranty is not transferable. Returns or
exchanges are not possible for wet products.
Have a look at our new paper plane models!
Our paper planes are the ideal way of passing the time. We offer revolutionary
new developments of the traditional common paper planes. If your lesson,
conference, or lecture turn out to be deadly boring, you can have a wonderful time
with our planes. All our models are folded from one paper sheet.
They are exclusively folded without using any adhesive. Several models are
equipped with a folded landing gear enabling a safe landing on the intended location
provided that you have aimed well. Other models are able to fly loops or cover long
distances. Let them start from a vista point in the mountains and see where they
touch the ground.
1. Long Distance Glider
With this paper rocket you can send all your messages even when
sitting in a hall or in the cinema pretty near the back.
2. Giant Wing
An unbelievable sailplane! It is amazingly robust and can even do
alignment
= left
alignment
= justify
rightindent
=60
minlinecount
=2
102 第 4 章 : 文 本 处 理

aerobatics. But it is best suited to gliding.
fillcolor, charspacing,
fontsize, fontname
3. C one Head R ocket
This paper arrow can be thrown with big swing. We launched it from
the roof of a hotel. It stayed in the air a long time and covered a
considerable distance.
4. Super Dart
The super dart can fly giant loops with a radius of 4 or 5 meters and
cover very long distances. Its heavy cone point is slightly bowed
upwards to get the lift required for loops.
图 4.12
格 式 化
textflow
5. German Bi-Plane
Brand-new and ready for take-off. If you have lessons in the history of
aviation you can show your interest by letting it land on your teacher's
desk.
图 4.13
简 单 textflow 放 置
Terms of payment: 30 days net. 30 days warranty starting at the day of
sale. This warranty covers defects in workmanship only. Kraxi Systems,
Inc., at its option, repairs or replaces the product under warranty. This
warranty is not transferable. Returns or exchanges are not possible for
wet products.
数 量 , 并 在 再 次 调 用 该 函 数 时 , 继 续 文 本 的 剩 余 部 分 。 以 下 代 码 片 段 演 示 如 何 在 两 个 限 定 框
中 放 置 textflow ( 可 在 图 4.14 中 查 看 结 果 ):
textflow =
PDF_create_textflow(p, text, 0, "fontname=Helvetica fontsize=9 encoding=winansi");
result = PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
/* Check whether the text could be fully placed in the fitbox */
if (!strcmp(result, "_boxfull"))
PDF_fit_textflow(p, textflow, left_x + offset, left_y, right_x +offset, right_y, "");
PDF_delete_textflow(p, textflow);
在 多 个 页 上 放 置 文 本 若 使 用 PDF_fit_textflow( ) 放 置 的 文 本 在 限 定 框 中 不 能 全 部 放 下 , 则
可 能 有 必 要 创 建 一 个 新 页 。 用 于 在 多 个 页 上 放 置 textflow 的 基 础 代 码 如 下 所 示 :
textflow = PDF_create_textflow(p, text, 0, optlist);
do
{
PDF_begin_page_ext(p, pagewidth, pageheight, "");
result = PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
PDF_end_page_ext(p, "");
} while (strcmp(result, "_stop"))
PDF_delete_textflow(p, textflow);
第 一 个 限 定 框
Terms of payment: 30
days net. 30 days
warranty starting at the
day of sale. This
warranty covers defects
in workmanship only.
Kraxi Systems, Inc., at
its option, repairs or
第 二 个 限 定 框
replaces the product
under warranty. This
warranty is not
transferable. Returns or
exchanges are not
possible for wet
products.
图 4.14
在 两 个 限 定 框 中 放 置
textflow
4.9 多 行 textflow 103

leftindent = 15
parindent = 20
leading = 140%
图 4.15
使 用 选 项 放 置
textflow
Have a look at our new paper plane models! Our paper planes
are the ideal way of passing the time. We offer revolutionary new
developments of the traditional common paper planes.
If your lesson, conference, or lecture turn out to be deadly boring,
you can have a wonderful time with our planes. All our models are
folded from one paper sheet.
They are exclusively folded without using any adhesive. Several
models are equipped with a folded landing gear enabling a safe landing
on the intended location provided that you have aimed well. Other
models are able to fly loops or cover long distances. Let them start
from a vista point in the mountains and see where they touch the
ground.
rightindent = 10
alignment =
justify
4.9.2 段 落 格 式 设 置 选 项
在 上 一 示 例 中 , 我 们 使 用 段 落 的 默 认 设 置 。 例 如 , 默 认 对 齐 方 式 是 左 对 齐 , 行 距 是 100%
( 与 字 体 大 小 相 同 )。
为 了 调 整 段 落 的 格 式 设 置 , 我 们 可 以 对 PDF_create_textflow( ) 提 供 更 多 选 项 。 例 如 , 我
们 可 以 将 文 本 从 左 边 距 缩 排 15 个 单 位 , 从 右 边 距 缩 排 10 个 单 位 。 另 外 , 每 个 段 落 的 第 一 行
应 缩 排 20 个 单 位 。 文 本 应 对 照 左 右 边 距 对 齐 , 并 将 行 距 增 加 到 140%。 最 终 , 我 们 将 字 体 大
小 减 少 到 8 个 单 位 。 用 于 实 现 此 设 想 的 、 使 用 了 选 项 列 表 的 扩 展 代 码 如 下 所 示 ( 可 在 图 4.15
中 查 看 结 果 ):
char optlist[] =
"leftindent=15 rightindent=10 parindent=20 alignment=justify "
"leading=140% fontname=Helvetica fontsize=8 encoding=winansi"
/* place textflow in the fitbox using the options */
textflow = PDF_create_textflow(p, text, 0, optlist);
PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
PDF_delete_textflow(p, textflow);
4.9.3 内 嵌 选 项 列 表 和 宏
图 4.15 中 的 文 本 还 不 正 确 。 标 题 “Have a look at our new paper plane models!”( 看 一 看
我 们 的 新 纸 飞 机 模 型 !) 应 独 自 占 用 一 行 , 并 应 使 用 较 大 的 字 号 居 中 显 示 。 有 一 些 方 法 可 以
用 来 达 到 此 目 的 。
到 现 在 为 止 , 我 们 是 在 直 接 提 供 给 函 数 的 选 项 列 表 中 提 供 格 式 化 选 项 。 为 了 继 续 相 同 的
方 式 , 我 们 必 须 拆 分 文 本 , 并 将 其 放 置 到 两 个 单 独 的 调 用 中 , 一 个 调 用 针 对 标 题 , 另 一 个 调
用 针 对 剩 余 的 文 本 。 不 过 , 这 将 比 较 麻 烦 。
为 此 , textflow 功 能 支 持 所 谓 的 内 嵌 选 项 。 简 单 来 说 就 是 将 选 项 嵌 入 在 文 本 中 。 内 嵌 选
项 列 表 作 为 正 文 的 一 部 分 提 供 。 默 认 情 况 下 , 它 们 用 “” 字 符 分 隔 。 因 此 , 我 们
将 按 如 下 方 式 将 用 于 设 置 标 题 和 其 余 段 落 格 式 的 选 项 集 成 到 正 文 中 ( 在 后 面 的 所 有 示 例 中 ,
内 嵌 选 项 列 表 都 会 用 颜 色 标 出 ; 段 落 结 束 字 符 将 使 用 箭 头 表 示 ):
Have a look at our new paper plane models!
Our paper planes are the ideal way of passing the time.We offer
revolutionary new developments of the traditional common paper planes.
If your lesson, conference, or lecture
turn out to be deadly boring, you can have a wonderful time
104 第 4 章 : 文 本 处 理

H1
Body
Body_indented
Have a look at our new paper plane models!
Our paper planes are the ideal way of passing the time. We offer
revolutionary new developments of the traditional common paper
planes.
If your lesson, conference, or lecture turn out to be deadly boring,
you can have a wonderful time with our planes. All our models are
folded from one paper sheet.
They are exclusively folded without using any adhesive. Several
models are equipped with a folded landing gear enabling a safe landing
on the intended location provided that you have aimed well. Other
models are able to fly loops or cover long distances. Let them start
from a vista point in the mountains and see where they touch the
ground.
图 4.16
将 内 嵌 选 项 与
宏 组 合 使 用
with our planes.All our models are folded from one paper sheet.
They are exclusively folded without using any adhesive.Several
models are equipped with a folded landing gear enabling a safe
landing on the intended location provided that you have aimed well.
Other models are able to fly loops or cover long distances.Let them
start from a vista point in the mountains and see
where they touch the ground.
可 以 使 用 begoptlistchar 和 endoptlistchar 选 项 重 新 定 义 围 绕 选 项 列 表 的 字 符 ( 请 参 见 表
8.24)。 将 关 键 字 none 提 供 给 begoptlistchar 选 项 会 完 全 禁 用 对 选 项 列 表 的 搜 索 。 若 文 本 未
包 含 内 嵌 选 项 列 表 , 且 想 确 保 “” 将 作 为 常 规 字 符 进 行 处 理 , 则 可 以 使 用 这 一 方 法 。
宏 上 面 的 文 本 基 本 上 包 含 一 些 不 同 类 型 的 段 落 , 例 如 标 题 和 带 缩 排 或 不 带 缩 排 正 文 。 每 一
种 段 落 类 型 都 单 独 设 置 格 式 , 并 在 较 长 的 textflow 中 多 次 出 现 。 为 了 避 免 每 一 段 落 都 用 相
应 的 内 嵌 选 项 开 始 , 我 们 可 以 将 这 些 选 项 组 合 成 宏 的 形 式 , 并 通 过 宏 名 称 在 文 本 中 引 用 相 应
的 宏 。 如 图 4.16 中 所 示 , 我 们 可 以 定 义 三 个 宏 , 它 们 分 别 是 用 于 标 题 的 名 为 H1 的 宏 , 用 于
主 要 段 落 的 名 为 Body 的 宏 和 用 于 缩 排 的 段 落 的 名 为 Body_indented 的 宏 。 为 了 使 用 宏 , 我
们 将 & 字 符 放 置 在 宏 名 称 前 面 , 并 将 其 放 入 选 项 列 表 中 。 以 下 代 码 片 段 根 据 先 前 使 用 的 内
嵌 选 项 定 义 三 个 宏 并 在 文 本 中 使 用 这 些 宏 :
Have a look at our new paper plane models!
Our paper planes are the ideal way of passing the time.We offer
revolutionary new developments of the traditional common paper planes.
If your lesson, conference, or lecture
turn out to be deadly boring, you can have a wonderful time
with our planes.All our models are folded from one paper sheet.
They are exclusively folded without using any adhesive.Several
models are equipped with a folded landing gear enabling a safe
landing on the intended location provided that you have aimed well.
4.9 多 行 textflow 105

hortabmethod ruler
tabalignment left right right right
ruler 30 150
250
350
图 4.17
放 置 文 本
作 为 表
ITEM DESCRIPTION QUANTITY PRICE AMOUNT
1 Super Kite 2 20.00 40.00
2 Turbo Flyer 5 40.00 200.00
3 Giga Trash 1 180.00 180.00
TOTAL 420.00
Other models are able to fly loops or cover long distances.Let them
start from a vista point in the mountains and see
where they touch the ground.
明 确 设 置 选 项 请 注 意 , 所 有 未 在 宏 中 设 置 的 选 项 将 保 留 其 先 前 的 值 。 为 了 避 免 由 选 项 的 不
必 要 “ 继 承 ” 产 生 的 副 作 用 , 应 明 确 指 定 特 殊 的 宏 所 需 的 所 有 设 置 。 这 样 , 不 管 宏 的 顺 序
或 与 其 他 选 项 列 表 的 组 合 如 何 , 都 可 以 确 保 宏 将 始 终 如 一 地 工 作 。
另 一 方 面 , 可 以 利 用 这 种 方 式 有 意 保 留 上 下 文 的 某 些 设 置 , 而 不 用 明 确 提 供 它 们 。 例 如 ,
宏 可 能 会 指 定 字 体 名 称 , 而 不 提 供 fontsize 选 项 。 结 果 , 字 体 大 小 将 总 是 匹 配 先 前 文 本 中 的
字 体 大 小 。
使 用 内 嵌 选 项 还 是 使 用 作 为 函 数 参 数 传 递 的 选 项 ? 当 使 用 textflow 时 , 文 本 是 全 部 包 含
在 程 序 代 码 中 还 是 来 自 于 一 些 外 部 源 , 格 式 化 说 明 是 与 文 本 中 分 离 的 还 是 作 为 文 本 的 一 部
分 , 这 些 方 面 的 差 异 会 导 致 结 果 出 现 很 大 的 不 同 。 在 大 多 数 应 用 程 序 中 , 实 际 的 文 本 将 来 自
于 一 些 外 部 源 ( 例 如 数 据 库 )。 在 实 际 中 主 要 有 两 种 情 形 :
> 文 本 内 容 来 自 外 部 源 , 格 式 化 选 项 来 自 程 序 : 外 部 源 传 递 小 段 文 本 , 然 后 在 程 序 内 部 进
行 合 成 , 并 在 运 行 时 与 格 式 化 选 项 ( 在 函 数 调 用 中 ) 进 行 组 合 。
> 文 本 内 容 和 格 式 化 选 项 均 来 自 外 部 源 : 包 括 格 式 化 选 项 在 内 的 大 批 文 本 都 来 自 于 外 部
源 。 格 式 设 置 通 过 文 本 中 的 内 嵌 选 项 ( 用 简 单 选 项 或 宏 表 示 ) 提 供 。 对 于 宏 , 必 须 对 宏
定 义 和 宏 调 用 进 行 区 分 。 这 样 就 允 许 存 在 一 种 有 趣 的 中 间 形 式 : 文 本 内 容 来 自 于 外 部
源 , 并 包 含 用 于 格 式 化 的 宏 调 用 。 不 过 , 仅 在 运 行 时 混 合 宏 定 义 。 这 样 做 有 个 优 势 , 即
不 需 要 修 改 外 部 文 本 就 可 以 轻 松 更 改 格 式 。 例 如 , 当 生 成 贺 卡 时 , 可 以 通 过 宏 定 义 不 同
样 式 , 以 使 贺 卡 呈 现 浪 漫 风 格 、 技 术 风 格 或 其 他 风 格 。
4.9.4 制 表 位
在 下 一 个 示 例 中 , 我 们 将 使 用 制 表 符 制 作 一 个 带 有 左 对 齐 列 和 右 对 齐 列 的 表 。 此 表 包 含 以 下
文 本 行 , 其 中 的 各 个 项 用 制 表 符 分 隔 ( 用 箭 头 指 示 ):
ITEM DESCRIPTION QUANTITY PRICE AMOUNT
1 Super Kite 2 20.00 40.00
2 Turbo Flyer 5 40.00 200.00
3 Giga Trash 1 180.00 180.00
TOTAL 420.00
以 下 代 码 片 段 制 作 一 个 表 , 其 中 , 使 用 ruler 选 项 定 义 制 表 符 位 置 , 使 用 tabalignment 以 指
定 制 表 位 对 齐 方 式 , 使 用 hortabmethod 指 定 用 于 处 理 制 表 位 的 方 法 ( 可 以 在 图 4.17 中 查 看
结 果 ):
/* assemble option list */
char optlist[] =
106 第 4 章 : 文 本 处 理

"ruler {30 150 250 350} "
"tabalignment {left right right right} "
"hortabmethod ruler leading=120% fontname=Helvetica fontsize=9 encoding=winansi";
/* place textflow in fitbox */
textflow = PDF_create_textflow(p, table, 0, optlist);
PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
PDF_delete_textflow(p, textflow);
4.9.5 编 号 列 表
以 下 示 例 演 示 如 何 使 用 内 嵌 选 项 leftindent 设 置 编 号 列 表 的 格 式 ( 可 在 图 4.18 中 查 看 结 果 ):
1.Long Distance Glider: With this paper rocket you can send all
your messages even when sitting in a hall or in the cinema pretty near the back.
2.Giant Wing: An unbelievable sailplane! It is amazingly
robust and can even do aerobatics. But it is best suited to gliding.
3.Cone Head Rocket: This paper arrow can be thrown with big
swing. We launched it from the roof of a hotel. It stayed in the air a long time and
covered a considerable distance.
设 置 和 重 新 设 置 缩 排 值 比 较 麻 烦 , 特 别 是 每 个 段 落 都 需 要 进 行 此 操 作 。 更 加 完 美 的 解 决 方 案 是
定 义 一 个 名 为 list 的 宏 。 为 了 方 便 起 见 , 其 中 定 义 一 个 宏 indent 用 作 常 量 。 宏 定 义 如 下 所 示 :
1. Long Distance Glider: With this paper rocket you can send all your messages
even when sitting in a hall or in the cinema pretty near the back.
2. Giant Wing: An unbelievable sailplane! It is amazingly robust and can even do
aerobatics. But it is best suited to gliding.
3. Cone Head Rocket: This paper arrow can be thrown with big swing. We launched
it from the roof of a hotel. It stayed in the air a long time and covered a
considerable distance.
leftindent 选 项 定 义 距 离 左 页 边 距 的 距 离 。 parindent 选 项 被 设 置 为 leftindent 的 负 值 , 以 便
取 消 缩 排 每 个 段 落 的 第 一 行 。 选 项 hortabsize、hortabmethod 和 ruler 指 定 与 leftindent 对 应
的 制 表 位 。 它 使 数 字 后 面 的 文 本 缩 排 leftindent 中 指 定 的 距 离 。 图 4.19 显 示 了 所 使 用 的
parindent 和 leftindent 选 项 。
1. Long Distance Glider: With this paper rocket you can send all your
messages even when sitting in a hall or in the cinema pretty near the
back.
2. Giant Wing: An unbelievable sailplane! It is amazingly robust and can
even do aerobatics. But it is best suited to gliding.
3. Cone Head Rocket: This paper arrow can be thrown with big swing. We
launched it from the roof of a hotel. It stayed in the air a long time and
covered a considerable distance.
图 4.18
编 号 列 表
4.9 多 行 textflow 107

leftindent = &indent
parindent = – &indent 1. Long Distance Glider: With this paper rocket you can send all your
messages even when sitting in a hall or in the cinema pretty near
the back.
2. Giant Wing: An unbelievable sailplane! It is amazingly robust and
can even do aerobatics. But it is best suited to gliding.
图 4.19
使 用 宏 的
编 号 列 表
3. Cone Head Rocket: This paper arrow can be thrown with big swing.
We launched it from the roof of a hotel. It stayed in the air a long
time and covered a considerable distance.
4.9.6 控 制 字 符 、 字 符 映 射 和 符 号 字 体
textflow 中 的 控 制 字 符 可 对 textflow 中 的 不 同 字 符 进 行 特 殊 的 处 理 。PDFlib 支 持 符 号 字
符 名 称 , 此 类 名 称 可 以 用 于 替 换 charmapping 选 项 ( 在 处 理 文 本 之 前 替 换 其 中 的 字 符 , 请
参 见 以 下 内 容 ) 中 对 应 的 字 符 代 码 。 表 4.5 列 出 了 textflow 函 数 使 用 的 所 有 控 制 字 符 以 及 相
应 的 符 号 名 称 , 并 解 释 各 自 的 含 意 。 虽 然 一 个 选 项 列 表 只 能 使 用 一 个 选 项 , 但 是 可 以 接 连 提
供 多 个 选 项 列 表 。 例 如 , 以 下 序 列 将 创 建 一 个 空 行 :
替 换 字 符 或 字 符 序 列 charmapping 选 项 可 以 用 于 使 用 其 他 字 符 替 换 文 本 中 的 一 些 字 符 。
让 我 们 从 简 单 的 示 例 开 始 , 在 此 示 例 中 我 们 将 使 用 空 格 字 符 替 换 文 本 中 的 所 有 制 表 符 。 可 通
过 charmapping 选 项 来 达 到 此 目 的 , 如 下 所 示 :
charmapping {hortab space}
此 命 令 使 用 了 符 号 字 符 名 称 hortab 和 space。 可 以 在 表 4.5 中 找 到 所 有 已 知 字 符 名 称 的 列 表 。
若 要 一 次 实 现 多 个 映 射 , 可 以 使 用 以 下 命 令 , 使 用 空 格 字 符 替 换 所 有 制 表 符 和 换 行 符 组 合 :
charmapping {hortab space CRLF space LF space CR space}
以 下 命 令 移 除 所 有 自 动 连 字 符 :
charmapping {shy {shy 0}}
每 个 制 表 符 都 将 被 替 换 为 四 个 空 格 字 符 :
charmapping {hortab {space 4}}
每 个 任 意 长 度 的 换 行 符 序 列 都 将 减 少 为 单 个 换 行 符 :
charmapping {linefeed {linefeed -1}}
每 个 CRLF 组 合 序 列 都 将 被 替 换 为 单 个 空 格 :
charmapping {CRLF {space -1}}
我 们 将 更 进 一 步 地 讨 论 最 后 一 个 示 例 。 让 我 们 假 定 , 您 接 收 的 文 本 中 的 行 已 由 一 些 其 他 软 件
通 过 固 定 的 换 行 符 分 离 , 因 此 无 法 正 确 地 设 置 这 些 行 的 格 式 。 您 需 要 用 空 格 符 替 换 这 些 换 行
符 以 便 在 限 定 框 内 实 现 正 确 的 格 式 设 置 。 若 要 达 到 此 目 的 , 我 们 用 单 个 空 格 符 替 换 任 意 长 度
的 换 行 符 序 列 。 最 初 的 文 本 如 下 所 示 :
To fold the famous rocket looper proceed as follows:
Take a sheet of paper.Fold it
108 第 4 章 : 文 本 处 理

To fold the famous rocket looper proceed as follows:
Take a sheet of paper. Fold it
lengthwise in the middle.
Then, fold down the upper corners. Fold the
long sides inwards
that the points A and B meet on the central fold.
To fold the famous rocket looper proceed as follows: Take a sheet of
paper. Fold it lengthwise in the middle. Then, fold down the upper
corners. Fold the long sides inwards that the points A and B meet on
the central fold.
图 4.20
顶 部 : 带 有 多 余 的 换 行 符 的 文 本
底 部 : 使 用 charmapping 选 项 替
换 换 行 符
lengthwise in the middle.
Then, fold down the upper corners.Fold the
long sides inwards
that the points A and B meet on the central fold.
以 下 代 码 片 段 演 示 如 何 替 换 多 余 的 换 行 符 以 及 如 何 对 替 换 后 的 文 本 设 置 格 式 :/* assemble
option list */
char optlist[] = "fontname=Helvetica fontsize=9 encoding=winansi alignment=justify "
"charmapping {CRLF {space -1}}"
/* place textflow in fitbox */
textflow = PDF_create_textflow(p, text, 0, optlist);
PDF_fit_textflow(p, textflow, left_x, left_y, right_x, right_y, "");
PDF_delete_textflow(p, textflow);
图 4.20 显 示 了 文 本 未 经 修 改 的 textflow 输 出 以 及 使 用 charmapping 选 项 修 复 过 的 textflow
输 出 。
textflow 中 的 符 号 字 体 在 textflow 中 使 用 符 号 字 体 ( 更 准 确 地 说 , 应 是 用 了 第 89 页 上
的 第 4.5.6 节 “Unicode 兼 容 的 字 体 ” 表 中 列 出 的 字 体 之 外 的 非 Unicode 兼 容 的 字 体 的 文
本 ) 时 , 应 特 别 注 意 :
> 表 4.5 中 列 出 的 控 制 字 符 将 不 会 进 行 特 殊 处 理 , 也 就 是 说 这 些 控 制 字 符 没 有 特 殊 含 意 。
> 一 些 textflow 选 项 会 因 为 对 符 号 字 体 没 有 任 何 意 义 而 被 忽 略 , 例 如 tabalignchar。
表 8.24 列 出 了 将 对 非 Unicode 兼 容 字 体 忽 略 的 所 有 选 项 。
> 因 为 内 嵌 选 项 列 表 不 能 在 带 有 符 号 字 体 的 文 本 部 分 中 使 用 ( 由 于 符 号 没 有 内 在 含 意 , 因
此 不 可 能 定 位 和 解 释 选 项 列 表 ), 必 须 使 用 textlen 选 项 显 式 指 定 由 符 号 字 符 组 成 的 文 本
片 段 的 长 度 。
> 在 textlen 字 符 的 后 面 , 必 须 在 文 本 中 放 置 一 个 新 的 内 嵌 选 项 列 表 以 便 转 换 为 其 他 字 体 /
编 码 组 合 。
以 下 文 本 包 含 一 个 来 自 符 号 字 体 的 、 插 入 在 拉 丁 字 符 之 间 的 字 形 :
The Greek letter
A
symbolizes beginning.
若 在 Symbol 片 段 中 省 略 textlen 选 项 , 或 未 能 在 Symbol 片 段 后 立 即 提 供 其 他 内 嵌 选 项 , 将
产 生 一 个 异 常 。
4.9 多 行 textflow 109

Our paper planes are the ideal way of
passing the time. We offer revolutionary
brand new developments of the
traditional common paper planes. If
your lesson, conference, or lecture turn
out to be deadly boring, you can have
a wonderful time with our planes. All
our models are folded from one paper
sheet. They are exclusively folded
without using any adhesive. Several
models are equipped with a folded
landing gear enabling a safe landing
on the intended location provided that
you have aimed well. Other models are
able to fly loops or cover long distances.
Let them start from a vista point
in the mountains and see where they
touch the ground.
图 4.21
带 有 自 动 连 字 符 的 分 散 对 齐 的 文 本 , 使 用 默
认 设 置 和 宽 限 定 框
Our paper planes are the ideal way of
passing the time. We offer revolutionary
brand new developments of the
traditional common paper planes. If
your lesson, conference, or lecture turn
out to be deadly boring, you can have
a wonderful time with our planes. All
our models are folded from one paper
sheet. They are exclusively folded
without using any adhesive. Several
models are equipped with a folded
landing gear enabling a safe landing
on the intended location provided that
you have aimed well. Other models are
able to fly loops or cover long
distances. Let them start from a vista
point in the mountains and see where
they touch the ground.
图 4.22
不 带 自 动 连 字 符 的 分 散 对 齐 的 文 本 , 使 用
默 认 设 置 和 宽 限 定 框 。
4.9.7 断 字
PDFlib 不 会 自 动 对 文 本 进 行 断 字 , 但 是 可 以 在 出 现 由 自 动 连 字 符 明 确 标 记 的 断 字 机 会 时 实
现 断 字 。 自 动 连 字 符 在 Unicode 中 的 位 置 是 U+00AD, 但 是 也 可 以 使 用 其 他 一 些 方 法 在 非
Unicode 环 境 中 指 定 自 动 连 字 符 :
> 在 所 有 cp1250 – cp1258 ( 包 括 winansi) 和 iso8859-1 – iso8859-16 编 码 中 , 自 动 连 字 符 对
应 于 十 进 制 173、 八 进 制 255 或 十 六 进 制 0xAD。
> 在 ebcdic 编 码 中 , 自 动 连 字 符 对 应 于 十 进 制 202、 八 进 制 312 或 十 六 进 制 0xCA。
> 若 编 码 未 包 含 自 动 连 字 符 , 则 可 以 使 用 字 符 实 体 引 用 , 例 如 macroman( 请 参 见 第 87 页
上 的 第 4.5.5 节 “ 字 符 引 用 ”)。 &shy ;
除 了 自 动 连 字 符 指 定 的 中 断 机 会 以 外 , 在 极 端 情 况 下 , 当 其 他 调 整 方 法 ( 例 如 更 改 字 间 距
或 挤 压 文 本 ) 不 可 用 时 , 可 以 强 行 断 字 。
注 : PDFlib 遵 守 CJK 字 符 的 排 版 规 则 。
带 有 或 不 带 自 动 连 字 符 的 分 散 对 齐 的 文 本 在 以 下 的 示 例 中 , 我 们 将 使 用 分 散 对 齐 的 方 式
打 印 下 面 的 文 本 。 文 本 中 包 含 自 动 连 字 符 ( 在 此 处 以 短 线 显 示 ):
Our paper planes are the ideal way of pas sing the time. We offer revolu tionary
brand new dev elop ments of the tradi tional common paper planes. If your lesson,
confe rence, or lecture turn out to be deadly boring, you can have a wonder ful time
with our planes. All our models are folded from one paper sheet. They are exclu sively
folded without using any adhe sive. Several models are equip ped with a folded
landing gear enab ling a safe landing on the intended loca tion provided that you
have aimed well. Other models are able to fly loops or cover long dist ances. Let them
start from a vista point in the mount ains and see where they touch the ground.
图 4.21 显 示 了 使 用 默 认 选 项 设 置 生 成 的 分 散 对 齐 的 文 本 输 出 。 由 于 各 项 条 件 都 很 好 , 因 此 文
本 输 出 很 美 观 : 限 定 框 足 够 宽 , 并 且 自 动 连 字 符 指 定 了 一 些 明 显 的 中 断 机 会 。 从 图 4.22 中
可 以 看 到 , 即 使 没 有 明 确 的 自 动 连 字 符 , 输 出 效 果 看 上 去 也 不 错 。 两 种 情 况 下 的 选 项 列 表 如
下 所 示 :
110 第 4 章 : 文 本 处 理

fontname=Helvetica fontsize=9 encoding=winansi alignment=justify
4.9.8 控 制 换 行 算 法
PDFlib 执 行 一 种 复 杂 的 换 行 算 法 。 1 表 4.9 列 出 了 可 用 来 控 制 换 行 算 法 的 textflow 选 项 。
表 4.9 用 于 控 制 换 行 算 法 的 选 项
选 项 类 型 说 明
adjustmethod 关 键 字 如 果 在 压 缩 或 扩 展 单 词 之 间 的 距 离 后 文 本 部 分 无 法 在 某 个 行 中 放 下 , 此 时 用 来
调 整 行 的 方 法 需 要 考 虑 到 由 minspacing 和 maxspacing 选 项 指 定 的 限 制 。 默 认
值 :auto
auto 按 顺 序 应 用 以 下 方 法 :shrink、 spread、 nofit、 split。
clip 与 nofit 相 同 ( 请 参 见 以 下 内 容 ), 但 将 剪 切 位 于 限 定 框 右 边 缘 的 长
文 本 部 分 ( 将 考 虑 rightindent 选 项 )。
nofit 最 后 一 个 单 词 将 移 动 到 下 一 行 , 前 提 是 剩 余 ( 短 ) 行 的 长 度 不 会 比
nofitlimit 选 项 中 指 定 的 百 分 比 长 度 短 。 在 这 种 情 况 下 , 甚 至 分 散 对
齐 的 段 落 看 上 去 也 会 有 点 错 乱 。
shrink 若 一 个 单 词 在 行 中 放 不 下 , 则 会 根 据 shrinklimit 选 项 压 缩 文 本 直 到
可 以 将 该 单 词 完 整 放 入 。 若 它 仍 无 法 放 入 到 行 中 , 则 将 应 用 nofit
方 法 。
split 最 后 的 单 词 将 不 会 移 动 到 下 一 行 , 但 会 强 制 断 字 。 对 于 文 本 字 体 ,
将 插 入 一 个 连 字 符 , 但 符 号 字 体 除 外 。
spread 最 后 的 字 将 移 动 到 下 一 行 , 并 服 从 spreadlimit 选 项 , 通 过 增 加 字
中 的 字 符 之 间 的 距 离 对 齐 剩 余 的 行 。 若 仍 无 法 对 齐 , 将 应 用 nofit
方 法 。
avoidbreak 布 尔 值 若 为 true, 则 避 免 任 何 换 行 直 到 avoidbreak 重 置 为 false。 默 认 值 :false
hyphenchar 整 数 用 于 在 换 行 处 替 换 自 动 连 字 符 的 字 符 的 Unicode 值 。 默 认 值 : 若 在 字 体 中 可
用 , 则 为 U+00AD ( 自 动 连 字 符 ), 否 则 为 U+002D ( 减 号 连 字 符 )
maxspacing
minspacing
nofitlimit
浮 点 数 或
百 分 比
浮 点 数 或
百 分 比
指 定 单 词 之 间 的 最 大 距 离 或 最 小 距 离 ( 通 过 用 户 坐 标 表 示 , 或 作 为 空 格 字 符 宽
度 的 百 分 比 )。 计 算 的 字 间 距 受 提 供 的 值 的 限 制 ( 但 是 仍 将 加 上 wordspacing
选 项 的 值 )。 默 认 值 :minspacing=50%, maxspacing=500%
nofit 方 法 对 行 的 长 度 的 下 限 ( 通 过 用 户 坐 标 表 示 , 或 作 为 限 定 框 宽 度 的 百 分
比 )。 默 认 值 :75%。
shrinklimit 百 分 比 shrink 方 法 对 压 缩 文 本 的 下 限 ; 计 算 的 shrinking 因 素 受 提 供 的 值 的 限 制 , 但 将
用 horizscaling 选 项 的 值 相 乘 。 默 认 值 :85%。
spreadlimit
浮 点 数 或
百 分 比
spread 方 法 对 两 个 字 符 之 间 的 距 离 的 上 限 ( 通 过 用 户 坐 标 表 示 , 或 作 为 字 体 大
小 的 百 分 比 ); 计 算 的 值 将 与 charspacing 选 项 的 值 相 加 。 默 认 值 :0。
换 行 规 则 当 某 个 单 词 或 由 空 格 字 符 环 绕 的 其 他 文 本 序 列 无 法 放 入 到 行 中 时 , 必 须 将 它 移
动 到 下 一 行 。 在 这 种 情 况 下 , 换 行 算 法 决 定 可 能 在 哪 个 字 符 后 换 行 。
例 如 , 决 不 会 断 开 像 -12+235/8*45 这 样 的 公 式 , 而 字 符 串 PDF-345+LIBRARY 可 能 会 在 减
号 字 符 处 断 开 换 到 下 一 行 。 若 文 本 包 含 自 动 连 字 符 , 则 也 可 以 在 该 字 符 后 断 开 。
对 于 圆 括 号 和 引 号 , 它 取 决 于 我 们 是 否 有 一 个 开 始 或 结 束 字 符 : 开 始 圆 括 号 和 开 始 引 号
不 会 提 供 任 何 断 开 机 会 。 为 了 查 找 引 号 是 否 开 始 或 结 束 一 个 序 列 , 需 要 检 查 引 号 对 。
通 常 内 嵌 选 项 列 表 不 会 创 建 换 行 机 会 以 允 许 字 内 的 选 项 更 改 。 不 过 , 当 选 项 列 表 由 空 格
字 符 环 绕 时 , 在 选 项 列 表 的 开 始 处 有 换 行 机 会 。 若 换 行 出 现 在 选 项 列 表 处 且
alignment=justify, 则 将 忽 略 选 项 列 表 前 面 的 空 格 。 选 项 列 表 后 面 的 空 格 将 保 留 , 并 将 出 现
在 下 一 行 的 开 始 处 。
1. 对 此 感 兴 趣 的 用 户 请 注 意 , PDFlib 遵 从 “Unicode 标 准 附 录 #14: 换 行 属 性 ” 中 的 建 议
( 请 参 见 www.unicode.org/reports/tr14)。 不 考 虑 组 合 标 记 。
4.9 多 行 textflow 111

Our paper planes
are the ideal way of
passing the time. We
offer revolutionary
brand new developments
of the traditional
common paper planes.
If your lesson, conference,
or lecture
turn out to be deadly
boring, you can have
a wonderful time
with our planes. All
our models are
folded from one
paper sheet. They
are exclusively folded
without using any
减 少 字 间 距 ( 默 认 方 法 , minspacing 选 项 )
压 缩 行 (shrink 方 法 , shrinklimit 选 项 )
强 制 使 用 连 字 符 (split 方 法 )
增 加 字 间 距 ( 默 认 方 法 , maxspacing 选 项 )
图 4.23
在 窄 限 定 框 中 使 用 默 认 设 置 分 散 对 齐 的 文 本
窄 限 定 框 中 分 散 对 齐 的 文 本 限 定 框 越 窄 , 就 需 要 越 多 地 处 理 用 于 控 制 分 散 对 齐 文 本 的 选
项 。 图 4.23 演 示 在 窄 限 定 框 中 用 于 调 整 文 本 的 多 种 方 法 的 结 果 。 图 4.23 中 的 选 项 设 置 基 本
上 合 适 , 但 maxspacing 提 供 的 字 间 距 相 当 大 。 不 过 , 建 议 为 窄 限 定 框 保 留 此 选 项 设 置 , 因
为 若 不 这 样 , 由 split 方 法 引 起 的 难 看 的 强 制 断 字 将 会 更 多 地 出 现 。
若 限 定 框 太 窄 以 至 于 出 现 很 少 使 用 的 强 制 断 字 , 则 应 考 虑 插 入 连 字 符 , 或 修 改 控 制 分 散
对 齐 文 本 的 选 项 。
用 于 分 散 对 齐 文 本 的 选 项 shrinklimit 视 觉 效 果 最 好 的 解 决 方 案 是 减 少 shrinklimit 选 项 的
值 , 此 选 项 指 定 shrink 方 法 应 用 的 收 缩 因 子 的 下 限 。 图 4.24 显 示 如 何 通 过 将 文 本 压 缩 50%
来 避 免 强 制 断 字 。 选 项 列 表 如 下 所 示 :
fontname=Helvetica fontsize=9 encoding=winansi alignment=justify shrinklimit=50%
用 于 分 散 对 齐 文 本 的 选 项 spreadlimit 扩 展 文 本 是 用 来 控 制 换 行 的 另 外 一 种 方 法 , 它 由
spread 方 法 实 现 并 由 spreadlimit 选 项 控 制 。 不 过 , 这 种 方 法 的 效 果 并 不 令 人 满 意 , 很 少 使
用 。 图 4.25 演 示 了 最 大 字 符 间 距 为 5 个 单 位 的 文 本 。 选 项 列 表 如 下 所 示 :
Our paper planes
are the ideal way of
passing the time.We
offer revolutionary
brand new developments
of the traditional
common paper planes.
If your lesson, conference,
or lecture turn out to
be deadly boring,
you can have a
wonderful time with
our planes. All our
models are folded
from one paper
sheet. They are
exclusively folded without
using any adhesive.
图 4.24
将 行 压 缩 50%
压 缩 行 (shrink 方 法 , shrinklimit 选 项 )
112 第 4 章 : 文 本 处 理

Our paper planes
are the ideal way of
passing the time. We
offer revolutionary
brand new developments
of the traditional
common paper planes.
If your lesson,
conference, or lecture
turn out to be deadly
boring, you can have
a wonderful time
with our planes.
缩 短 行 (nofit 方 法 , nofitlimit 选 项 )
图 4.26
最 小 宽 度 为 50% 的 分 散 对 齐 文 本
fontname=Helvetica fontsize=9 encoding=winansi alignment=justify spreadlimit=5
用 于 分 散 对 齐 文 本 的 选 项 nofitlimit nofitlimit 选 项 在 应 用 nofit 方 法 时 控 制 行 缩 小 的 程
度 。 当 限 定 框 非 常 窄 时 , 减 少 默 认 值 75% 相 对 于 强 制 断 字 更 为 可 行 。 图 4.26 显 示 了 生 成 的
最 小 文 本 宽 度 为 50% 的 文 本 输 出 。 选 项 列 表 如 下 所 示 :
fontname=Helvetica fontsize=9 encoding=winansi alignment=justify nofitlimit=50
4.9.9 使 用 textflow 格 式 化 CJK 文 本
textflow 引 擎 现 在 可 以 按 照 Unicode 标 准 将 CJK 字 符 作 为 表 意 字 形 进 行 处 理 。 因 此 ,CJK 文
本 将 决 不 会 断 字 。 为 了 改 进 格 式 设 置 , 当 使 用 带 有 CJK 文 本 的 textflow 时 , 推 荐 使 用 以 下
选 项 ; 这 些 选 项 将 对 插 入 的 拉 丁 文 本 禁 用 断 字 并 创 建 间 距 均 匀 的 文 本 输 出 :
hyphenchar=none
alignment=justify
shrinklimit=100%
spreadlimit=100%
对 CJK 文 本 使 用 textflow 时 , 请 注 意 以 下 限 制 :
> 不 支 持 垂 直 书 写 模 式 。
> 只 能 使 用 Unicode 兼 容 的 编 码 , 即 unicode 或 Unicode 兼 容 的 预 定 义 CMap 之
Our paper planes
are the ideal way of
passing the time. We
offer revolutionary
b r a n d n e w
developments of the
traditional common
paper planes. If your
lesson, conference,
or lecture turn out to
be deadly boring,
you can have a
wonderful time with
our planes.
图 4.25
最 大 字 符 间 距 为 5 个 单 位 的 分 散 对 齐 文 本
扩 展 行 (spread 方 法 , spreadlimit 选 项 )
4.9 多 行 textflow 113

114 第 4 章 : 文 本 处 理

5 导 入 和 放 置 对 象
PDFlib 提 供 多 种 功 能 以 便 从 现 有 的 PDF 文 档 导 入 光 栅 图 像 和 页 , 并 将 它 们 放 置 到 页 面 上 。
本 章 介 绍 有 关 处 理 光 栅 图 像 和 从 现 有 PDF 文 档 导 入 页 的 详 细 信 息 。 它 还 显 示 一 些 示 例 , 这
些 示 例 演 示 如 何 在 输 出 页 面 上 放 置 图 像 和 PDF 页 。
5.1 导 入 光 栅 图 像
5.1.1 基 本 图 像 处 理
在 PDFlib 中 嵌 入 光 栅 图 像 可 以 轻 松 实 现 。 首 先 , 必 须 用 一 个 PDFlib 函 数 打 开 图 像 文 件 , 对
图 像 参 数 进 行 简 短 的 分 析 。 PDF_load_image( ) 函 数 返 回 一 个 句 柄 用 作 图 像 说 明 。 此 句 柄 可
以 随 同 positioning 和 scaling 参 数 , 在 对 PDF_fit_image( ) 的 调 用 中 使 用 :
if ((image = PDF_load_image(p, "auto", "image.jpg", 0, "")) == -1) {
fprintf(stderr,"Error: Couldn't read image file.\n");
} else {
PDF_fit_image(p, image, 0.0, 0.0, "");
PDF_close_image(p, image);
}
PDF_fit_image( ) 函 数 的 最 后 的 参 数 是 一 个 选 项 列 表 , 它 支 持 用 于 定 位 、 缩 放 和 旋 转 图 像 的
各 种 选 项 。 有 关 这 些 选 项 的 详 细 信 息 将 在 第 123 页 上 的 第 5.3 节 “ 放 置 图 像 和 导 入 的 PDF
页 ” 中 讨 论 。
重 用 图 像 数 据 PDFlib 支 持 一 项 重 要 的 PDF 优 化 技 术 , 以 便 使 用 重 复 的 光 栅 图 像 。 让 我 们
以 在 多 个 页 面 上 使 用 的 不 变 的 徽 标 或 背 景 的 布 局 为 例 。 在 这 种 情 况 下 , 可 以 只 在 PDF 中 包
含 一 次 实 际 图 像 , 并 在 使 用 该 图 像 的 每 个 页 面 上 仅 生 成 一 个 引 用 。 每 次 需 要 在 特 殊 页 面 上 放
置 徽 标 或 背 景 时 , 只 需 加 载 一 次 图 像 文 件 , 并 调 用 PDF_fit_image( )。 用 户 也 可 以 在 多 个 页
面 上 放 置 图 像 , 或 对 出 现 在 不 同 位 置 的 相 同 图 像 使 用 不 同 的 缩 放 因 素 ( 只 要 图 像 没 有 被 关
闭 )。 根 据 图 像 的 尺 寸 和 出 现 次 数 , 此 技 术 会 导 致 产 生 巨 大 的 空 间 存 储 需 要 。
内 嵌 图 像 与 可 重 用 的 图 像 ( 作 为 图 像 XObject 写 入 到 PDF 输 出 ) 相 反 , 内 嵌 图 像 直 接 写
入 相 应 的 内 容 流 ( 页 、 模 式 、 模 板 或 字 形 说 明 ) 中 。 这 将 产 生 一 些 空 间 存 储 需 要 , 但 是 根
据 PDF Reference 中 的 建 议 , 只 应 用 于 数 量 不 大 的 图 像 数 据 ( 最 多 4KB)。 内 嵌 图 像 主 要 是
在 Type 3 字 体 的 点 阵 字 形 说 明 中 使 用 。
通 过 提 供 inline 选 项 , 可 以 使 用 PDF_load_image( ) 接 口 生 成 内 嵌 图 像 。 内 嵌 图 像 不 可 重
用 , 也 就 是 说 , 相 应 的 句 柄 不 得 提 供 给 接 受 图 像 句 柄 的 任 何 调 用 。 为 此 , 若 inline 选 项 已 提
供 , 则 PDF_load_image( ) 在 内 部 执 行 以 下 代 码 的 等 效 代 码 :
PDF_fit_image(p, image, 0, 0, "");
PDF_close_image(p, image);
缩 放 和 dpi 计 算 PDFlib 从 不 更 改 导 入 的 图 像 中 的 像 素 的 数 量 。 缩 放 不 是 扩 大 图 像 像 素 就
是 缩 小 图 像 像 素 , 但 是 不 会 执 行 任 何 缩 减 像 素 取 样 ( 图 像 中 的 像 素 数 量 将 总 是 保 持 不 变 )。
在 用 户 坐 标 中 , 缩 放 因 素 为 1 导 致 像 素 尺 寸 为 1 单 位 。 换 言 之 , 若 尚 未 缩 放 用 户 坐 标 系 统 ,
则 将 使 用 本 地 分 辨 率 导 入 图 像 ( 若 未 包 含 任 何 分 辨 率 信 息 , 则 为 72 dpi, 因 为 默 认 每 英 寸 有
72 个 单 位 )。
5.1 导 入 光 栅 图 像 115

已 导 入 图 像 的 色 彩 空 间 除 了 添 加 或 移 除 ICC 配 置 文 件 并 根 据 PDF_load_image( ) 中 提 供 的
选 项 使 用 专 色 之 外 ,PDFlib 通 常 将 保 留 已 导 入 图 像 的 本 地 色 彩 空 间 。 不 过 , 这 对 一 些 不 常 见
的 组 合 不 可 行 , 例 如 TIFF 中 的 YCbCr 将 转 换 为 RGB。
PDFlib 不 执 行 RGB 和 CMYK 之 间 的 任 何 转 换 。 若 这 样 的 转 换 是 必 需 的 , 则 在 PDFlib 中
加 载 图 像 之 前 , 必 须 对 图 像 数 据 应 用 此 转 换 。
5.1.2 受 支 持 的 图 像 文 件 格 式
PDFlib 处 理 以 下 描 述 的 图 像 文 件 格 式 。 默 认 情 况 下 , 如 果 可 能 的 话 ,PDFlib 将 压 缩 的 图 像
数 据 无 改 变 地 传 递 给 PDF 输 出 , 因 为 PDF 内 部 支 持 在 常 见 图 像 文 件 格 式 中 使 用 的 大 多 数
压 缩 方 案 。 此 技 术 ( 在 以 下 的 描 述 中 称 作 pass-through 模 式 ) 导 致 快 速 图 像 导 入 , 因 为 此
技 术 不 再 需 要 对 图 像 数 据 进 行 解 压 缩 以 及 随 后 的 再 压 缩 。 不 过 , 在 这 种 模 式 下 ,PDFlib 无
法 检 查 已 压 缩 图 像 数 据 的 完 整 性 。 当 在 Acrobat 中 使 用 PDF 文 档 时 , 不 完 整 的 图 像 数 据 或
损 坏 的 图 像 数 据 可 能 导 致 错 误 或 警 告 消 息 ( 例 如 读 取 比 预 期 少 的 图 像 数 据 ) 。 可 以 使 用
PDF_load_image( ) 的 passthrough 选 项 控 制 Pass-through 模 式 。
若 无 法 成 功 导 入 图 像 文 件 , PDF_load_image( ) 将 返 回 一 个 错 误 代 码 。 若 想 知 道 有 关 图 像
失 败 的 更 多 详 细 信 息 , 请 调 用 PDF_get_errmsg( ) 以 检 索 详 细 的 错 误 消 息 。
PNG 图 像 PDFlib 支 持 所 有 风 格 的 PNG 图 像 (ISO 15948)。 多 数 情 况 下 , 都 是 在 passthrough
模 式 中 处 理 PNG 图 像 。 用 了 隔 行 扫 描 或 包 含 一 个 alpha 通 道 ( 此 通 道 总 会 丢 失 ,
请 参 见 以 下 内 容 ) 的 PNG 图 像 必 须 是 未 压 缩 的 , 这 样 将 将 比 pass-through 模 式 花 多 很 多 时
间 。 若 PNG 图 像 包 含 透 明 度 信 息 , 则 在 生 成 的 PDF 中 保 留 透 明 度 ( 请 参 见 第 118 页 上 的 第
5.1.3 节 “ 图 像 蒙 版 和 透 明 度 ”)。 不 过 , alpha 通 道 不 受 PDFlib 支 持 。
JPEG 图 像 从 不 对 JPEG 图 像 (ISO 10918-1) 进 行 解 压 缩 , 但 是 一 些 风 格 可 能 需 要 代 码 转 换
以 便 在 Acrobat 中 正 确 显 示 。PDFlib 对 一 些 关 键 类 型 的 JPEG 图 像 自 动 使 用 代 码 转 换 , 但 是
也 可 以 通 过 PDF_load_image( ) 的 passthrough 选 项 控 制 代 码 转 换 。PDFlib 支 持 以 下 JPEG 图
像 风 格 :
> 灰 度 、 RGB ( 通 常 编 码 为 YCbCr) 和 CMYK 颜 色 。
> 基 线 JPEG 压 缩 , 被 大 量 JPEG 图 像 采 用 。
> 渐 进 JPEG 压 缩 。
可 以 用 一 些 不 同 的 文 件 格 式 对 JPEG 图 像 进 行 打 包 。PDFlib 支 持 所 有 常 见 的 JPEG 文 件 格 式 ,
并 将 读 取 以 下 风 格 的 分 辨 率 信 息 :
> JFIF, 由 多 种 图 像 应 用 程 序 生 成 。
> JPEG 文 件 由 Adobe Photoshop 和 其 他 Adobe 应 用 程 序 编 写 。PDFlib 采 用 了 一 个 必 要 的
替 代 方 法 以 正 确 处 理 Photoshop 生 成 的 CMYK JPEG 文 件 。
注 : PDFlib 不 解 释 SPIFF 文 件 格 式 的 JPEG 图 像 中 的 分 辨 率 信 息 , 也 不 解 释 EXIF 文 件 格 式 的 JPEG
图 像 中 的 色 彩 空 间 信 息 。
JPEG2000 图 像 JPEG2000 图 像 (ISO 15444-2) 需 要 PDF 1.5 或 更 高 版 本 , 并 总 是 在 passthrough
模 式 中 进 行 处 理 。 PDFlib 支 持 JPEG2000 图 像 , 如 下 所 示 :
> JP2 和 JPX 基 线 图 像 ( 通 常 是 *.jp2 或 *.jpf) 受 支 持 , 但 具 有 以 下 色 彩 空 间 条 件 约 束 。 支
持 所 有 有 效 的 颜 色 深 度 值 。
> 支 持 以 下 色 彩 空 间 :sRGB、sRGB-grey、ROMM-RGB、sYCC、e-sRGB、e-sYCC、CIELab、
基 于 ICC 的 色 彩 空 间 ( 受 限 制 的 或 全 部 ICC 配 置 文 件 ) 和 CMYK。 PDFlib 将 不 会 改 变
JPEG2000 图 像 文 件 中 的 原 始 色 彩 空 间 。
> 包 含 软 蒙 版 的 图 像 可 以 与 mask 选 项 一 起 使 用 以 准 备 一 个 可 以 应 用 于 其 他 图 像 的 蒙 版 。
116 第 5 章 : 导 入 和 放 置 对 象

无 法 对 JPEG2000 图 像 应 用 外 部 ICC 配 置 文 件 , 也 就 是 说 , 禁 止 使 用 iccprofile 选 项 。 并
将 一 直 保 留 JPEG2000 图 像 文 件 中 包 含 的 ICC 配 置 文 件 , 也 就 是 说 ,honoriccprofile 选 项
总 是 为 true。
> JPEG2000 图 像 不 支 持 colorize 选 项 。
注 : 根 据 ISO 15444-6 ( 通 常 为 *.jpm), 不 带 JPX 包 装 的 原 始 JPEG2000 代 码 流 ( 通 常 为 *.j2k)
和 JPM 复 合 图 像 文 件 将 不 被 支 持 。
GIF 图 像 PDFlib 支 持 带 有 隔 行 扫 描 和 未 隔 行 扫 描 的 像 素 数 据 的 所 有 GIF 风 格 ( 特 别 是 GIF
87a 和 89a) 和 所 有 调 色 板 尺 寸 。 并 总 是 使 用 Flate 压 缩 对 GIF 图 像 进 行 再 压 缩 。
TIFF 图 像 PDFlib 将 在 pass-through 模 式 中 处 理 多 数 TIFF 图 像 。 PDFlib 支 持 以 下 风 格 的
TIFF 图 像 :
> 压 缩 方 案 : 在 pass-through 模 式 中 处 理 未 压 缩 、CCITT(group 3、group 4 和 RLE)、
ZIP (=Flate) 和 PackBits (=RunLength) ; 其 他 压 缩 方 案 如 LZW 和 JPEG 将 通 过 解 压 缩
处 理 。
> 颜 色 : 黑 白 、 灰 度 、 RGB、 CMYK、 CIELab 和 YCbCr 图 像 ; 将 忽 略 在 文 件 中 可 能 出 现 的
任 何 alpha 通 道 或 蒙 版 。
> 包 含 多 个 的 图 像 TIFF 文 件 ( 请 参 见 第 120 页 上 的 第 5.1.5 节 “ 多 页 图 像 文 件 ”)
> 颜 色 深 度 必 须 是 每 个 颜 色 采 样 1、2、4、8 或 16 位 。 在 PDF 1.5 模 式 中 , 多 数 情 况 下 ,16 位
颜 色 深 度 将 与 pass-through 模 式 一 起 保 留 , 但 是 对 于 某 些 图 像 文 件 会 减 少 到 8 位 ( 带 有
little-endian/Intel 字 节 顺 序 和 16 位 调 色 板 图 像 的 ZIP 压 缩 )。
在 PDF 文 件 中 , 多 带 区 TIFF 图 像 会 转 换 为 多 个 图 像 , PDF 文 件 视 觉 上 完 全 再 现 了 原 始 图
像 , 但 是 可 以 使 用 Acrobat 的 TouchUp 对 象 工 具 选 择 个 别 图 像 。 可 以 使 用 TIFFlib 包 中 的
tiffcp 命 令 行 工 具 将 多 带 区 TIFF 图 像 转 换 为 单 带 区 图 像 。 1 ImageMagick 2 工 具 总 是 写 入 单 带
区 TIFF 图 像 。
PDFlib 可 完 全 处 理 方 向 标 签 , 该 标 签 在 一 些 TIFF 文 件 中 指 定 所 需 的 图 像 方 向 。 通 过 将
ignoreorientation 选 项 设 置 为 true, 可 以 指 示 PDFlib 忽 略 方 向 标 签 ( 和 许 多 应 用 程 序 的 做
法 一 样 )。
一 些 TIFF 功 能 ( 如 专 色 ) 和 某 些 功 能 组 合 ( 如 带 蒙 版 的 CMYK 图 像 ) 都 不 受 支 持 。 尽 管
带 JPEG 压 缩 的 TIFF 图 像 通 常 都 受 支 持 , 但 一 些 所 谓 旧 式 TIFF-JPEG 风 格 的 TIFF 图 像 除 外 。
BMP 图 像 在 pass-through 模 式 中 无 法 处 理 BMP 图 像 。 PDFlib 支 持 以 下 风 格 的 BMP
图 像 :
> BMP 版 本 2 和 3 ;
> 每 组 件 的 颜 色 深 度 为 1、 4 和 8 位 , 包 括 3x8=24 位 TrueColor。 16 位 图 像 将 作 为
5+5+5 以 及 1 个 未 使 用 的 位 进 行 处 理 。 32 位 图 像 将 作 为 3x8 位 图 像 处 理 ( 剩 余 的 8 位
将 被 忽 略 )。
> 黑 白 或 RGB 颜 色 ( 索 引 的 和 直 接 的 );
> 未 压 缩 以 及 4 位 和 8 位 RLE 压 缩 ;
> 若 像 素 是 按 自 下 而 上 的 顺 序 存 储 , 则 PDFlib 将 不 映 像 图 像 ( 这 是 BMP 中 很 少 使 用 的 功
能 , 在 各 应 用 程 序 中 将 进 行 不 同 的 解 释 )。
CCITT 图 像 Group 3 或 Group 4 传 真 压 缩 的 图 像 数 据 总 是 在 pass-through 模 式 中 处 理 。
请 注 意 , 这 种 格 式 实 际 意 味 着 原 始 CCITT 压 缩 的 图 像 数 据 , 而 不 是 使 用 CCITT 压 缩 的 TIFF
文 件 。 原 始 CCITT 压 缩 的 图 像 文 件 通 常 在 终 端 用 户 应 用 程 序 中 不 受 支 持 , 而 只 能 使 用 与 传 真
1. 请 参 见 www.libtiff.org
2. 请 参 见 www.imagemagick.org
5.1 导 入 光 栅 图 像 117

有 关 的 软 件 生 成 。 因 为 PDFlib 无 法 分 析 CCITT 图 像 , 所 以 客 户 端 必 须 将 所 有 相 关 的 图 像 参
数 传 递 给 PDF_load_image( )。
原 始 数 据 未 压 缩 的 ( 原 始 ) 图 像 数 据 对 一 些 特 殊 的 应 用 程 序 可 能 很 有 用 。 可 以 从 颜 色 分
量 的 数 量 来 推 导 图 像 的 本 质 :1 个 分 量 表 示 灰 度 图 像 , 3 个 分 量 表 示 RGB 图 像 , 4 个 分 量 表
示 CMYK 图 像 。
5.1.3 图 像 蒙 版 和 透 明 度
PDF 中 的 透 明 度 PDF 支 持 各 种 透 明 度 功 能 , 所 有 这 些 功 能 都 在 PDFlib 中 实 现 :
> 根 据 位 置 蒙 版 : 图 像 可 能 携 带 内 部 信 息 “ 打 印 前 景 或 背 景 ” 。 这 可 以 由 1 位 蒙 版 图 像 实
现 , 在 目 录 图 像 中 使 用 经 常 会 使 用 到 它 。
> 根 据 颜 色 值 蒙 版 : 某 种 颜 色 的 像 素 不 会 绘 制 , 而 页 面 上 先 前 绘 制 的 部 分 透 射 出 来 ( 即 ,
忽 略 图 像 中 所 有 蓝 色 像 素 )。 在 电 视 和 视 频 技 术 中 , 这 也 称 作 蓝 色 屏 蔽 , 经 常 用 于 将 气 象
人 员 和 气 象 图 组 合 到 一 个 图 像 中 。
> PDF 1.4 介 绍 alpha 通 道 或 软 蒙 版 。 它 们 可 以 用 于 创 建 前 景 和 背 景 之 间 的 平 滑 转 换 , 或 创
建 半 透 明 对 象 ( 混 合 图 像 和 背 景 )。 软 蒙 版 由 带 1-8 位 / 像 素 的 1 分 量 图 像 表 示 。
PDFlib 支 持 图 像 中 的 三 种 透 明 度 信 息 : 隐 式 透 明 度 、 显 式 透 明 度 和 图 像 蒙 版 。
注 : 蒙 版 必 须 与 底 层 的 图 像 具 有 相 同 的 方 向 , 否 则 将 会 被 拒 绝 。 因 为 方 向 取 决 于 图 像 文 件 格 式 和
其 他 因 素 , 所 以 难 以 检 测 。 为 此 , 建 议 对 蒙 版 和 图 像 使 用 相 同 的 文 件 格 式 和 创 建 软 件 。
隐 式 透 明 度 在 隐 式 情 况 下 , 将 使 用 外 部 图 像 文 件 中 的 透 明 度 信 息 , 前 提 是 图 像 文 件 格 式 支
持 透 明 度 或 alpha 通 道 ( 并 非 所 有 图 像 文 件 格 式 都 是 如 此 )。 在 以 下 的 图 像 文 件 格 式 中 检 测
透 明 度 信 息 :
> GIF 图 像 文 件 可 能 包 含 一 个 PDFlib 遵 从 的 透 明 度 颜 色 值 。
> PNG 图 像 文 件 可 能 包 含 一 些 风 格 的 透 明 度 信 息 或 整 个 alpha 通 道 。 PDFlib 将 保 留 单 个
透 明 度 颜 色 值 ; 若 给 定 带 附 加 alpha 值 的 多 个 颜 色 值 , 则 仅 使 用 第 一 个 带 有 50% 以 下 的
alpha 值 的 颜 色 值 。 忽 略 整 个 alpha 通 道 。
显 式 透 明 度 显 式 情 况 下 要 求 两 个 涉 及 图 像 操 作 的 步 骤 。 首 先 , 必 须 准 备 好 稍 后 作 为 透 明 度
蒙 版 使 用 的 图 像 。 通 过 使 用 mask 选 项 打 开 图 像 来 完 成 此 操 作 。 在 PDF 1.3( 仅 支 持 1 位 蒙 版 )
中 , 此 选 项 为 必 选 ; 在 PDF 1.4 中 , 此 选 项 为 可 选 的 。 以 下 类 型 的 图 像 可 以 用 于 构 造 蒙 版 :
> PNG 图 像
> TIFF 图 像 ( 仅 单 带 区 )
> 原 始 图 像 数 据
蒙 版 中 的 为 0( 零 ) 像 素 值 将 导 致 所 蒙 版 图 像 的 相 应 部 分 被 绘 制 , 而 高 像 素 值 导 致 背 景 透 射
出 来 。 若 像 素 具 有 大 于 1 位 / 像 素 , 中 间 值 将 针 对 背 景 混 合 前 景 图 像 , 提 供 透 明 效 果 。 在 第
二 步 中 , 蒙 版 应 用 于 其 他 通 过 以 下 图 像 函 数 之 一 获 得 的 图 像 :
mask = PDF_load_image(p, "png", maskfilename, 0, "mask");
if (mask == -1)
return;
sprintf(optlist, "masked %d", mask);
image = PDF_load_image(p, type, filename, optlist)
if (image == -1)
return;
PDF_fit_image(p, image, x, y, "");
请 注 意 , PDF_load_image( ) 的 选 项 列 表 的 不 同 用 法 :mask 用 于 定 义 蒙 版 , masked 用 于 对
其 他 图 像 应 用 蒙 版 。
118 第 5 章 : 导 入 和 放 置 对 象

图 像 和 蒙 版 可 能 有 不 同 的 像 素 尺 寸 ; 蒙 版 将 指 定 缩 放 到 图 像 的 尺 寸 。
注 : PDFlib 将 多 带 区 TIFF 图 像 转 换 为 多 个 PDF 图 像 , 转 换 后 各 个 PDF 图 像 将 单 独 蒙 版 。 因 为 通 常
不 希 望 这 样 做 , 所 以 会 拒 绝 将 此 类 图 像 用 作 蒙 版 和 所 蒙 版 的 目 标 图 像 。 避 免 混 淆 隐 式 情 况 和
显 式 情 况 也 很 重 要 , 也 就 是 说 , 不 要 将 带 有 透 明 颜 色 值 的 图 像 作 为 蒙 版 使 用 。
图 像 蒙 版 图 像 蒙 版 是 指 位 深 度 为 1 ( 位 图 ) 的 图 像 , 在 此 图 像 中 零 位 将 视 为 透 明 : 已 在 页
面 上 存 在 的 任 何 内 容 都 将 通 过 图 像 的 透 明 部 分 透 射 出 来 。 对 1 位 像 素 使 用 当 前 填 充 色 进 行 着
色 。 以 下 类 型 的 图 像 可 以 作 为 图 像 蒙 版 使 用 :
> PNG 图 像
> TIFF 图 像 ( 单 带 区 或 多 带 区 )
> JPEG 图 像 ( 仅 作 为 软 蒙 版 , 请 参 见 以 下 内 容 )
> BMP ; 请 注 意 ,BMP 图 像 的 定 向 方 式 与 其 他 图 像 类 型 的 定 向 方 式 不 同 。 为 此 , 在 BMP 图
像 作 为 蒙 版 使 用 之 前 , 必 须 沿 x 轴 反 射 此 图 像 。
> 原 始 图 像 数 据
使 用 mask 选 项 打 开 图 像 蒙 版 , 在 完 成 对 所 需 填 充 色 的 设 置 后 , 将 该 蒙 版 放 置 在 页 面 上 :
mask = PDF_load_image(p, "tiff", maskfilename, 0, "mask");
PDF_setcolor(p, "fill", "rgb", (float) 1, (float) 0, (float) 0, (float) 0);
if (mask != -1) {
PDF_fit_image(p, mask, x, y, "");
}
若 需 要 对 图 像 ( 没 有 表 示 透 明 的 零 位 像 素 ) 应 用 颜 色 , 必 须 使 用 colorize 选 项 ( 请 参 见
第 119 页 上 的 第 5.1.4 节 “ 图 像 着 色 ”)。
软 蒙 版 软 蒙 版 将 图 像 蒙 版 的 概 念 推 广 到 具 有 1 位 以 上 深 度 的 蒙 版 。 PDF 1.4 中 已 引 入 了 软
蒙 版 , 用 于 将 图 像 与 一 些 现 有 背 景 混 合 。 PDFlib 接 受 所 有 类 型 的 单 通 道 ( 灰 度 ) 图 像 作 为
软 蒙 版 。 它 们 的 使 用 方 法 与 图 像 蒙 版 相 同 , 只 要 PDF 输 出 兼 容 性 只 要 包 括 PDF 1.4。
忽 略 透 明 度 有 时 , 需 要 忽 略 在 图 像 文 件 中 可 能 包 含 的 任 何 透 明 度 信 息 。 例 如 ,Acrobat 的
消 除 锯 齿 功 能 ( 也 称 作 “ 平 滑 ”) 不 能 用 于 仅 包 含 黑 色 和 透 明 的 1 位 图 像 。 为 此 , 当 透 明 度
信 息 保 留 在 生 成 的 PDF 中 时 , 细 节 丰 富 的 导 入 图 像 ( 例 如 , 光 栅 化 文 本 ) 可 能 看 起 来 很 不
舒 服 。 为 了 处 理 这 种 情 况 , 当 打 开 文 件 时 , 可 以 用 ignoremask 选 项 禁 用 PDFlib 的 自 动 透 明
度 支 持 :
image = PDF_load_image(p, "gif", filename, 0, "ignoremask");
5.1.4 图 像 着 色
与 图 像 蒙 版 ( 对 图 像 的 非 透 明 部 分 应 用 颜 色 ) 类 似 , PDFlib 支 持 用 专 色 给 图 像 着 色 。 此 功
能 可 用 于 以 下 格 式 的 黑 白 或 灰 度 图 像 :
> BMP
> PNG
> JPEG
> TIFF
> GIF
对 于 带 RGB 调 色 板 的 图 像 , 仅 当 调 色 板 只 包 含 灰 色 值 并 且 调 色 板 索 引 与 灰 色 值 一 致 时 , 着
色 才 算 合 理 。
5.1 导 入 光 栅 图 像 119

为 了 用 专 色 给 图 像 着 色 , 您 必 须 在 加 载 图 像 时 提 供 colorize 选 项 并 提 供 由 PDF_
makespotcolor( ) 返 回 的 相 应 的 专 色 句 柄 :
PDF_setcolor(p, "both", "cmyk", 1, .79, 0, 0);
spot = PDF_makespotcolor(p, "PANTONE Reflex Blue CV", 0);
sprintf(optlist, "colorize %d", spot);
image = PDF_load_image(p, "tiff", "image.tif", 0, optlist)
if (image != -1) {
PDF_fit_image(p, image, x, y, "");
}
5.1.5 多 页 图 像 文 件
PDFlib 支 持 包 含 多 个 图 像 的 TIFF 文 件 , 也 称 作 “ 多 页 文 件 ”。 为 了 使 用 多 页 TIFF, 需 在 对
PDF_load_image( ) 的 调 用 中 使 用 附 加 的 字 符 串 和 数 字 参 数 :
image = PDF_load_image(p, "tiff", filename, 0, "page 2");
page 选 项 指 示 要 使 用 多 图 像 文 件 。 最 后 一 个 参 数 指 定 要 使 用 的 图 像 的 编 号 。 第 一 个 图 像 的
编 号 为 1。 此 选 项 可 以 增 加 直 到 PDF_load_image( ) 返 回 -1 ( 假 定 imagewarning=false), 发
出 信 号 表 示 文 件 中 再 没 有 图 像 可 用 。
类 似 以 下 的 代 码 片 段 可 以 用 于 将 多 图 像 TIFF 文 件 中 的 所 有 图 像 转 换 为 多 页 PDF 文 件 :
for (frame = 1; /* */ ; frame++) {
sprintf(optlist, "page %d", frame);
image = PDF_load_image(p, "tiff", filename, 0, optlist);
if (image == -1)
break;
PDF_begin_page(p, width, height);
PDF_fit_image(p, image, 0.0, 0.0, "");
PDF_close_image(p, image);
PDF_end_page(p);
}
5.1.6 OPI 支 持
当 加 载 图 像 时 , 根 据 OPI ( 开 放 印 前 作 业 界 面 ) 版 本 1.3 或 2.0, 在 对 PDF_load_image( ) 的
调 用 中 将 提 供 附 加 信 息 。 PDFlib 接 受 所 有 标 准 OPI 1.3 或 2.0 PostScript 注 释 作 为 选 项 ( 不
是 相 应 的 PDF 关 键 字 !), 并 将 提 供 的 OPI 信 息 传 递 到 生 成 的 PDF 输 出 ( 不 做 任 何 修 改 )。
以 下 示 例 将 OPI 信 息 附 加 到 图 像 :
optlist13 =
"OPI-1.3 { ALDImageFilename bigfile.tif "
"ALDImageDimensions {400 561} "
"ALDImageCropRect {10 10 390 550} "
"ALDImagePosition {10 10 10 540 390 540 390 10} }";
image = PDF_load_image(p, "tiff", filename, 0, optlist13);
注 : 一 些 OPI 服 务 器 ( 例 如 Helios EtherShare 中 包 含 的 一 种 OPI 服 务 器 ) 不 能 正 确 实 现 对 PDFlib 在
默 认 情 况 下 生 成 的 PDF Image XObject 的 OPI 处 理 。 在 这 种 情 况 下 , 通 过 对 PDF_load_image( )
提 供 模 板 选 项 可 以 强 制 生 成 Form XObject。
120 第 5 章 : 导 入 和 放 置 对 象

5.2 使 用 PDI (PDF 导 入 库 ) 生 成 PDF 页
注 : 本 节 中 描 述 的 所 有 函 数 都 需 要 PDFlib+PDI。 PDF 导 入 库 (PDI) 未 包 含 在 PDFlib 或 PDFlib Lite
中 。 尽 管 PDI 已 经 在 所 有 预 编 译 版 本 的 PDFlib 中 集 成 , 但 是 仍 需 要 PDI( 或 包 含 PDI 的 PPS)
的 许 可 密 钥 。
5.2.1 PDI 功 能 和 应 用 程 序
若 可 选 PDI (PDF 导 入 ) 库 已 附 加 到 PDFlib, 则 可 以 导 入 现 有 PDF 文 档 中 的 页 。 PDI 包 含
用 于 PDF 文 件 格 式 的 分 析 器 , 并 准 备 现 有 PDF 文 档 中 的 页 以 便 轻 松 使 用 PDFlib。 从 概 念 上
讲 , 导 入 的 PDF 页 与 导 入 的 光 栅 图 像 ( 例 如 TIFF 或 PNG) 的 处 理 方 法 类 似 。 打 开 一 个 PDF
文 档 , 选 择 要 导 入 的 页 , 然 后 将 该 页 放 置 在 输 出 页 面 上 , 应 用 任 何 PDFlib 的 转 换 函 数 以 转
换 , 缩 放 、 旋 转 或 歪 移 导 入 的 页 。 将 导 入 的 PDF 页 放 置 在 输 出 页 面 上 后 , 通 过 使 用 任 何
PDFlib 的 文 本 或 图 形 函 数 , 可 以 轻 松 将 到 导 入 的 页 与 新 内 容 组 合 ( 将 导 入 的 页 看 作 新 内 容
的 背 景 )。 使 用 PDFlib 和 PDI, 您 可 以 轻 松 完 成 以 下 任 务 :
> 覆 盖 多 PDF 文 档 中 的 两 个 或 多 个 页 ( 例 如 对 现 有 文 档 添 加 信 纸 格 式 以 模 拟 预 先 印 刷 的
信 纸 );
> 在 现 有 文 档 中 放 置 PDF 广 告 ;
> 剪 裁 PDF 页 面 的 可 见 区 域 以 便 除 去 不 需 要 的 元 素 ( 例 如 , 剪 裁 标 记 ) 或 缩 放 页 ;
> 在 一 张 纸 上 打 印 多 页 ;
> 处 理 符 合 多 PDF/X 的 文 档 以 创 建 新 的 PDF/X 文 件 ;
> 添 加 一 些 文 本 ( 例 如 标 题 、 页 脚 、 戳 记 、 页 码 ) 或 图 像 ( 例 如 , 公 司 徽 标 ) 到 现 有 PDF 页 ;
> 将 输 入 文 档 中 的 所 有 页 复 制 到 输 出 文 档 , 并 在 页 面 上 放 置 条 形 码 。
为 了 放 置 PDF 背 景 页 并 用 动 态 数 据 填 充 该 页 ( 例 如 , 邮 件 合 并 、 在 Web 上 个 性 化 PDF 文
档 、 表 单 填 充 ), 我 们 建 议 与 PDFlib 块 一 起 使 用 PDI ( 请 参 见 第 6 章 )。
5.2.2 与 PDFlib 一 起 使 用 PDI 函 数
常 规 注 意 事 项 PDI 将 仅 导 入 实 际 页 内 容 , 而 并 不 是 在 导 入 的 PDF 文 档 中 可 能 将 出 现 的 任
何 超 文 本 功 能 ( 例 如 声 音 、 电 影 、 嵌 入 的 文 件 、 超 文 本 链 接 、 表 单 域 、 JavaScript、 书 签 、
缩 略 图 和 注 释 ), 了 解 这 一 点 很 重 要 。 可 以 使 用 相 应 的 PDFlib 函 数 生 成 这 些 超 文 本 功 能 。 当
导 入 页 面 时 , PDFlib 块 也 将 被 忽 略 。
不 能 通 过 其 他 PDFlib 函 数 重 用 导 入 页 的 各 个 元 素 。 例 如 , 对 一 些 其 他 内 容 不 可 能 重 用 导
入 的 文 档 的 字 体 , 所 有 必 需 的 字 体 都 必 须 在 PDFlib 中 配 置 。 若 多 个 导 入 的 文 档 都 包 含 相 同
字 体 的 嵌 入 的 字 体 信 息 , 则 PDI 将 不 会 移 除 任 何 重 复 的 字 体 数 据 。 另 一 方 面 , 若 字 体 从 一 些
导 入 的 PDF 中 缺 失 , 则 这 些 字 体 也 将 从 生 成 的 PDF 输 出 文 件 中 缺 失 。 作 为 最 佳 选 择 , 您 应
尽 可 能 长 时 间 地 保 持 导 入 的 文 档 为 打 开 状 态 , 以 避 免 在 输 出 文 档 中 多 次 嵌 入 相 同 的 字 体 。
PDI 无 论 如 何 也 不 会 更 改 导 入 的 PDF 文 档 的 颜 色 。 例 如 , 若 PDF 包 含 ICC 配 置 文 件 , 则
这 些 文 件 将 在 输 出 文 档 中 保 留 。
PDFlib 使 用 模 板 功 能 以 便 在 输 出 页 面 上 放 置 导 入 的 PDF 页 。 因 为 一 些 第 三 方 PDF 软 件 不
能 正 确 支 持 模 板 , 所 以 在 Acrobat 之 外 的 某 些 环 境 中 会 存 在 一 些 限 制 ( 请 参 见 第 56 页 上 的
第 3.2.4 节 “ 模 板 ”)。
对 于 PDFlib 生 成 的 、 包 含 从 其 他 PDF 文 档 导 入 的 页 的 输 出 , 可 以 再 次 使 用 PDFlib+PDI
进 行 处 理 。 不 过 , 由 于 PostScript 打 印 中 的 限 制 , 嵌 套 级 别 不 应 超 过 10。
用 于 导 入 PDF 页 的 代 码 片 段 可 以 使 用 非 常 简 单 的 代 码 结 构 处 理 现 有 PDF 文 档 中 的 页 。 以
下 代 码 片 段 从 现 有 文 档 中 打 开 某 个 页 , 并 将 页 面 内 容 复 制 到 输 出 PDF 文 档 中 的 新 页 上 ( 此
文 档 必 须 事 先 已 打 开 ):
5.2 使 用 PDI (PDF 导 入 库 ) 生 成 PDF 页 121

int doc, page, pageno = 1;
char *filename = "input.pdf";
...
doc = PDF_open_pdi(p, filename, "", 0);
if (doc == -1) {
printf("Couldn't open PDF input file '%s'\n", filename);
exit(1);
}
page = PDF_open_pdi_page(p, doc, pageno, "");
if (page == -1) {
printf("Couldn't open page %d of PDF file '%s'\n", pageno, filename);
exit(2);
}
/* dummy page size, will be modified by the adjustpage option */
PDF_begin_page(p, 20, 20);
PDF_fit_pdi_page(p, page, 0, 0, "adjustpage");
PDF_close_pdi_page(p, page);
...add more content to the page using PDFlib functions...
PDF_end_page(p);
PDF_fit_pdi_page( ) 的 最 后 一 个 参 数 是 一 个 选 项 列 表 , 此 列 表 支 持 用 于 定 位 、 缩 放 和 旋 转 导
入 的 页 的 各 种 选 项 。 有 关 这 些 选 项 的 详 细 信 息 将 在 第 123 页 上 的 第 5.3 节 “ 放 置 图 像 和 导 入
的 PDF 页 ” 中 讨 论 。
导 入 的 PDF 页 的 尺 寸 导 入 的 PDF 页 的 处 理 方 式 类 似 于 导 入 的 光 栅 图 像 , 并 可 以 使 用
PDF_fit_pdi_page( ) 将 其 放 置 在 输 出 页 面 上 。 默 认 情 况 下 , PDI 会 按 照 页 在 Acrobat 中 的 相
同 显 示 方 式 进 行 导 入 , 具 体 如 下 :
> 裁 剪 将 被 保 留 ( 从 技 术 上 讲 , 若 裁 剪 框 存 在 , PDI 将 相 对 于 媒 体 框 优 先 考 虑 裁 剪 框 ; 请
参 见 第 55 页 上 的 第 3.2.2 节 “ 页 面 大 小 和 坐 标 限 制 ”);
> 已 对 页 使 用 的 旋 转 将 保 留 。
另 外 , 您 可 以 使 用 pdiusebox 选 项 来 显 式 指 示 PDI 使 用 页 面 的 任 何 媒 体 框 、 裁 剪 框 、 出 血
框 、 裁 切 框 或 作 品 框 项 ( 若 存 在 ) , 以 便 确 定 导 入 页 面 的 尺 寸 ( 有 关 详 细 信 息 , 请 参 见
表 8.46)。
许 多 重 要 属 性 ( 例 如 导 入 的 PDF 页 的 宽 度 和 高 度 )、 所 有 方 框 项 以 及 文 档 中 的 页 的 数 目
都 可 以 通 过 PDFlib 的 参 数 机 制 查 询 。 相 关 参 数 已 在 表 8.45 和 表 8.46 中 列 出 。 对 导 入 的 PDF
页 在 输 出 页 上 的 位 置 作 出 决 定 时 , 这 些 属 性 会 有 用 。
带 图 层 的 导 入 PDF 页 Acrobat 6 (PDF 1.5) 引 入 了 图 层 功 能 ( 技 术 上 称 作 “ 可 选 内 容 ”)。
PDI 将 忽 略 可 能 在 文 件 中 存 在 的 任 何 图 层 信 息 。 在 导 入 的 页 中 的 所 有 图 层 ( 包 括 不 可 见 图
层 ) 都 将 在 生 成 的 输 出 中 可 见 。
带 OPI 信 息 的 导 入 的 PDF 在 输 入 PDF 中 存 在 的 OPI 信 息 将 在 输 出 中 毫 无 修 改 地 保 留 。
5.2.3 可 接 受 的 PDF 文 档
通 常 ,PDI 将 乐 意 处 理 所 有 类 型 的 、 可 以 用 Acrobat 打 开 的 PDF 文 档 , 而 不 管 在 文 件 内 使 用
的 PDF 版 本 号 或 功 能 。 为 了 导 入 已 加 密 文 档 ( 即 具 有 权 限 设 置 或 口 令 的 文 件 ) 中 的 页 , 必
须 提 供 相 应 的 许 可 口 令 。
不 过 , 在 少 数 情 况 下 , PDF 文 档 或 文 档 的 某 个 页 会 被 PDI 拒 绝 。
122 第 5 章 : 导 入 和 放 置 对 象

默 认 情 况 下 , 若 PDF 文 档 或 页 无 法 成 功 导 入 , PDF_open_pdi( ) 和 PDF_open_pdi_page( )
将 返 回 一 个 错 误 代 码 。 不 过 , 若 想 知 道 有 关 失 败 的 更 多 详 细 信 息 , 可 以 使 用 PDF_get_
errmsg( ) 查 询 原 因 。 另 外 , 可 以 将 pdiwarning 选 项 或 参 数 设 置 为 true, 这 样 在 文 档 无 法 打
开 的 情 况 下 , 将 引 发 一 个 异 常 :
PDF_set_parameter(p, "pdiwarning", "true"); /* enable PDI warnings */
这 将 导 致 PDF_open_pdi( ) 和 PDF_open_pdi_page( ) 引 发 一 个 异 常 , 并 在 相 应 的 异 常 消 息 中
提 供 有 关 失 败 的 更 多 详 细 信 息 。 使 用 PDI 无 法 导 入 以 下 类 型 的 PDF 文 档 :
> 其 使 用 的 PDF 版 本 号 比 当 前 要 生 成 的 PDF 输 出 文 档 更 高 的 PDF 文 档 。 因 为 在 导 入 带 有 更
高 版 本 号 的 PDF 之 后 ,PDFlib 不 再 能 够 确 保 输 出 将 实 际 符 合 所 请 求 的 PDF 版 本 。 解 决 方
案 : 使 用 PDF_begin_document( ) 中 的 compatibility 选 项 , 将 输 出 PDF 的 版 本 设 置 为 要
求 的 级 别 。
> 其 PDF/X 规 范 等 级 与 当 前 输 出 文 档 的 PDF/X 级 别 不 兼 容 的 PDF 文 档 。
> 带 有 损 坏 的 交 叉 引 用 表 的 PDF 文 档 。 通 过 Acrobat 的 警 告 消 息 “ 文 件 已 损 坏 但 正 在 修
复 ”, 可 以 识 别 这 样 的 文 件 。 解 决 方 案 : 用 Acrobat 打 开 并 重 新 保 存 文 件 。
另 外 , 默 认 情 况 下 , 将 拒 绝 以 下 类 型 的 PDF 文 档 ; 不 过 , 通 过 将 infomode 选 项 设 置 为 true,
可 以 打 开 这 些 文 档 以 便 查 询 信 息 ( 与 导 入 页 相 反 ):
> 没 有 相 应 的 口 令 的 已 加 密 PDF 文 档 ( 例 外 : 使 用 Distiller 设 置 “ 对 象 级 别 压 缩 : 最 大
值 ” 创 建 的 PDF 1.6 文 档 );
> 在 PDF_begin_document( ) 中 的 tagged 选 项 为 true 的 情 况 下 的 标 签 PDF。
5.3 放 置 图 像 和 导 入 的 PDF 页
用 于 放 置 光 栅 图 像 和 模 板 的 PDF_fit_image( ) 函 数 以 及 用 于 放 置 导 入 的 PDF 页 的 PDF_fit_
pdi_page( ) 都 提 供 大 量 的 选 项 以 便 在 页 面 上 控 制 放 置 位 置 。 本 节 通 过 列 举 一 些 常 见 应 用 程 序
任 务 说 明 最 重 要 的 选 项 。 完 整 的 列 表 和 所 有 选 项 的 说 明 可 以 在 表 8.41 中 找 到 。
使 用 PDFlib 可 以 轻 松 完 成 光 栅 图 像 嵌 入 。 必 须 使 用 PDF_load_image( ) 首 先 加 载 图 像 文
件 。 此 函 数 返 回 一 个 图 像 句 柄 , 它 可 以 与 定 位 和 缩 放 选 项 在 PDF_fit_image( ) 中 使 用 。
嵌 入 导 入 的 PDF 页 的 方 式 相 同 。 必 须 使 用 PDF_open_pdi_page( ) 打 开 PDF 页 来 获 取 页 句
柄 以 便 在 PDF_fit_pdi_page( ) 中 使 用 。 可 以 对 光 栅 图 像 使 用 相 同 的 定 位 和 缩 放 选 项 。
本 节 中 的 所 有 示 例 对 光 栅 图 像 、 模 板 和 导 入 的 PDF 页 都 起 相 同 的 作 用 。 尽 管 这 里 仅 提 供
了 用 于 光 栅 图 像 的 代 码 示 例 , 但 我 们 谈 论 的 一 般 意 义 的 对 象 放 置 。 请 注 意 , 在 调 用 任 何 fit
函 数 之 前 , 必 须 发 出 对 PDF_load_image( ) 或 PDF_open_pdi( ) 和 PDF_open_pdi_page( ) 的 调
用 。 为 了 简 单 起 见 , 在 这 里 不 重 现 这 些 调 用 。
5.3.1 缩 放 、 方 向 和 旋 转
简 单 放 置 让 我 们 从 最 简 单 的 情 况 开 始 ( 请 参 见 图 5.1): 按 照 对 象 的 原 始 尺 寸 将 其 放 置 在
某 个 位 置 :
PDF_fit_image(p, image, 80, 100, "");
在 此 代 码 片 段 中 , 对 象 的 左 下 角 放 置 在 用 户 坐 标 系 统 的 点 (80, 100) 上 。 此 点 称 作 参 考 点 。
选 项 列 表 ( 函 数 的 最 后 一 个 参 数 ) 为 空 。 这 表 示 按 对 象 的 原 始 尺 寸 将 其 放 置 在 提 供 的 参 考
点 上 。
在 矩 形 中 居 中 放 置 图 像 为 了 使 图 像 在 预 定 义 的 矩 形 中 居 中 放 置 , 您 自 己 不 需 要 作 任 何 计
算 , 而 只 需 使 用 如 下 所 示 的 合 适 的 选 项 就 可 以 实 现 :
5.3 放 置 图 像 和 导 入 的 PDF 页 123

PDF_fit_image(p, image, 80, 100, "boxsize {200 100} position 50 fitmethod meet");
带 缩 放 比 例 的 放 置 也 可 以 轻 松 使 用 以 下 变 体 ( 请 参 见 图 5.2)。 我 们 按 照 上 一 示 例 中 的 操
作 放 置 对 象 , 但 是 将 修 改 对 象 的 缩 放 比 例 :
PDF_fit_image(p, image, 80, 100, "scale 0.5");
此 代 码 片 段 将 对 象 的 左 下 角 放 置 在 用 户 坐 标 系 统 的 点 (80, 100) 上 。 另 外 , 按 照 缩 放 因 子
0.5, 沿 x 和 y 方 向 缩 小 对 象 , 使 该 对 象 以 其 原 始 尺 寸 的 50% 出 现 。
带 方 向 的 放 置 在 下 一 个 代 码 片 段 中 , 我 们 将 使 对 象 朝 西 放 置 ( 请 参 见 图 5.3):
PDF_fit_image(p, image, 80, 100, "scale 0.5 orientate west");
此 代 码 片 段 将 对 象 向 西 放 置 ( 逆 时 针 方 向 90 度 ), 然 后 将 对 象 的 左 下 角 ( 在 应 用 orientate
选 项 后 ) 转 换 到 参 考 点 (x, y)。 该 对 象 将 自 我 旋 转 。
带 旋 转 的 放 置 旋 转 对 象 ( 请 参 见 图 5.4) 的 方 式 与 定 向 类 似 。 不 过 , 旋 转 对 象 不 仅 影 响 放
置 的 对 象 , 而 且 还 会 影 响 整 个 坐 标 系 统 。 在 放 置 对 象 之 前 , 坐 标 系 统 将 在 参 考 点 (x, y) 沿 逆
时 针 方 向 旋 转 90 度 。 旋 转 的 对 象 的 右 下 角 ( 也 就 是 未 旋 转 的 对 象 的 左 下 角 ) 将 最 终 落 在 在
参 考 点 上 。 实 现 此 操 作 的 函 数 调 用 如 下 所 示 :
PDF_fit_image(p, image, 80, 100, "scale 0.5 rotate 90");
图 5.1
简 单 放 置
图 5.2
带 缩 放 比 例 的 放 置
图 5.3
带 方 向 的 放 置
图 5.4
带 旋 转 的 放 置
124 第 5 章 : 导 入 和 放 置 对 象

图 5.5
orientate 选 项
图 5.6
rotate 选 项
在 这 种 情 况 下 , 因 为 没 有 转 换 , 所 以 对 象 将 局 部 移 出 页 面 。
方 向 与 旋 转 的 比 较 方 向 和 旋 转 是 非 常 类 似 的 两 个 概 念 , 但 是 二 者 之 间 还 是 有 差 异 , 用 户
应 知 道 这 些 差 异 。 图 5.5 和 图 5.6 演 示 了 orientate 和 rotate 选 项 之 间 的 主 要 差 异 :
> orientate 选 项 在 参 考 点 (x, y) 旋 转 对 象 , 随 后 转 换 对 象 。 此 选 项 支 持 方 向 关 键 字 为 north、
east、 west 和 south。
> rotate 选 项 在 参 考 点 (x, y) 上 旋 转 对 象 , 但 不 作 任 何 转 换 。 此 选 项 支 持 任 意 旋 转 角 度 。 必
须 以 度 为 单 位 用 数 字 指 定 这 些 角 度 ( 整 圆 为 360 度 )。
5.3.2 调 整 页 面 尺 寸
在 下 一 个 示 例 中 ( 请 参 见 图 5.7), 我 们 将 页 面 的 尺 寸 自 动 调 整 到 对 象 的 尺 寸 。 例 如 , 这 对
存 档 PDF 格 式 的 图 像 很 有 用 。 参 考 点 (x, y) 可 以 用 于 指 定 页 面 的 尺 寸 是 正 好 等 于 对 象 的 尺
寸 , 还 是 比 对 象 的 尺 寸 大 一 点 或 小 一 点 。 当 扩 大 页 面 尺 寸 时 ( 请 参 见 图 5.7), 会 在 图 像 周
围 保 留 边 框 ; 当 页 面 尺 寸 小 于 图 像 尺 寸 时 , 将 剪 切 图 像 的 某 些 部 分 。 让 我 们 从 页 面 尺 寸 与 对
象 的 尺 寸 完 全 匹 配 开 始 :
PDF_fit_image(p, image, 0, 0, "adjustpage");
下 一 个 代 码 片 段 使 页 面 尺 寸 在 x 和 y 方 向 上 比 对 象 尺 寸 大 40 个 单 位 , 并 在 对 象 周 围 产 生 边 框 :
PDF_fit_image(p, image, 40, 40, "adjustpage");
图 5.7
调 整 页 面 尺 寸 。 从 左 向 右 :
完 全 相 同 、 扩 大 、 缩 小
5.3 放 置 图 像 和 导 入 的 PDF 页 125

下 一 个 代 码 片 段 使 页 面 尺 寸 在 x 和 y 方 向 上 比 对 象 尺 寸 小 40 个 单 位 。 将 在 页 边 框 处 剪 裁 对
象 , 对 象 内 的 一 些 区 域 ( 宽 度 为 40 个 单 位 ) 将 不 可 见 :
PDF_fit_image(p, image, -40, -40, "adjustpage");
除 了 按 照 x 坐 标 和 y 坐 标 的 方 法 放 置 之 外 ( 通 常 情 况 下 , 此 方 法 从 页 边 缘 或 坐 标 轴 指 定 对
象 的 距 离 ), 您 还 可 以 指 定 一 个 目 标 框 。 此 目 标 框 是 一 个 矩 形 区 域 , 放 置 在 此 区 域 中 的 对 象
将 遵 从 各 种 格 式 规 则 。 使 用 boxsize、 fitmethod 和 position 选 项 可 控 制 以 上 操 作 。
使 对 象 适 合 框 首 先 , 我 们 在 页 面 的 右 上 区 域 放 置 一 个 公 司 徽 标 ( 请 参 见 图 5.8)。 徽 标 将
在 其 中 出 现 的 目 标 矩 形 的 尺 寸 已 固 定 。 不 过 , 我 们 不 知 道 如 何 缩 放 徽 标 以 使 其 适 合 此 框 , 而
又 要 避 免 任 何 扭 曲 ( 禁 止 更 改 宽 度 和 高 度 的 比 例 )。 以 下 语 句 可 以 执 行 这 项 工 作 :
PDF_fit_image(p, image, 350, 750, "boxsize {200 100} position 0 fitmethod meet");
此 代 码 片 段 将 宽 为 200 个 单 位 、 高 为 100 个 单 位 (boxsize {200 100}) 的 框 的 左 下 角 放 置 在 点
(350, 750) 上 。 对 象 的 左 下 角 将 放 置 在 框 的 左 下 角 (position 0) 上 。 此 对 象 将 进 行 缩 放 以 使 其
高 度 和 / 或 宽 度 完 全 适 合 该 框 (fitmethod meet), 但 没 有 任 何 扭 曲 。
此 概 念 提 供 了 形 形 色 色 的 变 体 。 例 如 ,position 选 项 可 以 用 于 指 定 对 象 中 用 作 参 考 点 的 点
( 指 定 为 宽 度 和 高 度 的 百 分 比 )。position 选 项 还 将 指 定 目 标 框 内 的 参 考 点 。 若 宽 度 和 高 度 位
置 的 百 分 比 一 致 , 则 指 定 其 中 一 个 值 就 可 以 了 。 例 如 position 50 可 以 用 于 选 定 对 象 的 中 点
和 框 的 中 点 作 为 参 考 点 以 便 放 置 对 象 。
将 对 象 放 入 框 中 时 进 行 剪 裁 使 用 其 他 风 格 的 fitmethod 选 项 , 我 们 可 以 剪 裁 对 象 以 使 其
完 全 适 合 目 标 框 ( 请 参 见 图 5.9)。 在 这 种 情 况 下 , 将 不 会 缩 放 对 象 :
PDF_fit_image(p, image, 50, 80, "boxsize {100 400} position 50 fitmethod clip");
此 代 码 片 段 在 坐 标 (50, 80) 处 放 置 一 个 宽 度 为 100、 长 度 为 400 (boxsize {100 400}) 的 框 。 将
按 照 对 象 的 原 始 尺 寸 将 其 放 置 在 框 中 间 (position 50), 若 对 象 尺 寸 超 过 框 (fitmethod clip),
则 将 剪 裁 此 对 象 。
按 照 页 面 大 小 调 整 对 象 通 过 选 择 页 面 作 为 用 来 放 置 对 象 的 目 标 框 , 可 以 轻 松 将 对 象 调 整
到 给 定 页 面 的 尺 寸 。 以 下 语 句 使 用 尺 寸 为 595 x 842 的 A4 大 小 的 页 :
PDF_fit_image(p, image, 0, 0, "boxsize {595 842} position 0 fitmethod slice");
图 5.8
将 对 象 放 入 框 中
图 5.9
将 对 象 放 入 框 中 时
进 行 剪 裁
126 第 5 章 : 导 入 和 放 置 对 象

图 5.10
使 徽 标 适 合 页 面
在 此 代 码 片 段 中 , 在 页 面 的 左 下 角 放 置 一 个 框 。 该 框 的 尺 寸 等 于 A4 页 的 尺 寸 。 将 对 象 放 置
在 该 框 的 左 下 角 , 并 按 比 例 缩 放 此 对 象 直 到 它 完 全 覆 盖 框 以 及 页 面 。 若 对 象 超 过 该 框 , 则 此
对 象 将 被 剪 切 。 请 注 意 ,fitmethod slice 导 致 对 象 被 缩 放 ( 与 此 相 反 ,fitmethod clip 不 缩 放
对 象 )。 当 然 , 此 示 例 中 的 position 和 fitmethod 选 项 也 可 以 变 化 。
使 徽 标 适 合 页 面 我 们 如 何 实 现 图 5.10 中 旋 转 的 公 司 徽 标 ? 从 左 下 角 开 始 , 将 其 逆 时 针 方
向 旋 转 90 度 , 并 覆 盖 页 面 的 整 个 高 度 :
PDF_fit_image(p, image, 0, 0, "boxsize {595 842} orientate west fitmethod meet");
参 考 点 为 (0, 0), 方 向 指 定 为 orientate west。 为 了 确 保 徽 标 覆 盖 整 个 页 面 高 度 , 我 们 选 择 框
的 高 度 等 于 页 面 的 高 度 (842), 并 为 框 的 宽 度 选 择 一 个 足 够 大 的 值 (595)。 徽 标 的 比 例 不 应 更
改 , 因 此 我 们 选 择 fitmethod meet。
5.3 放 置 图 像 和 导 入 的 PDF 页 127

128 第 5 章 : 导 入 和 放 置 对 象

6 数 据 变 量 和 块
PDFlib 的 模 板 式 PDF 工 作 流 支 持 数 据 变 量 的 处 理 。 通 过 使 用 块 的 概 念 , 可 以 在 导 入 的 页 中
置 入 可 变 数 量 的 单 行 或 多 行 文 本 、 图 像 或 PDF 图 形 , 这 些 项 都 可 以 从 外 部 源 获 得 。 以 这 种
方 式 可 以 非 常 容 易 地 完 成 需 要 生 成 客 户 化 PDF 文 档 的 应 用 程 序 , 如 :
> 邮 件 合 成
> 灵 活 的 直 投 邮 件
> 事 务 和 报 表 处 理
> 名 片 个 性 化
注 : 块 处 理 需 要 PDFlib Personalization Server (PPS)。 尽 管 在 所 有 商 业 PDFlib 包 中 都 包 含 PPS, 但
是 您 必 须 购 买 PPS 的 许 可 证 密 钥 ; 仅 有 PDFlib 或 PDFlib+PDI 许 可 证 密 钥 是 不 够 的 。 在 PDF
模 板 中 交 互 建 立 块 需 要 Adobe Acrobat 的 PDFlib 块 增 效 工 具 。
6.1 安 装 PDFlib 块 增 效 工 具
PDFlib 的 块 增 效 工 具 和 它 的 姐 妹 , PDF 表 单 域 转 换 增 效 工 具 均 支 持 Windows 和 Mac 平 台
上 的 Acrobat 5, Acrobat 6/7 标 准 版 及 Acrobat 6/7 专 业 版 。 但 它 们 不 支 持 Acrobat 6/7
Elements 及 任 何 版 本 的 Acrobat Reader/Adobe Reader。
注 : 增 效 工 具 含 有 多 种 语 言 版 本 的 用 户 界 面 , 并 将 自 动 使 用 与 在 Acrobat 应 用 程 序 中 使 用 的 界 面
语 言 一 样 的 界 面 语 言 ( 如 果 可 能 )。 若 增 效 工 具 不 支 持 本 地 Acrobat 语 言 , 则 将 使 用 英 语 用
户 界 面 。
在 Windows 平 台 上 为 Acrobat 5/6/7 安 装 PDFlib 块 增 效 工 具 若 要 在 Acrobat 5、 6 或 7
中 安 装 PDFlib 块 增 效 工 具 和 PDF 表 单 域 转 换 增 效 工 具 , 则 必 须 将 增 效 工 具 文 件 拷 贝 到
Acrobat 增 效 工 具 文 件 夹 的 子 目 录 中 。 虽 然 增 效 工 具 安 装 程 序 将 自 动 完 成 此 操 作 , 但 是 也 可
以 手 动 完 成 。 增 效 工 具 文 件 称 作 Block.api 和 AcroFormConversion.api。 此 增 效 工 具 文 件 夹 的
典 型 位 置 如 下 所 示 :
C:\Program Files\Adobe\Acrobat 7.0\Acrobat\plug_ins\PDFlib Block Plugin
在 Mac 平 台 上 , 为 Acrobat 6/7 安 装 PDFlib 块 增 效 工 具 使 用 Acrobat 6/7, 增 效 工 具 文
件 夹 在 Finder 中 将 不 可 见 。 不 是 将 增 效 工 具 文 件 拖 到 增 效 工 具 文 件 夹 中 , 而 是 使 用 以 下 步
骤 ( 确 保 Acrobat 没 有 运 行 ):
> 双 击 磁 盘 映 像 文 件 , 提 取 增 效 工 具 文 件 并 存 入 一 个 文 件 夹 。
> 在 Finder 中 找 到 Acrobat 应 用 程 序 图 标 。 通 常 , 该 图 标 位 于 一 个 具 有 以 下 名 称 的 文 件 夹 中 :
/Applications/Adobe Acrobat 7.0 Professional
> 单 击 Acrobat 应 用 程 序 图 标 , 并 选 择 “ 文 件 ” -> “ 获 取 信 息 ”。
> 在 弹 出 的 窗 口 中 单 击 “ 增 效 工 具 ” 旁 边 的 三 角 形 。
> 单 击 Add..., 然 后 在 第 一 步 所 建 立 的 文 件 夹 中 选 择 PDFlib Block Plugin 文 件 夹 ( 如 果 是
Acrobat 7) 或 PDFlib Block Plugin Acro 5-6 文 件 夹 ( 如 果 是 Acrobat 6)。 注 意 , 在 安 装
后 , 相 应 的 文 件 夹 不 会 马 上 显 示 在 增 效 工 具 列 表 里 , 只 有 在 重 新 打 开 窗 口 时 , 它 才 会 显
示 在 列 表 中 。
在 Mac 平 台 上 为 Acrobat 5 安 装 PDFlib 块 增 效 工 具 若 要 安 装 Acrobat 5 的 增 效 工 具 , 先
双 击 磁 盘 映 像 文 件 。 将 PDFlib Block Plugin Acro 5-6 文 件 夹 拉 入 到 Acrobat 5 增 效 工 具 文 件 夹
中 。 典 型 的 增 效 工 具 文 件 夹 名 称 如 下 所 示 :
6.1 安 装 PDFlib 块 增 效 工 具 129

Applications/Adobe Acrobat 5.0/Plug-Ins
故 障 处 理 若 PDFlib 块 增 效 工 具 看 起 来 无 法 工 作 , 则 请 确 保 在 编 辑 、 首 选 项 、 [ 常 规 ...]、
启 动 (Acrobat 6/7) 或 选 项 (Acrobat 5) 中 , 框 “ 仅 使 用 认 证 的 增 效 工 具 ” 未 选 中 。 若 Acrobat
正 在 认 证 模 式 下 运 行 , 则 将 不 会 加 载 增 效 工 具 。
6.2 PDFlib 块 概 念 的 概 述
6.2.1 文 档 设 计 和 程 序 代 码 的 完 整 分 离
使 用 PDFlib 数 据 块 , 可 以 很 方 便 地 在 导 入 页 上 放 置 可 变 文 本 、 图 像 或 图 形 。 相 对 于 普 通 的
PDF 页 , 内 部 包 含 数 据 块 的 页 携 带 了 稍 后 在 服 务 器 端 将 要 处 理 的 信 息 。PDFlib 块 概 念 将 下 列
的 任 务 非 常 清 晰 的 分 开 :
> 设 计 师 可 以 创 建 页 布 局 , 并 指 定 可 变 文 本 和 图 像 元 素 的 位 置 和 一 些 相 关 的 属 性 如 字 体 大
小 、 颜 色 或 图 像 的 比 例 等 。 将 布 局 创 建 为 PDF 文 档 后 , 设 计 器 使 用 Acrobat 的 PDFlib 块
增 效 工 具 以 指 定 可 变 数 据 块 及 其 相 关 属 性 。
> 程 序 员 编 写 代 码 以 连 接 包 含 在 PDFlib 块 中 的 信 息 , 该 PDFlib 块 位 于 带 有 动 态 信 息 ( 例
如 , 数 据 库 域 ) 的 导 入 PDF 页 上 。 程 序 员 不 需 要 知 道 有 关 块 的 任 何 详 细 信 息 ( 它 是 否 包
含 名 称 或 ZIP 代 码 、 页 上 的 准 确 位 置 、 它 的 格 式 等 等 ), 因 此 该 块 独 立 于 任 何 布 局 更 改 。
PDFlib 将 维 护 基 于 文 件 中 找 到 的 块 属 性 的 与 所 有 块 相 关 的 详 细 信 息 。
换 言 之 , 程 序 员 编 写 的 代 码 是 “ 数 据 遮 蔽 ”– 它 较 为 普 通 并 不 依 赖 这 些 块 。 例 如 , 设 计 师 可
能 决 定 在 邮 件 中 使 用 收 件 人 的 名 , 而 不 使 用 姓 。 普 通 块 处 理 代 码 不 需 要 改 变 , 一 旦 设 计 器 使
用 Acrobat 增 效 工 具 更 改 块 属 性 以 使 用 名 替 换 姓 , 则 将 生 成 正 确 的 输 出 。
示 例 : 在 模 板 中 加 入 文 本 变 量 用 户 经 常 需 要 将 动 态 文 本 加 入 到 PDF 模 板 。 以 下 代 码 片 断
将 打 开 输 入 PDF 文 件 的 其 中 一 页 ( 模 板 ) , 将 其 放 置 在 输 出 页 面 上 , 并 将 一 些 文 本 变 量 填
入 名 为 firstname 的 文 本 块 中 :
doc = PDF_open_pdi(p, filename, "", 0);
if (doc == -1) {
printf("Couldn't open PDF template '%s'\n", filename);
return (1);
}
page = PDF_open_pdi_page(p, doc, pageno, "");
if (page == -1) {
printf("Couldn't open page %d of PDF template '%s'\n", pageno, filename);
return (2);
}
PDF_begin_page_ext(p, width, height, "");
PDF_fit_pdi_page(p, page, 0.0, 0.0, "");
PDF_fill_textblock(p, page, "firstname", "Serge", 0, "encoding winansi");
PDF_close_pdi_page(p, page);
PDF_end_page_ext(p, "");
130 第 6 章 : 数 据 变 量 和 块

6.2.2 块 属 性
块 的 行 为 可 以 通 过 块 属 性 来 控 制 。 使 用 Acrobat 里 的 PDFlib 块 增 效 工 具 可 以 将 属 性 指 定
给 块 。
标 准 块 属 性 PDFlib 块 在 页 上 定 义 为 矩 形 , 并 将 对 这 些 块 指 定 名 称 、 类 型 和 稍 后 将 在 服 务
器 端 处 理 的 一 组 公 开 属 性 。 名 称 是 用 来 标 识 块 的 任 意 字 符 串 , 例 如 firstname、 lastname 或
zipcode。 PDFlib 支 持 以 下 几 种 类 型 的 块 :
> Text ( 文 本 ) 类 型 意 味 着 块 将 保 留 一 行 或 多 行 原 文 数 据 。 将 使 用 Textflow 功 能 格 式 化 多
行 文 本 。 请 注 意 , 不 能 链 接 文 本 块 以 便 文 本 将 从 一 个 块 流 到 另 一 个 块 。
> Image ( 图 像 ) 类 型 意 味 着 块 将 保 留 一 个 光 栅 图 像 。 这 相 当 于 在 DTP 应 用 程 序 中 导 入 一
个 TIFF 或 JPEG 文 件 。
> PDF 类 型 意 味 着 块 将 保 留 从 其 他 PDF 文 档 中 的 页 上 导 入 的 任 意 PDF 图 形 。 这 相 当 于 在
DTP 应 用 程 序 中 导 入 一 个 EPS 图 形 。
不 同 的 类 型 块 会 带 有 不 同 的 标 准 属 性 。 例 如 , 文 本 块 可 能 指 定 文 本 的 字 体 和 尺 寸 , 图 像 块 或
PDF 块 可 能 指 定 缩 放 因 子 或 旋 转 。 对 于 每 种 块 类 型 ,PDFlib API 提 供 用 于 处 理 该 块 的 专 用 函
数 。 这 些 函 数 按 照 块 的 名 称 搜 索 该 块 的 导 入 的 PDF 页 , 分 析 页 的 属 性 并 根 据 相 应 的 块 属 性
将 一 些 客 户 端 提 供 的 数 据 ( 文 本 、 光 栅 图 像 或 PDF 页 ) 放 置 在 新 页 上 。
自 定 义 块 属 性 标 准 块 属 性 可 以 快 速 执 行 可 变 数 据 处 理 应 用 程 序 , 但 是 限 于 属 性 集 , 此 属 性
集 在 内 部 为 PDFlib 所 知 并 可 以 自 动 被 处 理 。 为 了 提 供 更 多 的 灵 活 性 , 设 计 器 也 可 以 对 块 指 定
自 定 义 属 性 。 这 些 属 性 可 以 用 于 扩 展 块 概 念 以 符 合 大 多 数 请 求 的 可 变 数 据 处 理 程 序 的 要 求 。
不 存 在 自 定 义 属 性 的 规 则 , 因 为 PDFlib 除 了 使 自 定 义 属 性 对 客 户 端 可 用 之 外 , 将 不 会 以
任 何 方 式 处 理 自 定 义 属 性 。 客 户 端 代 码 可 以 检 查 自 定 义 属 性 并 用 它 认 为 是 合 适 的 任 何 方 法
使 用 该 自 定 义 属 性 。 基 于 块 的 一 些 自 定 义 属 性 , 代 码 可 以 作 出 布 局 相 关 的 或 数 据 收 集 的 决
定 。 例 如 , 科 学 应 用 程 序 的 自 定 义 属 性 可 以 指 定 用 于 数 字 输 出 的 数 字 的 数 量 , 或 者 数 据 域 名
称 可 以 定 义 为 自 定 义 块 属 性 以 便 检 索 此 块 相 应 的 数 据 。
块 属 性 重 写 在 特 定 的 情 况 下 , 程 序 员 只 需 要 使 用 块 定 义 中 提 供 的 部 分 属 性 , 而 使 用 自 定 义
值 重 写 其 他 属 性 。 在 各 种 情 况 下 , 这 一 点 很 有 用 :
> 图 像 或 PDF 页 的 缩 放 因 子 将 被 计 算 , 而 不 是 从 块 定 义 中 得 到 。
> 例 如 , 当 用 可 变 数 量 的 数 据 项 生 成 发 票 时 , 通 过 编 程 方 式 更 改 块 坐 标 。
> 应 提 供 单 独 的 专 色 名 称 以 满 足 打 印 机 应 用 程 序 中 的 各 个 用 户 的 要 求 。
通 过 提 供 属 性 名 称 和 所 有 PDF_fill_*block( ) 函 数 的 选 项 列 表 中 的 相 应 的 值 完 成 属 性 重 写 , 如
下 所 示 :
PDF_fill_textblock(p, page, "firstname", "Serge", 0, "fontsize 12");
这 将 用 提 供 的 值 12 重 写 块 的 内 部 fontsize 属 性 。 几 乎 所 有 常 规 属 性 的 名 称 都 可 以 用 作 选 项 ,
以 及 那 些 指 定 给 特 殊 块 类 型 的 选 项 。 例 如 , 仅 PDF_fill_textblock( ) 允 许 underline 选 项 , 而
PDF_fill_imageblock( ) 和 PDF_fill_pdfblock( ) 都 允 许 scale 选 项 , 因 为 scale 是 图 像 和 PDF 块
的 有 效 属 性 。
属 性 重 写 仅 可 以 应 用 到 相 应 的 函 数 调 用 ; 它 们 将 不 会 存 储 在 块 定 义 中 。
坐 标 系 统 块 坐 标 是 以 PDF 的 缺 省 坐 标 系 统 为 依 据 。 当 带 有 块 的 页 放 置 在 输 出 页 上 时 , 几
个 与 位 置 和 比 例 相 关 的 选 项 将 提 供 给 PDF_fit_pdi_page( )。 处 理 块 的 时 候 , 这 些 参 数 将 被 用
到 。 这 使 得 将 同 一 模 版 在 同 一 页 重 复 出 现 多 次 成 为 可 能 。 例 如 , 一 个 名 片 模 版 可 以 在 同 一 张
纸 上 重 复 四 次 , 这 样 一 版 可 印 4 张 名 片 。 块 函 数 会 处 理 坐 标 系 统 的 变 换 , 并 将 块 内 容 填 到 正
6.2 PDFlib 块 概 念 的 概 述 131

确 的 位 置 。 用 户 需 做 的 是 先 将 输 入 模 版 所 有 块 填 写 后 生 成 页 。 然 后 再 将 该 页 重 复 几 次 写 入 输
出 页 不 同 的 位 置 , 并 接 着 做 一 系 列 的 块 处 理 , 依 次 类 推 。
注 : 块 增 效 工 具 所 显 示 的 坐 标 值 不 同 于 保 存 在 PDF 文 档 内 的 。 这 是 因 为 增 效 工 具 采 用 的 是 坐 标
原 点 位 于 页 面 左 上 角 的 Acrobat 坐 标 系 ; 而 真 正 存 于 PDF 文 档 内 的 坐 标 值 ( 存 于 块 的 坐 标
值 ) 是 采 用 坐 标 原 点 位 于 页 面 左 下 角 的 PDF 坐 标 系 统 。
6.2.3 为 什 么 不 使 用 PDF 表 单 域 ?
有 经 验 的 Acrobat 用 户 会 问 , 为 什 么 不 使 用 已 规 范 化 的 PDF 表 单 域 系 统 而 使 用 新 的 PDFlib
块 概 念 。 这 两 者 的 本 质 区 别 在 于 , PDF 表 单 域 是 为 交 互 式 填 写 而 设 计 的 , 而 PDFlib 块 是 为
自 动 化 填 写 而 设 计 的 。 对 于 既 需 要 交 互 式 填 写 又 需 要 自 动 化 填 写 的 应 用 程 序 , 可 以 使 用 将 表
单 域 转 换 为 块 的 功 能 ( 见 第 136 页 上 的 第 6.3.4 节 “ 将 PDF 表 单 域 转 换 为 PDFlib 块 ”)。
虽 然 这 两 者 在 功 能 上 有 许 多 重 合 , PDFlib 块 在 一 些 方 面 优 于 PDF 表 单 域 。 详 见 表 6.1 。
表 6.1 PDF 表 单 域 和 PDFlib 块 的 对 比
功 能 PDF 表 单 域 PDFlib 块
设 计 目 标 便 于 交 互 式 使 用 便 于 自 动 填 充
印 刷 上 的 功 能
( 除 字 体 和 字 体 大 小 的 选 择 )
– 字 距 调 整 、 单 词 和 字 符 间 的 空 格 调 整 、 上 下 划 线
及 删 除 线
字 体 控 制 字 体 嵌 入 字 体 嵌 入 , 子 集 和 编 码
文 本 格 式 的 控 制 支 持 左 、 中 、
右 对 齐 方 式
向 左 对 齐 、 居 中 对 齐 、 向 右 对 齐 、 调 整 ; 多 种 格
式 算 法 和 控 制 ; 可 内 嵌 选 项 控 制 文 本 外 观
更 改 文 本 内 的 字 体 或 其 他 文 本 属 性 – 是
合 并 的 结 果 是 PDF 页 面 说 明 的 整 体 – 是
部 分
用 户 可 以 编 辑 合 并 的 字 段 内 容 是 否
可 扩 展 的 属 性 集 – 是 ( 自 定 义 块 属 性 )
使 用 图 像 文 件 以 填 充 – BMP、CCITT、GIF、PNG、JPEG、JPEG2000、TIFF
颜 色 支 持 RGB 灰 度 、 RGB、 CMYK、 专 色 、 Lab
PDF/X 兼 容 – 是 ( 带 块 的 模 板 和 合 并 的 结 果 )
填 充 时 , 可 以 重 写 图 形 和 文 本 属 性 – 是
6.3 建 立 PDFlib 块
6.3.1 利 用 PDFlib 块 增 效 工 具 交 互 式 建 立 块
激 活 PDFlib 块 工 具 用 于 建 立 PDFlib 块 的 PDFlib 块 增 效 工 具 类 似 于 Acrobat 中 的 表 单 工
具 。 当 块 工 具 被 激 活 , 所 以 在 页 上 的 块 将 被 显 示 出 来 。 当 其 他 Acrobat 工 具 被 选 择 后 , 块 依
旧 存 在 但 会 被 隐 藏 。 用 户 可 以 用 以 下 几 种 方 式 激 活 块 工 具 :
> 在 Acrobat 的 “ 高 级 编 辑 ” 工 具 条 中 点 击 块 图 标 ( 在 Acrobat 5 中 :“ 编 辑 ” 工
具 栏 );
> 通 过 菜 单 项 “PDFlib 块 ” -> “PDFlib 块 工 具 ”;
> 使 用 快 捷 键 P ; 但 在 使 用 之 前 要 确 信 在 “ 编 辑 ”->“ 首 选 项 ”->“[ 常 规 ...]”->“ 常 规 ”
窗 口 中 选 择 了 “ 使 用 加 速 键 访 问 工 具 ”, 默 认 值 是 不 选 (Acrobat 5 不 需 此 步 )
建 立 和 修 改 块 当 您 激 活 了 块 工 具 后 , 就 可 以 移 动 十 字 光 标 以 在 页 面 上 要 求 的 位 置 建 立 所
需 尺 寸 的 块 。 所 有 块 都 是 矩 形 的 , 它 们 的 四 边 总 是 与 页 边 缘 平 行 。 当 用 户 建 立 了 新 块 后 , 将
132 第 6 章 : 数 据 变 量 和 块

出 现 块 属 性 对 话 框 , 您 可 以 在 对 话 框 中 编 辑 各 种 块 属 性 ( 见 第 135 页 上 的 第 6.3.2 节 “ 编 辑
块 属 性 ”)。 块 工 具 会 自 动 建 立 一 个 块 名 称 , 该 块 名 称 可 以 在 属 性 对 话 框 中 更 改 。 页 块 名 称
在 同 一 页 中 必 须 是 唯 一 的 。 您 可 以 将 顶 部 区 域 中 的 块 类 型 更 改 为 某 一 文 本 、 图 像 或 PDF。 常
规 和 自 定 义 标 签 将 总 是 可 用 , 而 根 据 选 择 的 块 类 型 不 同 , 一 次 只 能 激 活 一 个 文 本 、 图 像 和
PDF 标 签 。Textflow 标 签 仅 在 textflow 属 性 为 true 的 情 况 下 , 用 作 类 型 文 本 块 。 另 一 个 标 记
为 Tabs ( 跳 格 键 位 置 ) 的 标 签 仅 在 Textflow 标 签 中 的 hortabmethod 属 性 设 置 为 ruler 的 情
况 下 可 用 。
注 : 当 用 户 增 加 块 或 对 PDF 中 的 现 有 块 作 出 更 改 后 , 使 用 Acrobat 的 “ 另 存 为 ...” 指 令 ( 相 对
于 “ 保 存 ” 指 令 ) 可 取 得 较 小 的 文 件 大 小 。
注 : 当 使 用 Acrobat 的 Enfocus PitStop 增 效 工 具 去 编 辑 带 有 PDFlib 块 的 文 档 时 , 您 可 能 会 看 见 此
消 息 : 此 文 档 包 含 PDFlib 的 PieceInfo。 单 击 “ 确 定 ” 以 继 续 编 辑 或 单 击 “ 取 消 ” 以 中 止 编
辑 。 可 以 忽 略 此 消 息 ; 在 这 种 情 况 下 , 安 全 操 作 是 单 击 “ 确 定 ”。
选 择 块 块 拷 贝 , 块 移 动 等 几 个 块 操 作 , 都 需 在 选 择 块 后 方 可 进 行 。 用 户 可 以 通 过 块 工 具 去
选 择 一 个 或 多 个 块 , 如 下 所 示 :
> 若 选 择 一 个 块 , 只 需 用 鼠 标 单 击 相 应 块 。
> 在 按 下 Shift 键 的 同 时 单 击 其 他 块 以 扩 大 选 择 。
> 若 选 择 当 前 页 的 所 与 块 , 按 Ctrl-A ( 在 Windows 平 台 上 ) 或 Cmd-A ( 在 Mac 平 台 上 )
或 编 辑 , 全 部 选 定 。
上 下 文 菜 单 若 已 选 定 一 个 或 多 个 块 , 则 您 可 以 打 开 上 下 文 菜 单 以 快 速 访 问 块 相 关 的 函 数
( 在 PDFlib 块 菜 单 中 同 样 可 用 ) 如 要 打 开 上 下 文 菜 单 , 在 Windows 上 , 在 选 定 的 块 上 单 击
鼠 标 右 键 , 或 者 在 Mac 上 , 按 住 Ctrl 键 并 单 击 块 。
例 如 , 想 删 除 一 个 块 , 用 块 工 具 选 择 此 块 , 然 后 按 Delete 键 , 或 在 上 下 文 菜 单 中 选 择
“ 编 辑 ” -> “ 删 除 ”。
微 调 块 大 小 和 位 置 使 用 块 工 具 , 您 可 以 将 一 个 或 多 个 选 定 的 块 移 动 到 不 同 的 位 置 。 在 移
动 块 时 按 住 Shift 键 , 可 以 保 持 块 将 沿 着 水 平 和 垂 直 方 向 的 移 动 。 这 对 于 块 准 确 对 齐 很 有 帮
助 。 当 指 针 位 于 块 的 转 角 处 时 将 变 为 箭 头 , 并 且 您 可 以 重 新 调 整 块 的 大 小 。 要 调 整 多 个 块 的
位 置 和 大 小 , 可 以 在 选 择 两 个 或 两 个 以 上 的 块 后 , 使 用 “PDFlib 块 ” 菜 单 或 上 下 文 菜 单 中 的
“ 对 齐 ” 、“ 居 中 ”“ 分 布 ” 或 “ 大 小 ” 命 令 进 行 调 整 。 单 个 或 多 个 块 的 位 置 也 可 以 用 箭 头
键 进 行 调 整 。
另 外 , 您 可 以 在 属 性 对 话 框 中 输 入 用 数 字 表 示 的 块 坐 标 。 坐 标 系 统 的 原 点 位 于 页 的 左 上
角 。 当 前 在 Acrobat 中 选 定 的 坐 标 将 按 照 单 位 显 示 。 更 改 显 示 单 位 的 过 程 , 如 下 所 示 :
> 在 Acrobat 6/7 中 , 转 到 “ 编 辑 ”->“ 首 选 项 ”->“[ 常 规 ...]”->“ 单 位 和 网 线 ”[ 或
“ 页 面 单 位 ”], 并 选 择 点 、 英 寸 、 毫 米 、 派 卡 、 厘 米 中 的 某 一 项 。 您 还 可 以 跳 至 “ 视 图 ”
-> “ 导 航 标 签 ” -> “ 信 息 ”, 并 从 “ 选 项 ” 菜 单 中 选 择 一 个 单 位 。
> 在 Acrobat 5 中 , 跳 至 “ 编 辑 ” -> “ 首 选 项 ” -> “ 常 规 ” -> “ 显 示 ” -> “ 页 面 单 位 ”,
并 选 择 点 、 英 寸 、 毫 米 中 的 某 一 项 。 您 还 可 以 跳 至 “ 窗 口 ” -> “ 信 息 ”, 并 从 “ 信 息 ”
菜 单 选 择 一 个 单 位 。
请 注 意 , 选 定 的 单 位 只 会 影 响 Rect 属 性 , 而 不 会 影 响 任 何 其 他 数 字 属 性 。
通 过 选 择 图 像 或 图 形 建 立 块 作 为 手 动 拖 动 块 矩 形 的 一 个 替 换 , 您 可 以 使 用 现 有 页 内 容 定
义 块 大 小 。 首 先 , 确 保 已 启 用 菜 单 项 “PDFlib 块 ” -> “ 单 击 对 象 以 定 义 块 ”。 现 在 您 可 以
使 用 块 工 具 单 击 页 上 的 图 像 以 建 立 图 像 大 小 的 块 。 您 也 可 以 单 击 其 他 图 形 对 象 , 块 工 具 将 试
图 选 择 周 围 的 图 形 ( 例 如 徽 标 )。 单 击 对 象 功 能 是 作 为 定 义 块 的 一 个 辅 助 功 能 。 若 您 想 重 写
6.3 建 立 PDFlib 块 133

图 6.1
编 辑 块 属 性 :“ 文 本 流 ” 窗 格
仅 在 textflow=true 时 可 见 ;
“ 选 项 卡 ” 窗 格 仅 在
hortabmethod=ruler 时 可 见
调 整 块 的 位 置 和 大 小 , 以 后 您 可 以 不 受 任 何 限 制 的 这 样 做 。 块 将 不 会 对 作 为 定 位 和 调 整 大 小
的 辅 助 工 具 使 用 的 图 像 或 图 形 对 象 锁 定 。
单 击 对 象 功 能 将 试 图 识 别 形 成 页 上 的 逻 辑 元 素 的 矢 量 图 形 和 图 像 。 当 单 击 一 些 页 面 内 容
时 , 将 选 定 此 页 面 内 容 的 边 框 ( 周 围 的 矩 形 ), 除 非 此 对 象 是 空 白 或 太 大 。 在 下 一 个 步 骤 中 ,
其 他 部 分 包 含 在 检 测 的 矩 形 框 中 的 对 象 将 被 添 加 导 选 定 的 区 域 , 等 等 。 最 终 区 域 将 用 作 生 成
的 块 矩 形 的 基 础 。 最 终 的 结 果 是 单 击 对 象 功 能 将 试 图 选 择 完 整 图 形 , 而 不 是 选 择 单 个 行 。
单 击 对 象 功 能 并 不 完 善 : 根 据 页 面 内 容 的 性 质 的 不 同 , 它 不 会 总 是 选 择 用 户 所 需 内 容 。
请 记 住 该 功 能 仅 可 作 为 用 于 快 速 建 立 块 矩 形 的 定 位 辅 助 工 具 。
自 动 检 测 字 体 属 性 PDFlib 块 增 效 工 具 可 以 分 析 在 块 所 在 的 位 置 出 现 的 以 下 字 体 , 并 能 够
自 动 填 写 块 的 相 应 属 性 :
fontname, fontsize, fillcolor, charspacing, horizscaling, wordspacing,
textrendering, textrise
因 为 在 背 景 应 被 忽 略 时 , 对 字 体 属 性 进 行 自 动 检 测 会 引 起 不 希 望 发 生 的 行 为 , 使 用 “PDFlib
块 ” -> “ 检 测 基 本 字 体 和 颜 色 ” 可 以 启 用 或 停 用 此 自 动 检 测 。 默 认 情 况 下 , 此 功 能 被 关 闭 。
锁 定 块 块 可 以 被 锁 定 , 从 而 可 以 保 护 它 们 不 会 被 意 外 的 移 动 、 改 变 大 小 或 删 除 。 当 块 工 具
活 动 时 , 选 择 块 并 从 块 的 上 下 文 菜 单 中 选 择 锁 定 。 当 块 被 锁 定 后 , 此 块 不 能 被 移 动 、 改 变 大
小 或 删 除 ; 也 不 可 以 显 示 块 属 性 对 话 框 。
在 块 中 使 用 PDF/X 与 PDF 表 单 域 不 同 ,PDFlib 块 支 持 PDF/X 印 前 标 准 。 带 有 块 的 输 入 文
档 和 生 成 的 输 出 PDF 都 可 以 符 合 PDF/X 印 前 标 准 。 然 而 , 在 准 备 符 合 PDF/X 印 前 标 准
textflow 的 块 文 件 时 , 用 户 可 能 会 遇 到 以 下 几 个 问 题 :
> PDF/X-1:2001、 PDF/X-1a:2001 和 PDF/X-3:2002 都 基 于 Acrobat 4/PDF 1.3, 并 且 不 支 持
Acrobat 5 文 件 ;
> PDFlib 块 增 效 工 具 要 求 Acrobat 5 或 更 高 版 本 。
为 解 决 这 一 问 题 , 用 户 可 以 将 生 成 的 带 块 信 息 的 PDF 文 件 通 过 Acrobat 转 换 成 所 需 的 PDF
版 本 。 详 情 见 第 152 页 上 的 “ 更 改 文 档 的 PDF 版 本 ”。
134 第 6 章 : 数 据 变 量 和 块

6.3.2 编 辑 块 属 性
当 您 建 立 新 块 、 双 击 现 有 块 , 或 从 块 的 上 下 文 菜 单 选 择 “ 属 性 ” 时 , 属 性 对 话 框 将 弹 出 , 您
可 以 在 其 中 编 辑 与 选 定 的 块 相 关 的 所 有 设 置 ( 请 参 见 图 6.1)。 详 情 见 第 138 页 上 的 第 6.4 节
“ 用 于 自 动 化 处 理 的 标 准 属 性 ”, 块 属 性 大 致 分 以 下 几 类 :
> 块 名 称 、 块 类 型 、 说 明 和 常 规 标 签 里 的 所 有 属 性 将 适 用 于 所 有 块 类 型 。
> Text、 Image 和 PDF 标 签 中 的 属 性 只 分 别 适 用 于 对 应 的 块 类 型 。 仅 与 块 的 类 型 相 应 的 标
签 将 是 活 动 状 态 , 而 其 他 标 签 是 非 活 动 状 态 。
> 若 Text ( 文 本 ) 类 型 块 的 textflow 属 性 被 设 置 为 true, 另 一 个 名 为 Textflow 的 带 有
textflow 相 关 的 设 置 的 标 签 将 出 现 。
> 若 Text ( 文 本 ) 类 型 块 的 textflow 属 性 被 设 置 为 true, 同 时 Textflow 标 签 中 的
hortabmethod 属 性 设 置 为 ruler, 仍 将 出 现 另 一 个 名 为 Tabs 的 窗 格 , 您 可 以 在 此 窗 格
中 编 辑 跳 格 键 设 置 。
> “ 自 定 义 ” 选 项 卡 中 的 属 性 可 以 由 用 户 定 义 , 并 应 用 于 任 何 块 类 型 。
若 要 更 改 一 个 属 性 的 值 , 请 在 属 性 的 输 入 区 域 ( 例 如 linewidth) 中 输 入 需 要 的 数 字 或 字 符
串 , 从 下 拉 列 表 中 选 择 一 个 值 ( 例 如 fontname、fitmethod) 或 通 过 单 击 对 话 框 右 侧 的 “...”
按 钮 选 择 一 个 颜 色 值 或 文 件 名 称 ( 例 如 backgroundcolor)。 对 于 fontname 属 性 , 您 可 以 从
系 统 中 已 安 装 的 字 体 的 列 表 中 选 择 , 或 键 入 自 定 义 字 体 名 称 。 不 管 用 何 方 法 输 入 字 体 名 称 ,
字 体 必 须 在 系 统 上 可 用 , 在 该 系 统 上 将 使 用 PDFlib Personalization Server 填 充 块 。
完 成 对 属 性 的 编 辑 后 , 单 击 “ 确 定 ” 以 关 闭 属 性 对 话 框 。 刚 刚 定 义 的 属 性 将 存 储 在 PDF
文 件 中 作 为 块 定 义 的 一 部 分 。
交 叠 块 交 叠 块 很 难 进 行 选 择 , 因 为 用 鼠 标 点 击 一 个 区 域 将 总 是 选 定 最 上 层 的 块 。 在 这 种 情
况 下 , 可 以 使 用 上 下 文 菜 单 中 的 “ 选 择 块 ” 项 以 按 照 块 名 称 选 择 块 。 当 块 被 选 择 后 , 随 后
所 有 对 于 该 区 域 的 操 作 ( 如 双 击 ) 都 针 对 被 选 择 块 , 其 他 在 此 区 域 的 块 不 会 受 影 响 。 这 样 ,
即 使 被 局 部 或 完 全 覆 盖 的 块 属 性 也 可 以 很 方 便 地 编 辑 。
使 用 和 恢 复 属 性 默 认 值 为 了 保 存 一 些 数 量 的 键 入 和 单 击 , 块 工 具 会 记 住 在 上 一 个 块 的 属
性 对 话 框 中 输 入 的 属 性 值 。 当 您 建 立 一 个 新 的 块 时 , 将 再 次 使 用 这 些 值 。 当 然 , 您 可 以 随 时
通 过 不 同 的 值 重 写 这 些 值 。
按 下 属 性 对 话 框 中 的 “ 全 部 重 置 ” 按 钮 将 大 多 数 块 属 性 重 置 为 其 相 应 的 默 认 值 。 不 过 ,
以 下 项 将 保 持 不 变 :
> Name、 Type、 Rect 和 Description 属 性
> 所 有 自 定 义 属 性 。
共 享 块 属 性 通 过 按 住 Shift 键 并 使 用 块 工 具 选 择 多 个 块 的 方 式 , 您 可 以 选 择 在 页 上 选 择 任
意 数 目 的 块 。 双 击 任 意 一 个 被 选 块 或 按 Enter 键 , 一 个 共 享 块 属 性 对 话 框 将 弹 出 , 其 中 的 块
属 性 值 将 适 用 于 所 有 被 选 块 。 不 过 , 由 于 不 是 所 有 属 性 都 可 以 被 多 个 块 共 享 , 只 有 一 个 属 性
子 集 可 以 被 编 辑 。 若 想 具 体 了 解 哪 些 属 性 可 被 多 块 共 享 , 见 第 138 页 上 的 第 6.4 节 “ 用 于 自
动 化 处 理 的 标 准 属 性 ”。 自 定 义 属 性 不 能 被 共 享 。
6.3.3 页 和 文 件 之 间 的 块 拷 贝
块 增 效 工 具 提 供 了 几 种 在 当 前 页 , 当 前 文 档 或 不 同 文 件 间 移 动 和 拷 贝 块 的 方 法 :
> 拖 动 鼠 标 进 行 块 移 动 或 拷 贝 , 或 粘 贴 到 别 的 页 或 打 开 的 文 件
> 在 同 一 文 件 中 , 复 制 相 同 的 块 到 一 或 多 页 里
> 导 出 块 到 新 文 件 ( 空 白 页 面 ) 或 已 存 在 文 件 ( 对 现 有 页 使 用 块 )
> 从 其 他 文 档 导 入 块
6.3 建 立 PDFlib 块 135

为 了 在 保 留 块 定 义 的 同 时 更 新 页 面 内 容 , 您 可 以 在 保 留 块 的 同 时 替 换 以 下 页 。 使 用 “ 文 档 ”
-> “ 替 换 页 面 ”(Acrobat 5 和 7) 或 “ 文 档 ” -> “ 页 面 ” -> “ 替 换 ” (Acrobat 6)。
移 动 和 复 制 块 在 按 下 Ctrl 键 ( 在 Windows 上 ) 或 Alt 键 ( 在 Mac 上 ) 的 同 时 , 选 择 一
个 或 多 个 块 并 将 其 拖 动 到 新 的 位 置 , 可 以 重 新 定 位 块 或 创 建 块 的 副 本 。 当 按 下 键 的 时 候 , 鼠
标 指 针 将 改 变 。 复 制 的 块 将 与 原 始 的 块 有 相 同 的 属 性 , 除 了 其 名 称 和 位 置 将 自 动 更 改 以 外 。
您 还 可 以 使 用 复 制 / 粘 贴 将 块 复 制 到 同 一 页 的 其 他 位 置 、 同 一 文 档 中 的 其 他 页 或 当 前 在
Acrobat 中 打 开 的 其 他 文 档 :
> 启 用 块 工 具 并 选 择 您 想 要 复 制 的 块 。
> 使 用 Ctrl-C( 在 Windows 平 台 上 ) 或 Cmd-C( 在 Mac 平 台 上 ) 或 “ 编 辑 ”->“ 复 制 ”,
将 选 定 的 块 复 制 到 剪 贴 板 。
> 使 用 Ctrl-V ( 在 Windows 平 台 上 ) 或 Cmd-V ( 在 Mac 平 台 上 ) 或 “ 编 辑 ” -> “ 粘
贴 ”, 粘 贴 当 前 位 于 剪 贴 板 中 的 块 。
复 制 块 到 其 他 页 您 可 以 同 时 创 建 当 前 文 档 中 的 任 意 数 目 页 上 的 一 个 或 多 个 块 的 副 本 :
> 启 用 块 工 具 , 并 选 择 您 想 要 复 制 的 块 。
> 从 “PDFlib 块 ” 菜 单 或 上 下 文 菜 单 选 择 “ 导 入 和 导 出 ” -> “ 复 制 ”。
> 选 择 要 复 制 的 块 ( 选 定 的 块 或 页 上 的 所 有 块 ) 以 及 您 想 要 用 来 复 制 块 的 目 标 页 的 范 围 。
导 出 和 导 入 块 通 过 使 用 块 的 导 出 / 导 入 功 能 , 可 以 共 享 单 个 页 上 的 块 定 义 或 多 个 PDF 文
件 之 间 的 某 一 文 档 中 的 所 有 块 。 在 保 留 现 有 块 定 义 的 同 时 更 新 页 面 内 容 , 这 一 点 很 有 用 。 将
块 定 义 导 出 到 一 个 分 离 的 文 件 的 过 程 , 如 下 所 示 :
> 启 用 块 工 具 , 并 选 择 您 想 要 导 出 的 块 。
> 从 “PDFlib 块 ” 菜 单 或 上 下 文 菜 单 中 选 择 “ 导 入 和 导 出 ” -> “ 导 出 ”。 为 包 含 块 定 义 的
文 件 输 入 页 范 围 和 文 件 名 称 。
您 可 以 通 过 “PDFlib 块 ” -> “ 导 入 和 导 出 ” -> “ 导 入 ” 导 入 块 定 义 。 导 入 块 时 , 您 可 以 选
择 是 对 文 档 中 的 所 有 的 页 还 是 仅 对 页 范 围 使 用 导 入 的 块 。 若 已 选 定 多 个 页 , 则 块 定 义 将 不 变
地 被 复 制 到 这 些 页 。 若 目 标 范 围 内 的 页 多 于 导 入 的 块 定 义 文 件 中 的 页 , 则 您 可 以 使 用 “ 重
复 模 板 ” 复 选 框 。 若 此 复 选 框 被 激 活 , 则 将 在 当 前 文 档 中 重 复 导 入 的 文 件 中 的 块 的 顺 序 , 直
致 文 档 的 结 尾 。
在 导 出 时 , 将 块 复 制 到 其 他 文 档 当 导 出 块 时 , 您 可 以 立 即 对 其 他 文 档 中 的 页 使 用 这 些
块 , 从 而 使 这 些 块 从 一 个 文 档 传 播 到 另 一 个 文 档 。 为 此 , 选 择 一 个 现 有 文 档 , 以 将 块 导 出 到
此 文 档 。 若 您 启 用 复 选 框 “ 删 除 已 存 块 ”, 则 在 将 新 的 块 复 制 到 文 档 中 之 前 , 将 删 除 目 标 文
档 中 可 能 存 在 的 所 有 块 。
6.3.4 将 PDF 表 单 域 转 换 为 PDFlib 块
作 为 手 动 创 建 PDFlib 块 的 一 个 替 换 , 您 可 以 将 PDF 表 单 域 自 动 转 换 为 块 。 若 您 需 要 使 用
PDFlib Personalization Server 自 动 填 写 复 杂 的 PDF 表 单 , 或 需 要 大 量 的 现 有 PDF 表 单 以 便
自 动 填 充 , 这 一 点 特 别 方 便 。 为 了 将 页 上 的 所 有 表 单 域 转 换 为 PDFlib 块 , 请 选 择 “PDFlib
块 ”->“ 转 换 表 单 域 ”->“ 当 前 页 ”。 若 要 转 换 文 档 中 的 所 有 表 单 域 , 则 请 选 择 “ 所 有 页 ”。
最 终 , 您 只 能 使 用 “ 所 选 表 单 域 ” 转 换 所 选 表 单 域 ( 选 择 Acrobat 的 表 单 工 具 或 选 择 对 象
工 具 来 选 定 表 单 域 )。
136 第 6 章 : 数 据 变 量 和 块

表 单 域 转 换 详 细 信 息 自 动 表 单 域 转 换 将 “PDFlib 块 ”->“ 转 换 表 单 域 ”->“ 转 换 选 项 ” 对
话 框 中 选 定 的 类 型 的 表 单 域 转 换 为 Text 类 型 块 。 默 认 情 况 下 , 将 转 换 所 有 表 单 域 类 型 。 根
据 表 6.2, 已 转 换 域 的 属 性 将 转 换 为 相 应 的 块 属 性 。
表 6.2 PDF 表 单 域 到 PDFlib 块 的 转 换
PDF 表 单 域 属 性 ...
... 将 转 换 成 对 应 的 PDFlib 属 性
所 有 域
位 置
一 般 , Rect
名 称
一 般 , Name
工 具 提 示
一 般 , Description
外 观 , 文 本 , 字 体
文 本 , fontname
外 观 , 文 本 , 字 体 大 小
文 本 ,fontsize ;“auto” 值 将 会 换 算 为 相 当 于 2/3 块 高 度 的 固 定 字 体 大
小 , 并 且 fitmethod 将 被 设 为 “auto”。 对 于 多 行 文 本 的 表 单 域 / 块 , 这
种 组 合 将 会 自 动 生 成 适 合 的 字 体 大 小 , 其 值 可 能 比 2/3 块 高 度 的 初 始 值
要 小 。
外 观 , 文 本 , 文 本 颜 色
文 本 , strokecolor ; 文 本 , fillcolor
外 观 , 边 框 , 边 框 颜 色
一 般 , bordercolor
外 观 , 边 框 , 填 充 颜 色
一 般 , backgroundcolor
外 观 , 边 框 , 线 宽 一 般 , linewidth: 细 =1, 中 =2, 厚 =3
常 规 , 一 般 属 性 , 表 单 域 一 般 , Status: 显 示 =active, 隐 藏 =ignore, 显 示 但 不 打 印 =ignore,
隐 藏 但 可 打 印 =active
常 规 , 一 般 属 性 , 方 向
一 般 , orientate:0=north, 90=west, 180=south, 270=east
文 本 域
选 项 , 默 认 值
文 本 , defaulttext
选 项 , 对 齐
一 般 , 位 置 : 左 ={left center}, 中 ={center center}, 右 ={right, center}
选 项 , 多 行
文 本 , textflow: 选 中 =true, 未 选 中 =false
单 选 按 钮 和 复 选 框
若 选 择 了 “ 默 认 选 中 复 选 框 / 按 文 本 , defaulttext: 方 格 =4, 圆 圈 =l, 十 字 =8, 菱 形 =u, 正 方 形
钮 ”: 选 项 , 复 选 框 样 式 或 选 项 , =n, 星 形 =H ( 这 些 字 符 分 别 对 应 于 ZapfDingbats 字 体 的 符 号 )
按 钮 样 式
列 表 框 和 组 合 框
选 项 , 所 选 ( 默 认 ) 项 目 文 本 , defaulttext
按 钮
选 项 , 图 标 和 标 签 , 标 签 文 本 , defaulttext
具 有 相 同 名 称 的 多 个 表 单 域 允 许 同 一 页 面 上 的 多 个 表 单 域 具 有 相 同 的 名 称 , 而 页 上 的 块
名 称 必 须 是 唯 一 的 。 当 见 表 单 域 转 换 为 块 时 , 将 为 生 成 的 块 的 名 称 添 加 一 个 用 数 字 表 示 的
后 缀 以 创 建 唯 一 的 块 名 称 ( 参 见 第 137 页 上 的 “ 表 单 域 与 其 相 应 块 的 关 联 ” )。
请 注 意 , 由 于 Acrobat 中 的 某 个 问 题 , 导 致 无 法 准 确 报 告 具 有 相 同 名 称 的 表 单 域 的 域 属
性 。 若 多 个 域 的 名 称 相 同 而 属 性 不 同 , 则 将 不 会 在 生 成 的 块 中 反 映 这 些 差 异 。 在 这 种 情 况
下 , 转 换 过 程 将 发 出 警 告 并 提 供 受 影 响 的 表 单 域 的 名 称 。 在 这 种 情 况 下 , 您 应 仔 细 检 查 生 成
的 块 中 的 属 性 。
表 单 域 与 其 相 应 块 的 关 联 当 转 换 多 个 具 有 相 同 名 的 表 单 域 ( 如 : 单 选 按 钮 ) 为 块 时 , 表
单 域 名 将 被 修 改 。 这 给 准 确 识 别 块 与 其 特 定 的 表 单 域 的 联 系 带 来 难 度 。 尤 其 是 对 于 使 用 PDF
或 XPDF 文 件 作 为 填 写 块 的 源 文 件 从 而 取 得 类 似 于 表 单 域 填 写 效 果 的 情 况 。
6.3 建 立 PDFlib 块 137

为 了 解 决 这 个 问 题 , AcroFormConversion 增 效 工 具 在 创 建 相 应 块 时 将 原 表 单 域 作 为 自
定 义 属 性 具 体 纪 录 下 来 。
表 6.3 识 别 原 表 域 对 应 块 的 自 定 义 属 性
自 定 义 属 性
意 义
PDFlib:field:name 完 全 合 乎 规 范 的 表 域 名 。
PDFlib:field:pagenumber 表 域 在 原 文 档 的 页 码 ( 字 符 串 形 式 )。
PDFlib:field:type
相 应 表 域 的 类 型 , 可 为 :pushbutton, checkbox, radiobutton, listbox, combobox,
textfield 或 signature.
PDFlib:field:value ( 仅 对 type=checkbox) 表 域 的 出 口 值 。
将 块 绑 定 到 相 应 的 表 单 域 为 了 使 PDF 表 单 域 和 生 成 的 PDFlib 块 保 持 同 步 , 可 以 将 生 成 的
块 绑 定 到 相 应 的 表 单 域 。 这 意 味 着 块 工 具 将 内 部 保 持 表 单 域 和 块 之 间 的 关 系 。 当 再 次 启 用 转
换 过 程 时 , 将 更 新 绑 定 块 以 反 映 相 应 的 PDF 表 单 域 的 属 性 。 绑 定 块 对 于 避 免 重 复 工 作 很 有
用 : 当 更 新 表 单 以 便 交 互 使 用 时 , 也 会 自 动 更 新 相 应 的 块 。
块 生 成 以 后 , 若 您 不 想 保 留 转 换 的 表 单 域 , 则 可 以 在 “PDFlib 块 ” -> “ 转 换 表 单 域 ” ->
“ 转 换 选 项 ” 对 话 框 中 选 择 “ 删 除 转 换 的 表 单 域 ”。 在 转 换 过 程 完 成 后 , 此 选 项 将 永 久 性 移
除 表 单 域 。 任 何 与 受 影 响 的 域 相 关 的 操 作 ( 例 如 JavaScript) 也 将 从 文 档 移 除 。
批 量 转 换 若 您 有 许 多 带 表 单 域 的 PDF 文 档 需 要 转 换 为 PDFlib 块 , 则 您 可 以 使 用 批 转 换 功
能 自 动 处 理 任 意 数 量 的 文 档 。 可 以 通 过 “PDFlib 块 ” -> “ 转 换 表 单 域 ” -> “ 批 转 换 ” 使 用
批 处 理 对 话 框 。
> 可 以 单 个 选 定 输 入 文 件 ; 另 外 , 可 以 处 理 文 件 夹 的 全 部 内 容 。
> 输 出 文 件 可 以 编 写 到 输 入 文 件 所 在 的 同 一 文 件 夹 , 或 编 写 到 不 同 的 文 件 夹 。 输 出 文 件 可
以 接 受 一 个 前 缀 以 便 将 其 与 输 入 文 件 区 分 开 来 。
> 当 对 大 量 文 档 进 行 处 理 时 , 建 议 指 定 一 个 日 志 文 件 。 在 转 换 完 成 后 , 此 日 志 文 件 将 包 含
已 处 理 文 件 的 完 全 列 表 以 及 有 关 每 个 转 换 的 结 果 的 详 细 信 息 ( 该 信 息 中 包 含 可 能 存 在 的
错 误 消 息 )。
在 转 换 过 程 中 , 尽 管 转 换 的 PDF 文 档 将 在 Acrobat 中 可 见 , 但 是 您 无 法 使 用 任 何 Acrobat 的
菜 单 函 数 或 工 具 。
6.4 用 于 自 动 化 处 理 的 标 准 属 性
PDFlib 支 持 可 以 指 定 给 各 种 块 类 型 的 一 般 属 性 。 另 外 , 还 存 在 一 些 可 以 与 块 类 型 Text、
Image 和 PDF 相 关 的 属 性 。 一 些 属 性 是 共 享 的 , 这 意 味 着 使 用 块 增 效 工 具 可 以 立 即 将 这 些 属
性 指 定 给 多 个 块 。
除 了 句 柄 和 操 作 列 表 之 外 , 属 性 支 持 与 选 项 列 表 相 同 的 数 据 类 型 ( 请 参 见 第 168 页 上 的
第 8.1.2 节 “ 选 项 列 表 ”)。
许 多 的 块 属 性 具 有 与 PDF_fit_image( ) 等 功 能 选 项 ( 如 fitmethod) 或 PDFlib 参 数 ( 如
charspacing) 相 同 的 名 称 。 在 这 种 情 况 下 , 这 些 块 属 性 的 行 为 与 文 档 描 述 的 相 同 选 项 或 参 数
的 行 为 完 全 一 致 。
PDFlib 的 属 性 处 理 PDFlib 块 功 能 PDF_fill_*block( ) 将 根 据 下 列 顺 序 处 理 块 属 性 :
> 若 backgroundcolor 属 性 存 在 且 具 有 非 None 的 色 彩 空 间 关 键 字 , 则 使 用 指 定 的 颜 色 填 充
块 矩 形 。
> 处 理 除 了 bordercolor 和 linewidth 外 的 其 他 属 性 。
138 第 6 章 : 数 据 变 量 和 块

若 bordercolor 属 性 存 在 且 具 有 非 None 的 色 彩 空 间 关 键 字 , 则 将 使 用 指 定 的 颜 色 和 行 宽
绘 制 块 边 框 。
若 文 本 和 缺 省 文 本 均 未 提 供 , 则 不 会 有 包 括 背 景 颜 色 和 块 边 框 在 内 的 任 何 输 出 。PDFlib 不 提
供 剪 切 ; 若 您 想 确 保 块 内 容 未 超 过 块 矩 形 区 域 , 应 避 免 使 用 fitmethod nofit。
若 在 块 属 性 中 使 用 分 色 , 则 指 定 的 专 色 名 称 必 须 是 PDFlib 理 解 的 ( 见 第 58 页 上 的
第 3.3.3 节 “ 专 色 ”), 或 者 在 较 早 已 调 用 PDF_makespotcolor( ) 专 门 指 定 的 ; 否 则 , 块 功
能 将 失 败 。
6.4.1 一 般 属 性
一 般 属 性 适 用 于 所 有 块 类 型 (Text,Image,PDF)。 对 于 块 管 理 、 自 身 描 述 块 矩 形 的 外 观 和 管 理
在 块 内 部 放 置 内 容 的 方 式 , 一 般 属 性 都 是 必 需 的 。 PDFlib 块 增 效 工 具 将 自 动 生 成 必 需 的 属
性 。 表 6.4 列 出 了 一 般 属 性 。
表 6.4 一 般 块 属 性
关 键 字 类 型 可 能 的 值 和 说 明
块 管 理
Name string ( 必 需 的 ) 块 名 。 在 一 页 里 , 块 名 必 须 是 唯 一 的 , 但 同 一 块 名 可 出 现 在 同 一
文 档 的 不 同 页 中 。 块 名 中 不 允 许 出 现 [ ] / 这 三 个 字 符 。 块 名 最 不 能 超 过
125 个 字 符 。
Description string 块 的 函 数 的 可 供 人 读 的 说 明 , 采 用 PDFDocEncoding 或 Unicode 编 码 ( 在 后
者 情 况 下 , 以 BOM 开 头 )。 此 属 性 仅 用 于 用 户 信 息 , 在 进 行 块 处 理 时 该 属
性 将 被 忽 略 。
Locked boolean ( 可 共 享 的 ) 若 值 为 true, 块 增 效 工 具 将 不 能 编 辑 该 块 及 其 属 性 。 当 进 行 块
处 理 时 该 属 性 将 被 忽 略 。 默 认 值 :false。
Rect rectangle ( 必 需 的 ) 块 坐 标 。 坐 标 系 统 的 原 点 位 于 页 的 左 下 角 。 不 过 , 块 增 效 工 具 将
按 照 Acrobat 的 表 示 法 显 示 坐 标 , 也 就 是 说 , 原 点 在 页 的 左 上 角 。 坐 标 将 用
在 Acrobat 中 当 前 选 定 的 单 位 进 行 显 示 , 但 在 PDF 文 档 里 将 以 点 为 单 位 进 行
存 储 。
Status keyword 关 键 字 描 述 块 将 如 何 被 处 理 ( 默 认 值 :active):
active 该 块 将 按 照 其 属 性 设 置 被 完 全 处 理 。
ignore 该 块 将 被 忽 略 。
static 不 将 放 置 任 何 可 变 内 容 ; 而 将 使 用 块 的 默 认 文 本 、 图 像 或 PDF 内
容 ( 如 果 可 用 )。
Subtype keyword ( 必 需 的 ) 块 类 型 , 其 值 可 为 Text、 Image 或 PDF
Type keyword ( 必 需 的 ) 始 终 为 Block
块 外 观
backgroundcolor color ( 可 共 享 的 ) 若 此 属 性 存 在 并 具 有 非 None 的 色 彩 空 间 关 键 字 , 则 将 绘 制 一
个 矩 形 并 用 提 供 的 颜 色 填 充 该 矩 形 。 这 对 覆 盖 当 前 页 已 有 内 容 很 有 效 。 默
认 值 :None
bordercolor color ( 可 共 享 的 ) 若 此 属 性 存 在 并 具 有 非 None 的 色 彩 空 间 关 键 字 , 则 将 绘 制 一
个 矩 形 并 用 提 供 的 颜 色 为 该 矩 形 描 边 。 默 认 值 :None
linewidth float ( 可 共 享 的 ; 必 须 大 于 0) 用 于 绘 制 块 边 框 的 线 宽 度 ; 只 有 在 bordercolor
被 设 置 时 才 有 效 。 默 认 值 : 1
6.4 用 于 自 动 化 处 理 的 标 准 属 性 139

表 6.4 一 般 块 属 性
关 键 字 类 型 可 能 的 值 和 说 明
内 容 排 版
fitmethod keyword ( 可 共 享 的 ) 当 提 供 的 内 容 不 能 完 全 排 入 块 矩 形 框 时 的 策 略 。 其 可 选 值 为
auto、 nofit、 clip、 meet 1 、 slice 1 和 entire 1 。 对 于 简 单 的 文 本 块 、 图 像 和
PDF 块 , 将 根 据 表 8.19 和 表 8.41) 说 明 此 属 性 。 默 认 值 :auto. 对 于 textflow
块 ( 此 处 的 块 对 于 文 本 太 小 ), 说 明 如 下 所 示 :
auto fontsize 和 leading 将 被 减 小 直 至 文 本 可 完 全 排 入 矩 形 框
nofit 文 本 将 超 出 块 矩 形 框 底 线 。
clip 文 本 将 在 块 矩 形 框 处 剪 切 。
orientate keyword ( 可 共 享 的 ) 当 内 容 被 放 置 时 , 指 定 内 容 的 必 需 方 向 ( 请 参 见 表 8.41)。 其
可 选 值 为 north、 east、 south 和 west。 默 认 值 :north
position 1
float 或
keyword
list
( 可 共 享 的 ) 用 于 指 定 内 容 内 的 参 考 点 的 位 置 的 一 个 或 两 个 值 ( 对 于 文 本
请 参 见 表 8.19, 对 于 图 像 /PDF 请 参 见 表 8.41)。 position 被 指 定 为 块 内 的 百
分 比 。 默 认 值 :{0, 0}, 即 左 下 脚
rotate float ( 可 共 享 的 ) 在 处 理 开 始 之 前 , 块 将 反 时 针 方 向 旋 转 的 旋 转 角 ( 以 度 为 单
位 )。 参 考 点 为 旋 转 的 中 心 。 默 认 值 : 0
1. textflow 块 (text blocks with textflow=true) 不 支 持 此 关 键 字 或 属 性 。
6.4.2 Text 属 性
文 本 相 关 的 属 性 适 用 于 Text 类 型 块 ( 除 了 一 般 属 性 之 外 ) 。 所 有 文 本 相 关 的 属 性 都 可 以 被
共 享 。
所 有 文 本 块 的 属 性 文 本 块 取 决 于 textflow 属 性 , 可 以 包 含 单 行 或 多 行 文 本 。 表 6.5 列 出 了
适 用 于 这 两 种 类 型 的 文 本 相 关 的 属 性 。
表 6.5 Text 块 属 性
关 键 字 类 型 可 能 的 值 和 说 明
charspacing float 或 percentage 字 符 间 距 ( 请 参 见 表 8.18)。 其 值 为 字 体 大 小 的 百 分 比 。 默 认 值 : 0
defaulttext string 若 客 户 端 未 提 供 替 代 文 本 , 则 将 使 用 的 文 本 。 1
fillcolor color 填 充 文 本 的 颜 色 。 默 认 值 :gray 0 (=black)
fontname 2 string PDF_load_font( ) 要 求 的 字 体 的 名 称 。 PDFlib 块 增 效 工 具 将 显 示 一 个
系 统 已 安 装 的 字 体 的 列 表 。 不 过 , 这 些 字 体 名 称 可 能 在 Mac、
Windows 和 Unix 系 统 之 间 不 可 移 植 。
当 对 块 进 行 填 充 时 , 除 非 已 经 提 供 字 体 选 项 , 否 则 必 须 将 文 本 的 编
码 指 定 为 PDF_fill_textblock( ) 的 选 项 。
fontsize 2 float 字 体 的 大 小 ( 以 点 为 单 位 )
fontstyle keyword 字 体 样 式 必 须 是 normal、 bold、 italic 或 bolditalic 中 的 一 款 ( 请 参
见 表 8.16)
horizscaling float 或 percentage 水 平 文 本 缩 放 ( 请 参 见 表 8.18)。 默 认 值 :100%
italicangle float 文 本 的 倾 斜 角 度 ,( 请 参 见 表 8.18)。 默 认 值 :0
kerning boolean 字 距 调 整 行 为 ( 请 参 见 表 8.18)。 默 认 值 :false
margin float list 用 来 描 述 文 本 框 的 其 他 水 平 和 垂 直 扩 展 的 一 个 或 两 个 浮 点 值 ( 请 参
见 表 8.19)。 默 认 值 : 0
monospace integer 1...2048 强 制 字 体 中 的 所 有 字 符 使 用 相 同 宽 度 ( 请 参 见 表 8.16) 默 认 值 :
absent ( 使 用 字 体 的 规 格 )
overline boolean 上 划 线 模 式 ( 请 参 见 表 8.18)。 默 认 值 :false
strikeout boolean 删 除 线 模 式 ( 请 参 见 表 8.18)。 默 认 值 :false
140 第 6 章 : 数 据 变 量 和 块

表 6.5 Text 块 属 性
关 键 字 类 型 可 能 的 值 和 说 明
strokecolor color 文 本 描 边 色 。 默 认 值 :gray 0 (=black)
textflow boolean 控 制 单 行 或 多 行 文 本 处 理 ( 默 认 值 :false):
false 文 本 可 以 跨 单 行 并 将 使 用 PDF_fit_text( ) 处 理 此 文 本 。
true 文 本 将 跨 多 行 并 将 使 用 PDF_fit_textflow( ) 处 理 此 文 本 。
将 忽 略 常 规 属 性 位 置 。 除 了 标 准 文 本 属 性 之 外 , 还 可 以
指 定 所 有 textflow 相 关 的 属 性 ( 请 参 见 表 6.6)。
textrendering integer 文 本 渲 染 模 式 ( 请 参 见 表 8.18)。 默 认 值 : 0
textrise float 或 percentage 文 本 提 升 参 数 ( 请 参 见 表 8.18)。 其 值 为 字 体 大 小 的 百 分 比 。
默 认 值 : 0
underline boolean 下 划 线 模 式 ( 请 参 见 表 8.18)。 默 认 值 :false
underlineposition float、 percentage 用 于 相 对 于 基 线 的 加 下 划 线 的 文 本 的 描 边 线 的 位 置 ( 请 参 见 表
或 keyword 8.20)。 其 值 为 字 体 大 小 的 百 分 比 。 默 认 值 :auto
underlinewidth
float、 percentage
或 keyword
加 下 划 线 的 文 本 的 行 宽 ( 请 参 见 表 8.20)。 其 值 为 字 体 大 小 的 百 分
比 。 默 认 值 :auto
wordspacing float 或 percentage 单 词 间 距 ( 请 参 见 表 8.18)。 其 值 为 字 体 大 小 的 百 分 比 。 默 认 值 :0
1. 将 用 winansi 编 码 或 Unicode 说 明 此 文 本 。
2. 文 本 块 中 需 要 此 属 性 ; PDFlib 块 增 效 工 具 将 自 动 强 制 使 用 此 属 性 。
textflow 块 属 性 textflow 相 关 的 属 性 适 用 于 Text 类 型 的 块 , 此 处 textflow 属 性 为 true。
文 本 相 关 的 属 性 将 用 于 构 建 初 始 选 项 列 表 以 便 处 理 textflow ( 与 PDF_create_textflow( ) 的
optlist 参 数 对 应 )。 尽 管 使 用 增 效 工 具 无 法 指 定 选 项 列 表 , 但 是 当 使 用 PDF_fill_textblock( )
填 充 块 时 , 可 以 在 服 务 器 上 提 供 这 些 选 项 列 表 作 为 文 本 内 容 的 一 部 分 。 所 有 textflow 相 关
的 属 性 都 可 以 共 享 。 表 6.6 列 出 textflow 相 关 的 属 性 。
表 6.6 textflow 块 属 性
关 键 字 类 型 可 能 的 值 和 说 明
文 本 语 义 属 性 :
tabalignchar integer 小 数 部 分 以 之 对 齐 的 字 符 Unicode 值 。 默 认 值 : ’.’ 字 符 (U+002E)
控 制 文 本 排 版 的 属 性 :
alignment keyword 指 定 文 本 行 在 段 落 中 的 对 齐 方 式 ( 默 认 值 :left):
left 起 于 leftindent, 向 左 对 齐
center 以 leftindent 和 rightindent 之 间 的 中 心 对 齐
right 向 右 对 齐 , 止 于 rightindent
justify 左 右 两 边 对 齐
firstlinedist float、
percentage、 或
keyword
定 界 框 顶 部 与 第 一 行 文 本 的 基 线 之 间 的 距 离 , 以 用 户 坐 标 或 相 关 字 体 大
小 的 百 分 比 为 单 位 ( 用 该 行 的 第 一 个 字 体 大 小 为 单 位 , 如 果
fixedleading=true 并 且 该 字 体 大 小 是 该 行 中 最 大 的 ), 或 者 用 关 键 字
( 默 认 值 :leading):
leading 第 一 行 的 行 距 值 ; 常 用 可 触 及 定 界 框 顶 部 的 典 型 字 符 如 À 为
基 准 。
ascender 第 一 行 的 字 体 上 伸 部 分 ; 常 用 可 触 及 定 界 框 顶 部 的 带 较 大 的
上 伸 部 分 的 典 型 字 符 如 d 和 h 为 基 准 。
capheight 为 首 行 确 定 的 大 写 高 度 值 ; 常 用 可 触 及 定 界 框 顶 部 的 典 型 的
大 写 字 母 字 符 如 H 为 基 准 。
xheight 第 一 行 的 xheight 值 ; 常 用 可 触 及 定 界 框 顶 部 的 典 型 的 小 写
字 母 字 符 如 x 为 基 准 。
若 fixedleading=false, 第 一 行 里 leading、 ascender 、 xheight 或
capheight 中 的 最 大 值 将 被 使 用 。
6.4 用 于 自 动 化 处 理 的 标 准 属 性 141

表 6.6 textflow 块 属 性 ( 续 )
关 键 字 类 型 可 能 的 值 和 说 明
fixedleading boolean 如 果 值 为 true, 每 行 的 第 一 个 行 距 将 作 为 该 行 的 leading 值 。 否 则 , 每
行 的 最 大 行 距 将 作 为 该 行 的 leading 值 。 默 认 值 :false
hortabsize
float 或
percentage
水 平 制 表 键 的 宽 度 1 。 具 体 解 释 将 取 决 于 hortabmethod 选 项 。 默 认 值 :
7.5%
hortabmethod keyword 文 本 中 的 水 平 制 表 键 的 处 理 。 若 计 算 的 位 置 位 于 当 前 文 本 位 置 的 左 侧 ,
则 将 忽 略 制 表 键 ( 默 认 值 :relative):
relative 位 置 将 按 hortabsize 中 指 定 的 数 量 前 进 。
typewriter 位 置 将 移 到 下 一 个 hortabsize 的 倍 数 的 位 置 。
ruler 位 置 将 前 进 到 ruler 选 项 中 的 第 n 个 制 表 键 值 , 此 处 n 为 目
前 在 行 中 找 到 的 选 项 卡 数 量 。 若 n 大 于 制 表 键 的 数 量 , 则 将
使 用 相 关 方 法 。
lastalignment keyword 排 版 段 落 中 的 最 后 一 行 。 支 持 所 有 alignment 选 项 的 关 键 字 , 外 加 以 下
( 默 认 值 :auto):
auto 若 alignment 选 项 值 不 是 justify, 使 用 该 方 式 排 版 。 在 后 者
情 况 下 , 将 使 用 left 方 式 。
lastlinedist
leading
parindent
rightindent
leftindent
float、
percentage 或
keyword
float 或
percentage
float 或
percentage
float 或
percentage
( 若 fitmethod=nofit, 将 忽 略 ) 最 后 的 文 本 行 基 线 与 定 界 框 底 部 之 间 的
最 小 距 离 , 以 用 户 坐 标 或 相 关 字 体 大 小 的 百 分 比 为 单 位 ( 用 该 行 的 第
一 个 字 体 大 小 为 单 位 , 如 果 fixedleading= true 并 且 该 字 体 大 小 是 该 行 中
最 大 的 ), 或 者 使 用 关 键 字 ( 默 认 值 :0, 也 就 是 说 , 定 界 框 的 底 部 用
作 基 线 , 且 典 型 的 下 伸 部 分 将 超 出 定 界 框 ):
descender 最 后 一 行 的 字 体 下 伸 值 ; 常 用 可 触 及 定 界 框 底 部 的 带 下 伸 部
分 的 典 型 字 符 如 g 和 j 为 基 准 。
如 果 fixedleading=false, 最 后 一 行 descender 中 的 最 大 值 将 被 使 用 。
两 个 相 连 文 本 行 基 线 之 间 的 距 离 , 以 用 户 坐 标 或 相 关 字 体 大 小 的 百 分 比
为 单 位 。 默 认 值 :100%
段 落 第 一 行 的 左 缩 排 1 。 该 数 值 将 追 加 到 leftindent 上 。 在 一 行 中 指 定 这
一 选 项 , 其 行 为 就 如 制 表 键 。 默 认 值 :0
所 有 文 本 行 的 左 或 右 缩 排
1 。 若 在 行 内 指 定 leftindent, 并 且 确 定 的 位 置
在 当 前 文 本 位 置 的 左 侧 , 则 将 为 当 前 行 忽 略 此 选 项 。 默 认 值 : 0
rotate float 旋 转 坐 标 系 统 , 以 定 界 框 的 左 下 角 为 中 心 并 将 指 定 的 值 作 为 旋 转 角
( 以 度 为 单 位 )。 这 将 导 致 框 和 文 本 被 旋 转 。 一 旦 文 本 已 放 置 , 旋 转 将
重 置 。 默 认 值 : 0
ruler 2
list of floats 或
percentages
当 hortabmethod=ruler 时 , 制 表 键 绝 对 值 列 表
。 这 个 列 表 可 包 含 多 至
32 个 非 负 数 的 值 , 以 上 升 秩 序 排 列 。 默 认 值 :hortabsize 的 整 数 倍 数
tabalignment list of keywords 制 表 键 对 齐 方 式 列 表 中 的 每 个 项 都 定 义 ruler 选 项 中 的 相 应 的 项 的 对 齐
方 式 ( 默 认 值 :left)
center 制 表 键 内 文 本 向 中 对 齐
decimal 第 一 个 tabalignchar 示 例 将 在 制 表 键 位 置 左 对 齐 。 如 果 找 不
到 tabalignchar, 则 将 采 用 向 右 对 齐 。
left 制 表 键 内 文 本 向 左 对 齐 。
right 制 表 键 内 文 本 向 右 对 齐 。
verticalalign keyword 定 界 框 内 的 文 本 垂 直 对 齐 ( 默 认 值 :top):
top 排 版 文 本 将 从 第 一 行 开 始 , 由 上 至 下 。 若 文 本 不 能 填 满 定 界
框 , 会 在 文 本 下 端 留 出 空 白 。
center 文 本 将 以 定 界 框 的 垂 直 中 心 对 齐 。 若 文 本 不 能 填 满 定 界 框 ,
会 在 文 本 上 、 下 端 留 出 空 白 。
bottom 排 版 文 本 将 从 最 后 一 行 开 始 , 由 下 至 上 。 若 文 本 不 能 填 满 定
界 框 , 会 在 文 本 上 端 留 出 空 白 。
justify 文 本 将 对 齐 定 界 框 的 顶 部 及 底 部 。 为 了 获 得 此 效 果 , 行 距 可
增 加 至 linespreadlimit 定 义 的 最 大 限 。 当 firstlinedist=leading
时 , 第 一 行 的 高 度 将 会 被 增 加 。
142 第 6 章 : 数 据 变 量 和 块

表 6.6 textflow 块 属 性 ( 续 )
关 键 字 类 型 可 能 的 值 和 说 明
控 制 分 行 算 法 的 属 性 :
adjustmethod keyword 当 使 用 大 于 等 于 minspacing 并 小 于 等 于 maxspacing 的 单 词 距 离 选 项 进
行 增 加 或 缩 减 单 词 间 距 离 的 调 整 后 , 仍 有 部 分 文 本 不 能 排 入 同 一 文 本 行
时 , 所 采 用 的 方 法 。 默 认 值 :auto
auto 按 顺 序 使 用 以 下 方 法 :shrink、 spread、 nofit、 split。
clip 类 似 于 nofit, 除 了 将 剪 切 定 界 框 ( 考 虑 rightindent 选 项 )
右 边 缘 的 长 的 部 分 以 外 。
nofit 末 尾 单 词 将 移 动 到 下 一 行 , 以 使 剩 余 ( 短 ) 行 将 不 会 少 于
nofitlimit 选 项 中 指 定 的 百 分 比 即 使 对 齐 的 段 落 也 可 能 看 起 来
有 点 不 规 则 。
shrink 若 单 词 不 能 完 全 排 入 当 前 行 , 将 缩 减 文 本 直 至 shrinklimit。
若 仍 不 能 满 足 要 求 , 则 将 使 用 nofit 方 法 。
split 末 尾 单 词 将 不 会 移 动 到 下 一 行 , 但 是 将 强 制 对 其 添 加 连 字
符 。 为 文 本 字 体 , 而 非 为 符 号 字 体 插 入 连 字 符 。
spread 末 尾 字 将 移 动 到 下 一 行 , 并 将 根 据 spreadlimit 通 过 增 加 词 中
字 符 之 间 的 距 离 对 齐 剩 余 ( 短 ) 行 。 若 仍 无 法 实 现 对 齐 , 则
将 使 用 nofit 方 法 。
linespreadlimit
maxlines
maxspacing
minspacing
nofitlimit
float 或
percentage
integer 或
keyword
float 或
percentage
float 或
percentage
( 只 有 当 verticalalign=justify 时 有 效 ) 垂 直 排 版 行 距 调 整 最 大 值 , 以 用
户 坐 标 或 相 关 行 距 的 百 分 比 为 单 位 。 默 认 值 : 200%
该 属 性 值 可 以 是 整 数 代 表 定 界 框 可 容 纳 文 本 行 的 最 大 值 ; 亦 可 是 关 键 字
auto, 代 表 定 界 框 所 含 文 本 行 数 没 有 限 制 。 若 已 放 置 最 大 行 数 , 则
PDF_fit_textflow( ) 将 返 回 string _boxfull。
单 词 间 最 大 或 最 小 的 距 离 ( 以 用 户 坐 标 或 间 隔 字 符 的 宽 度 的 百 分 比 为
单 位 )。 计 算 的 字 间 距 受 提 供 的 值 的 限 制 ( 但 是 仍 将 添 加 wordspacing
选 项 )。 默 认 值 :minspacing=50%、 maxspacing=500%
对 于 nofit 方 式 , 所 需 文 本 行 长 度 的 下 限 ( 以 在 用 户 坐 标 中 或 定 界 框 的
宽 度 的 百 分 比 为 单 位 )。 默 认 值 : 75%
shrinklimit percentage 对 于 shrink 方 式 , 可 缩 减 文 本 的 下 限 ; 计 算 的 收 缩 因 素 受 限 于 提 供 的
值 , 但 是 将 乘 以 horizscaling 选 项 提 供 的 值 。 默 认 值 : 85%
spreadlimit
float 或
percentage
1. 在 用 户 坐 标 中 , 或 作 为 定 界 框 的 宽 度 的 百 分 比
2. 可 以 在 “ 块 属 性 ” 对 话 框 中 的 “ 制 表 位 ” 区 域 编 辑 标 尺 。
对 于 spread 方 式 , 可 调 整 字 间 距 的 上 限 ; ( 以 用 户 坐 标 中 或 字 体 大 小
的 百 分 比 为 单 位 ); 计 算 的 字 符 距 离 将 被 添 加 到 charspacing 选 项 的 值 。
默 认 值 : 0
6.4.3 Image 属 性
图 像 相 关 的 属 性 适 用 于 Image 类 型 块 ( 除 常 规 属 性 之 外 )。 所 有 图 像 相 关 的 属 性 都 可 以 被 共
享 。 表 6.7 列 出 了 图 像 相 关 的 属 性 。
表 6.7 Image 块 属 性
关 键 字 类 型 可 能 的 值 和 说 明
defaultimage string 若 客 户 端 未 提 供 替 代 图 像 , 将 使 用 的 图 像 的 路 径 名 称 。 建 议 使 用 不 带 绝 对
路 径 的 文 件 名 , 并 在 PPS 客 户 应 用 程 序 中 使 用 SearchPath 功 能 。 这 将 使 块
处 理 独 立 于 平 台 及 文 件 系 统 的 细 节 。
dpi float list 以 像 素 / 英 寸 为 单 位 , 用 一 或 两 个 数 值 指 定 所 需 图 像 在 水 平 和 垂 直 方 向 的
分 辨 率 。 如 果 此 值 为 0, 若 图 像 内 部 的 分 辨 率 存 在 , 将 使 用 内 部 分 辨 率 ;
否 则 , 将 使 用 72 dpi 分 辨 率 。 若 fitmethod 属 性 与 关 键 字 auto、 meet、
slice 或 entire 中 的 某 一 关 键 字 一 起 被 提 供 , 此 属 性 将 被 忽 略 。 默 认 值 : 0
scale float list 用 一 或 两 个 数 值 指 定 在 水 平 和 垂 直 方 向 的 缩 放 比 例 。 若 fitmethod 属 性 与
关 键 字 auto、 meet、 slice 或 entire 中 的 某 一 关 键 字 一 起 被 提 供 , 此 属 性 将
被 忽 略 。 默 认 值 :1
6.4 用 于 自 动 化 处 理 的 标 准 属 性 143

6.4.4 PDF 属 性
PDF 相 关 的 属 性 适 用 于 PDF 类 型 块 ( 除 常 规 属 性 之 外 )。 所 有 PDF 相 关 的 属 性 都 可 以 被 共
享 。 表 6.8 列 出 了 PDF 相 关 的 属 性 。
表 6.8 PDF 块 属 性
关 键 字 类 型 可 能 的 值 和 说 明
defaultpdf string 若 客 户 端 未 提 供 替 代 PDF, 将 使 用 的 PDF 文 档 的 路 径 名 称 。 建 议 使 用 不 带
绝 对 路 径 的 文 件 名 , 并 在 PPS 客 户 应 用 程 序 中 使 用 SearchPath 功 能 。 这 将
使 块 处 理 独 立 于 平 台 和 文 件 系 统 的 细 节 。
defaultpdfpage integer 默 认 PDF 文 档 的 页 数 。 默 认 值 : 1
scale float list 用 一 或 两 个 数 值 指 定 在 水 平 和 垂 直 方 向 必 需 的 缩 放 比 例 因 素 。 若 fitmethod
属 性 与 关 键 字 auto、 meet、 slice 或 entire 中 的 某 一 关 键 字 一 起 被 提 供 , 此
选 项 将 被 忽 略 。 默 认 值 : 1
pdiusebox keyword ( 其 值 可 为 :media、 crop、 bleed、 trim、 art) 使 用 已 放 置 的 页 的 媒 体 框 、
裁 剪 框 、 出 血 框 、 裁 切 框 或 作 品 框 以 确 定 页 的 大 小 ( 请 参 见 表 8.46)。 默
认 值 :crop
6.4.5 自 定 义 属 性
自 定 义 属 性 适 用 于 各 种 块 类 型 ( 除 常 规 属 性 和 特 定 块 类 型 的 属 性 之 外 )。 自 定 义 属 性 是 可 选
的 , 并 不 能 共 享 。 表 6.9 列 出 了 自 定 义 属 性 的 命 名 规 则 。
表 6.9 自 定 义 块 属 性
关 键 字 类 型 可 能 的 值 和 说 明
任 何 名 称 都 不 包
含 [、 ]、 / 这 三 个
字 符 。
string、
name、
float、
float list
与 自 定 义 属 性 对 应 的 值 的 说 明 完 全 适 用 于 客 户 端 应 用 程 序 。
144 第 6 章 : 数 据 变 量 和 块

6.5 询 问 块 名 及 其 属 性
除 了 自 动 块 处 理 外 ,PDFlib 支 持 一 些 可 用 于 列 举 块 名 并 询 问 标 准 属 性 或 自 定 义 属 性 的 功 能 。
寻 找 块 的 数 目 和 名 称 客 户 端 必 须 不 知 道 导 入 的 页 上 的 块 的 名 称 和 数 量 , 因 为 这 些 也 可 以
查 询 。 以 下 语 句 返 回 当 前 页 的 块 数 :
blockcount = PDF_get_pdi_value(p, "vdp/blockcount", doc, page, 0);
以 下 语 句 返 回 页 上 的 块 号 为 5 的 块 的 名 称 ( 从 0 开 始 进 行 块 计 数 ), 若 此 块 不 存 在 , 则 返 回
一 个 空 字 符 串 ( 不 过 , 如 果 pdiwarning 参 数 或 选 项 设 置 为 true, 则 将 引 发 异 常 ):
blockname = PDF_get_pdi_parameter(p, "vdp/Blocks[5]/Name", doc, page, 0, &len);
返 回 的 块 名 称 可 以 在 后 面 用 于 查 询 块 的 属 性 或 用 于 使 用 文 本 、 图 像 或 PDF 内 容 填 充 块 。
在 路 径 语 法 中 , 对 于 为 块 属 性 寻 址 , 以 下 表 达 式 都 是 同 等 的 , 假 定 带 序 列 的
块 的 Name 属 性 已 设 置 为 :
Blocks[]/
Blocks//
查 找 块 坐 标 两 个 坐 标 对 (llx, lly) 和 (urx, ury) 描 述 名 为 foo 的 块 的 左 下 角 和 右 上 角 可 以 按 如
下 所 示 查 询 :
llx = PDF_get_pdi_value(p, "vdp/Blocks/foo/Rect[0]", doc, page, 0);
lly = PDF_get_pdi_value(p, "vdp/Blocks/foo/Rect[1]", doc, page, 0);
urx = PDF_get_pdi_value(p, "vdp/Blocks/foo/Rect[2]", doc, page, 0);
ury = PDF_get_pdi_value(p, "vdp/Blocks/foo/Rect[3]", doc, page, 0);
请 注 意 , 在 默 认 的 用 户 坐 标 系 统 ( 该 系 统 的 原 点 位 于 左 下 角 , 也 许 被 页 的 裁 剪 框 修 改 ) 中
提 供 这 些 坐 标 , 而 块 增 效 工 具 根 据 Acrobat 的 用 户 界 面 坐 标 系 统 ( 该 系 统 的 原 点 位 于 页 的
左 上 角 ) 显 示 坐 标 。 因 为 用 于 重 写 块 坐 标 的 Rect 选 项 不 会 考 虑 裁 剪 框 项 使 用 的 任 何 修 改 , 所
以 若 裁 剪 框 存 在 , 则 从 原 始 块 查 询 的 坐 标 不 能 直 接 作 为 新 坐 标 使 用 。 作 为 工 作 区 , 您 可 以 使
用 refpoint 和 boxsize 选 项 。
还 请 注 意 , 当 查 询 块 坐 标 时 , 不 会 考 虑 topdown 参 数 。
不 存 在 的 块 属 性 及 其 缺 省 值 由 于 API 的 局 限 性 , PDF_get_pdi_value( ) 不 能 被 用 于 判 断 一
个 块 属 性 是 确 实 存 在 且 其 值 为 0, 还 是 在 文 档 中 缺 失 该 属 性 从 而 使 用 缺 省 值 。
如 果 是 string 属 性 缺 失 , PDF_get_pdi_parameter( ) 将 会 返 回 一 个 空 的 字 符 串 。 如 果 是
numerical 属 性 缺 失 ( 从 而 使 用 缺 省 值 ), PDF_get_pdi_value( ) 将 会 返 回 值 0 ( 零 ) 。 因 为 大
多 数 的 numerical 属 性 缺 省 值 为 0, 故 这 类 情 况 无 需 特 殊 处 理 。 然 而 需 注 意 一 些 numerical
属 性 如 :linewidth, horizscaling, leading, 和 scale, 它 们 的 缺 省 值 非 0 ( 并 且 0 值 不 合 逻 辑 )。
在 这 种 情 况 下 , 用 户 需 做 特 殊 处 理 以 便 在 PDF_get_pdi_value( ) 返 回 0 值 时 , 可 正 确 匹 配 相
应 属 性 的 缺 省 值 。
PDFlib pCOS 可 在 PDF 文 件 里 查 询 包 括 块 属 性 在 内 的 各 种 信 息 。
查 询 自 定 义 属 性 可 以 按 照 以 下 示 例 中 那 样 查 询 自 定 义 属 性 , 在 此 示 例 中 , 从 名 为 b1 的 块
中 查 询 属 性 zipcode:
zip = PDF_get_pdi_parameter(p, "vdp/Blocks/b1/Custom/zipcode", doc, page, 0, &len);
6.5 询 问 块 名 及 其 属 性 145

若 不 知 道 块 中 包 含 哪 些 自 定 义 块 属 性 , 可 以 在 运 行 时 获 得 。 在 此 示 例 中 , 从 名 为 b1 的 块 中
查 询 第 一 个 自 定 义 块 属 性 的 名 称 :
propname = PDF_get_pdi_parameter(p, "vdp/Blocks/b1/Custom[0].key", doc, page, 0, &len);
用 增 加 下 标 变 量 来 替 代 0, 可 获 得 所 有 自 定 义 属 性 的 名 字 。 当 一 个 空 字 符 串 返 回 时 意 味 着 已
查 询 了 该 块 所 有 自 定 义 属 性 。 .
自 定 义 属 性 的 命 名 空 间 为 了 在 对 不 同 的 源 的 PDF 文 档 进 行 交 换 时 避 免 混 淆 , 建 议 在 所 有
自 定 义 属 性 名 称 中 使 用 Internet 域 名 作 为 公 司 特 定 的 前 缀 , 紧 跟 冒 号 “:” 和 实 际 属 性 名
称 。 例 如 , ACME 公 司 应 使 用 以 下 属 性 名 称 :
acme.com:digits
acme.com:refnumber
由 于 标 准 属 性 和 自 定 义 属 性 是 按 照 不 同 方 式 在 块 中 存 储 , 所 以 标 准 PDFlib 属 性 名 称 ( 在
第 138 页 上 的 第 6.4 节 “ 用 于 自 动 化 处 理 的 标 准 属 性 ” 中 定 义 ) 将 决 不 会 与 自 定 义 属 性 名
称 起 冲 突 。
6.6 PDFlib 块 规 格
PDFlib 块 语 法 完 全 符 合 PDF 引 用 , 该 引 用 指 定 一 个 扩 展 机 制 , 此 机 制 允 许 应 用 程 序 存 储 附
加 到 包 含 一 个 PDF 页 的 数 据 结 构 的 私 人 数 据 。 下 面 提 供 PDFlib 块 语 法 的 具 体 描 述 , 以 方 便
一 些 用 户 想 通 过 PDFlib 块 增 效 工 具 之 外 的 方 式 建 立 PDFlib 块 。 对 于 使 用 PDFlib 增 效 工 具
的 用 户 , 可 跳 过 此 章 节 。
6.6.1 PDFlib 块 的 PDF 对 象 结 构
PDF 页 字 典 包 含 了 /PieceInfo 项 , 其 值 将 指 向 另 一 个 字 典 。 此 字 典 含 有 /PDFlib 项 , 其 值 指 向
一 个 应 用 程 序 数 据 字 典 。 此 应 用 程 序 数 据 字 典 包 含 表 6.10 中 列 出 的 两 个 标 准 项 。
表 6.10 PDFlib 应 用 程 序 数 据 字 典 项
项 类 型 值
LastModified date string ( 必 需 的 ) 有 关 页 上 的 块 创 建 或 最 近 被 修 改 的 日 期 和 时 间 。
Private dictionary ( 必 需 的 ) 块 列 表 ( 请 参 见 表 6.11)
块 列 表 是 一 个 包 含 与 块 处 理 相 关 的 常 规 信 息 及 当 前 页 所 有 块 的 字 典 。 表 6.11 列 出 了 块 列 表
字 典 中 的 项 。
表 6.11 块 列 表 字 典 中 的 项
项 类 型 值
Version number ( 必 需 的 ) 文 件 要 遵 从 的 块 规 格 的 版 本 号 。 此 文 档 说 明 块 规 格 的 版 本 6。
Blocks dictionary ( 必 需 的 ) 每 个 项 都 是 一 个 包 含 块 的 名 称 的 名 称 对 象 ; 相 应 的 值 是 用 于 此 块 的 块
字 典 ( 请 参 见 表 6.13)。 块 字 典 中 的 /Name 项 必 须 与 此 字 典 中 的 块 的 名 称 一 致 。
PluginVersion string ( 必 需 的 , 除 非 pdfmark 项 存 在 1 ) 包 含 PDFlib 块 增 效 工 具 的 版 本 识 别 的 字 符
串 , 该 增 效 工 具 已 用 于 创 建 块 。
pdfmark boolean ( 必 需 的 , 除 非 PluginVersion 项 存 在
) 若 块 列 表 是 用 pdfmarks 生 成 的 , 则 此
值 必 须 为 true。
1. PluginVersion 和 pdfmark 这 两 项 中 必 须 有 一 个 项 存 在 。
146 第 6 章 : 数 据 变 量 和 块

块 属 性 的 数 据 类 型 属 性 支 持 相 同 的 数 据 类 型 作 为 选 项 列 表 ( 请 参 见 第 168 页 上 的 第 8.1.2
节 “ 选 项 列 表 ”), 句 柄 和 操 作 列 表 除 外 。 表 6.12 详 细 记 录 这 些 类 型 如 何 映 射 为 PDF 数 据 类
型 。
表 6.12 用 于 块 属 性 的 数 据 类 型
块 类 型 PDF 类 型 备 注
boolean boolean
string string
keyword name 提 供 特 殊 属 性 支 持 的 关 键 字 的 列 表 之 外 的 关 键 字 是 错 误 的 。
float, integer number 选 项 列 表 支 持 点 和 逗 号 作 为 十 进 制 分 隔 符 , 而 PDF 数 字 仅 支 持 小 数 点 。
percentage array with 数 组 中 的 第 一 个 元 素 是 数 字 , 第 二 个 元 素 是 含 有 百 分 比 符 号 的 字 符 串 。
two elements
color array with
two elements
数 组 中 的 第 一 个 元 素 指 定 一 个 色 彩 空 间 , 第 二 个 元 素 指 定 一 个 色 彩 值 , 如 下 所
示 。 数 组 中 的 第 一 个 元 素 支 持 以 下 项 :
/DeviceGray
第 二 个 元 素 是 单 个 灰 度 值 。
/DeviceRGB
第 二 个 元 素 是 含 有 三 个 元 素 (RGB 值 ) 的 数 组 。
/DeviceCMYK
第 二 个 元 素 是 含 有 四 个 元 素 (CMYK 值 ) 的 数 组 。
[/Separation/spotname]
第 一 个 元 素 是 一 个 含 有 关 键 字 /Separation 和 颜 色 名 称 的 数 组 。 第 二
个 元 素 是 一 个 淡 色 值 。
[/Lab] 第 一 个 元 素 是 包 含 关 键 字 /Lab 的 数 组 。 第 二 个 元 素 是 一 个 含 有 三 个
元 素 (Lab 值 ) 的 数 组 。
若 要 指 定 不 使 用 某 种 颜 色 , 必 须 省 略 相 应 的 属 性 。
块 字 典 项 块 字 典 可 能 包 含 表 6.13 中 的 项 。 根 据 常 规 组 中 的 /Subtype 项 , 仅 可 能 存 在 某 一
文 本 、 图 像 或 PDF 组 中 的 项 ( 请 参 见 表 6.4)。
表 6.13 块 字 典 中 的 项
项 类 型 值
常 规 属 性
( 其 中 的 一 些 项 是 必 需 的 ) 根 据 表 6.4 的 常 规 属 性
text 属 性
image 属 性
( 可 选 的 ) 根 据 表 6.5 和 表 6.6 的 Text 和 textflow 属 性
( 可 选 的 ) 根 据 表 6.7 的 Image 属 性
PDF 属 性
( 可 选 的 ) 根 据 表 6.8 的 PDF 属 性
Custom dict ( 可 选 的 ) 一 个 含 有 自 定 义 属 性 选 项 及 其 相 应 值 的 字 典 ( 根 据 表 6.9)。
Internal dict ( 可 选 的 ) 保 留 此 项 以 供 私 人 使 用 , 且 应 用 程 序 不 应 依 赖 于 此 项 的 存 在 或 特 定
的 行 为 。 目 前 , 此 项 用 于 维 护 转 换 的 表 单 域 和 相 应 的 块 之 间 的 关 系 。
示 例 以 下 片 段 显 示 用 于 两 个 块 的 PDF 代 码 , 这 两 个 块 分 别 为 称 作 job_title 的 文 本 块 和 称
作 logo 的 图 像 块 。 文 本 块 包 含 称 作 format 的 自 定 义 属 性 :
>
/Contents 12 0 R
/Type /Page
/Parent 1 0 R
/MediaBox [ 0 0 595 842 ]
/PieceInfo >
6.6 PDFlib 块 规 格 147

13 0 obj
>
/LastModified (D:20050813200730)
>>
endobj
14 0 obj
>>
endobj
15 0 obj
>
6.6.2 利 用 pdfmarks 生 成 PDFlib 块
作 为 使 用 增 效 工 具 创 建 PDFlib 块 的 一 个 替 换 , 可 以 通 过 将 适 当 的 pdfmark 命 令 插 入
PostScript 流 并 将 其 制 作 为 PDF 来 生 成 块 。 有 关 pdfmark 运 算 符 的 详 细 信 息 将 在 Acrobat
文 件 中 讨 论 。 以 下 片 段 显 示 前 一 节 中 可 用 于 生 成 块 定 义 的 pdfmark 运 算 符 :
% ---------- Setup for the blocks on a page ----------
[/_objdef {B1} /type /dict /OBJ pdfmark % Blocks dict
[{ThisPage}
>>
>> /PUT pdfmark
148 第 6 章 : 数 据 变 量 和 块

% ---------- text block ----------
[{B1} >
>> /PUT pdfmark
% ---------- image block ----------
[{B1}
>> /PUT pdfmar
6.6 PDFlib 块 规 格 149

150 第 6 章 : 数 据 变 量 和 块

7 生 成 各 种 风 格 的 PDF
7.1 Acrobat 和 PDF 版 本
按 照 用 户 的 选 项 ,PDFlib 可 生 成 PDF 1.3 (Acrobat 4)、PDF 1.4 (Acrobat 5)、PDF 1.5 (Acrobat 6)
或 PDF 1.6 (Acrobat 7) 的 文 件 。 可 使 用 PDF_begin_document( ) 中 的 compatibility 选 项 控 制 生
成 文 件 的 版 本 。
用 于 PDF 1.4 或 更 高 版 本 的 PDFlib 功 能 在 PDF 1.3 兼 容 模 式 下 , 将 无 法 使 用 PDFlib 针 对
PDF 1.4( 参 见 表 7.1) 和 PDF 1.5 ( 参 见 表 7.2) 而 设 计 的 功 能 。 在 PDF 1.3 模 式 下 尝 试 使 用 这
些 功 能 会 导 致 异 常 。
表 7.1 无 法 在 PDF 1.3 兼 容 模 式 下 使 用 的 、 用 于 PDF 1.4 的 PDFlib 功 能
功 能
PDFlib API 函 数 和 参 数
平 滑 着 色 ( 颜 色 混 合 ) PDF_shading_pattern( ), PDF_shfill( ), PDF_shading( )
软 蒙 版
PDF_ load_image( ), 带 有 指 向 像 素 深 度 大 于 1 位 的 图 像 的 masked 选 项
128 位 加 密 PDF_begin_document( ), 带 有 userpassword、 masterpassword 和
permissions 选 项
扩 展 权 限 设 置 PDF_begin_document( ), 带 有 permissions 选 项 , 参 见 表 7.3
CJK 字 体 的 某 些 CMap PDF_load_font( ), 参 见 表 4.7
透 明 度 及 其 他 图 形 状 态 选 项 PDF_create_gstate( ), 带 有 alphaisshape、 blendmode、 opacityfill、
opacitystroke 和 textknockout 选 项
某 些 动 作 选 项 PDF_create_action( ), 参 见 表 8.49
某 些 注 释 选 项 PDF_create_annotation( ), 参 见 表 8.51
某 些 域 选 项 PDF_create_field( ) 和 PDF_create_fieldgroup( ), 参 见 表 8.52
标 签 PDF
PDF_begin_document( ) 中 的 tagged 选 项
用 于 PDF 1.5 或 更 高 版 本 的 PDFlib 输 出 功 能 在 PDF 1.3 或 1.4 兼 容 模 式 下 , 将 无 法 使 用
表 7.2 列 出 的 、 PDFlib 针 对 PDF 1.5 而 设 计 的 功 能 。 在 PDF 1.3 或 PDF 1.4 模 式 下 尝 试 使
用 这 些 功 能 会 导 致 异 常 。
表 7.2 无 法 在 PDF 1.3 或 1.4 兼 容 模 式 下 使 用 的 、 用 于 PDF 1.5 的 PDFlib 功 能
功 能
PDFlib API 函 数 和 参 数
某 些 域 选 项 PDF_create_field( ) 和 PDF_create_fieldgroup( ), 参 见 表 8.52
某 些 注 释 选 项 PDF_create_annotation( ), 参 见 表 8.51
扩 展 权 限 设 置 PDF_begin_document( ) 中 的 permissions=plainmetadata, 参 见 表 7.3
CJK 字 体 的 某 些 CMap PDF_load_font( ), 参 见 表 4.7
标 签 PDF 某 些 PDF_begin_item( ) 选 项 , 参 见 表 8.57 和 表 8.58
图 层
JPEG2000 图 像
PDF_define_layer( ), PDF_begin_layer( ), PDF_end_layer( ) 和
PDF_layer_dependency( )
PDF_load_image( ) 中 的 imagetype=jpeg2000
7.1 Acrobat 和 PDF 版 本 151

PDI 导 入 文 档 的 PDF 版 本 在 所 有 兼 容 模 式 下 , 只 能 用 PDI 导 入 兼 容 级 别 相 同 或 较 低 的
PDF 文 档 。 如 果 必 须 导 入 兼 容 级 别 较 高 的 PDF, 必 须 相 应 地 设 置 compatibility 选 项 , 参 见
第 122 页 上 的 第 5.2.3 节 “ 可 接 受 的 PDF 文 档 ”。
更 改 文 档 的 PDF 版 本 如 果 必 须 根 据 特 定 PDF 版 本 创 建 输 出 , 但 需 要 导 入 使 用 较 高 PDF 版
本 的 PDF, 您 必 须 将 文 档 转 换 为 所 需 的 较 低 PDF 版 本 , 然 后 才 能 用 PDI 导 入 这 些 文 档 。 可
使 用 Acrobat 完 成 转 换 ; 具 体 取 决 于 所 使 用 的 Acrobat 版 本 :
> Acrobat 7 : 可 以 使 用 高 级 、PDF 优 化 器 、 兼 容 版 本 将 文 件 另 存 为 PDF 1.3 至 PDF 1.6 格 式 。
> Acrobat 6: 可 以 使 用 文 件 、 减 少 文 件 大 小 ..., 将 文 件 另 存 为 PDF 1.3 至 PDF 1.5 格 式 。
> Acrobat 5: 可 使 用 callas software 开 发 的 附 加 增 效 工 具 ( 称 为 pdfSaveAs1.3), 将 文 档
1
转 换 为 PDF 1.3。 可 从 callas 网 站 上 下 载 功 能 完 全 的 演 示 版 本 。 因 为 有 些 版 本 的 PDF/X 要
求 PDF 1.3, 所 以 这 个 转 换 增 效 工 具 对 处 理 块 和 PDF/X 特 别 有 用 ( 参 见 第 134 页 上 的 “ 在
块 中 使 用 PDF/X” 和 第 155 页 上 的 第 7.4.2 节 “ 生 成 符 合 PDF/X 标 准 的 输 出 ”)。
7.2 加 密 PDF
7.2.1 PDF 安 全 性 的 优 缺 点
PDF 支 持 各 种 安 全 功 能 , 可 帮 助 保 护 文 档 的 内 容 。 这 些 功 能 基 于 使 用 对 称 加 密 的 Acrobat 标
准 加 密 处 理 程 序 。 Acrobat Reader 和 完 全 版 的 Acrobat 产 品 都 支 持 下 列 安 全 功 能 :
> 通 过 权 限 限 制 某 些 对 PDF 文 档 的 操 作 , 如 打 印 或 提 取 文 本 等 。
> 打 开 文 件 时 要 求 文 档 打 开 口 令 。
> 更 改 任 何 安 全 设 置 都 要 求 许 可 口 令 , 如 权 限 、 文 档 打 开 口 令 或 许 可 口 令 等 设 置 。 如 果 具
有 文 档 打 开 口 令 和 许 可 口 令 , 可 使 用 任 一 口 令 打 开 文 件 , 以 便 阅 读 或 打 印 。
如 果 文 件 具 有 文 档 打 开 口 令 、 许 可 口 令 或 任 何 权 限 限 制 设 置 , 则 表 明 文 件 是 加 密 的 。
破 解 受 保 护 的 PDF 文 档 保 护 文 档 使 用 的 加 密 密 钥 长 度 取 决 于 客 户 端 选 择 的 PDF 兼 容 级 别 :
> 对 于 1.3 及 较 低 的 PDF 版 本 ( 即 Acrobat 4), 密 钥 长 度 为 40 位 。
> 对 于 PDF 版 本 1.4 及 更 高 版 本 , 密 钥 长 度 为 128 位 。 这 要 求 Acrobat 5 或 更 高 版 本 。 对 于
PDF 1.5, 密 钥 长 度 同 样 为 128 位 , 但 采 用 的 加 密 方 法 略 有 不 同 ; 这 要 求 Acrobat 6。
大 家 都 知 道 , 用 于 对 称 加 密 的 40 位 密 钥 ( 如 PDF 中 使 用 的 密 钥 ) 不 是 很 安 全 。 实 际 上 , 使
用 公 开 出 售 的 破 解 软 件 , 可 以 通 过 强 力 攻 击 停 用 40 位 PDF 安 全 性 设 置 ; 根 据 口 令 的 长 度 和
质 量 , 可 能 需 要 数 天 或 数 周 时 间 。 为 了 最 大 程 度 提 高 安 全 性 , 我 们 建 议 采 取 以 下 措 施 :
> 尽 可 能 使 用 128 位 加 密 ( 即 PDF 1.4 兼 容 设 置 ) 。 这 要 求 该 文 档 的 所 有 用 户 都 使 用
Acrobat 5 或 更 高 版 本 。
> 口 令 长 度 至 少 应 包 含 六 个 字 符 , 且 应 包 含 非 字 母 字 符 。 口 令 不 应 与 配 偶 姓 名 、 宠 物 昵 称
或 生 日 等 类 似 , 以 防 止 所 谓 的 词 典 攻 击 或 口 令 猜 测 。 重 要 的 一 点 是 , 即 使 采 用 128 位 加
密 , 也 可 以 在 短 短 几 分 钟 内 破 解 较 短 的 口 令 。
访 问 权 限 设 置 禁 止 打 印 等 访 问 限 制 将 停 用 Acrobat 中 对 应 的 功 能 。 但 是 , 这 并 不 一 定 能 停
用 第 三 方 PDF 浏 览 器 或 其 他 软 件 的 相 关 功 能 。 是 否 遵 守 访 问 权 限 具 体 取 决 于 PDF 工 具 的 开
发 人 员 。 实 际 上 , 我 们 已 经 知 道 , 有 几 种 PDF 工 具 会 完 全 忽 略 权 限 设 置 ; 而 且 , 有 些 公 开
出 售 的 PDF 破 解 工 具 也 可 用 来 停 用 任 何 访 问 限 制 。 这 与 破 解 加 密 无 关 ; 目 前 没 有 办 法 在 保
持 PDF 文 件 可 以 查 看 的 同 时 , 确 保 不 被 打 印 。Adobe 自 己 的 《PDF Reference》 中 便 有 相 关
说 明 :
1. 参 见 www.callassoftware.com
152 第 7 章 : 生 成 各 种 风 格 的 PDF

PDF 加 密 本 身 不 能 执 行 加 密 词 典 中 规 定 的 文 档 权 限 。PDF 浏 览 器 的 实 施 者 可 自 行 决 定 , 是
否 尊 重 文 档 创 建 程 序 根 据 文 件 所 含 权 限 限 制 用 户 对 加 密 PDF 文 件 的 访 问 的 意 图 。
7.2.2 用 PDFlib 保 护 文 档
口 令 可 使 用 PDF_begin_document( ) 中 的 userpassword 和 masterpassword 选 项 设 置 口
令 。 PDFlib 与 客 户 端 提 供 的 口 令 的 交 互 方 式 如 下 :
> 如 果 提 供 了 文 档 打 开 口 令 或 权 限 ( 参 见 下 文 ), 但 没 有 提 供 许 可 口 令 , 则 一 般 用 户 将 能
够 更 改 安 全 性 设 置 。 因 此 , PDFlib 会 认 为 这 种 情 况 是 个 错 误 。
> 如 果 文 档 打 开 口 令 和 许 可 口 令 相 同 , 将 无 法 区 分 文 件 的 用 户 和 所 有 者 ; 这 同 样 不 能 有 效
地 保 护 文 档 。 PDFlib 会 认 为 这 种 情 况 是 个 错 误 。
> 对 于 文 档 打 开 口 令 和 许 可 口 令 , 最 多 可 使 用 32 个 字 符 。 多 余 的 字 符 将 被 忽 略 , 但 不 影 响
加 密 效 果 。 不 允 许 空 口 令 。
提 供 的 口 令 将 用 于 此 后 生 成 的 所 有 文 档 。
口 令 中 的 非 ASCII 字 符 在 口 令 中 使 用 0x20 至 0x7E 范 围 以 外 的 字 符 时 , 应 特 别 注 意 ; 传
统 ASCII 字 符 集 不 包 括 这 些 字 符 。 例 如 , 在 口 令 中 使 用 字 符 Ä。 在 Mac 上 , 该 字 符 的 代 码 是
0x80 ; 而 在 Windows 上 , 它 的 代 码 是 0xC4。 因 为 用 户 希 望 在 两 个 平 台 上 都 可 以 使 用 口 令
Ä 打 开 文 件 , 所 以 Acrobat 会 在 应 用 口 令 之 前 将 提 供 的 口 令 转 换 为 一 种 内 部 编 码 ( 称 为
PDFDocEncoding) 。 此 编 码 中 不 包 括 的 字 符 将 映 射 到 空 格 字 符 。 PDFDocEncoding 包 含
Mac 和 Windows 平 台 的 所 有 字 符 , 但 要 求 对 几 个 字 符 进 行 转 换 。 在 以 上 示 例 中 , 用 户 在
Mac 上 使 用 口 令 Ä 加 密 文 件 时 , 如 果 直 接 使 用 Ä 的 代 码 ,PDI 将 不 能 解 密 文 件 。 因 此 ,PDI
会 应 用 与 Acrobat 相 同 的 口 令 转 换 , 以 确 保 成 功 解 密 用 Mac 或 Windows 版 Acrobat 加 密 的
文 件 。 解 密 过 程 中 , PDI 将 自 动 检 测 所 需 的 转 换 :
> 如 果 文 档 使 用 Windows 上 的 Acrobat 或 者 PDFlib PLOP 2.1 或 更 高 版 本 加 密 , 将 进 行
WinAnsi 到 PDFDocEncoding 的 转 换 ;
> 如 果 文 档 使 用 Mac 上 的 Acrobat 加 密 , 则 进 行 MacRoman 到 PDFDocEncoding 的 转 换 ;
> 如 果 文 档 使 用 其 他 软 件 加 密 , 则 不 进 行 转 换 ; 这 包 括 PDFlib PLOP 2.0( 但 不 包 括 任 何 更
新 的 版 本 )。
加 密 文 件 时 ,PDFlib 会 像 Windows 上 的 Acrobat 那 样 , 用 WinAnsi 编 码 解 释 提 供 的 口 令 ,
即 : 它 将 对 提 供 的 文 档 打 开 口 令 和 许 可 口 令 应 用 WinAnsi 到 PDFDocEncoding 的 转 换 ; 在
EBCDIC 平 台 上 , 它 将 在 这 之 前 应 用 EBCDIC 到 WinAnsi 的 转 换 。
权 限 可 以 使 用 PDF_begin_document( ) 中 的 permissions 选 项 设 置 访 问 限 制 。 它 包 含 一 个 或
多 个 访 问 限 制 关 键 字 。 设 置 permissions 选 项 时 , 必 须 同 时 设 置 masterpassword 选 项 ; 这 是
因 为 , 如 不 同 时 设 置 ,Acrobat 用 户 很 容 易 就 能 删 除 权 限 设 置 。 默 认 情 况 下 , 允 许 所 有 动 作 。
指 定 访 问 限 制 将 停 用 Acrobat 中 相 应 的 功 能 。 无 需 任 何 文 档 打 开 口 令 便 可 应 用 访 问 限 制 。 如
以 下 示 例 所 示 , 可 以 指 定 多 个 限 制 关 键 字 :
PDF_begin_document(p, filename, 0, "permissions {noprint nocopy}");
表 7.3 列 出 了 所 有 支 持 的 访 问 限 制 关 键 字 。 如 表 中 的 详 细 信 息 所 述 , 有 些 关 键 字 要 求 兼 容
PDF 1.4 或 更 高 版 本 。 如 果 PDF 输 出 版 本 过 低 , 它 们 将 被 拒 绝 。
表 7.3 PDF_begin_document( ) 中 permissions 选 项 的 访 问 限 制 关 键 字
关 键 字
说 明
noprint Acrobat 将 阻 止 打 印 文 件 。
nomodify Acrobat 将 阻 止 用 户 添 加 表 单 域 或 做 任 何 其 他 更 改 。
7.2 加 密 PDF 153

表 7.3 PDF_begin_document( ) 中 permissions 选 项 的 访 问 限 制 关 键 字
关 键 字
说 明
nocopy Acrobat 将 阻 止 复 制 或 提 取 文 本 或 图 形 , 并 将 停 用 辅 助 工 具 接 口 。
noannots Acrobat 将 阻 止 添 加 或 更 改 注 释 或 表 单 域 。
noforms (PDF 1.4) Acrobat 将 阻 止 填 充 表 单 域 ; 即 使 没 有 指 定 noannots, 也 是 如 此 。
noaccessible (PDF 1.4) Acrobat 将 阻 止 提 取 文 本 或 图 形 , 以 限 制 辅 助 工 具 ( 如 读 屏 器 程 序 )。
noassemble (PDF 1.4) 即 使 没 有 指 定 nomodify, Acrobat 也 将 阻 止 插 入 、 删 除 或 旋 转 页 面 的 操 作 ,
并 将 阻 止 创 建 书 签 和 缩 览 图 。
nohiresprint
(PDF 1.4) Acrobat 将 阻 止 高 分 辨 率 打 印 。 如 果 没 有 指 定 noprint, 则 只 能 使 用 “ 打 印 为
图 像 ” 功 能 ; 这 将 打 印 以 低 分 辨 率 呈 现 的 页 面 。
plainmetadata (PDF 1.5) 保 持 文 档 元 数 据 不 加 密 ; 即 使 加 密 文 档 , 也 是 如 此 。 在 这 里 , 是 指 XMP 元 数
据 相 关 , 与 文 档 信 息 域 元 数 据 无 关 。
7.3 网 页 优 化 的 ( 线 性 化 的 ) PDF
PDFlib 可 以 对 PDF 文 档 应 用 一 个 称 为 线 性 化 处 理 的 过 程 ( 在 Acrobat 4 中 , 线 性 化 的 PDF
称 为 优 化 , 在 Acrobat 5 和 更 高 版 本 中 称 为 快 速 Web 查 看 )。 线 性 化 处 理 可 重 新 组 织 PDF 文
件 内 的 对 象 , 并 添 加 可 用 来 提 高 访 问 速 度 的 补 充 信 息 。
非 线 性 化 的 PDF 必 须 完 全 传 送 到 客 户 端 , 而 Web 服 务 器 可 以 使 用 一 个 称 为 byteserving
的 过 程 传 送 线 性 化 的 PDF, 一 次 只 传 送 一 个 页 面 。 这 允 许 Acrobat( 作 为 浏 览 器 增 效 工 具 运
行 ) 单 独 检 索 PDF 文 档 的 各 个 部 分 。 因 此 , 不 必 等 待 从 服 务 器 下 载 整 个 文 档 , 即 可 向 用 户
显 示 文 档 的 第 一 个 页 面 。 这 样 可 增 强 用 户 的 体 验 。
请 注 意 , Web 服 务 器 向 浏 览 器 传 送 PDF 数 据 , 而 非 PDFlib。 而 PDFlib 负 责 准 备
byteserving 的 PDF 文 件 。 要 利 用 byteserving PDF, 必 须 满 足 下 列 所 有 要 求 :
> PDF 文 档 必 须 进 行 线 性 化 处 理 , 这 可 通 过 PDF_begin_document( ) 中 的 linearize 选 项 实
现 。 在 Acrobat 中 , 可 以 通 过 查 看 文 档 属 性 来 检 查 文 件 是 否 已 经 过 线 性 化 处 理 ; 具 体 属
性 是 快 速 Web 查 看 : 是 。
> Web 服 务 器 必 须 支 持 byteserving。 基 础 字 节 范 围 协 议 是 HTTP 1.1 的 一 部 分 , 因 此 所 有
最 新 版 Web 服 务 器 都 实 施 了 该 协 议 。 具 体 讲 , 下 列 Web 服 务 器 支 持 byteserving:
Microsoft Internet Information Server (IIS) 3.0 及 更 高 版 本
Apache 1.2.1 及 更 高 版 本 ; 但 是 Apache 1.3.14 ( 不 包 括 其 他 版 本 ) 存 在 一 个 错 误 , 会 阻 止
byteserving
> 用 户 必 须 作 为 浏 览 器 增 效 工 具 使 用 Acrobat, 并 在 Acrobat 中 启 用 “ 每 次 一 页 ” 下 载 方
式 (Acrobat 6: 编 辑 、 首 选 项 、 因 特 网 、 允 许 快 速 Web 查 看 ; Acrobat 5: 编 辑 、 首 选
项 、 常 规 ...、 选 项 、 允 许 快 速 Web 查 看 )。 请 注 意 , 默 认 启 用 该 选 项 。
通 过 Web 发 送 时 , PDF 文 件 越 大 ( 以 页 数 或 MB 值 来 衡 量 ), 就 越 能 发 挥 线 性 化 的 优 势 。
注 : 由 于 要 添 加 额 外 的 线 性 化 信 息 , 对 PDF 文 档 进 行 线 性 化 处 理 一 般 会 导 致 文 件 大 小 略 有 增 大 。
线 性 化 的 临 时 存 储 空 间 要 求 在 进 行 线 性 化 处 理 之 前 , PDFlib 必 须 创 建 整 个 文 档 ; 文 档
创 建 完 毕 后 , 必 须 作 为 单 独 的 步 骤 应 用 线 性 化 过 程 。 因 此 , PDFlib 对 线 性 化 有 额 外 的 存
储 要 求 。 要 求 的 临 时 存 储 空 间 大 体 相 当 于 生 成 文 档 的 大 小 ( 未 进 行 线 性 化 处 理 ) 。 根 据
PDF_begin_document( ) 中 的 inmemory 选 项 ,PDFlib 会 将 线 性 化 数 据 置 于 内 存 或 临 时 磁 盘
文 件 内 。
154 第 7 章 : 生 成 各 种 风 格 的 PDF

7.4 PDF/X
7.4.1 PDF/X 系 列 标 准
ISO 15930 标 准 系 列 规 定 的 PDF/X 格 式 旨 在 提 供 一 种 一 致 、 可 靠 的 PDF, 用 来 传 送 适 用 于 商
业 印 刷 的 数 据 1 。 PDFlib 能 够 根 据 以 下 PDF/X 版 本 生 成 输 出 并 处 理 输 入 。
ISO 15930-1 规 定 的 PDF/X-1:2001 和 PDF/X-1a:2001 这 些 用 于 “ 盲 交 换 ” 的 标 准 基 于
PDF 1.3, 并 支 持 CMYK 和 专 色 数 据 ; 所 谓 盲 交 换 , 就 是 在 交 换 印 刷 数 据 时 不 要 求 事 先 讨 论 任 何
技 术 问 题 。 这 些 标 准 明 确 禁 止 使 用 RGB 和 设 备 无 关 颜 色 ( 基 于 ICC,Lab)。PDF/X-1:2001 支 持
一 种 在 PDF 工 作 流 程 中 集 成 旧 文 件 ( 如 TIFF/IT) 的 机 制 ; 此 标 准 已 经 过 时 了 。 PDF/X-1a:2001
不 包 含 这 种 支 持 旧 文 件 的 功 能 , 被 广 泛 用 来 交 换 出 版 物 广 告 及 其 他 应 用 ( 尤 其 是 在 北 美 )。
ISO 15930-4 中 规 定 的 PDF/X-1a:2003 此 标 准 的 前 身 是 PDF/X-1a:2001。 它 基 于 PDF 1.4,
禁 止 使 用 某 些 功 能 ( 例 如 , 透 明 度 )。 PDF/X-1a:2003 完 全 包 括 在 PDF/X-3:2003 中 , 支 持
CMYK 和 专 色 , 以 及 CMYK 输 出 设 备 。
ISO 15930-5 中 规 定 的 PDF/X-2:2003 此 标 准 针 对 “ 部 分 交 换 ”; 这 种 交 换 方 式 要 求 文 件
的 提 供 方 和 接 收 方 事 先 讨 论 相 关 技 术 问 题 。 根 据 此 标 准 , PDF 文 档 可 以 引 用 外 部 实 体 ( 指
向 当 前 文 档 外 部 的 PDF 页 面 )。PDF/X-2:2003 基 于 PDF 1.4。 作 为 PDF/X-3:2003 的 扩 展 , 它
支 持 设 备 无 关 颜 色 。
ISO 15930-3 中 规 定 的 PDF/X-3:2002 此 标 准 基 于 PDF 1.3 ; 除 灰 度 、 CMYK 和 专 色 之 外 ,
它 还 支 持 基 于 设 备 无 关 颜 色 的 现 代 工 作 流 程 。 此 标 准 在 欧 洲 国 家 / 地 区 尤 为 盛 行 。 输 出 设 备
可 以 采 用 单 色 、 RGB 或 CMYK。
ISO 15930-6 中 规 定 的 PDF/X-3:2003 此 标 准 的 前 身 是 PDF/X-3:2002。 它 基 于 PDF 1.4,
禁 止 使 用 某 些 功 能 ( 例 如 , 透 明 度 )。
如 下 文 引 用 的 PDF/X 标 准 没 有 带 任 何 标 准 颁 布 年 份 信 息 , 则 指 该 标 准 的 所 有 版 本 。 例 如 ,
PDF/X-3 指 PDF/X-3:2002 和 PDF-X/3:2003。
注 : PDF/X-1:2001、 PDF/X-1a:2001 和 PDF/X-1a:2003 模 式 不 支 持 PANTONE® 颜 色 。
7.4.2 生 成 符 合 PDF/X 标 准 的 输 出
可 通 过 以 下 方 法 , 使 用 PDFlib 创 建 符 合 PDF/X 标 准 的 输 出 :
> PDFlib 将 自 动 完 成 几 种 正 式 的 PDF/X 设 置 , 如 PDF 版 本 号 和 PDF/X 规 范 等 级 密 钥 等 。
> PDFlib 客 户 端 必 须 明 确 使 用 表 7.4 中 列 出 的 某 些 函 数 调 用 或 参 数 设 置 。
> PDFlib 客 户 端 不 能 使 用 表 7.5 中 列 出 的 某 些 函 数 调 用 和 参 数 设 置 。
> 从 现 有 符 合 PDF/X 标 准 的 文 档 中 导 出 页 面 时 , 还 应 遵 守 其 他 规 则 ( 参 见 第 158 页 上 的
第 7.4.3 节 “ 用 PDI 导 入 PDF/X 文 档 ”)。
要 求 的 操 作 表 7.4 列 出 了 生 成 PDF/X 兼 容 输 出 要 求 的 所 有 操 作 。 除 非 另 有 说 明 , 否 则 其 中
列 出 的 各 项 操 作 均 适 用 于 所 有 PDF/X 规 范 等 级 。 处 于 PDF/X 模 式 下 时 , 如 果 不 调 用 要 求 的
函 数 , 将 触 发 异 常 。
禁 止 的 操 作 表 7.5 列 出 了 在 生 成 PDF/X 兼 容 输 出 时 所 有 禁 止 使 用 的 操 作 。 除 非 另 有 说 明 ,
否 则 其 中 列 出 的 各 项 操 作 均 适 用 于 所 有 PDF/X 规 范 等 级 。 处 于 PDF/X 模 式 下 时 , 调 用 禁 止
1. 请 参 见 www.pdfx3.org 和 www.pdf-x.com
7.4 PDF/X 155

表 7.4 实 现 PDF/X 兼 容 性 必 须 执 行 的 操 作
项 目
实 现 PDF/X 兼 容 性 的 PDFlib 函 数 和 参 数 要 求
规 范 等 级 PDF_begin_document( ) 中 的 pdfx 选 项 必 须 设 为 要 求 的 PDF/X 规 范 等 级 。
输 出 条 件
( 输 出 方 法 )
在 PDF_begin_document( ) 之 后 , 必 须 立 即 调 用 usage=outputintent 的
PDF_load_iccprofile( ) 或 action=copyoutputintent 的 PDF_process_pdi( )。 如 果 使 用 HKS
或 Pantone 专 色 、 基 于 ICC 的 颜 色 或 Lab 颜 色 , 则 必 须 嵌 入 输 出 设 备 的 ICC 配 置 文 件 ;
这 种 情 况 下 , 不 允 许 使 用 标 准 的 输 出 条 件 。 PDF/X-1 和 PDF/X-1a: 输 出 设 备 必 须 为 单 色
或 CMYK 设 备 ; PDF/X-3: 输 出 设 备 必 须 为 单 色 、 RGB 或 CMYK 设 备 。
字 体 嵌 入 将 PDF_load_font( ) 的 embedding 选 项 设 为 true, 启 用 字 体 嵌 入 。
页 面 大 小 页 面 框 可 通 过 裁 剪 框 、 出 血 框 、 裁 切 框 和 作 品 框 参 数 设 置 , 必 须 满 足 以 下 要 求 :
> 必 须 设 置 裁 切 框 或 作 品 框 , 但 不 能 同 时 设 置 这 两 个 框 条 目 。 如 果 既 没 有 裁 切 框 也 没
有 作 品 框 , 若 裁 剪 框 存 在 , PDFlib 将 其 作 为 裁 切 框 , 否 则 将 媒 体 框 作 为 裁 切 框 。
> 出 血 框 ( 如 果 有 ) 必 须 完 全 包 含 作 品 框 和 裁 切 框 。
> 裁 剪 框 ( 如 果 有 ) 必 须 完 全 包 含 作 品 框 和 裁 切 框 。
灰 度 颜 色
RGB 颜 色
CMYK 颜 色
PDF/X-3: 如 果 使 用 灰 度 图 像 , 或 者 PDF_setcolor( ) 使 用 灰 度 色 彩 空 间 , 并 且 PDF/X 输
出 条 件 不 是 CMYK 或 灰 度 设 备 , 则 必 须 设 置 PDF_begin_page_ext( ) 中 的 defaultgray
选 项 。
PDF/X-3: 如 果 使 用 RGB 图 像 , 或 者 PDF_setcolor( ) 使 用 RGB 色 彩 空 间 , 并 且 PDF/X 输
出 条 件 不 是 RGB 设 备 , 则 必 须 设 置 PDF_begin_page_ext( ) 中 的 defaultrgb 选 项 。
PDF/X-3: 如 果 使 用 CMYK 图 像 , 或 者 PDF_setcolor( ) 使 用 CMYK 色 彩 空 间 , 并 且 PDF/X
输 出 条 件 不 是 CMYK 设 备 , 则 必 须 设 置 PDF_begin_page_ext( ) 中 的 defaultcmyk 选 项 。
文 档 信 息 关 键 字 必 须 用 PDF_set_info( ) 设 置 Creator 和 Title 信 息 关 键 字 。
的 函 数 将 触 发 异 常 。 但 是 , 根 据 imagewarning 参 数 的 设 置 , 不 可 接 受 的 图 像 可 能 不 会 导 致
异 常 。 同 样 , 如 果 导 入 的 PDF 页 面 不 匹 配 当 前 PDF/X 规 范 等 级 , 对 应 的 PDI 调 用 将 失 败 ,
而 不 触 发 异 常 ( 具 体 取 决 于 pdiwarning 参 数 )。
表 7.5 实 现 PDF/X 兼 容 性 必 须 避 免 的 操 作
项 目
实 现 PDF/X 兼 容 性 应 避 免 的 PDFlib 函 数 和 参 数
灰 度 颜 色 PDF/X-1 和 PDF/X-1a: 必 须 避 免 使 用 PDF_begin_page_ext( ) 中 的 defaultgray 选 项 。
RGB 颜 色
PDF/X-1 和 PDF/X-1a: 必 须 避 免 使 用 RGB 图 像 和 PDF_begin_page_ext( ) 中 的 defaultrgb
选 项 。
CMYK 颜 色 PDF/X-1 和 PDF/X-1a: 必 须 避 免 使 用 PDF_begin_page_ext( ) 中 的 defaultcmyk 选 项 。
基 于 ICC 的 颜 色 PDF/X-1 和 PDF/X-1a: 必 须 避 免 使 用 PDF_setcolor( ) 中 的 iccbasedgray/rgb/cmyk 色 彩 空
间 以 及 setcolor:iccprofilegray/rgb/cmyk 参 数 。
Lab 颜 色 PDF/X-1 和 PDF/X-1a: 必 须 避 免 使 用 PDF_setcolor( ) 中 的 Lab 色 彩 空 间 。
注 释 和 表 单 域
动 作 和 JavaScript
图 像
透 明 度
查 看 程 序 首 选 项 /
浏 览 和 打 印 区 域
必 须 避 免 在 出 血 框 内 使 用 注 释 ( 如 果 没 有 出 血 框 , 应 避 免 在 裁 切 框 / 作 品 框 内 使 用 注
释 ):PDF_create_annotation( )、 PDF_create_field( ) 及 相 关 的 已 淘 汰 的 函 数 。
必 须 避 免 使 用 任 何 包 括 JavaScript 的 动 作 :PDF_create_action( ) 及 相 关 的 已 淘 汰 的 函 数
PDF/X-1 和 PDF/X-1a: 必 须 避 免 使 用 带 RGB、 基 于 ICC、 YCbCr 或 Lab 颜 色 的 图 像 。 对
于 着 色 图 像 , 用 来 替 代 专 色 的 颜 色 必 须 满 足 相 同 的 条 件 。
必 须 避 免 PDF_load_image( ) 中 的 OPI-1.3 和 OPI-2.0 选 项 。
必 须 避 免 对 图 像 使 用 软 蒙 版 : 除 非 蒙 版 指 向 1 位 图 像 , 否 则 必 须 避 免 使 用
PDF_load_image( ) 的 mask 选 项 。
除 非 设 置 的 值 为 1, 否 则 必 须 避 免 使 用 PDF_create_gstate( ) 的 opacityfill 和
opacitystroke 选 项 。
对 PDF_set_parameter( ) 使 用 viewarea、 viewclip、 printarea 和 printclip 关 键 字 时 ,
不 允 许 使 用 除 media 或 bleed 之 外 的 其 他 值 。
文 档 信 息 关 键 字 必 须 避 免 对 PDF_set_info( ) 使 用 除 True 或 False 之 外 的 Trapped 信 息 关 键 字 。
156 第 7 章 : 生 成 各 种 风 格 的 PDF

表 7.5 实 现 PDF/X 兼 容 性 必 须 避 免 的 操 作
项 目
安 全 性 PDF/X-1 ( 而 非 PDF/X-1a): 必 须 避 免 使 用 userpassword 选 项 及 PDF_begin_document( )
中 permissions 选 项 的 值 noprint。
PDF/X-1a 和 PDF/X-3: 必 须 避 免 使 用 PDF_begin_document( ) 中 的 userpassword、
masterpassword 和 permissions 选 项 。
PDF 版 本 / 兼 容 性
PDF 导 入 (PDI)
实 现 PDF/X 兼 容 性 应 避 免 的 PDFlib 函 数 和 参 数
在 调 用 PDF_begin_document( ) 函 数 时 , 由 于 PDFlib 会 自 动 完 成 compatibility 选 项 的
填 写 , 所 以 应 必 须 避 免 使 用 compatibility 选 项 ( 有 关 不 同 PDF 版 本 中 各 功 能 的 详 细
信 息 , 参 见 表 7.1 和 表 7.2)。
PDF/X-1:2001、 PDF/X-1a:2001 和 PDF/X-3:2002 都 基 于 PDF 1.3。 必 须 避 免 使 用 要 求
PDF 1.4 或 更 高 版 本 的 操 作 , 例 如 透 明 度 或 软 蒙 版 。
PDF/X-1a:2003、 PDF/X-2:2003 和 PDF/X-3:2003 都 基 于 PDF 1.4。 必 须 避 免 使 用 要 求
PDF 1.5 的 操 作 , 例 如 图 层 。
导 入 的 文 档 必 须 遵 守 与 输 出 文 档 相 同 的 PDF/X 等 级 , 且 必 须 已 根 据 相 同 的 输 出 方 法 做
了 预 先 处 理 。
标 准 输 出 条 件 输 出 条 件 可 定 义 预 期 的 目 标 设 备 , 这 主 要 用 于 实 现 可 靠 的 校 样 。 输 出 方 法 可
由 ICC 配 置 文 件 指 定 , 也 可 通 过 提 供 标 准 输 出 方 法 的 名 称 指 定 。 表 7.6 列 出 了 PDFlib 已 知 的
标 准 输 出 方 法 名 称 。 可 使 用 StandardOutputIntent 资 源 类 别 定 义 其 他 标 准 输 出 方 法 ( 参 见
第 49 页 上 的 第 3.1.5 节 “ 资 源 配 置 和 文 件 搜 索 ”)。 用 户 应 确 保 只 添 加 PDF/X 处 理 软 件 能 够
识 别 的 标 准 输 出 方 法 名 称 。 可 通 过 以 下 方 式 引 用 标 准 输 出 方 法 :
PDF_load_iccprofile(p, "CGATS TR 001", 0, "usage outputintent");
创 建 PDF/X-3 输 出 或 者 使 用 任 何 HKS、Pantone、Lab 颜 色 或 基 于 ICC 的 颜 色 时 , 不 允 许 使
用 标 准 输 出 方 法 , 但 必 须 嵌 入 输 出 设 备 的 ICC 配 置 文 件 。
表 7.6 PDF/X 的 标 准 输 出 方 法
输 出 方 法
CGATS TR 001
描 述
美 国 SWOP ( 出 版 物 ) 印 刷
OF COM PO P1 F60 ISO 12647-2、 阳 图 版 、 1 型 纸 ( 光 亮 铜 版 纸 )
OF COM PO P2 F60 ISO 12647-2、 阳 图 版 、 2 型 纸 ( 粗 面 铜 版 纸 )
OF COM PO-P3 F60 1
ISO 12647-2、 阳 图 版 、 3 型 纸 ( 低 克 重 铜 版 卷 筒 纸 )
OF COM PO P4 F60 ISO 12647-2、 阳 图 版 、 4 型 纸 ( 白 色 胶 印 胶 版 纸 )
OF COM NE P1 F60 ISO 12647-2、 阴 图 版 、 1 型 纸 ( 光 亮 铜 版 纸 )
OF COM NE P2 F60 ISO 12647-2、 阴 图 版 、 2 型 纸 ( 粗 面 铜 版 纸 )
OF COM NE P3 F60 ISO 12647-2、 阴 图 版 、 3 型 纸 ( 低 克 重 铜 版 卷 筒 纸 )
OF COM NE P4 F60 ISO 12647-2、 阴 图 版 、 4 型 纸 ( 白 色 胶 印 胶 版 纸 )
SC GC2 CO F30
ISO 12647-5、 2 类 色 域 、 传 统 紫 外 线 或 水 性 风 干 纸
Ifra_NP_40lcm_neg+CTP_05.00 冷 凝 胶 版 印 刷 ( 计 算 机 直 接 制 版 )
1. 尽 管 P0 与 P3 间 的 破 折 号 看 上 去 不 太 一 样 , 这 实 际 上 是 标 准 规 定 的 要 求 。
7.4 PDF/X 157

7.4.3 用 PDI 导 入 PDF/X 文 档
将 现 有 PDF 文 档 中 的 页 面 导 入 PDF/X 兼 容 输 出 文 档 时 , 有 一 些 特 殊 规 则 ( 有 关 PDF 导 入 库
PDI 的 详 细 信 息 , 参 见 第 121 页 上 的 第 5.2 节 “ 使 用 PDI (PDF 导 入 库 ) 生 成 PDF 页 ”)。 所
有 导 入 的 文 档 都 必 须 遵 守 可 接 受 的 PDF/X 规 范 级 别 , 具 体 参 见 表 7.7。 作 为 一 条 通 行 规 则 ,
可 以 接 受 遵 守 与 生 成 输 出 文 档 相 同 的 PDF/X 规 范 级 别 或 同 一 级 别 的 较 低 版 本 的 输 入 文 档 。
此 外 , 也 可 接 受 某 些 其 他 组 合 。 如 果 在 PDFlib 中 配 置 了 某 个 PDF/X 规 范 级 别 , 且 导 入 文 档
遵 守 某 个 可 接 受 的 级 别 , 则 可 以 保 证 生 成 的 输 出 文 档 遵 守 选 定 的 PDF/X 规 范 级 别 。 不 遵 守
某 一 可 接 受 的 PDF/X 级 别 的 导 入 文 档 将 被 拒 绝 。
表 7.7 各 种 PDF/X 输 出 级 别 可 以 接 受 的 PDF/X 输 入 级 别 ; 必 须 避 免 采 用 其 他 组 合 。
导 入 文 档 的 PDF/X 级 别
PDF/X 输 出 级 别 PDF/X-1:2001 PDF/X-1a:2001 PDF/X-1a:2003 PDF/X-2:2003 PDF/X-3:2002 PDF/X-3:2003
PDF/X-1:2001 允 许 允 许
PDF/X-1a:2001
允 许
PDF/X-1a:2003 允 许 允 许
PDF/X-2:2003 允 许 允 许 允 许 允 许 允 许
PDF/X-3:2002 允 许 允 许
PDF/X-3:2003 允 许 允 许 允 许 允 许
如 果 要 导 入 多 个 PDF/X 文 档 , 则 必 须 根 据 相 同 的 输 出 条 件 准 备 这 些 文 档 。 尽 管 PDFlib 能 够
纠 正 某 些 项 目 , 但 它 并 非 为 完 全 校 验 PDF/X 而 设 计 的 , 也 不 会 强 制 导 入 文 档 完 全 的 兼 容
PDF/X。 例 如 , PDFlib 不 会 嵌 入 导 入 PDF 页 面 中 缺 失 的 字 体 , 也 不 会 对 导 入 的 页 面 进 行 任
何 颜 色 校 正 。
如 果 希 望 合 并 导 入 的 页 面 , 以 使 生 成 的 PDF 输 出 文 档 遵 守 与 输 入 文 档 相 同 的 PDF/X 规 范
级 别 和 输 出 条 件 , 可 查 询 导 入 PDF 的 PDF/X 状 态 , 具 体 如 下 :
pdfxlevel = PDF_get_pdi_parameter(p, "pdfx", doc, -1, 0, &len);
如 果 遵 守 某 个 ISO PDF/X 级 别 , 此 语 句 将 检 索 指 示 导 入 文 档 PDF/X 规 范 级 别 的 字 符 串 ; 否
则 , 将 返 回 none。 返 回 的 字 符 串 可 用 来 适 当 地 设 置 输 出 文 档 的 PDF/X 规 范 级 别 , 具 体 使 用
PDF_begin_document( ) 中 的 pdfx 选 项 。
除 查 询 PDF/X 规 范 级 别 之 外 , 还 可 以 复 制 导 入 文 档 中 的 PDF/X 输 出 方 法 , 具 体 如 下 :
ret = PDF_process_pdi(p, doc, -1, "action copyoutputintent");
PDF_load_iccprofile( ) 设 置 输 出 方 法 的 一 种 替 代 方 式 , 并 可 以 将 导 入 文 档 的 输 出 方 法 复 制 到
生 成 的 输 入 文 档 中 , 而 不 考 虑 输 出 方 法 是 用 标 准 名 称 还 是 ICC 配 置 文 件 定 义 的 。 生 成 输 出 文
档 的 输 出 方 法 必 须 一 次 设 置 完 成 , 可 以 将 复 制 导 入 文 档 的 输 出 方 法 , 也 可 以 使 用 usage 选 项
设 置 为 outputintent 的 PDF_load_iccprofile( ) 来 明 确 设 置 输 出 方 法 。
7.5 标 签 PDF
标 签 PDF 是 一 种 增 强 型 PDF, 可 支 持 PDF 浏 览 器 的 其 他 工 具 , 例 如 : 辅 助 功 能 的 支 持 、 文
本 重 排 、 可 靠 的 文 本 提 取 以 及 将 文 档 转 换 为 RTF 或 XML 等 其 他 格 式 。
PDFlib 支 持 标 签 PDF 的 生 成 。 但 是 , 只 有 客 户 端 在 生 成 PDF 输 出 时 提 供 文 档 内 部 结 构 的
相 关 信 息 并 遵 守 某 些 规 则 的 情 况 下 , 才 能 创 建 标 签 PDF。
注 : PDFlib 目 前 不 支 持 自 定 义 结 构 元 素 类 型 ( 即 , 只 能 使 用 PDF 定 义 的 标 准 结 构 类 型 )、 角 色 映
射 以 及 结 构 元 素 属 性 。
158 第 7 章 : 生 成 各 种 风 格 的 PDF

7.5.1 用 PDFlib 生 成 标 签 PDF
要 求 的 操 作 表 7.8 列 出 了 生 成 标 签 PDF 输 出 要 求 的 所 有 操 作 。 处 于 PDF 模 式 下 时 , 如 果
不 调 用 要 求 的 函 数 , 将 触 发 异 常 。
表 7.8 生 成 标 签 PDF 必 须 应 用 的 操 作
项 目
标 签 PDF 输 出
实 现 PDF 兼 容 性 的 PDFlib 函 数 和 参 数 要 求
PDF_begin_document( ) 中 的 tagged 选 项 必 须 设 为 true。
文 档 语 言 必 须 设 置 PDF_begin_document( ) 中 的 lang 选 项 , 以 指 定 文 档 的 自 然 语 言 。 最 初 ,
必 须 设 置 整 个 文 档 的 自 然 语 言 , 但 此 后 可 在 任 意 结 构 级 别 上 覆 盖 具 体 项 目 的 设 置 。
结 构 信 息 必 须 标 识 结 构 信 息 和 伪 像 等 。 所 有 内 容 生 成 API 函 数 都 必 须 用 PDF_begin_item( ) /
PDF_end_item( ) 对 括 起 来 。
兼 容 Unicode 的 文 本 输 出 生 成 标 签 PDF 时 , 所 有 文 本 输 出 都 必 须 使 用 兼 容 Unicode 的 字
体 ; 详 细 信 息 , 参 见 第 89 页 上 的 第 4.5.6 节 “Unicode 兼 容 的 字 体 ”。 这 表 示 , 使 用 的 所 有
字 体 都 必 须 提 供 到 Unicode 的 映 射 。 只 有 通 过 PDF_begin_item( ) 中 的 ActualText 或 Alt 选 项
为 内 容 提 供 替 代 文 本 的 情 况 下 , 才 允 许 使 用 不 兼 容 Unicode 的 字 体 。 如 果 生 成 标 签 PDF 时
使 用 了 没 有 正 确 Unicode 映 射 的 文 本 , PDFlib 将 引 发 异 常 。
注 : 有 些 情 况 下 ,PDFlib 无 法 检 测 到 字 体 编 码 错 误 的 问 题 , 例 如 编 码 为 文 本 字 体 的 符 号 字 体 等 。
而 且 , 由 于 历 史 问 题 , 具 有 某 些 排 版 变 化 的 PostScript 字 体 ( 例 如 专 业 字 体 ) 也 可 能 会 导 致
输 出 无 法 访 问 。
页 面 内 容 顺 序 定 义 页 面 内 容 的 文 本 、 图 形 和 页 面 运 算 符 的 顺 序 称 为 内 容 流 顺 序 ; 由 逻 辑
结 构 树 定 义 的 内 容 顺 序 称 为 逻 辑 顺 序 。 生 成 标 签 PDF 要 求 客 户 端 遵 守 某 些 内 容 顺 序 方 面 的
规 则 。
推 荐 的 、 也 是 很 自 然 的 方 法 是 , 依 次 生 成 结 构 元 素 的 所 有 构 成 部 分 , 然 后 移 至 下 一 个 元
素 。 从 技 术 角 度 讲 , 应 以 深 度 优 先 遍 历 创 建 结 构 树 。
以 下 方 法 应 避 免 : 输 出 第 一 个 元 素 的 一 部 分 、 切 换 到 下 一 元 素 的 一 部 分 , 然 后 在 返 回 第
一 个 元 素 , 等 等 。 如 果 采 用 这 种 方 法 , 结 构 树 是 在 多 次 遍 历 中 建 立 的 , 且 每 次 遍 历 只 生 成 元
素 的 一 部 分 。
用 PDI 导 入 页 面 由 于 导 入 文 档 的 结 构 会 干 扰 生 成 的 结 构 , 所 以 不 能 在 标 签 PDF 模 式 下 导
入 标 签 PDF 文 档 或 其 他 包 含 结 构 信 息 的 PDF 文 档 页 面 。
但 是 , 可 导 入 非 结 构 化 文 档 中 的 页 面 。 请 注 意 , 除 非 使 用 适 当 的 ActualText 添 加 了 标 签 ,
否 则 Acrobat 的 辅 助 功 能 会 “ 按 原 样 ” 处 理 这 些 页 面 。
伪 像 不 属 于 作 者 原 始 内 容 的 一 部 分 的 图 形 或 文 本 对 象 称 为 伪 像 。 伪 像 应 使 用 Artifact 伪 标
签 等 加 以 标 识 , 可 分 为 以 下 几 个 类 别 :
> 分 页 : 自 动 标 题 和 页 码 等 功 能
> 版 面 : 标 尺 和 表 格 阴 影 等 排 版 或 设 计 元 素
> 页 面 : 裁 切 标 记 和 颜 色 条 等 印 刷 辅 助 功 能
尽 管 没 有 严 格 规 定 , 但 我 们 强 烈 建 议 标 识 伪 像 , 以 帮 助 实 现 文 本 重 排 和 辅 助 功 能 。
内 嵌 项 目 PDF 定 义 了 块 级 结 构 元 素 (BLSE) 和 内 嵌 级 结 构 元 素 (ILSE) ; 有 关 确 切 定 义 , 参
见 表 8.57。 BLSE 可 包 含 其 他 BLSE 或 实 际 内 容 , 而 ILSE 始 终 只 包 含 内 容 。 此 外 , PDFlib 还
可 区 分 如 下 项 目 :
ASpan 项 目 属 于 常 规 项 目 还 是 内 嵌 项 目 的 决 定 由 客 户 端 通 过 PDF_begin_item( ) 的 inline 选
项 控 制 。 建 议 将 辅 助 功 能 范 围 强 制 设 为 常 规 项 目 (inline=false), 例 如 : 包 含 多 种 语 言 且 被 多
7.5 标 签 PDF 159

表 7.9 常 规 项 目 和 内 嵌 项 目
常 规 项 目
内 嵌 项 目
受 影 响 的 项 目 所 有 分 组 元 素 和 BLSE 所 有 ILSE 和 非 结 构 标 签
( 伪 标 签 )
可 更 改 常 规 / 内 嵌 状 态 否 仅 用 于 ASpan 项 目
文 档 结 构 树 的 一 部 分 是 否
可 跨 越 页 面 边 界 是 否
可 被 其 他 项 目 中 断 是 否
可 暂 停 和 启 动 是 否
可 以 任 意 深 度 嵌 套 是 只 能 与 其 他 内 嵌 项 目 一 起 使 用
个 页 面 分 隔 的 段 落 。 此 外 , 也 可 以 关 闭 项 目 , 在 下 一 页 上 开 始 一 个 新 项 目 。 必 须 在 打 开 项 目
的 同 一 页 面 上 关 闭 内 嵌 项 目 。
可 选 操 作 表 7.10 列 出 了 生 成 标 签 PDF 输 出 时 的 所 有 可 选 操 作 。 尽 管 没 有 严 格 规 定 , 但 这
些 功 能 将 提 升 生 成 标 签 PDF 输 出 的 质 量 , 因 此 建 议 使 用 。
表 7.10 生 成 标 签 PDF 的 可 选 操 作
项 目
连 字
实 现 标 签 PDF 兼 容 性 的 可 选 PDFlib 函 数 和 参 数
断 字 符 ( 在 行 尾 将 单 字 分 为 两 部 分 ) 应 使 用 自 动 连 字 符 (U+00A0) 表 示 , 而 非 强 制 连
字 符 (U+002D)
字 边 界
即 使 定 位 方 面 没 有 严 格 规 定 , 但 还 是 应 该 使 用 空 格 (U+0020) 分 隔 单 字 。 可 使 用
autospace 参 数 , 在 每 次 调 用 show 函 数 后 自 动 生 成 空 格 字 符 。
伪 像 为 了 区 分 实 际 内 容 和 页 面 伪 像 , 应 使 用 tag=Artifact 的 PDF_begin_item( ) 等 标 识 伪 像 。
禁 止 的 操 作 表 7.11 列 出 了 在 生 成 标 签 PDF 输 出 时 禁 止 的 所 有 操 作 。 处 于 标 签 PDF 模 式 下
时 , 调 用 禁 止 的 函 数 将 触 发 异 常 。
表 7.11 生 成 标 签 PDF 时 必 须 避 免 的 操 作
项 目
实 现 标 签 PDF 兼 容 性 应 避 免 的 PDFlib 函 数 和 参 数
不 兼 容 Unicode 的
字 体
必 须 避 免 使 用 不 兼 容 Unicode 的 字 体 , 具 体 参 见 第 89 页 上 的 第 4.5.6 节 “Unicode 兼
容 的 字 体 ”。
PDF 导 入 不 能 导 入 包 含 结 构 信 息 的 PDF 文 档 中 的 页 面 ( 尤 其 是 : 标 签 PDF 文 档 )。
7.5.2 用 直 接 Text Output 和 Textflows 创 建 标 签 PDF
最 低 标 签 PDF 示 例 以 下 示 例 代 码 可 创 建 一 个 非 常 简 单 的 标 签 PDF 文 档 。 它 的 结 构 树 只 包
含 一 个 P 元 素 。 以 下 代 码 使 用 autospace 功 能 , 在 文 本 片 段 之 间 自 动 生 成 空 格 字 符 :
if (PDF_begin_document(p, "hello-tagged.pdf", 0, "tagged=true lang=en") == -1)
{
printf("Error:%s\n", PDF_get_errmsg(p));
return(2);
}
/* 在 文 本 块 之 间 自 动 创 建 空 格 */
PDF_set_parameter(p, "autospace", "true");
/* 作 为 文 档 结 构 根 级 的 子 级 打 开 第 一 个 结 构 元 素 (=0) */
160 第 7 章 : 生 成 各 种 风 格 的 PDF

id = PDF_begin_item(p, "P", "Title = {Simple Paragraph}");
PDF_begin_page_ext(p, 0, 0, "width=a4.width height=a4.height");
font = PDF_load_font(p, "Helvetica-Bold", 0, "host", "");
PDF_setfont(p, font, 24);
PDF_show_xy(p, "Hello, Tagged PDF!", 50, 700);
PDF_continue_text(p, "This PDF has a very simple");
PDF_continue_text(p, "document structure.");
PDF_end_page_ext(p, "");
PDF_end_item(p, id);
PDF_end_document(p, "");
用 文 本 流 生 成 标 签 PDF 文 本 流 功 能 提 供 了 强 大 的 文 本 格 式 化 功 能 ( 参 见 第 101 页 上 的
第 4.9 节 “ 多 行 textflow” ) 。 由 于 具 体 文 本 片 段 不 再 受 客 户 端 的 直 接 控 制 , 而 将 由
PDFlib 自 动 完 成 格 式 化 , 因 此 用 文 本 流 生 成 标 签 PDF 时 , 必 须 格 外 小 心 :
> 文 本 流 不 能 包 含 具 体 的 结 构 元 素 , 但 文 本 流 可 以 包 含 在 结 构 元 素 之 中 。
> 文 本 流 的 所 有 部 分 ( 用 特 定 文 本 流 句 柄 执 行 的 所 有 PDF_fit_textflow( ) 调 用 ) 应 包 含 在 一
个 结 构 元 素 中 。
> 由 于 文 本 流 的 各 个 部 分 可 能 分 布 在 多 个 页 面 中 , 而 这 些 页 面 可 能 包 含 其 他 结 构 项 目 , 所
以 选 择 适 当 的 父 级 项 目 时 应 特 别 注 意 ( 不 要 使 用 parent 参 数 -1, 因 为 这 可 能 指 向 错 误 的
父 级 元 素 )。
7.5.3 启 动 复 杂 布 局 的 项 目
为 了 帮 助 创 建 具 有 复 杂 的 非 线 性 页 面 布 局 的 结 构 信 息 , PDFlib 支 持 一 种 称 为 项 目 启 动 的 功
能 。 在 开 发 人 员 必 须 跟 踪 多 个 结 构 分 支 , 且 每 个 分 支 都 可 能 跨 一 个 或 多 个 页 面 的 情 况 下 , 可
使 用 这 种 功 能 启 动 以 前 创 建 的 结 构 元 素 。 这 种 技 术 通 常 可 用 于 以 下 情 况 :
> 一 个 页 面 上 的 多 个 栏
> 小 结 或 插 入 等 中 断 主 文 本 的 插 入 操 作
> 放 置 在 两 栏 之 间 的 表 格 和 插 图
通 过 启 动 功 能 , 可 在 两 个 逻 辑 分 支 之 间 切 换 以 及 其 他 情 况 下 使 用 经 过 改 进 的 页 面 内 容 生 成
方 法 。 这 种 方 法 比 依 次 完 成 每 个 分 支 更 加 高 效 。 我 们 以 图 7.1 中 显 示 的 页 面 布 局 为 例 , 说 明
启 动 功 能 的 优 点 。 该 布 局 包 含 两 个 主 文 本 栏 , 文 本 栏 被 黑 色 背 景 显 示 的 框 中 的 一 个 表 格 和 插
入 注 释 以 及 页 眉 和 页 脚 中 断 。
按 逻 辑 顺 序 生 成 页 面 内 容 从 逻 辑 结 构 的 角 度 讲 , 应 按 照 以 下 顺 序 创 建 页 面 内 容 : 左 栏 、
右 栏 ( 页 面 右 下 角 部 分 )、 表 格 、 插 入 、 页 眉 和 页 脚 。 以 下 伪 代 码 便 采 用 了 这 一 顺 序 :
/* 按 照 逻 辑 结 构 顺 序 创 建 页 面 布 局 */
id_art = PDF_begin_item(p, "Art", "Title = Article");
id_sect1 = PDF_begin_item(p, "Sect", "Title = {First Section}");
/* 1 创 建 左 栏 的 上 半 部 分 */
PDF_set_text_pos(p, x1_left, y1_left_top);
...
/* 2 创 建 左 栏 的 下 半 部 分 */
PDF_set_text_pos(p, x1_left, y1_left_bottom);
...
/* 3 创 建 右 栏 的 上 半 部 分 */
PDF_set_text_pos(p, x1_right, y1_right_top);
...
7.5 标 签 PDF 161

PDF_end_item(p, id_sect1);
id_sect2 = PDF_begin_item(p, "Sect", "Title = {Second Section}");
/* 4 创 建 右 栏 的 下 半 部 分 */
PDF_set_text_pos(p, x2_right, y2_right);
...
/* 可 在 下 一 页 继 续 第 二 部 分 */
PDF_end_item(p, id_sect2);
sprintf(optlist, "Title=Table parent=%d", id_art);
id_table = PDF_begin_item(p, "Table", optlist);
/* 5 创 建 表 格 结 构 和 内 容 */
PDF_set_text_pos(p, x_start_table, y_start_table);
...
PDF_end_item(p, id_table);
sprintf(optlist, "Title=Insert parent=%d", id_art);
id_insert = PDF_begin_item(p, "P", optlist);
/* 6 创 建 插 入 结 构 和 内 容 */
PDF_set_text_pos(p, x_start_table, y_start_table);
...
PDF_end_item(p, id_insert);
id_artifact = PDF_begin_item(p, "Artifact", "");
/* 7+8 创 建 页 眉 和 页 脚 */
PDF_set_text_pos(p, x_header, y_header);
...
PDF_set_text_pos(p, x_footer, y_footer);
...
PDF_end_item(p, id_artifact);
/* 文 章 可 在 下 一 页 中 继 续 */
...
PDF_end_item(p, id_art);
162 第 7 章 : 生 成 各 种 风 格 的 PDF

图 7.1
按 照 逻 辑 结 构 顺 序
( 左 侧 ) 和 显 示 顺 序
( 右 侧 ) 创 建 复 杂 页 面
布 局 。 在 继 续 创 建
片 段 4 和 6 之 前 , 右 侧
示 例 使 用 项 目 启 动 功
能 创 建 第 一 部 分 。
7
1
6
5
2 3
4
8
1
2
5
3
4 6
7
8
按 照 显 示 顺 序 创 建 页 面 内 容 采 用 “ 逻 辑 顺 序 ” 的 方 法 会 强 制 创 建 程 序 按 逻 辑 顺 序 构 建 页
面 内 容 ; 即 使 按 显 示 顺 序 创 建 会 更 加 容 易 的 情 况 下 , 也 是 如 此 : 页 眉 、 左 栏 上 半 部 分 、 左 栏
下 半 部 分 、 插 入 、 右 栏 、 页 脚 。 使 用 PDF_activate_item( ) 时 , 可 按 如 下 所 示 实 施 此 顺 序 :
/* 按 照 显 示 顺 序 创 建 页 面 布 局 */
id_header = PDF_begin_item(p, "Artifact", "");
/* 1 创 建 页 眉 */
PDF_set_text_pos(p, x_header, y_header);
...
PDF_end_item(p, id_header);
id_art = PDF_begin_item(p, "Art", "Title = Article");
id_sect1 = PDF_begin_item(p, "Sect", "Title = {First Section}");
/* 2 创 建 左 栏 的 上 半 部 分 */
PDF_set_text_pos(p, x1_left, y1_left_top);
...
sprintf(optlist, "Title=Table parent=%d", id_art);
id_table = PDF_begin_item(p, "Table", optlist);
/* 3 创 建 表 格 结 构 和 内 容 */
PDF_set_text_pos(p, x_start_table, y_start_table);
...
PDF_end_item(p, id_table);
/* 继 续 第 一 部 分 */
PDF_activate_item(p, id_sect1);
/* 4 创 建 左 栏 的 下 半 部 分 */
PDF_set_text_pos(p, x1_left, y1_left_bottom);
...
sprintf(optlist, "Title=Insert parent=%d", id_art);
id_insert = PDF_begin_item(p, "P", optlist);
7.5 标 签 PDF 163

* 5 创 建 插 入 结 构 和 内 容 */
PDF_set_text_pos(p, x_start_table, y_start_table);
...
PDF_end_item(p, id_insert);
/* 继 续 创 建 第 一 部 分 的 其 他 内 容 */
PDF_activate_item(p, id_sect1);
/* 6 创 建 右 栏 的 上 半 部 分 */
PDF_set_text_pos(p, x1_right, y1_right_top);
...
PDF_end_item(p, id_sect1);
id_sect2 = PDF_begin_item(p, "Sect", "Title = {Second Section}");
/* 7 创 建 右 栏 的 下 半 部 分 */
PDF_set_text_pos(p, x2_right, y2_right);
...
/* 可 在 下 一 页 继 续 第 二 部 分 */
PDF_end_item(p, id_sect2);
id_footer = PDF_begin_item(p, "Artifact", "");
/* 8 创 建 页 脚 */
PDF_set_text_pos(p, x_footer, y_footer);
...
PDF_end_item(p, id_footer);
/* 文 章 可 在 下 一 页 中 继 续 */
...
PDF_end_item(p, id_art);
采 用 这 种 结 构 元 素 的 顺 序 时 , 主 文 本 ( 跨 一 个 半 栏 ) 会 被 表 格 和 插 入 内 容 中 断 两 次 。 因 此 ,
必 须 使 用 PDF_activate_item( ) 启 动 两 次 。
如 果 内 容 跨 多 个 页 面 , 可 以 采 用 相 同 的 技 术 。 例 如 , 可 以 首 先 创 建 页 眉 或 其 他 插 入 内 容 ,
然 后 再 次 启 动 主 页 面 内 容 元 素 。
7.5.4 在 Acrobat 中 使 用 标 签 PDF
本 节 介 绍 我 们 在 Adobe Acrobat 6.0 中 对 标 签 PDF 输 出 进 行 测 试 期 间 的 发 现 , 主 要 与
Acrobat 中 的 错 误 和 异 常 行 为 有 关 。 同 时 , 还 提 出 了 我 们 发 现 的 变 通 方 法 。
Acrobat 的 重 排 功 能 Acrobat 允 许 标 签 PDF 文 档 进 行 重 排 , 即 : 调 整 页 面 内 容 以 适 应 当 前
窗 口 大 小 。 在 测 试 标 签 PDF 的 过 程 中 , 我 们 在 重 排 功 能 方 面 有 如 下 发 现 :
> 页 面 内 容 的 顺 序 应 遵 守 所 需 的 重 排 顺 序 。
> 符 号 ( 非 Unicode 字 体 ) 可 能 导 致 Acrobat 的 重 排 功 能 崩 溃 。 因 此 , 我 们 建 议 将 文 本 置
于 插 图 元 素 中 。
> BLSE 可 能 同 时 包 含 子 级 结 构 元 素 和 直 接 内 容 元 素 。 为 使 重 排 功 能 ( 以 及 辅 助 功 能 检 查 器
和 朗 读 功 能 ) 正 常 运 行 , 我 们 建 议 将 直 接 元 素 置 于 第 一 个 子 级 元 素 之 前 。
> 应 为 表 格 和 插 图 提 供 BBox 选 项 。 BBox 应 准 确 无 误 ; 但 是 , 对 于 表 格 , 只 需 准 确 设 置 左
下 角 即 可 。 除 提 供 BBox 条 目 之 外 , 也 可 在 BLSE 标 签 内 创 建 图 形 , 例 如 P、H 等 。 但 是 ,
启 动 重 排 时 , 将 不 显 示 矢 量 图 形 。 如 果 客 户 端 未 提 供 BBox 选 项 ( 而 依 靠 自 动 BBox 生
成 ), 应 在 表 格 元 素 之 外 绘 制 单 元 格 边 框 等 所 有 表 格 图 形 。
> 表 格 元 素 的 子 级 元 素 只 应 包 含 与 表 格 相 关 的 元 素 (TR、TD、TH、THead、TBody 等 ), 不
能 包 含 任 何 其 他 元 素 。 例 如 , 尽 管 能 生 成 正 确 的 标 签 PDF, 但 在 表 格 内 使 用 标 题 元 素 可
能 会 导 致 重 排 问 题 。
164 第 7 章 : 生 成 各 种 风 格 的 PDF

私 有 标 签 包 含 的 内 容 不 能 导 出 为 其 他 格 式 。 但 是 , 它 们 要 受 重 排 和 朗 读 功 能 的 影 响 , 因
此 私 有 标 签 内 的 插 图 必 须 具 有 替 代 文 本 。
> 导 入 图 像 应 包 含 在 插 图 元 素 内 , 导 入 的 PDF 页 面 应 包 含 在 表 单 项 目 内 。 为 了 防 止 重 排 问
题 , 应 避 免 使 用 公 式 项 目 类 型 。
> 重 排 功 能 似 乎 无 法 正 确 处 理 用 topdown 选 项 生 成 的 PDF 文 档 。
> 应 避 免 使 用 具 有 混 合 子 级 类 型 的 结 构 项 目 ( 例 如 , 同 时 具 有 页 面 内 容 序 列 和 非 内 嵌 结 构
元 素 ), 否 则 可 能 导 致 重 排 失 败 。
> 如 果 启 动 项 目 只 包 含 内 容 , 不 包 含 结 构 子 级 , 重 排 可 能 会 失 败 ; 尤 其 是 在 另 一 页 面 上 启
动 项 目 时 。 可 在 非 内 嵌 范 围 标 签 内 包 装 启 动 项 目 , 以 避 免 此 问 题 。
Acrobat 的 辅 助 功 能 检 查 器 Acrobat 的 辅 助 功 能 检 查 器 可 用 来 确 定 标 签 PDF 文 档 是 否 适
用 于 读 屏 器 等 辅 助 技 术 。
> 包 含 导 入 图 像 的 元 素 应 使 用 Alt 属 性 。 ActualText 属 性 可 能 会 导 致 辅 助 功 能 检 查 器 崩 溃 。
使 用 Alt 而 不 使 用 ActualText 的 另 一 个 原 因 是 , 朗 读 功 能 会 捕 捉 真 实 文 本 。
> 如 果 导 入 PDF 页 面 的 第 一 个 项 目 是 表 单 标 签 , 则 可 导 致 辅 助 功 能 检 查 器 出 现 问 题 。
> 如 果 在 TOCI 标 签 内 设 置 Lbl 标 签 ( 如 《PDF Reference》 中 所 述 ) , 辅 助 功 能 检 查 器 将
发 出 警 告 , 指 出 未 在 LI 标 签 内 设 置 Lbl 标 签 。
用 Acrobat 导 出 为 其 他 格 式 标 签 PDF 可 显 著 提 高 Acrobat 将 PDF 文 档 导 出 为 其 他 格 式 的
效 果 。
> 如 果 导 入 PDF 页 面 具 有 表 单 标 签 , 在 Acrobat 中 , ActualText 选 项 内 提 供 的 文 本 将 导 出
为 其 他 格 式 , 而 Alt 标 签 中 提 供 的 文 本 将 被 忽 略 。 但 是 , 朗 读 功 能 可 用 于 以 上 两 种 文 本 。
> 包 含 导 入 图 像 的 元 素 应 使 用 Alt 属 性 , 而 非 ActualText 属 性 , 以 使 导 出 功 能 可 以 捕 捉 真 实
文 本 。
> NonStruct 标 签 的 内 容 不 会 导 出 到 HTML 4.01 CSS 1.0 格 式 ( 但 是 可 用 于 HTML 3.2 导
出 )。
> 应 为 ILSE 提 供 替 代 文 本 ( 例 如 Code、 Quote 或 Reference)。 如 果 使 用 了 Alt 选 项 , 朗 读
功 能 将 会 读 出 提 供 的 文 本 , 但 导 出 为 其 他 格 式 的 将 是 实 际 的 内 容 。 如 果 使 用 ActualText
选 项 , 读 出 和 导 出 的 都 是 提 供 的 文 本 。
Acrobat 的 朗 读 功 能 标 签 PDF 可 增 强 Acrobat 的 文 本 朗 读 功 能 。
> 提 供 Alt 或 ActualText 时 , 最 好 在 开 头 包 括 一 个 空 格 字 符 。 这 样 , 朗 读 功 能 便 可 将 文 本 与
前 一 句 区 分 开 来 。 由 于 同 样 的 原 因 , 最 好 同 时 在 结 尾 处 包 括 一 个 句 点 ’.’ 符 号 。 否 则 , 朗
读 功 能 将 尝 试 组 合 前 一 句 的 最 后 一 个 单 字 和 替 代 文 本 的 第 一 个 单 字
7.5 标 签 PDF 165

166 第 7 章 : 生 成 各 种 风 格 的 PDF

8 用 于 PDFlib、 PDI 和 PPS 的 API 参 考
API 参 考 记 录 了 所 有 支 持 的 PDFlib、 PDI (PDF Import) 和 PPS (PDFlib Personalization
Server) 函 数 。
8.1 数 据 类 型 和 命 名 约 定
8.1.1 PDFlib 数 据 类 型
特 定 语 言 绑 定 使 用 的 具 体 语 法 实 际 上 可 能 会 与 本 章 介 绍 的 C 语 言 语 法 略 有 区 别 。 这 在 PDF
文 档 参 数 (API 引 用 中 的 PDF *) 的 使 用 中 尤 为 突 出 , 在 C 语 言 绑 定 中 , 几 乎 所 有 PDFlib 函
数 必 须 用 它 作 为 第 一 个 自 变 量 ; 而 在 其 他 一 些 语 言 绑 定 中 , 由 语 言 包 装 创 建 的 对 象 内 已 隐
含 其 信 息 , 故 无 此 要 求 。
表 8.1 详 细 说 明 了 所 有 语 言 绑 定 使 用 的 PDF 数 据 类 型 以 及 字 符 串 类 型 。 由 于 所 有 绑 定 中
都 有 明 显 的 对 应 数 据 类 型 , 所 以 表 中 没 有 提 及 整 型 、 长 整 型 和 双 精 度 型 数 据 。 有 关 特 定 语 言
的 更 多 详 细 信 息 , 请 参 阅 对 应 语 言 的 章 节 以 及 第 2 章 中 的 示 例 。
表 8.1 语 言 绑 定 中 的 数 据 类 型
语 言 绑 定 p 参 数 ? PDF_ 前 缀 ? 字 符 串 数 据 类 型 二 进 制 数 据 类 型
C ( 同 时 用 于
本 API 参 考 )
是 是 const char * 1
const char *
C++ 否 否 string 2
char *
Cobol 3
是
4
否
STRING
STRING
Java 否 否 String byte[ ]
Perl 是 是 字 符 串 string
PHP 是 是 string string
Python 是 是 string string
RPG 是 是 string, 但 必 须 添 加 x’00’ data
Tcl 是 是 string byte array
1. 这 里 认 为 C 语 言 NULL 字 符 串 值 相 当 于 空 字 符 串 。
2. NULL 字 符 串 值 不 能 用 于 C++ 绑 定 。
3. 有 关 Cobol 数 据 类 型 的 更 多 信 息 , 请 参 见 第 19 页 上 的 第 2.2.1 节 “ 有 关 Cobol 的 特 别 注 意 事 项 ”。
4. Cobol 程 序 必 须 使 用 PDFlib 函 数 的 缩 写 名 称 。
Unicode 字 符 串 PDFlib 可 在 所 有 相 关 区 域 接 受 Unicode 字 符 串 , 并 支 持 各 种 与 Unicode
相 关 的 格 式 和 设 置 。 有 关 详 细 信 息 , 请 查 阅 第 84 页 上 的 第 4.5.2 节 “ 内 容 字 符 串 、 超 文 本 字
符 串 和 名 称 字 符 串 ”; 同 时 , 请 注 意 本 章 将 使 用 的 下 列 字 符 串 类 型 :
> 内 容 字 符 串
> 超 文 本 字 符 串
> 名 称 字 符 串
PDFlib 函 数 的 命 名 约 定 在 C 语 言 绑 定 中 , 所 有 PDFlib 函 数 都 置 于 全 局 命 名 空 间 内 , 并 在
名 称 中 附 带 通 用 的 PDF_ 前 缀 , 以 最 大 限 度 减 少 占 用 的 命 名 空 间 。 相 反 , 其 他 几 种 语 言 绑 定
将 PDF 文 档 参 数 隐 藏 在 语 言 包 装 创 建 的 对 象 内 。 对 于 这 些 绑 定 , 必 须 更 改 本 API 参 考 提 供
的 函 数 名 称 , 省 略 PDF_ 前 缀 并 将 PDF * 参 数 用 作 第 一 个 自 变 量 。 例 如 ,C 及 类 似 语 言 的 API
描 述
8.1 数 据 类 型 和 命 名 约 定 167

PDF *p;
PDF_begin_document(PDF *p, const char *filename, const char *optlist);
当 通 过 Java 使 用 此 函 数 时 , 将 转 换 为 :
pdflib p;
p.begin_document(String filename, String optlist);
8.1.2 选 项 列 表
选 项 列 表 是 种 强 大 且 简 便 的 PDFlib 操 作 控 制 方 法 。 许 多 PDFlib API 方 法 都 支 持 选 项 列 表
( 简 称 optlists), 而 不 要 求 大 量 的 函 数 参 数 。 这 些 选 项 列 表 是 字 符 串 , 可 以 包 含 任 意 数 量 的
选 项 。 选 项 列 表 支 持 各 种 数 据 类 型 以 及 数 组 等 复 合 数 据 。 在 大 多 数 语 言 中 , 可 通 过 连 接 所 需
关 键 字 和 值 来 简 便 地 构 建 optlists。 C 语 言 编 程 人 员 也 许 需 要 使 用 sprintf( ) 函 数 构 建
optlists。
一 个 optlist 是 一 个 字 符 串 , 包 含 一 对 或 多 对 表 单
key value
可 用 任 意 空 白 字 符 ( 例 如 空 格 、 制 表 符 、 回 车 符 、 换 行 符 等 ) 分 隔 名 称 和 值 , 以 及 多 个 名
称 / 值 对 。 值 可 以 是 多 个 值 组 成 的 列 表 。 也 可 以 在 名 称 和 值 之 间 使 用 等 号 ’=’:
key=value
如 果 值 是 个 包 含 空 白 字 符 或 等 号 的 字 符 串 , 则 必 须 用 括 号 将 该 字 符 串 括 起 来 :
key={multiple words}
key={value=containing=equal=signs}
若 选 项 列 表 带 有 子 选 项 , 则 需 另 加 一 对 括 号 将 子 选 项 括 起 , 即 使 子 选 项 只 有 一 个 元 素 :
key={{value}}
由 于 选 项 列 表 将 由 左 至 右 计 算 , 可 以 在 同 一 列 表 内 多 次 使 用 同 一 选 项 。 这 时 , 最 后 一 次 出 现
的 选 项 将 覆 盖 前 面 的 选 项 。 在 下 面 的 示 例 中 , 第 一 个 选 项 赋 值 将 被 第 二 个 覆 盖 ; 该 选 项 列 表
处 理 完 后 , 键 值 将 为 2:
key=1 key=2
选 项 列 表 支 持 表 8.2 所 列 的 数 据 类 型 。 本 章 下 文 将 更 加 详 细 地 讨 论 这 些 数 据 类 型 。
表 8.2 选 项 列 表 中 的 数 据 类 型
种 类 数 据 类 型
简 单 布 尔 型 、 字 符 串 、 内 容 / 超 文 本 / 名 称 字 符 串 、 单 字 符 、 关 键 字 、 浮 点 型 、 整 型 、 句 柄
复 杂 列 表 、 矩 形 、 动 作 列 表 、 颜 色
简 单 值 简 单 值 可 以 使 用 下 列 任 一 数 据 类 型 :
> 布 尔 型 :true 或 false ; 如 果 省 略 布 尔 选 项 的 值 , 则 默 认 值 为 true。 作 为 简 略 表 示 法 , 可
使 用 noname 替 代 name=false。
> 字 符 串 : 这 些 字 符 串 是 ASCII 纯 文 本 字 符 串 , 通 常 用 于 不 可 本 地 化 的 关 键 字 。 包 含 空 白
字 符 或 = 的 字 符 串 必 须 用 { 和 } 括 起 来 。 可 以 使 用 { } 构 建 空 字 符 串 。 如 果 字 符 { 和 } 是 字
符 串 的 一 部 分 , 则 必 须 在 前 面 添 加 \ 字 符 。
168 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

内 容 字 符 串 、 超 文 本 字 符 串 和 名 称 字 符 串 : 这 些 字 符 串 可 容 纳 各 种 格 式 的 Unicode 内 容 ;
有 关 详 细 信 息 , 请 参 见 第 84 页 上 的 第 4.5.2 节 “ 内 容 字 符 串 、 超 文 本 字 符 串 和 名 称 字
符 串 ”。
> 单 字 符 : 这 些 字 符 串 是 单 个 的 Unicode 字 符 , 可 支 持 多 种 语 法 变 体 :10 进 制 数 值 ( 例
如 173), 带 x、X、0x、0X 或 U+(xAD、0xAD、U+00AD) 前 缀 的 16 进 制 数 值 , 或 者
第 87 页 上 的 第 4.5.5 节 “ 字 符 引 用 ” 介 绍 的 不 带 ’&’ 和 ’;’ 修 饰 符 (shy、#xAD、#173) 的
数 字 或 字 符 引 用 。 单 字 符 必 须 处 于 0-65535 (0-xFFFF) 的 范 围 内 。
> 关 键 字 : 预 定 义 固 定 关 键 字 列 表 中 的 一 项 。
> 浮 点 型 和 整 型 :10 进 制 浮 点 小 数 或 整 数 ; 可 使 用 小 数 点 和 逗 号 作 为 浮 点 值 的 小 数 分 隔 符 。
整 型 值 可 以 x、 X、 0x 或 0X 开 头 , 指 定 16 进 制 值 。 有 些 选 项 可 直 接 在 值 后 添 加 % 字 符 ,
以 支 持 百 分 比 ; 相 关 文 档 中 有 具 体 说 明 。
> 句 柄 : 包 括 几 种 PDFlib 内 部 句 柄 , 例 如 : 字 体 、 图 像 或 动 作 句 柄 。 从 技 术 角 度 讲 , 这 些
值 是 整 型 值 。
根 据 选 项 的 类 型 和 解 释 , 可 能 还 有 其 他 限 制 。 例 如 , 整 型 或 浮 点 型 选 项 可 能 会 限 制 在 一 定 的
值 范 围 内 ; 句 柄 必 须 对 相 应 的 对 象 类 型 有 效 , 等 等 。 第 8 章 中 相 关 函 数 的 说 明 中 具 体 规 定 了
各 个 选 项 的 条 件 。 以 下 是 一 些 简 单 值 的 示 例 ( 第 一 行 显 示 包 含 空 白 字 符 的 口 令 字 符 串 ):
PDF_open_pdi( ): password {secret string}
PDF_create_gstate( ): linewidth 0.5 blendmode overlay opacityfill 0.75
PDF_load_font( ): embedding=true subsetting=true subsetlimit=50 kerning=false
PDF_load_font( ): embedding subsetting subsetlimit=50 nokerning
PDF_create_textflow( ): leading=150%
PDF_create_textflow( ): charmapping={ 0x0A 0x20 }
列 表 值 列 表 值 由 多 个 值 组 成 , 可 以 是 简 单 值 或 依 次 排 列 的 列 表 值 。 列 表 要 用 { 和 } 括 起
来 。 以 下 是 一 些 列 表 值 的 示 例 :
PDF_fit_image( ): boxsize={500 600} position={50 0}
PDF_create_gstate( ): dasharray={11 22 33}
PDF_create_annotation( ): polylinelist={{10 20 30 40}}
矩 形 矩 形 是 个 包 含 四 个 浮 点 值 的 列 表 , 指 定 矩 形 左 下 角 和 右 上 角 的 坐 标 。 根 据 不 同 的 选
项 , 解 释 矩 形 坐 标 的 坐 标 系 统 也 不 尽 相 同 ( 如 标 准 或 用 户 坐 标 系 统 ), 将 单 独 论 述 。 示 例 :
PDF_begin_document( ): cropbox {0 0 500 600}
动 作 列 表 动 作 列 表 可 指 定 一 个 或 多 个 动 作 。 列 表 中 的 每 一 项 都 包 括 一 个 事 件 关 键 字 ( 触
发 器 ) 和 一 个 动 作 句 柄 列 表 ; 该 动 作 句 柄 列 表 必 须 用 PDF_create_action( ) 创 建 。 各 个 动 作 将
按 照 列 表 顺 序 执 行 。 对 于 各 个 选 项 , 将 单 独 介 绍 允 许 的 事 件 集 ( 例 如 docopen) 和 动 作 类 型
( 例 如 JavaScript)。 示 例 ( 假 定 先 前 的 PDF_create_action( ) 调 用 已 返 回 值 0、 1 和 2):
PDF_begin_document( ): action {open 0}
PDF_create_bookmark( ): action {activate {0 1 2}}
PDF_create_field( ): action {keystroke 0 format 1 validate 2}
颜 色 颜 色 选 项 是 个 列 表 , 包 含 色 彩 空 间 关 键 字 和 具 有 不 同 数 量 的 浮 点 值 的 列 表 ( 具 体 取
决 于 特 定 色 彩 空 间 )。 色 彩 空 间 关 键 字 等 同 于 PDF_setcolor( ) ( 参 见 第 221 页 上 的 第 8.5.1 节
“ 设 置 颜 色 和 色 彩 空 间 ”); 其 所 有 可 能 的 值 在 第 57 页 上 的 第 3.3.1 节 “ 颜 色 和 色 彩 空 间 ” 中
给 出 说 明 :
> 色 彩 空 间 关 键 字 gray、 rgb、 和 cmyk 可 能 附 带 一 个 、 三 个 或 四 个 浮 点 值 。
> 色 彩 空 间 关 键 字 lab 可 能 附 带 三 个 浮 点 值 。
8.1 数 据 类 型 和 命 名 约 定 169

色 彩 空 间 关 键 字 spot 可 能 附 带 一 个 专 色 句 柄 和 色 调 值 。 另 外 , 色 彩 空 间 关 键 字 spotname
可 附 带 一 个 专 色 名 称 和 一 个 包 含 色 调 的 浮 点 值 。
> 色 彩 空 间 关 键 字 iccbasedgray、 iccbasedrgb 和 iccbasedcmyk 可 能 附 带 一 个 、 三 个 或 四 个
浮 点 值 。
> 色 彩 空 间 关 键 字 pattern 可 通 过 一 个 pattern 句 柄 来 补 充 。
> 色 彩 空 间 关 键 字 none 可 能 用 来 指 定 色 彩 缺 失 的 情 况 。
根 据 具 体 函 数 的 详 细 说 明 , 特 定 选 项 列 表 可 能 只 提 供 上 述 关 键 字 的 一 部 分 。 以 下 是 一 些 颜 色
值 的 示 例 :
PDF_fill_textblock( ): strokecolor={ rgb 1 0 0 }
PDF_fill_textblock( ): bordercolor=none
PDF_fill_textblock( ): fillcolor={ spotname {PANTONE 281 U} 0.5 }
PDF_fill_textblock( ): fillcolor={ spotname 1 0.8 }
8.2 常 规 函 数
8.2.1 设 置
表 8.3 列 出 了 本 节 的 相 关 参 数 及 相 应 的 值 。
表 8.3 设 置 函 数 的 参 数 和 值
函 数 关 键 字 说 明
set_parameter compatibility 不 常 用 , 使 用 PDF_begin_document( ) 的 compatibility 选 项 。
set_parameter pdfx 不 常 用 , 使 用 PDF_begin_document( ) 的 pdfx 选 项 。
set_parameter flush 不 常 用 , 使 用 PDF_begin_document_callback( ) 的 flush 选 项 。
set_parameter SearchPath ( 不 支 持 MVS) 包 含 要 读 取 文 件 的 目 录 的 相 对 或 绝 对 路 径 名 。 可 设 置 多 个
SearchPath ; 各 项 将 累 积 , 并 首 先 使 用 最 近 设 置 的 一 项 ( 参 见 第 49 页 上
的 第 3.1.5 节 “ 资 源 配 置 和 文 件 搜 索 ”)。 范 围 : 任 意
set_parameter resourcefile PDFlib UPR 资 源 文 件 的 相 对 或 绝 对 文 件 名 。 将 立 即 载 入 资 源 文 件 。 将 保 留
现 有 资 源 ; 如 果 再 次 设 置 , 他 们 的 值 将 由 新 值 覆 盖 。 范 围 : 任 意
set_parameter asciifile ( 只 支 持 iSeries 和 zSeries)。 要 求 采 用 ASCII 编 码 的 文 本 文 件 (PFA、 AFM、
UPR、 编 码 )。 默 认 值 :iSeries 上 为 true, zSeries 上 为 false。 范 围 : 任 意
set_parameter license 设 置 PDFlib、 PDFlib+PDI 或 PPS 的 许 可 密 钥 。 可 在 第 一 次 调 用 PDF_begin_
document( ) 之 前 设 置 密 钥 ( 甚 至 可 以 多 次 设 置 , 以 进 行 累 积 密 钥 )。
范 围 : 对 象
set_parameter licensefile 设 置 包 含 许 可 密 钥 的 文 件 的 文 件 名 。 该 文 件 在 第 一 次 调 用 PDF_begin_
document( ) 之 前 被 设 置 一 次 。 范 围 : 对 象 。
set_value compress 设 置 压 缩 级 别 。 该 参 数 不 会 影 响 以 通 过 (pass-through) 模 式 处 理 的 图 像 数
据 。 默 认 值 :6。 范 围 : 页 面 、 文 档
0 无 压 缩
1 最 快 速 度
9 最 佳 压 缩
get_value
major, minor
revision
分 别 返 回 PDFlib 的 主 要 、 次 要 或 修 订 版 本 号 。 范 围 : 任 意 、 空 1 。
get_parameter version 返 回 完 整 的 PDFlib 版 本 字 符 串 , 格 式 为 .., 可 能
附 带 beta、 rc 等 附 加 限 定 符 后 缀 。 范 围 : 任 意 、 空
。
get_parameter scope 返 回 当 前 范 围 的 名 称 ( 参 见 表 3.1)。 范 围 : 任 意 。
set_parameter trace ( 不 支 持 ) 如 果 为 true, 将 记 录 所 有 API 函 数 调 用 。 日 志 文 件 的 内 容 可 能 对
调 试 很 有 用 , PDFlib 支 持 人 员 可 能 也 需 要 这 些 内 容 。 范 围 : 任 意 。 默 认 值 :
false。
170 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.3 设 置 函 数 的 参 数 和 值
函 数 关 键 字 说 明
set_parameter tracefile ( 不 支 持 ) 设 置 跟 踪 文 件 名 。 范 围 : 任 意 , 但 必 须 在 启 用 跟 踪 之 前 设 置 。
默 认 值 :PDFlib.trace。
set_parameter logmsg ( 不 支 持 ) 如 果 启 用 了 日 志 , 将 提 供 的 文 本 写 入 日 志 文 件 。 这 可 能 对 调 试
客 户 端 代 码 很 有 用 。 范 围 : 任 意 。
1. 可 用 PDF * 的 NULL 或 0 自 变 量 调 用 。
C
C
void PDF_boot(void)
void PDF_shutdown(void)
分 别 用 来 启 动 和 关 闭 PDFlib。
范 围
空
绑 定 C: 尽 管 目 前 不 需 要 , 但 建 议 用 于 C 语 言 绑 定 。
其 他 绑 定 : 对 于 其 他 语 言 绑 定 , 启 动 和 关 闭 由 包 装 代 码 完 成 ; 故 不 提 供 这 些 函 数 。
Perl PHP resource PDF_new( )
C PDF *PDF_new(void)
用 默 认 设 置 创 建 新 的 PDFlib 对 象 。
详 细 说 明 此 函 数 使 用 PDFlib 的 内 部 默 认 错 误 处 理 和 内 存 分 配 例 程 创 建 新 的 PDFlib 对 象 。
返 回 值
指 向 PDFlib 对 象 的 句 柄 , 可 用 于 后 续 的 PDFlib 调 用 。 如 果 此 函 数 由 于 内 存 不 可 用 而 导 致 失
败 , 将 返 回 NULL (C 语 言 ) 或 引 发 异 常 。
范 围 空 ; 此 函 数 是 对 象 范 围 的 起 点 , 必 须 与 对 应 的 PDF_delete( ) 调 用 成 对 使 用 。
绑 定
根 据 不 同 的 语 言 绑 定 , 用 于 不 透 明 PDFlib 对 象 句 柄 的 数 据 类 型 会 有 所 差 异 。 由 于 PDFlib
客 户 端 所 要 做 的 就 是 作 为 第 一 个 自 变 量 将 PDF 句 柄 传 递 给 所 有 函 数 , 所 以 这 实 际 上 不 会 对
客 户 端 有 任 何 影 响 。
C: 为 了 在 运 行 时 动 态 地 载 入 PDFlib DLL, 应 用 PDF_new_dl( ) 替 代 ( 参 见 第 25 页 上 的 第
2.4.3 节 “ 使 用 PDFlib 作 为 在 运 行 时 加 载 的 DLL” )。PDF_new_dl( ) 将 返 回 一 个 指 向
PDFlib_api 结 构 的 指 针 ; 该 结 构 包 含 指 向 所 有 PDFlib API 函 数 的 指 针 。 如 果 无 法 载 入
DLL, 或 者 检 测 到 不 匹 配 的 主 要 / 次 要 版 本 号 , 将 返 回 NULL。
C++、 Java、 PHP 5: 由 于 此 函 数 隐 藏 在 PDFlib 构 造 函 数 内 , 所 以 无 法 使 用 。
C
PDF *PDF_new2(void (*errorhandler)(PDF *p, int errortype, const char *msg),
void* (*allocproc)(PDF *p, size_t size, const char *caller),
void* (*reallocproc)(PDF *p, void *mem, size_t size, const char *caller),
void (*freeproc)(PDF *p, void *mem),
void *opaque)
使 用 客 户 端 提 供 的 错 误 处 理 和 内 存 分 配 例 程 创 建 新 的 PDFlib 对 象 。
errorhandler 指 向 用 户 提 供 的 错 误 处 理 函 数 的 指 针 。PDF_TRY/PDF_CATCH 块 中 将 忽 略 错 误
句 柄 。
allocproc 指 向 用 户 提 供 的 内 存 分 配 函 数 的 指 针 。
8.2 常 规 函 数 171

eallocproc 指 向 用 户 提 供 的 内 存 重 新 分 配 函 数 的 指 针 。
freeproc 释 放 用 户 提 供 内 存 的 函 数 指 针 。
opaque 指 向 某 些 此 后 可 用 PDF_get_opaque( ) 返 回 的 用 户 数 据 。
返 回 值
详 细 说 明
范 围
绑 定
指 向 PDFlib 对 象 的 句 柄 , 可 用 于 后 续 的 PDFlib 调 用 。 如 果 此 函 数 由 于 内 存 不 可 用 而 导 致 失
败 , 将 返 回 NULL (C 语 言 ) 或 引 发 异 常 。
此 函 数 使 用 客 户 端 提 供 的 错 误 处 理 和 内 存 分 配 例 程 创 建 新 的 PDFlib 对 象 。 与 PDF_new( ) 不
同 , 调 用 方 可 以 选 择 提 供 自 己 的 错 误 处 理 和 内 存 分 配 过 程 。 错 误 句 柄 的 函 数 指 针 或 内 存 过 程
可 以 为 NULL, 或 两 者 同 时 为 NULL。 在 这 些 情 况 下 , PDFlib 将 使 用 默 认 例 程 。 必 须 同 时 提
供 所 有 三 个 内 存 例 程 , 或 一 个 都 不 提 供 。
空 ; 此 函 数 是 对 象 范 围 的 起 点 , 必 须 与 对 应 的 PDF_delete( ) 调 用 成 对 使 用 。 调 用 此 函 数 之
后 , 不 能 调 用 其 他 具 有 相 同 PDFlib 对 象 的 PDFlib 函 数 。
C++: 可 通 过 PDF 构 造 函 数 间 接 使 用 此 函 数 。 由 于 将 使 用 NULL 作 为 默 认 时 的 默 认 值 , 所
以 并 非 所 有 的 函 数 自 变 量 都 必 须 提 供 。 所 有 提 供 的 函 数 都 必 须 为 »C« 函 数 , 而 非 C++。
Perl PHP PDF_delete(resource p)
C void PDF_delete(PDF *p)
删 除 PDFlib 对 象 并 释 放 所 有 内 部 资 源 。
详 细 说 明
此 函 数 可 删 除 PDF 对 象 并 释 放 所 有 文 档 相 关 的 PDFlib 内 部 资 源 。 尽 管 生 成 单 个 文 档 不 一 定
要 求 删 除 PDF 对 象 , 但 强 烈 建 议 所 有 服 务 器 应 用 程 序 在 生 成 PDF 后 删 除 PDF 对 象 。 对 于 给
定 的 PDF 对 象 , 此 函 数 只 能 调 用 一 次 。 在 发 生 异 常 时 , 也 应 调 用 PDF_delete( ), 以 便 执 行 清
理 操 作 。PDF_delete( ) 本 身 可 保 证 不 引 发 任 何 异 常 。 如 果 将 生 成 多 个 PDF 文 档 , 不 必 在 建 成
每 个 文 档 后 调 用 PDF_delete( ), 只 需 在 整 个 PDF 文 档 序 列 完 成 后 调 用 即 可 。
范 围 任 意 ; 此 函 数 是 空 范 围 的 起 点 , 即 不 允 许 调 用 其 他 API 函 数 。
绑 定 C: 如 果 已 经 用 PDF_new_dl( ), 在 运 行 时 动 态 载 入 了 PDFlib DLL, 应 使 用 PDF_delete_dl( )
删 除 PDFlib 对 象 。
C++: 可 通 过 PDF 解 构 函 数 间 接 使 用 此 函 数 。
Java: 此 函 数 由 包 装 代 码 自 动 调 用 。 但 是 , 可 以 通 过 客 户 端 代 码 显 式 调 用 , 以 克 服 Java 终
结 器 系 统 中 的 缺 点 。
PHP:PDFlib 对 象 超 出 范 围 时 , 面 向 对 象 的 PHP 5 接 口 将 自 动 调 用 此 函 数 。
8.2.2 文 档 和 页 面
表 8.4 列 出 了 本 节 的 相 关 参 数 及 相 应 的 值 。
表 8.4 文 档 和 页 面 函 数 的 参 数 和 值
函 数 关 键 字 说 明
set_parameter openwarning 不 常 用 , 打 开 文 档 时 使 用 PDF_get_errmsg( ) 查 找 尝 试 失 败 的 原 因 。
set_value
pagewidth
pageheight
不 常 用 , 使 用 PDF_begin_page_ext( ) 的 width 和 height 参 数 , 或 者 使 用
PDF_begin_page_ext( ) 或 PDF_end_page_ext( ) 的 mediabox 选 项 。
set_parameter topdown 如 果 为 true, 将 假 定 页 面 、 图 案 或 模 板 开 头 坐 标 系 统 的 原 点 位 于 页 面 左
上 角 , y 坐 标 值 向 下 增 加 ; 否 则 , 将 使 用 默 认 坐 标 系 统 ( 参 见 第 53 页 上
的 第 3.2.1 节 “ 坐 标 系 统 ”)。 范 围 : 文 档 。 默 认 值 :false
172 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.4 文 档 和 页 面 函 数 的 参 数 和 值
函 数 关 键 字 说 明
get_value pagewidth 获 取 当 前 页 面 的 页 面 大 小 (MediaBox 的 尺 寸 )。 范 围 : 页 面 、 路 径
pageheight
set_value 作 品 框
BleedBox
CropBox
TrimBox
不 常 用 , 使 用 PDF_begin_page_ext( ) 或 PDF_end_page_ext( ) 的 artbox、
bleedbox、 cropbox 和 trimbox 选 项 。
set_parameter
userpassword
masterpassword
permissions
不 常 用 , 使 用 PDF_begin_document( ) 的 userpassword/masterpassword/
permissions 选 项 。
C++ Java
Perl PHP
C
int begin_document(String filename, String optlist)
int PDF_begin_document(resource p, string filename, string optlist)
int PDF_begin_document(PDF *p, const char *filename, int len, const char *optlist)
C++
C
void begin_document_callback(size_t (*writeproc) (PDF *p, void *data, size_t size),
string optlist)
void PDF_begin_document_callback(PDF *p,
size_t (*writeproc) (PDF *p, void *data, size_t size), const char *optlist)
根 据 各 种 选 项 创 建 新 的 PDF 文 件 。
filename ( 名 称 字 符 串 , 但 只 在 Windows 上 支 持 Unicode 文 件 名 ) 将 生 成 PDF 输 出 文 件
的 绝 对 或 相 对 文 件 名 。 如 果 filename 为 空 , 则 将 在 内 存 中 生 成 PDF 文 档 , 而 不 创 建 文 件 ,
因 而 只 能 从 客 户 端 通 过 PDF_get_buffer( ) 函 数 来 获 取 生 成 的 PDF 数 据 。 特 殊 文 件 名 »–« 可 用
来 在 stdout 通 道 上 生 成 PDF。 在 Windows 上 , 可 以 使 用 UNC 路 径 或 映 射 网 络 驱 动 器 。
len ( 仅 用 于 C 语 言 绑 定 ) UTF-16 字 符 串 的 filename 长 度 ( 以 字 节 为 单 位 ) 。 如 果 len =
0, 则 必 须 提 供 以 null 终 结 的 字 符 串 。
writeproc ( 仅 用 于 C 和 C++)C 回 调 函 数 , 可 由 PDFlib 调 用 , 以 提 交 生 成 的 ( 部 分 )PDF
数 据 。
optlist 选 项 列 表 , 根 据 表 8.5 或 表 8.6 指 定 文 档 选 项 。PDF_end_document( ) 中 指 定 的 选 项
优 先 于 PDF_begin_document( ) 中 指 定 的 相 同 选 项 。
返 回 值
详 细 说 明
范 围
绑 定
-1 未 产 生 错 误 时 , 返 回 -1 ( 在 PHP 中 : 返 回 0) , 否 则 为 1。 如 果 filename 为 空 , 此 函 数 始
终 都 能 成 功 运 行 , 则 不 会 返 回 错 误 值 -1 ( 在 PHP 中 : 返 回 0)。
此 函 数 使 用 提 供 的 filename 创 建 新 PDF 文 件 。 PDFlib 将 尝 试 使 用 给 定 文 件 名 打 开 文 件 , 并
在 PDF 文 档 完 成 时 关 闭 文 件 。
PDF_begin_document_callback( ) 会 在 内 存 中 打 开 新 PDF 文 档 , 而 不 写 入 磁 盘 文 件 。 作 为
提 供 的 回 调 函 数 , writeproc 必 须 返 回 写 入 的 字 节 数 。 如 果 返 回 值 不 匹 配 PDFlib 提 供 的 size
自 变 量 , 将 引 发 异 常 。 writeproc 的 调 用 频 率 可 由 flush 选 项 配 置 。
对 象 ; 如 果 文 件 可 以 成 功 打 开 , 此 函 数 将 为 文 档 范 围 的 起 点 ; 必 须 始 终 与 对 应 的 PDF_end_
document( ) 调 用 成 对 使 用 。
C、 C++、 Java、 JScript: 确 保 正 确 地 转 义 反 斜 线 路 径 分 隔 符 。 例 如 , 以 下 路 径 指 示 网 络 驱
动 器 上 的 一 个 文 件 :\\\\malik\\rp\\foo.pdf。
8.2 常 规 函 数 173

PDF_begin_document_callback( ) 只 能 用 于 C 和 C++。 提 供 的 writeproc 必 须 为 C 语 言 函 数 ,
而 非 C++。
表 8.5 PDF_begin_document( ) 和 PDF_begin_document_callback( ) 的 文 档 选 项
选 项 类 型 描 述
compatibility 关 键 字 将 文 档 的 PDF 版 本 设 为 Acrobat 4、 5、 6 或 7 的 »1.3«、 »1.4«、 »1.5« 或 »1.6« 字
符 串 。 有 关 详 细 信 息 , 请 参 见 第 151 页 上 的 第 7.1 节 “Acrobat 和 PDF 版 本 ”。
如 果 使 用 pdfx 参 数 , 则 忽 略 此 选 项 。 默 认 值 :»1.5«
flush 关 键 字 ( 仅 用 于 PDF_begin_document_callback( )) 设 置 刷 新 策 略 ; 有 关 详 细 信 息 ,
请 参 见 第 51 页 上 的 第 3.1.6 节 “ 在 内 存 中 生 成 PDF 文 档 ”( 默 认 值 :page):
none 只 在 文 档 结 尾 刷 新 一 次
page 在 每 页 的 结 尾 刷 新 一 次
content 在 所 有 字 体 、 图 像 、 文 件 附 件 和 页 面 后 进 行 刷 新
heavy 始 终 在 内 部 64 KB 文 档 缓 冲 区 已 满 时 刷 新
groups
字 符 串
列 表
定 义 文 档 中 使 用 的 页 面 组 的 名 称 和 顺 序
inmemory 布 尔 型 ( 仅 用 于 PDF_begin_document( )) 如 果 为 true, 并 且 linearize 选 项 也 为 true,
PDFlib 将 不 为 线 性 化 处 理 创 建 任 何 临 时 文 件 , 而 在 内 存 中 处 理 文 件 。 这 可 能 会
大 大 提 高 某 些 系 统 上 的 性 能 ( 尤 其 是 MVS), 但 要 求 两 倍 于 文 档 大 小 的 内 存 。
如 果 为 false, 将 为 线 性 化 处 理 创 建 临 时 文 件 。 默 认 值 :false
lang 字 符 串 ( 如 果 tagged=true, 则 要 求 此 选 项 ) 将 文 档 的 自 然 语 言 设 为 由 两 个 字 符 组 成 的
ISO 639 语 言 代 码 ( 例 如 :DE、 EN、 FR、 JA), 后 面 可 以 跟 一 个 连 字 符 和 由 两
个 字 符 组 成 的 ISO 3166 国 家 / 地 区 代 码 ( 例 如 :EN-US、 EN-GB、 ES-MX)。 不
区 分 大 小 写 。
在 初 始 化 时 , 需 为 文 档 的 语 言 规 范 统 一 赋 值 , 随 后 可 在 结 构 树 的 各 个 级 别 上 用
新 值 覆 盖 。
linearize 布 尔 型 ( 仅 用 于 PDF_begin_document( )) 如 果 为 true, 将 对 输 出 文 档 进 行 线 性 化 处 理
( 参 见 第 154 页 上 的 第 7.3 节 “ 网 页 优 化 的 ( 线 性 化 的 ) PDF”)。 在 MVS 系 统
上 , 此 选 项 不 能 用 于 将 生 成 的 PDF 输 出 到 内 存 ( 即 , 空 filename)。 默 认 值 :
false
masterpassword 字 符 串 文 档 的 许 可 口 令 。 如 果 此 选 项 为 空 , 将 不 应 用 许 可 口 令 。 默 认 值 :empty
permissions
关 键 字
列 表
输 出 文 档 的 访 问 权 限 列 表 。 此 选 项 可 包 含 任 意 数 量 的 noprint、 nomodify、
nocopy、 noannots、 noassemble、 noforms、 noaccessible、 nohiresprint 和
plainmetadata 关 键 字 ( 参 见 表 7.3)。 默 认 值 :empty
pdfx 关 键 字 设 置 PDF/X 规 范 等 级 , 例 如 »PDF/X-1:2001« 、 »PDF/X-1a:2001«、 »PDF/
X-1a:2003«、 »PDF/X-2:2003«、 »PDF/X-3:2002«、 »PDF/X-3:2003«, 或 »none«
或 ( 参 见 第 155 页 上 的 第 7.4 节 “PDF/X”)。 默 认 值 :none
recordsize 整 型 ( 仅 用 于 MVS) 输 出 文 件 的 记 录 大 小 。 默 认 值 :0 ( 无 阻 断 输 出 )
tagged 布 尔 型 (PDF 1.4 或 更 高 版 本 ) 如 果 为 true, 则 生 成 加 标 签 的 PDF 输 出 。 必 须 由 客 户 端
在 加 标 签 的 PDF 模 式 下 , 提 供 正 确 的 结 构 信 息 ( 参 见 第 259 页 上 的 第 8.10 节
“ 标 签 PDF 的 结 构 函 数 ”)。 默 认 值 :false
tempdirname 字 符 串 ( 仅 用 于 PDF_begin_document( )) 在 其 中 创 建 线 性 化 处 理 所 需 临 时 文 件 的 目 录
的 名 称 。 如 果 为 空 , PDFlib 将 在 当 前 目 录 内 生 成 临 时 文 件 。 如 果 提 供 了
tempfilenames 选 项 , 则 将 忽 略 此 选 项 。 默 认 值 :empty
tempfilenames
两 个 字 符
串 组 成 的
列 表
( 仅 用 于 MVS 和 PDF_begin_document( ))PDFlib 内 部 处 理 所 需 的 两 个 临 时 文 件
的 完 全 文 件 名 。 如 果 为 空 , PDFlib 将 生 成 唯 一 的 临 时 文 件 名 。 用 户 负 责 在 PDF_
end_document( ) 之 后 删 除 临 时 文 件 。 如 果 提 供 了 此 选 项 , filename 参 数 不 能
为 空 。 默 认 值 :empty
userpassword 字 符 串 文 档 的 文 档 打 开 口 令 。 如 果 为 空 , 则 不 应 用 文 档 打 开 口 令 。 默 认 值 :empty
174 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
void end_document(String optlist)
PDF_end_document(resource p, string optlist)
void PDF_end_document(PDF *p, const char *optlist)
关 闭 生 成 的 PDF 文 件 并 应 用 各 种 选 项 。
optlist 选 项 列 表 , 根 据 表 8.6 指 定 文 档 选 项 。 PDF_end_document( ) 中 指 定 的 选 项 优 先 于
PDF_begin_document( ) 中 指 定 的 相 同 选 项 。
详 细 说 明 此 函 数 完 成 PDF 文 档 生 成 , 释 放 所 有 文 档 相 关 的 资 源 ; 如 果 已 经 用 PDF_begin_document( )
打 开 了 文 档 , 此 函 数 还 可 关 闭 输 出 文 件 。 无 论 使 用 何 种 方 法 打 开 PDF 文 档 , 客 户 端 完 成 页
面 生 成 操 作 时 都 必 须 调 用 此 函 数 。
在 内 存 中 生 成 文 档 时 ( 而 不 在 文 件 中 ), 调 用 此 函 数 后 仍 将 保 留 文 档 缓 冲 区 ( 因 此 , 可
使 用 PDF_get_buffer( ) 提 取 数 据 ), 并 将 在 下 次 调 用 PDF_begin_document( ) 或 者 PDFlib 对
象 在 PDF_delete( ) 中 的 超 出 范 围 时 释 放 文 档 缓 冲 区 。
范 围
文 档 ; 此 函 数 终 结 文 档 范 围 , 应 始 终 与 PDF_begin_document( ) 或 PDF_begin_document_
callback( ) 函 数 调 用 成 对 使 用 。
表 8.6 PDF_begin_document( ) 和 PDF_end_document( ) 的 文 档 选 项
选 项 类 型 描 述
action 动 作 列 表 ( 打 开 动 作 适 用 于 PDF 1.3 或 更 高 版 本 , 而 其 余 动 作 只 适 用 于 PDF 1.4 或 更
高 版 本 。 由 于 只 能 在 调 用 PDF_begin_document( ) 之 后 创 建 动 作 , 所 以 此
选 项 只 适 用 于 PDF_end_document( )) 下 列 一 项 或 多 项 事 件 的 文 档 动 作 列
表 ( 默 认 值 : 空 列 表 ):
open 打 开 文 档 时 执 行 的 动 作 。 请 注 意 , 由 于 在 Acrobat 中 的 执 行 顺
序 , 文 档 级 JavaScript 不 能 用 于 open 动 作 。
didprint 打 印 文 档 后 执 行 的 JavaScript 动 作 。
didsave 保 存 文 档 后 执 行 的 JavaScript 动 作 。
willclose 关 闭 文 档 前 执 行 的 JavaScript 动 作 。
willprint 打 印 文 档 前 执 行 的 JavaScript 动 作 。
willsave 保 存 文 档 前 执 行 的 JavaScript 动 作 。
destination 选 项 列 表 选 项 列 表 , 根 据 表 8.50 指 定 文 档 打 开 动 作 。 打 开 动 作 将 取 代 此 选 项 , 并
将 用 作 默 认 动 作 。
labels
选 项 列 表
的 列 表
包 含 根 据 表 8.8 提 供 的 一 个 或 多 个 选 项 列 表 的 列 表 , 指 定 符 号 页 面 名 称 。
页 面 名 称 将 在 Acrobat 的 状 态 行 中 显 示 为 页 面 标 签 ( 而 非 页 码 )。 在 一 个
文 档 中 , style/prefix/start 值 的 组 合 必 须 是 唯 一 的 。 默 认 值 :none
moddate 布 尔 型 如 果 为 true, 将 创 建 ModDate ( 修 改 日 期 ) 文 档 信 息 关 键 字 , 以 符 合 某
些 preflight 工 具 的 要 求 。 默 认 值 :false
openmode 关 键 字 设 置 文 档 打 开 时 的 外 观 。 默 认 值 : 如 果 文 档 包 含 任 何 书 签 , 则 为
bookmarks ; 否 则 为 none:
none 打 开 时 不 显 示 任 何 其 他 面 板 。
bookmarks 打 开 时 显 示 书 签 面 板 。
thumbnails 打 开 时 显 示 缩 览 图 面 板
fullscreen 以 全 屏 模 式 打 开 ( 不 适 用 于 浏 览 器 )。
layers (PDF 1.5) 打 开 时 显 示 图 层 面 板 。
pagelayout 关 键 字 打 开 文 档 时 使 用 的 页 面 版 面 ( 默 认 值 :singlepage):
singlepage 一 次 显 示 一 页 。
onecolumn 在 一 列 中 连 续 显 示 多 页 。
twocolumnleft 在 两 列 中 显 示 多 页 , 奇 数 页 在 左 侧 。
twocolumnright 在 两 列 中 显 示 多 页 , 奇 数 页 在 右 侧 。
uri 字 符 串 设 置 文 档 的 基 本 URL。 将 具 有 指 向 其 他 文 档 的 相 对 Web 链 接 的 文 档 移 至
不 同 位 置 时 , 此 选 项 非 常 有 用 。 设 置 到 »old« 位 置 的 基 本 URL 可 确 保 相 对
链 接 仍 然 可 以 使 用 。 默 认 值 :none
8.2 常 规 函 数 175

表 8.6 PDF_begin_document( ) 和 PDF_end_document( ) 的 文 档 选 项 ( 续 )
选 项 类 型 描 述
viewerpreferences 选 项 列 表 选 项 列 表 , 根 据 表 8.7 指 定 各 种 查 看 器 首 选 项 。 默 认 值 :empty
metadata 选 项 列 表 (PDF 1.4) 提 供 文 档 的 元 数 据 。 PDFlib 不 同 步 元 数 据 和 文 档 信 息 域 。 此 选 项
列 表 可 以 包 含 下 列 选 项 :
inputencoding (keyword)
用 来 解 释 提 供 的 数 据 的 编 码 方 式 。 默 认 值 :unicode
inputformat (keyword)
提 供 的 数 据 的 格 式 。 默 认 值 :utf8 ( 基 于 EBCDIC 的 系 统 上 为
ebcdicutf8); 但 是 , 如 果 inputencoding 为 8 位 编 码 方 式 , 则
默 认 为 bytes。
filename (name string, required) 包 含 元 数 据 的 基 于 磁 盘 的 文 件 或 虚 拟 文
件 的 文 件 名 。 此 文 件 必 须 包 含 格 式 正 确 的 XMP 元 数 据 , 无 需
压 缩 即 可 将 其 复 制 到 输 出 中 。 PDFlib 将 自 动 生 成 XDP 包 头 和
包 尾 。
outputformat (keyword)
数 据 写 入 PDF 输 出 时 采 用 的 格 式 ( 输 出 编 码 始 终 为 unicode)。
可 能 的 值 包 括 utf8、 utf16be 和 utf16le。 默 认 值 : 如 果
inputformat=bytes, 为 utf8 ; 否 则 为 inputformat
表 8.7 PDF_begin_document( ) 和 PDF_end_document( ) 中 viewerpreference 选 项 的 子 选 项
选 项 类 型 描 述
centerwindow 布 尔 型 指 定 是 否 将 文 档 窗 口 置 于 屏 幕 中 央 。 默 认 值 :false
direction 关 键 字 阅 读 文 档 的 顺 序 , 将 影 响 双 页 面 视 图 中 的 滚 动 顺 序 。( 默 认 为 l2r):
l2r 从 左 至 右
r2l 从 右 至 左 ( 包 括 直 排 书 写 系 统 )
displaydoctitle 布 尔 型 指 定 是 否 在 Acrobat 的 标 题 栏 (true) 或 是 文 件 名 (false) 中 显 示 Title 文 档 信
息 域 。 默 认 值 :false
fitwindow 布 尔 型 指 定 是 否 将 文 档 窗 口 的 大 小 调 整 为 第 一 页 的 大 小 。 默 认 值 :false
hidemenubar 布 尔 型 指 定 是 否 隐 藏 Acrobat 菜 单 栏 。 默 认 值 :false
hidetoolbar 布 尔 型 指 定 是 否 隐 藏 Acrobat 工 具 栏 。 在 浏 览 器 中 查 看 PDF 时 , Acrobat 会 忽 略
此 设 置 。 默 认 值 :false
hidewindowui 布 尔 型 指 定 是 否 隐 藏 Acrobat 的 窗 口 控 件 。 默 认 值 :false
nonfullscreenpagemode 关 键 字 ( 仅 用 于 openmode 选 项 设 为 fullscreen 的 情 况 ) 指 定 如 何 在 现 有 全 屏 模
式 下 显 示 文 档 ( 默 认 值 :none):
bookmarks 显 示 页 面 和 书 签 窗 格
thumbnails 显 示 页 面 和 缩 览 图 窗 格
layers
显 示 页 面 和 图 层 窗 格
none
只 显 示 页 面
viewarea
viewclip
printarea
printclip
关 键 字
在 屏 幕 上 查 看 或 打 印 文 档 时 , 代 表 要 显 示 或 剪 贴 的 页 面 区 域 的 页 面 边 界 框
类 型 。 Acrobat 会 忽 略 此 设 置 , 但 可 能 对 其 他 应 用 程 序 很 有 用 ( 默 认 值 :
crop):
art 使 用 作 品 框
bleed 使 用 出 血 框
crop 使 用 裁 剪 框
media 使 用 媒 体 框
trim 使 用 裁 切 框
PDF/X: 不 允 许 除 media 或 bleed 之 外 的 值 。
176 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.8 PDF_begin/end_document( ) 中 labels 选 项 和 PDF_begin/end_page_ext( ) 中 label 选 项 的 子 选 项
选 项 类 型 描 述
group 字 符 串 ( 仅 用 于 PDF_begin_document( ) ; 如 果 文 档 使 用 页 面 组 , 则 要 求 此 选 项 ;
否 则 , 不 允 许 使 用 此 选 项 。) 标 签 将 应 用 于 指 定 组 以 及 应 用 新 标 签 之 前 的
所 有 后 续 组 中 的 所 有 页 面 。
hypertextencoding 关 键 字 指 定 prefix 选 项 的 编 码 方 式 ( 参 见 第 85 页 上 的 第 4.5.4 节 “ 不 支 持
Unicode 的 语 言 中 的 字 符 串 处 理 ”)。 空 字 符 串 相 当 于 unicode。
默 认 值 : 全 局 hypertextencoding 参 数 的 值 。
pagenumber 整 型 ( 仅 用 于 PDF_end_document( ) ; 如 果 文 档 不 使 用 页 面 组 , 则 要 求 此 选
项 , 否 则 不 允 许 使 用 此 选 项 ) 标 签 将 应 用 于 指 定 页 面 以 及 应 用 新 标 签 之 前
的 所 有 页 面 。
prefix
超 文 本 字 处 于 该 范 围 内 的 所 有 标 签 的 标 签 前 缀 。 默 认 值 :none
符 串
start 整 型 >= 1 该 范 围 内 第 一 个 标 签 的 数 值 。 该 范 围 内 的 后 续 页 面 将 从 该 值 开 始 , 依 次 编
号 。 默 认 值 :1
style 关 键 字 要 使 用 的 编 号 样 式 ( 默 认 值 :none):
none 无 页 码 ; 标 签 将 只 包 含 前 缀 。
D 十 进 制 阿 拉 伯 数 字 (1、 2、 3、 ...)
R 大 写 罗 马 数 字 (I、 II、 III、 ...)
r 小 写 罗 马 数 字 (i、 ii、 iii、 ...)
A 大 写 字 母 (A、 B、 C、 ...、 AA、 BB、 CC、 ...)
a 小 写 字 母 (a、 b、 c、 ...、 aa、 bb、 cc、 ...)
C++ const char *get_buffer(long *size)
Java byte[] get_buffer( )
Perl PHP string PDF_get_buffer(resource p)
C const char * PDF_get_buffer(PDF *p, long *size)
获 取 PDF 输 出 缓 存 区 的 内 容 。
size ( 仅 用 于 C 和 C++ 语 言 绑 定 ) 指 向 内 存 位 置 的 C 语 言 指 针 ; 将 在 其 中 存 储 返 回 数 据 的
长 度 ( 以 字 节 为 单 位 )。
返 回 值
详 细 说 明
范 围
充 满 二 进 制 PDF 数 据 的 缓 存 区 , 供 客 户 端 使 用 。 根 据 表 8.1 返 回 二 进 制 数 据 的 语 言 特 定 数 据
类 型 。 调 用 任 何 其 他 PDFlib 函 数 之 前 , 返 回 的 缓 存 区 必 须 供 客 户 端 使 用 。 如 果 希 望 在 调 用
其 他 PDFlib 函 数 时 使 用 , 切 记 要 复 制 数 据 ( 尤 其 是 在 调 用 PDF_create_pvf( ) 创 建 包 含 该 数
据 的 PVF 文 件 之 前 )。
提 取 全 部 或 部 分 包 含 生 成 PDF 数 据 的 缓 存 区 。 如 果 此 函 数 在 页 面 描 述 之 间 调 用 , 它 将 返 回
迄 今 为 止 生 成 的 PDF 数 据 。 如 果 在 内 存 中 生 成 PDF, 此 函 数 至 少 须 在 PDF_end_document( )
之 后 调 用 , 并 将 返 回 PDF 文 档 的 剩 余 部 分 。 可 以 在 此 之 前 调 用 此 函 数 , 以 提 取 部 分 文 档 数
据 。 如 果 此 函 数 只 在 PDF_end_document( ) 之 后 调 用 一 次 , 则 返 回 的 缓 存 区 肯 定 会 在 连 续 缓
存 区 内 包 含 整 个 PDF 文 档 。
由 于 PDF 输 出 包 含 二 进 制 字 符 , 客 户 端 软 件 必 须 准 备 接 受 包 括 空 值 在 内 的 不 可 打 印 字 符 。
对 象 、 文 档 ( 换 言 之 : 在 PDF_end_page_ext( ) 之 后 和 PDF_begin_page_ext( ) 之 前 , 或 者
在 PDF_end_document( ) 之 后 和 PDF_delete( ) 之 前 。 此 函 数 只 能 在 已 确 保 向 PDF_begin_
document( ) 提 供 了 空 的 filename 的 情 况 下 , 才 只 能 使 用 。
如 果 PDF_begin_document( ) 中 的 linearize 选 项 已 设 为 true, 则 范 围 将 限 制 在 对 象 内 ;
即 : 只 能 在 PDF_end_document( ) 之 后 调 用 此 函 数 。
8.2 常 规 函 数 177

绑 定 C 和 C++:size 参 数 只 能 用 于 C 和 C++ 客 户 端 。
其 他 绑 定 : 将 返 回 适 当 长 度 的 对 象 , 且 必 须 省 略 size 参 数 。
C++ Java
Perl PHP
C
void begin_page_ext(double width, double height, String optlist)
PDF_begin_page_ext(resource p, float width, float height, string optlist)
void PDF_begin_page_ext(PDF *p, double width, double height, const char *optlist)
向 文 档 添 加 一 个 新 页 面 并 指 定 各 种 选 项 。
width, height width 和 height 参 数 以 点 数 为 单 位 指 定 新 页 面 的 尺 寸 。 可 用 具 有 相 同 名 称
的 选 项 覆 盖 这 两 个 参 数 ( 这 种 情 况 下 , 可 为 参 数 使 用 虚 值 0)。 表 3.4 列 出 了 常 用 的 页 面 格
式 。 有 关 更 多 详 细 信 息 (width 和 height 选 项 ), 另 请 参 见 表 8.10。
optlist 根 据 表 8.9 和 表 8.10 提 供 的 选 项 列 表 。 这 些 选 项 的 优 先 级 低 于 PDF_end_page_
ext( ) 中 指 定 的 相 同 选 项 。
详 细 说 明 此 函 数 将 新 页 面 的 所 有 文 本 、 图 形 和 颜 色 状 态 参 数 重 设 为 他 们 的 默 认 值 。
范 围 文 档 ; 此 参 数 是 页 面 范 围 的 开 头 , 必 须 与 对 应 的 PDF_end_page_ext( ) 调 用 成 对 使 用 。
参 数
使 用 此 函 数 时 , 将 忽 略 下 列 不 常 用 的 参 数 :pagewidth、 pageheight、 ArtBox、 BleedBox、
CropBox、 TrimBox。
表 8.9 PDF_begin_page_ext( ) 的 选 项
选 项 类 型 描 述
group 字 符 串 ( 如 果 文 档 使 用 页 面 组 , 则 要 求 此 选 项 ; 否 则 , 不 允 许 使 用 此 选 项 。) 页
面 所 属 页 面 组 的 名 称 。 此 名 称 可 使 页 面 保 持 在 一 个 页 面 组 内 , 并 可 用
PDF_resume_page( ) 确 定 页 面 地 址 。
pagenumber 整 型 如 果 用 值 n 指 定 此 选 项 , 则 将 在 group 选 项 指 定 的 页 面 组 内 现 有 第 n 页 前
插 入 页 面 ( 如 果 文 档 不 使 用 页 面 组 , 则 在 文 档 中 插 入 页 面 )。 如 果 未 指
定 此 选 项 , 将 在 页 面 组 末 尾 插 入 页 面 。
separationinfo 选 项 列 表 包 含 当 前 页 面 的 详 细 分 色 信 息 的 选 项 列 表 。 Acrobat 中 将 忽 略 此 选 项 , 但
第 三 方 软 件 可 能 会 用 它 在 预 分 色 工 作 流 程 中 确 定 并 正 确 预 览 分 色 页 :
pages ( 整 型 ; 一 组 分 色 页 的 第 一 个 页 面 要 求 此 选 项 , 但 同 一 组 的 后
续 页 面 不 允 许 使 用 此 选 项 ) 属 于 同 一 组 分 色 页 的 页 面 数 量 ; 分
色 页 包 含 单 个 复 合 页 的 颜 色 数 据 。 同 一 组 内 的 所 有 页 面 必 须 在
文 件 中 依 次 显 示 。
spotname ( 字 符 串 ; 除 非 提 供 了 spotcolor, 否 则 要 求 使 用 此 选 项 ) 当 前
页 面 的 色 料 名 称 。
spotcolor ( 专 色 句 柄 ) 描 述 当 前 页 面 色 料 的 颜 色 句 柄 。
topdown 布 尔 型 如 果 为 true, 将 假 定 页 面 开 头 坐 标 系 统 的 原 点 位 于 页 面 左 上 角 , y 坐 标 值
向 下 增 加 ; 否 则 , 将 使 用 默 认 坐 标 系 统 ( 参 见 第 53 页 上 的 第 3.2.1 节 “ 坐
标 系 统 ”)。 默 认 值 :false
C++ Java
Perl PHP
C
void end_page_ext(String optlist)
PDF_end_page_ext(resource p, string optlist)
void PDF_end_page_ext(PDF *p, const char *optlist)
完 成 页 面 并 应 用 各 种 选 项 。
optlist 根 据 表 8.10 提 供 的 选 项 列 表 。 PDF_end_page_ext( ) 中 指 定 的 选 项 优 先 于
PDF_begin_page_ext( ) 中 指 定 的 相 同 选 项 。
178 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

范 围 页 面 ; 此 函 数 终 结 页 面 范 围 , 必 须 与 对 应 的 PDF_begin_page_ext( ) 调 用 成 对 使 用 。
表 8.10 PDF_begin_page_ext( ) 和 PDF_end_page_ext( ) 的 选 项
选 项 类 型 描 述
action 动 作 列 表 下 列 一 个 或 多 个 事 件 的 页 面 动 作 列 表 。 默 认 值 :empty list:
open 打 开 页 面 时 执 行 的 动 作 。
close 关 闭 页 面 时 执 行 的 动 作 。
artbox
bleedbox
cropbox
mediabox
trimbox
矩 形 ( 如 果 topdown 选 项 或 参 数 为 true, 不 允 许 使 用 mediabox 选 项 ) 更 改 当 前 页
面 的 页 面 框 参 数 。 各 个 框 的 坐 标 在 默 认 坐 标 系 统 中 指 定 ( 有 关 详 细 信 息 , 请 参
见 第 55 页 上 的 第 3.2.2 节 “ 页 面 大 小 和 坐 标 限 制 ”)。 默 认 情 况 下 , 将 只 使 用
width 和 height 参 数 创 建 媒 体 框 (MediaBox)。 mediabox 选 项 将 覆 盖 width 和
height 选 项 和 参 数 。
defaultgray
defaultrgb
defaultcmyk
icc 句 柄 根 据 提 供 的 配 置 文 件 句 柄 , 设 置 页 面 的 默 认 灰 色 、 RGB 或 CMYK 色 彩 空 间 。
duration 浮 点 型 如 果 openmode=fullscreen, 则 以 秒 为 单 位 , 设 置 当 前 页 面 的 显 示 时 间 ( 参 见
表 8.6)。 默 认 值 :1
label 选 项 列 表 根 据 表 8.8 提 供 的 选 项 列 表 , 指 定 符 号 页 面 名 称 。 页 面 名 称 将 在 Acrobat 的 状
态 行 中 显 示 为 页 面 标 签 ( 而 非 页 码 )。 指 定 的 编 号 方 案 将 用 于 当 前 和 后 续 页
面 , 直 至 再 次 更 改 为 止 。 在 一 个 文 档 中 , style/prefix/start 值 的 组 合 必 须 是 唯
一 的 。
metadata 选 项 列 表 (PDF 1.4) 提 供 页 面 的 元 数 据 。 有 关 详 细 信 息 , 请 参 阅 表 8.6 中 对 metadata 选 项
的 描 述 。
rotate 整 型 页 面 旋 转 值 。 旋 转 将 影 响 页 面 显 示 , 但 不 会 修 改 坐 标 系 统 。 可 能 的 值 包 括 0、
90、 180、 270。 默 认 值 :0
transition 关 键 字 如 果 openmode=fullscreen, 设 置 当 前 页 面 的 页 面 转 换 , 以 实 现 特 殊 效 果 ; 在
Acrobat 的 全 屏 模 式 下 , 以 演 示 文 稿 的 形 式 显 示 PDF 时 , 这 个 选 项 会 很 有 用
( 参 见 表 8.6)。 默 认 值 :replace
split 两 行 在 屏 幕 上 掠 过 , 显 示 整 个 页 面
blinds 多 行 在 屏 幕 上 掠 过 , 显 示 整 个 页 面
box 在 框 中 显 示 页 面
wipe 单 行 掠 过 屏 幕 , 显 示 整 个 页 面
dissolve 旧 页 面 分 解 , 逐 渐 显 示 页 面
glitter 分 解 效 果 从 屏 幕 的 一 个 边 缘 移 动 至 另 一 边 缘
replace 简 单 地 用 新 页 面 替 代 旧 页 面
fly (PDF 1.5) 新 页 面 飞 入 旧 页 面
push (PDF 1.5) 新 页 面 将 旧 页 面 推 出 屏 幕
cover (PDF 1.5) 新 页 面 滑 入 屏 幕 , 覆 盖 旧 页 面
uncover (PDF 1.5) 旧 页 面 滑 出 屏 幕 , 显 示 新 页 面
fade (PDF 1.5) 在 旧 页 面 中 逐 渐 显 示 新 页 面
width
height
浮 点 型 或 关
键 字
( 如 果 topdown 选 项 或 参 数 为 true, 则 不 允 许 此 选 项 ) 新 页 面 的 尺 寸 , 以 点 数
为 单 位 。 第 55 页 上 的 第 3.2.2 节 “ 页 面 大 小 和 坐 标 限 制 ” 介 绍 了 Acrobat 的 页
面 大 小 限 制 。 要 生 成 横 向 页 面 , 应 使 用 width > height 或 rotate 选 项 。 PDFlib
使 用 width 和 height 选 项 构 建 页 面 的 媒 体 框 , 但 也 可 以 使 用 mediabox 选 项 显
式 设 置 媒 体 框 。 width 和 height 选 项 将 覆 盖 名 称 相 同 的 参 数 。
可 在 下 列 符 号 页 面 大 小 名 称 后 附 加 .width 或 .height, 将 其 用 作 关 键 字 , 例 如 :
a4.width、 a4.height。 有 关 下 列 数 字 值 的 信 息 , 请 参 见 表 3.4:
a0、 a1、 a2、 a3、 a4、 a5、 a6、 b5、 letter、 legal、 ledger 或 11x17
8.2 常 规 函 数 179

C++ Java
Perl PHP
C
void suspend_page(String optlist)
PDF_suspend_page(resource p, string optlist)
void PDF_suspend_page(PDF *p, const char *optlist)
暂 停 当 前 页 面 , 以 便 可 以 在 稍 后 恢 复 。
optlist 供 将 来 使 用 的 选 项 列 表 。
详 细 说 明 将 在 内 部 保 存 当 前 页 面 的 完 全 状 态 ( 图 形 、 颜 色 、 文 本 等 )。 稍 后 可 使 用 PDF_resume_page( )
恢 复 页 面 , 以 添 加 更 多 内 容 。 必 须 先 恢 复 暂 停 的 页 面 , 然 后 才 能 将 其 关 闭 。
范 围
页 面 ; 此 参 数 是 文 档 范 围 的 开 头 , 必 须 与 对 应 的 PDF_resume_page( ) 调 用 成 对 使 用 。 不 能 在
标 签 PDF 模 式 下 使 用 此 函 数 。
C++ Java
Perl PHP
C
void resume_page(String optlist)
PDF_resume_page(resource p, string optlist)
void PDF_resume_page(PDF *p, const char *optlist)
恢 复 页 面 , 以 向 其 添 加 更 多 内 容 。
optlist 根 据 表 8.11 提 供 的 选 项 列 表 。
详 细 说 明
必 须 已 经 使 用 PDF_suspend_page( ) 暂 停 页 面 。 页 面 将 再 次 打 开 ; 这 样 , 便 能 够 添 加 更 多 内
容 。 关 闭 之 前 , 必 须 先 恢 复 所 有 已 暂 停 的 页 面 ; 即 使 未 添 加 更 多 内 容 , 也 是 如 此 。
范 围 文 档 ; 此 参 数 是 页 面 范 围 的 开 头 , 必 须 与 对 应 的 PDF_suspend_page( ) 调 用 成 对 使 用 。
表 8.11 PDF_resume_page( ) 的 选 项
选 项 类 型 描 述
group 字 符 串 ( 如 果 文 档 使 用 页 面 组 , 则 要 求 此 选 项 ; 否 则 , 不 允 许 使 用 此 选 项 。) 恢 复 的
页 面 所 属 页 面 组 的 名 称 。 必 须 已 经 用 PDF_begin_document( ) 中 的 groups 选 项
定 义 了 组 名 。
pagenumber 整 型 如 果 提 供 了 此 选 项 , 将 恢 复 group 选 项 中 选 择 的 页 面 组 内 、 具 有 指 定 页 码 的 页
面 ( 如 果 文 档 不 使 用 页 面 组 , 则 在 文 档 中 恢 复 )。 如 果 缺 少 此 选 项 , 将 恢 复 该
组 中 的 最 后 一 页 。
void PDF_open_mem(PDF *p, size_t (*writeproc) (PDF *p, void *data, size_t size))
不 常 用 , 使 用 PDF_begin_document_callback( )。
int PDF_open_file(PDF *p, const char *filename)
void PDF_close(PDF *p)
不 常 用 , 使 用 PDF_begin_document( ) 和 PDF_end_document( )。
180 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

void PDF_begin_page(PDF *p, double width, double height)
void PDF_end_page(PDF *p)
不 常 用 , 使 用 PDF_begin_page_ext( ) 和 PDF_end_page_ext( )。
8.2.3 参 数 处 理
PDFlib 可 维 护 众 多 内 部 参 数 , 用 来 控 制 PDFlib 的 操 作 和 PDF 输 出 的 外 观 。 有 四 个 函 数 可 用
来 设 置 和 返 回 数 字 及 字 符 串 参 数 。 所 有 参 数 ( 包 括 关 键 字 和 值 ) 都 区 分 大 小 写 。 本 章 以 下
各 个 小 节 将 分 别 介 绍 提 供 的 参 数 。
C++ Java
Perl PHP
C
double get_value(String key, double modifier)
float PDF_get_value(resource p, string key, float modifier)
double PDF_get_value(PDF *p, const char *key, double modifier)
获 取 某 些 数 字 型 PDFlib 参 数 的 值 。
key 要 查 询 的 参 数 名 。
modifier 应 用 到 参 数 的 可 选 修 饰 符 。 各 参 数 表 中 将 说 明 是 否 要 求 修 饰 符 , 以 及 与 之 对 应 的
内 容 。 如 果 不 使 用 , 修 饰 符 必 须 为 0。
返 回 值 参 数 的 数 值 。
范 围 取 决 于 key。
另 请 参 见 PDF_get_pdi_value( )
C++ Java
Perl PHP
C
void set_value(String key, double value)
PDF_set_value(resource p, string key, float value)
void PDF_set_value(PDF *p, const char *key, double value)
设 置 某 些 数 字 型 PDFlib 参 数 的 值 。
key 要 设 置 的 参 数 名 。
value 要 设 置 的 新 参 数 值 。
范 围
取 决 于 key。
C++ Java
Perl PHP
C
String get_parameter(String key, double modifier)
string PDF_get_parameter(resource p, string key, float modifier)
const char * PDF_get_parameter(PDF *p, const char *key, double modifier)
获 取 某 些 字 符 串 型 PDFlib 参 数 的 内 容 。
key 要 查 询 的 参 数 名 。
modifier 应 用 到 参 数 的 可 选 修 饰 符 。 各 参 数 表 中 将 说 明 是 否 要 求 修 饰 符 , 以 及 与 之 对 应 的
内 容 。 如 果 不 使 用 , 修 饰 符 必 须 为 0。
返 回 值
作 为 超 文 本 字 符 串 的 参 数 字 符 串 值 。 可 以 在 所 处 文 档 范 围 结 束 之 前 使 用 返 回 的 字 符 串 。 如 果
没 有 信 息 , 将 返 回 空 字 符 串 。
8.2 常 规 函 数 181

范 围
取 决 于 key。
绑 定 C 和 C++:C 和 C++ 客 户 端 不 能 释 放 返 回 的 字 符 串 。 PDFlib 将 在 内 部 管 理 所 有 字 符 串 资 源 。
另 请 参 见 PDF_get_pdi_parameter( )
C++ Java
Perl PHP
C
void set_parameter(String key, String value)
PDF_set_parameter(resource p, string key, string value)
void PDF_set_parameter(PDF *p, const char *key, const char *value)
设 置 某 些 字 符 串 型 PDFlib 参 数 。
key 要 设 置 的 参 数 名 。
value ( 名 称 字 符 串 ) 要 设 置 的 新 参 数 值 。
范 围
取 决 于 key。
8.2.4 PDFlib 虚 拟 文 件 系 统 (PVF) 函 数
C++
Java
Perl PHP
C
void create_pvf(string filename, const void *data, size_t size, string optlist)
void create_pvf(String filename, byte[] data, String optlist)
PDF_create_pvf(resource p, string filename, string data, string optlist)
void PDF_create_pvf(PDF *p,
const char *filename, int len, const void *data, size_t size, const char *optlist)
用 内 存 中 提 供 的 数 据 创 建 命 名 的 只 读 虚 拟 文 件 。
filename ( 名 称 字 符 串 ) 虚 拟 文 件 的 文 件 名 。 这 是 个 任 意 字 符 串 , 稍 后 可 用 来 引 用 其 他
PDFlib 调 用 中 的 虚 拟 文 件 。
len ( 仅 用 于 C 语 言 绑 定 。) UTF-16 字 符 串 的 filename 长 度 ( 以 字 节 为 单 位 )。 如 果 len =
0, 则 必 须 提 供 以 null 终 结 的 字 符 串 。
data 对 虚 拟 文 件 的 数 据 的 引 用 。 在 C 和 C++ 语 言 中 , 这 是 个 指 向 内 存 位 置 的 指 针 。 在 Java
中 , 这 是 个 字 节 数 组 。 在 Perl 和 PHP 中 , 这 是 个 字 符 串 。
size ( 仅 用 于 C 和 C++) 包 含 数 据 的 内 存 块 的 长 度 , 以 字 节 为 单 位 。
optlist 根 据 表 8.12 提 供 的 选 项 列 表 。
详 细 说 明 可 以 为 任 何 使 用 输 入 文 件 的 API 函 数 提 供 虚 拟 文 件 名 ( 虚 拟 文 件 不 能 用 于 生 成 的 PDF 输 出 ,
可 在 PDF_begin_document( ) 中 使 用 空 文 件 名 , 以 实 现 这 一 目 的 )。 其 中 一 些 函 数 可 能 会 在
虚 拟 文 件 上 设 置 锁 定 , 直 至 数 据 不 再 需 要 为 止 。 虚 拟 文 件 将 一 直 保 存 在 内 存 中 , 直 至 使 用
PDF_delete_pvf( ) 显 式 删 除 或 在 PDF_delete( ) 中 自 动 删 除 为 止 。
每 个 PDFlib 对 象 都 将 维 护 自 己 的 PVF 文 件 组 。 虚 拟 文 件 不 能 在 不 同 PDFlib 对 象 之 间 共
享 , 但 可 以 通 过 虚 拟 文 件 , 使 用 相 同 的 PDFlib 对 象 创 建 多 个 文 档 。 处 理 不 同 PDFlib 对 象 的
多 个 线 程 无 需 同 步 PVF 的 使 用 。 如 果 filename 引 用 现 有 虚 拟 文 件 , 将 引 发 异 常 。 此 函 数 不
检 查 一 般 磁 盘 文 件 是 否 正 在 使 用 filename。
除 非 已 经 提 供 了 copy 选 项 , 否 则 在 相 应 地 成 功 调 用 PDF_delete_pvf( ) 之 前 , 调 用 方 不 能
修 改 或 释 放 ( 删 除 ) 提 供 的 数 据 。 如 不 遵 守 此 规 则 , 很 可 能 会 导 致 崩 溃 。
范 围
任 意
182 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.12 PDF_create_pvf( ) 的 选 项
选 项 类 型 描 述
copy 布 尔 型 PDFlib 会 立 即 创 建 所 提 供 数 据 的 内 部 副 本 。 在 这 种 情 况 下 , 调 用 方 可 以 在 此 调
用 后 立 即 删 除 提 供 的 数 据 。 在 COM、 .NET 和 Java 绑 定 中 , copy 选 项 将 自 动 设
为 true ( 其 他 绑 定 的 默 认 设 置 :false)。 在 其 他 语 言 绑 定 中 , 除 非 提 供 copy 选
项 , 否 则 不 会 复 制 数 据 。
C++ Java
Perl PHP
C
int delete_pvf(String filename)
int PDF_delete_pvf(resource p, string filename)
int PDF_delete_pvf(PDF *p, const char *filename, int len)
删 除 命 名 的 虚 拟 文 件 , 并 释 放 它 的 数 据 结 构 ( 但 不 释 放 内 容 )。
filename ( 名 称 字 符 串 ) 提 供 给 PDF_create_pvf( ) 的 虚 拟 文 件 文 件 名 。
len ( 仅 用 于 C 语 言 绑 定 。)UTF-16 字 符 串 的 filename 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0,
则 必 须 提 供 以 null 终 结 的 字 符 串 。
返 回 值 -1 ( 在 PHP 中 : 返 回 0) 其 条 件 是 , 对 应 的 虚 拟 文 件 存 在 , 但 已 被 锁 定 ; 否 则 , 为 1。
详 细 说 明
范 围
如 果 文 件 没 有 锁 定 , PDFlib 将 立 即 删 除 与 filename 关 联 的 数 据 结 构 。 如 果 filename 未 引 用
有 效 的 虚 拟 文 件 , 则 此 函 数 不 执 行 任 何 操 作 , 也 不 发 出 任 何 提 示 。 成 功 调 用 此 函 数 后 , 可 以
重 复 使 用 filename。 所 有 虚 拟 文 件 都 将 在 PDF_delete( ) 自 动 中 删 除 。
具 体 语 义 取 决 于 是 否 为 对 应 的 PDF_create_pvf( ) 调 用 提 供 了 copy 选 项 : 如 果 提 供 了 copy
选 项 , 将 同 时 释 放 文 件 的 管 理 数 据 结 构 和 实 际 的 文 件 内 容 ; 否 则 , 由 于 假 定 会 由 客 户 端 完 成
此 动 作 , 所 以 不 会 释 放 内 容 。
任 意
8.2.5 异 常 处 理
表 8.13 列 出 了 本 节 的 相 关 参 数 及 相 应 的 值 。
表 8.13 用 于 异 常 处 理 的 参 数 和 值
函 数 关 键 字 说 明
set_parameter warning 启 用 或 禁 用 警 告 ( 非 致 命 异 常 )。 可 能 的 值 包 括 true 和 false。
范 围 : 任 意 。 默 认 值 :true
C++ Java int get_errnum( )
Perl PHP int PDF_get_errnum(resource p)
C int PDF_get_errnum(PDF *p)
获 取 上 次 引 发 的 异 常 的 编 号 或 者 函 数 调 用 失 败 的 原 因 。
返 回 值 异 常 的 编 号 , 或 者 最 近 调 用 失 败 并 返 回 错 误 代 码 的 原 因 代 码 。
范 围
PDFlib 异 常 引 发 和 PDFlib 对 象 消 亡 之 间 。 或 者 , 也 可 以 在 函 数 返 回 -1 ( 在 PHP 中 : 返 回
0) 错 误 代 码 之 后 调 用 此 函 数 , 但 必 须 在 调 用 任 何 其 他 函 数 之 前 调 用 ; 本 节 列 出 的 函 数 除
外 。
绑 定 在 C++、 Java 和 PHP 5 中 , 还 可 以 在 PDFlibException 对 象 中 将 此 函 数 用 作 get_errnum( )。
8.2 常 规 函 数 183

C++ Java String get_errmsg( )
Perl PHP string PDF_get_errmsg(resource p)
C const char *PDF_get_errmsg(PDF *p)
获 取 上 次 引 发 的 异 常 的 文 本 或 者 函 数 调 用 失 败 的 原 因 。
返 回 值 包 含 上 次 引 发 的 异 常 描 述 或 者 最 近 一 次 函 数 调 用 失 败 并 返 回 错 误 代 码 的 原 因 的 文 本 。
范 围
PDFlib 异 常 引 发 和 PDFlib 对 象 消 亡 之 间 。 或 者 , 也 可 以 在 函 数 返 回 -1 ( 在 PHP 中 : 返 回
0) 错 误 代 码 之 后 调 用 此 函 数 , 但 必 须 在 调 用 任 何 其 他 函 数 之 前 调 用 ; 本 节 列 出 的 函 数 除
外 。
绑 定 在 C++、 Java 和 PHP 5 中 , 还 可 以 在 PDFlibException 对 象 中 将 此 函 数 用 作 get_errmsg( )。
C++ Java String get_apiname( )
Perl PHP string PDF_get_apiname(resource p)
C const char *PDF_get_apiname(PDF *p)
获 取 引 发 上 次 异 常 或 失 败 的 API 函 数 名 。
返 回 值 引 发 异 常 的 函 数 名 , 或 最 近 一 次 函 数 调 用 失 败 并 返 回 错 误 代 码 的 函 数 名 。
范 围
绑 定
PDFlib 异 常 引 发 和 PDFlib 对 象 消 亡 之 间 。 或 者 , 也 可 以 在 函 数 返 回 -1 ( 在 PHP 中 : 返 回
0) 错 误 代 码 之 后 调 用 此 函 数 , 但 必 须 在 调 用 任 何 其 他 函 数 之 前 调 用 ; 本 节 列 出 的 函 数 除
外 。
在 C++、 Java、 和 PHP 5 , 中 , 还 可 以 在 PDFlibException 对 象 中 将 此 函 数 用 作 get_
apiname( )。
C++ Java void *get_opaque( )
C void *PDF_get_opaque(PDF *p)
获 取 存 于 PDFlib 不 透 明 应 用 程 序 指 针 。
详 细 说 明
范 围
绑 定
这 个 函 数 将 返 回 存 于 PDFlib 不 透 明 应 用 程 序 指 针 。 这 指 针 将 被 用 于 PDF_new2( ) 函 数 的 调
用 中 。PDFlib 从 不 触 动 这 个 指 针 , 而 只 是 原 封 不 动 的 传 给 客 户 端 。 这 可 用 于 为 多 线 程 应 用
程 序 在 PDFlib 对 象 中 储 存 私 有 的 特 定 线 程 数 据 。 这 对 于 线 程 相 关 的 线 程 处 理 非 常 有 用 。
任 意
仅 用 于 C 和 C++
8.2.6 实 用 程 序 函 数
如 果 环 境 中 没 有 提 供 相 关 功 能 , 这 些 函 数 会 很 有 用 。
184 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
string utf16_to_utf8(string utf16string)
string PDF_utf16_to_utf8(resource p, string utf16string)
const char *PDF_utf16_to_utf8(PDF *p, const char *utf16string, int len, int *size)
将 字 符 串 从 UTF-16 格 式 转 换 为 UTF-8。
utf16string 要 转 换 的 字 符 串 。 将 计 算 字 符 串 内 的 字 节 顺 序 标 记 (BOM)。 如 果 BOM 缺 失 ,
则 假 定 为 平 台 的 本 身 字 节 顺 序 。
len ( 仅 用 于 C 语 言 绑 定 。) utf16string 的 长 度 ( 以 字 节 为 单 位 )。
size ( 仅 用 于 C 语 言 绑 定 。) 指 向 内 存 位 置 的 C 语 言 指 针 , 其 中 存 储 返 回 字 符 串 的 长 度 ( 以
字 节 为 单 位 )。 如 果 指 针 为 NULL, 将 忽 略 指 针 。
返 回 值
范 围
转 换 后 的 UTF-8 字 符 串 。 生 成 的 UTF-8 字 符 串 将 以 BOM (\xEF\xBB\xBF) 开 头 。 在 EBCDIC
平 台 上 , 包 括 BOM 的 转 换 结 果 将 最 终 转 换 为 EBCDIC。 在 调 用 除 PDF_utf16_to_utf8( ) 和
PDF_utf8_to_utf16( ) 之 外 的 其 他 PDFlib 函 数 或 引 发 异 常 之 前 , 返 回 的 字 符 串 将 一 直 有 效 。
如 果 此 后 仍 需 要 该 字 符 串 , 则 客 户 端 必 须 复 制 该 字 符 串 。 转 换 的 字 符 串 使 用 的 内 存 将 由
PDFlib 管 理 。
任 意
绑 定 此 函 数 不 能 用 于 支 持 Unicode 的 语 言 绑 定 。
C++ Java
Perl PHP
C
string utf8_to_utf16(string utf8string, string ordering)
string PDF_utf8_to_utf16(resource p, string utf8string, string ordering)
const char *PDF_utf8_to_utf16(PDF *p, const char *utf8string, const char *ordering, int *size)
将 字 符 串 从 UTF-8 格 式 转 换 为 UTF-16。
utf8string 要 转 换 的 字 符 串 , 其 中 必 须 包 含 有 效 的 UTF-8 序 列 ( 在 EBCDIC 平 台 上 , 必 须
用 EBCDIC 编 码 )。 如 果 存 在 字 节 顺 序 标 记 (BOM), 该 标 记 将 被 删 除 。
ordering 指 定 结 果 字 符 串 的 字 节 顺 序 。
> utf16 或 空 字 符 串 : 转 换 后 的 字 符 串 将 不 包 含 BOM, 并 将 按 平 台 的 本 身 字 节 顺 序 存 储 。
> utf16le: 转 换 后 的 字 符 串 将 用 little endian 格 式 进 行 格 式 化 , 并 将 添 加 LE BOM
(\xFF\xFE) 前 缀 。
> utf16be: 转 换 后 的 字 符 串 将 用 big endian 格 式 进 行 格 式 化 , 并 将 添 加 BE BOM
(\xFE\xFF) 前 缀 。
size ( 仅 用 于 C 语 言 绑 定 。) 指 向 内 存 位 置 的 C 语 言 指 针 , 其 中 存 储 返 回 字 符 串 的 长 度 ( 以
字 节 为 单 位 )。
返 回 值
范 围
转 换 后 的 UTF-16 字 符 串 。 在 调 用 除 PDF_utf16_to_utf8( ) 和 PDF_utf8_to_utf16( ) 之 外 的 其 他
PDFlib 函 数 或 引 发 异 常 之 前 , 返 回 的 字 符 串 将 一 直 有 效 。 如 果 此 后 仍 需 要 该 字 符 串 , 则 客 户
端 必 须 复 制 该 字 符 串 。 转 换 的 字 符 串 使 用 的 内 存 将 由 PDFlib 管 理 。
任 意
绑 定 此 函 数 不 能 用 于 支 持 Unicode 的 语 言 绑 定 。
8.2 常 规 函 数 185

8.3 文 本 函 数
8.3.1 字 体 处 理
表 8.14 列 出 了 本 节 的 相 关 参 数 及 相 应 的 值 。
表 8.14 字 体 函 数 的 参 数 和 值 ( 参 见 第 181 页 上 的 第 8.2.3 节 “ 参 数 处 理 ”)
函 数 关 键 字 说 明
set_parameter FontAFM
FontPFM
FontOutline
Encoding
HostFont
ICCProfile
SearchPath
标 准 -
OutputIntent
如 UPR 文 件 中 各 个 类 别 所 示 的 对 应 资 源 文 件 行 ( 参 见 第 49 页 上 的
第 3.1.5 节 “ 资 源 配 置 和 文 件 搜 索 ”)。 可 由 多 个 调 用 向 内 部 列 表 添
加 新 条 目 。( 另 请 参 见 表 8.3 中 的 resourcefile)。 范 围 : 任 意
get_value font 返 回 已 经 用 PDF_setfont( ) 设 置 的 当 前 字 体 的 标 识 符 ; 如 果 没 有 设 置
字 体 , 则 返 回 -1 ( 在 PHP 中 : 返 回 0)。 范 围 : 页 面 、 图 案 、 模 板 、
字 形
get_value fontmaxcode 返 回 标 识 符 中 的 字 体 的 有 效 字 形 ID 值 。 范 围 : 任 意
get_parameter fontname 当 前 字 体 的 名 称 , 必 须 事 先 用 PDF_setfont( ) 设 置 。 范 围 : 页 面 、
图 案 、 模 板 、 字 形
get_parameter fontencoding 当 前 字 体 使 用 的 编 码 名 称 或 CMap。 字 体 必 须 事 先 用 PDF_setfont( )
设 置 。 范 围 : 页 面 、 图 案 、 模 板 、 字 形
get_value fontsize 当 前 字 体 的 字 体 大 小 , 必 须 事 先 用 PDF_setfont( ) 设 置 。 范 围 : 页 面 、
图 案 、 模 板 、 字 形
get_parameter fontstyle 当 前 字 体 的 样 式 , 类 似 fontstyle 选 项 (normal、 bold、 italic 或
bolditalic)。 范 围 : 页 面 、 图 案 、 模 板 、 字 形
get_value
capheight
ascender
descender
返 回 修 饰 符 标 示 的 字 体 的 字 体 规 格 信 息 。 有 关 更 多 详 细 信 息 , 参 见
第 90 页 上 的 第 4.6 节 “ 文 本 规 格 和 文 本 变 体 ”。 这 些 值 以 字 体 大 小 的
分 数 表 示 , 因 此 必 须 乘 以 所 需 的 字 体 大 小 。 范 围 : 任 意
set_parameter fontwarning 如 果 为 false, 且 不 能 载 入 字 体 / 编 码 组 合 , 将 PDF_load_font( ) 将 返
回 -1 ( 在 PHP 中 : 返 回 0)。 默 认 值 :true。 范 围 : 任 意
get_value monospace 如 果 已 经 设 置 了 字 体 , 将 返 回 当 前 字 体 的 monospace 选 项 值 ; 否 则 ,
返 回 0。 范 围 : 页 面 、 图 案 、 模 板 、 字 形
set_value subsetlimit 如 果 文 档 使 用 字 体 子 集 大 于 字 体 中 的 字 符 百 分 比 , 将 停 用 字 体 子 集 。
默 认 值 :100 percent。 范 围 : 任 意
set_value subsetminsize 子 集 化 将 只 应 用 于 大 于 此 KB 大 小 的 字 体 ( 参 见 第 75 页 上 的 第 4.3 节
“ 字 体 嵌 入 和 子 集 化 ”)。 默 认 值 :100 KB。 范 围 : 任 意
set_parameter autosubsetting 控 制 TrueType 和 OpenType 字 体 的 子 集 化 自 动 启 动 。 默 认 值 :true。
范 围 : 任 意
set_parameter autocidfont 控 制 是 否 自 动 将 使 用 除 macroman 和 winansi 之 外 的 编 码 的 TrueType
字 体 转 换 为 CID 字 体 ( 参 见 第 75 页 上 的 第 4.3 节 “ 字 体 嵌 入 和 子 集
化 ”)。 默 认 值 :true。 范 围 : 任 意
set_parameter unicodemap 控 制 ToUnicode CMap 的 生 成 ( 参 见 第 83 页 上 的 第 4.5.1 节 “ 页 面 内
容 和 超 文 本 的 Unicode”)。 标 签 PDF 模 式 将 忽 略 此 参 数 。 默 认 值 :
true。 范 围 : 任 意
186 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
int load_font(String fontname, String encoding, String optlist)
int PDF_load_font(resource p, string fontname, string encoding, string optlist)
int PDF_load_font(PDF *p,
const char *fontname, int len, const char *encoding, const char *optlist)
搜 索 字 体 , 并 准 备 稍 后 使 用 。
fontname ( 名 称 字 符 串 ) 字 体 的 真 实 名 称 或 别 名 。 它 将 用 来 根 据 第 75 页 上 的 第 4.3.1 节
“PDFlib 搜 索 字 体 的 方 法 ” 中 的 描 述 查 找 字 体 数 据 。 区 分 大 小 写 。
len ( 仅 用 于 C 语 言 绑 定 )UTF-16 字 符 串 的 fontname 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0,
则 必 须 提 供 以 null 终 结 的 字 符 串 。
encoding 字 体 使 用 的 编 码 ( 区 分 大 小 写 ), 必 须 为 下 列 编 码 之 一 ( 有 关 更 多 信 息 , 参 见
第 78 页 上 的 第 4.4 节 “ 编 码 详 细 信 息 ”):
> 一 种 预 定 义 8 位 编 码 , winansi、 macroman、 macroman_apple、 ebcdic、 ebcdic_37、
pdfdoc、 iso8859-X、 cpXXXX 或 U+XXXX ;
> 用 于 自 动 选 择 编 码 的 host 或 auto ;
> 从 文 件 载 入 的 用 户 定 义 编 码 或 通 过 PDF_encoding_set_char( ) 定 义 的 编 码 的 名 称 ;
> 用 于 基 于 Unicode 的 寻 址 的 unicode ;
> 用 于 CJK 代 码 页 的 cpXXXX ( 参 见 表 4.8);
> 用 于 字 形 ID 寻 址 的 glyphid ;
> 用 于 选 择 字 体 内 部 编 码 的 builtin ;
> 标 准 CMap 的 名 称 ( 参 见 第 93 页 上 的 第 4.7 节 “ 中 文 、 日 文 和 韩 文 文 本 ”);
> 操 作 系 统 已 知 的 编 码 名 称 ( 并 非 所 有 平 台 上 都 可 以 使 用 )。
编 码 必 须 兼 容 选 择 的 字 体 。 表 8.15 列 出 了 所 有 允 许 的 编 码 和 字 体 类 型 组 合 。
optlist 根 据 表 8.16 提 供 的 选 项 列 表 。
返 回 值
字 体 句 柄 , 供 稍 后 与 PDF_setfont( ) 一 起 使 用 。 fontwarning 参 数 或 选 项 设 为 false 时 , 此 函
数 的 行 为 会 发 生 改 变 。 在 这 种 情 况 下 , 如 果 不 能 载 入 请 求 的 字 体 / 编 码 组 合 , 此 函 数 将 返 回
错 误 代 码 -1( 在 PHP 中 : 返 回 0), 而 不 引 发 异 常 。 但 是 , 提 供 错 误 参 数 时 , 仍 将 引 发 异 常 。
除 用 作 PDF_setfont( ) 及 相 关 函 数 的 自 变 量 外 , 返 回 的 数 值 字 体 句 柄 对 用 户 没 有 任 何 意
义 。 尤 其 是 , 在 不 同 文 档 中 请 求 相 同 的 字 体 / 编 码 组 合 可 能 会 导 致 不 同 的 字 体 句 柄 。
除 非 提 供 了 不 同 的 encoding 参 数 或 fontstyle 选 项 , 否 则 再 次 使 用 相 同 字 体 名 称 调 用 此 函
数 时 , 将 返 回 与 第 一 次 调 用 相 同 的 字 体 句 柄 。
冲 突 的 选 项 : 通 过 PDF_load_font( ) 载 入 或 者 通 过 PDF_fill_textblock( ) 请 求 字 体 , 而 不 使
用 embedding、 subsetting 或 subsetting 时 , 如 果 稍 后 再 次 载 入 相 同 字 体 , 将 忽 略 这 些
选 项 。
表 8.15 编 码 与 字 体 类 型 的 关 系
8 位
Unicode、 Unicode 其 他
字 体 格 式
编 码 内 建 字 形 cp936 1 等 。 CMap CMap
PostScript Type 1 是
2
是 – 3
是 – –
Type 3 是 – – – – –
带 有 TrueType 轮 廓 的
TrueType 和 OpenType 4
具 有 PostScript 轮 廓 的
Western OpenType (SID) 4
是
仅 限
Symbol
字 体
5
是
5
是 是 是
是
5 – –
5
是
– –
8.3 文 本 函 数 187

表 8.15 编 码 与 字 体 类 型 的 关 系
字 体 格 式
具 有 PostScript 轮 廓 的 CJK
OpenType (CID)
8 位
编 码 内 建 字 形
Unicode、
cp936 1 等 。
Unicode
CMap
– – 是 是 是 是
6, 7
标 准 CJK 字 体 ( 不 能 嵌 入 ) – – – – 7
是 是
其 他
CMap
1. 目 前 只 支 持 Windows 系 统 。
2. 不 支 持 PDF 核 心 字 体 , Symbol 和 ZapfDingbats 除 外 。
3. 最 多 可 寻 址 256 个 字 形 。
4. 除 非 使 用 内 建 编 码 或 8 位 编 码 , 否 则 将 作 为 CID 字 体 嵌 入 ; 8 位 编 码 只 包 含 Adobe 标 准 拉 丁 字 符 集 提 供 的 字 符 。 对 于 8 位 编
码 , 可 将 autocidfont 选 项 设 为 false, 来 禁 用 CID 字 体 生 成 。
5. 字 体 必 须 允 许 嵌 入 。
6. 不 支 持 子 集 化 。
7. 不 支 持 字 体 规 格 , 即 : 不 支 持 PDF_stringwidth( )、 kerning、 textflow、 overline/underline/strikeout 和 textx/texty。
详 细 说 明
范 围
此 函 数 准 备 字 体 , 以 供 稍 后 用 于 PDF_setfont( )。 将 从 内 存 或 者 ( 虚 拟 或 基 于 磁 盘 ) 的 规 格
文 件 载 入 字 体 规 格 。 如 果 由 于 配 置 问 题 而 不 能 使 用 请 求 的 字 体 / 编 码 组 合 ( 例 如 , 无 法 找 到
字 体 、 规 格 和 编 码 文 件 , 或 检 测 到 匹 配 错 误 ), 除 非 将 fontwarning 参 数 设 为 false, 否 则 将
引 发 异 常 。 如 能 使 用 , 此 参 数 返 回 的 值 可 以 用 作 其 他 字 体 相 关 函 数 的 font 自 变 量 。
文 档 、 页 面 、 图 案 、 模 板 、 字 形
参 数 参 见 表 8.14。
PDF/X
embedding 选 项 必 须 为 true。
表 8.16 PDF_load_font( ) 的 选 项
选 项 类 型 描 述
autosubsetting 布 尔 型 动 态 地 决 定 是 否 对 字 体 进 行 子 集 化 处 理 , 具 体 取 决 于 subsetlimit 和 subsetminsize
参 数 以 及 实 际 使 用 的 字 形 。 如 果 已 经 提 供 了 subsetting 选 项 , 将 忽 略 此 选 项 。 默
认 值 : 全 局 autosubsetting 参 数 的 值 。
autocidfont 布 尔 型 如 果 为 true, 具 有 除 winansi、macroman、builtin 之 外 的 8 位 编 码 的 TrueType
字 体 以 及 没 有 字 形 名 称 的 OpenType 字 体 将 自 动 存 储 为 CID 字 体 。 这 样 可 防 止
某 些 winansi 编 码 之 外 的 字 形 无 法 访 问 的 问 题 。 默 认 值 : 全 局 autocidfont 参 数
的 值 。
embedding 布 尔 型 控 制 是 否 嵌 入 字 体 。 此 选 项 对 Type 3 字 体 没 有 任 何 影 响 。 如 果 要 嵌 入 字 体 , 除
规 格 信 息 外 , 还 必 须 提 供 字 体 轮 廓 文 件 (TrueType 和 OpenType 字 体 则 无 此 要
求 ), 并 且 ,PDF 输 出 内 必 须 包 括 实 际 的 字 体 轮 廓 定 义 。 如 果 不 嵌 入 字 体 ,PDF
输 出 中 只 包 括 字 体 的 常 规 信 息 。 默 认 值 :false
fontstyle 关 键 字 控 制 人 工 字 形 的 生 成 。 这 些 伪 字 形 仅 用 于 没 有 嵌 入 的 TrueType ( 非 TTC) 和
OpenType 字 体 ( 参 见 第 92 页 上 的 第 4.6.3 节 “ 文 本 变 体 ”)。 可 能 的 关 键 字 包
括 normal、 bold、 italic 和 bolditalic。 默 认 值 :normal。
fontwarning 布 尔 型 如 果 为 true, 无 法 载 入 请 求 的 字 体 / 编 码 组 合 时 , 将 引 发 异 常 ; 如 果 为 false,
将 返 回 错 误 代 码 。( 编 码 搜 索 受 fontwarning 参 数 的 控 制 , 而 不 受 fontwarning
选 项 的 控 制 。) 默 认 值 : 全 局 fontwarning 参 数 的 值 。
kerning 布 尔 型 控 制 是 否 从 字 体 中 读 取 字 距 调 整 值 ( 参 见 第 90 页 上 的 第 4.6 节 “ 文 本 规 格 和
文 本 变 体 ”)。 默 认 值 :false
monospace
subsetlimit
整 型
1...2048
浮 点 型 或
百 分 比
强 制 字 体 中 的 所 有 字 形 使 用 指 定 的 宽 度 ( 在 字 体 坐 标 系 统 中 :1000 单 位 等 于
字 体 大 小 )。 对 于 Type 3 字 体 , 将 修 改 所 有 不 同 于 0 的 字 形 宽 度 。 只 建 议 为 标
准 CJK 字 体 使 用 此 选 项 , 不 支 持 核 心 字 体 ; 如 果 是 嵌 入 字 体 , 则 忽 略 此 选 项 。
默 认 值 :absent ( 将 使 用 字 体 提 供 的 规 格 )
如 果 文 档 中 使 用 的 字 形 与 字 体 中 字 形 总 数 的 百 分 比 超 出 提 供 的 百 分 比 , 将 停 用
字 体 子 集 化 。 默 认 值 : 全 局 subsetlimit 参 数 的 值 。
188 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.16 PDF_load_font( ) 的 选 项 ( 续 )
选 项 类 型 描 述
subsetminsize 浮 点 型 如 果 原 始 字 体 文 件 的 大 小 小 于 提 供 的 KB 值 , 将 停 用 字 体 子 集 化 。 默 认 值 : 全
局 subsetminsize 参 数 的 值 。
subsetting 布 尔 型 控 制 是 否 对 字 体 进 行 子 集 化 处 理 , 具 体 取 决 于 文 档 中 使 用 的 字 形 总 数 以 及
subsetlimit 和 subsetminsize 选 项 ( 参 见 第 75 页 上 的 第 4.3 节 “ 字 体 嵌 入 和 子
集 化 ”)。 默 认 值 :false
unicodemap 布 尔 型 控 制 ToUnicode CMap 的 生 成 ( 参 见 第 83 页 上 的 第 4.5.1 节 “ 页 面 内 容 和 超 文
本 的 Unicode”)。 标 签 PDF 模 式 将 忽 略 此 选 项 。 默 认 值 :true
C++ Java
Perl PHP
C
void PDF_setfont(int font, double fontsize)
PDF_setfont(resource p, int font, float fontsize)
void PDF_setfont(PDF *p, int font, double fontsize)
以 指 定 的 大 小 设 置 当 前 字 体 。
font PDF_load_font( ) 返 回 的 字 体 句 柄 。
fontsize 字 体 的 大 小 , 以 当 前 用 户 坐 标 系 统 的 单 位 表 示 。 字 体 大 小 不 能 为 0 ; 如 果 为 负
值 , 将 产 生 与 当 前 转 换 矩 阵 相 对 的 镜 像 文 本 。
详 细 说 明
范 围
参 数
在 绘 制 任 何 文 本 之 前 , 必 须 在 每 个 页 面 上 设 置 字 体 。 不 能 在 多 个 页 面 间 保 留 字 体 设 置 。 在 每
一 页 上 , 更 改 当 前 字 体 的 次 数 不 受 任 何 限 制 。
页 面 、 图 案 、 模 板 、 字 形
参 见 表 8.14。 此 函 数 自 动 将 leading 参 数 设 为 fontsize。
8.3.2 用 户 定 义 (Type 3) 字 体
C++ Java
Perl PHP
C
void begin_font(String fontname,
double a, double b, double c, double d, double e, double f, String optlist)
PDF_begin_font(resource p, string fontname,
float a, float b, float c, float d, float e, float f, string optlist)
void PDF_begin_font(PDF *p, char *fontname, int reserved,
double a, double b, double c, double d, double e, double f, const char *optlist)
开 始 Type 3 字 体 定 义 。
fontname ( 名 称 字 符 串 ) 用 来 注 册 字 体 的 名 称 , 稍 后 可 用 于 PDF_load_font( )。
reserved ( 仅 用 于 C 语 言 绑 定 ) 保 留 , 必 须 为 0。
a, b, c, d, e, f 字 体 矩 阵 的 元 素 。 此 矩 阵 定 义 将 在 其 中 绘 制 字 形 的 坐 标 系 统 。 这 六 个 值 在
PostScript 和 PDF 中 , 以 相 同 的 方 式 构 成 坐 标 系 统 ( 参 见 相 关 参 考 )。 为 了 避 免 转 换 退 化 ,
a*d 不 能 等 于 b*c。 1000 x 1000 坐 标 系 统 典 型 的 字 体 矩 阵 是 [0.001, 0, 0, 0.001, 0, 0]。
optlist 根 据 表 8.17 提 供 的 选 项 列 表 。
详 细 说 明
此 函 数 将 所 有 文 本 、 图 形 和 颜 色 状 态 参 数 重 设 为 他 们 的 默 认 值 。 字 体 可 以 包 含 任 意 数 量 的 字
形 , 但 只 能 通 过 编 码 访 问 256 个 字 形 。 可 以 在 当 前 文 档 范 围 结 束 之 前 使 用 定 义 的 字 体 。
范 围 文 档 、 页 面 ; 此 参 数 是 字 体 范 围 的 开 头 , 必 须 与 对 应 的 PDF_end_font( ) 调 用 成 对 使 用 。
8.3 文 本 函 数 189

表 8.17 PDF_begin_font( ) 的 选 项
选 项 类 型 描 述
colorized 布 尔 型 如 果 为 true, 字 体 可 以 显 式 指 定 具 体 字 符 的 颜 色 。 如 果 为 false, 将 使 用
( 使 用 字 体 时 , 而 非 定 义 字 体 时 的 ) 当 前 颜 色 绘 制 所 有 字 符 , 字 形 定 义
不 能 包 含 除 蒙 版 外 的 任 何 其 他 色 彩 运 算 符 或 图 像 。 默 认 值 :false
C++ Java void end_font( )
Perl PHP PDF_end_font(resource p)
C void PDF_end_font(PDF *p)
终 结 Type 3 字 体 定 义 。
范 围 字 体 ; 此 函 数 终 结 字 体 范 围 , 必 须 与 对 应 的 PDF_begin_font( ) 调 用 成 对 使 用 。
C++ Java
Perl PHP
C
void begin_glyph(String glyphname,
double wx, double llx, double lly, double urx, double ury)
PDF_begin_glyph(resource p, string glyphname,
float wx, float llx, float lly, float urx, float ury)
void PDF_begin_glyph(PDF *p,
char *glyphname, double wx, double llx, double lly, double urx, double ury)
开 始 Type 3 字 体 的 字 形 定 义 。
glyphname 字 形 的 名 称 。 此 名 称 必 须 用 于 将 与 该 字 体 一 起 使 用 的 任 何 编 码 。 字 体 内 的 字 形
名 称 必 须 是 唯 一 的 。
wx 字 形 坐 标 系 统 内 字 形 的 宽 度 , 具 体 由 字 体 的 矩 阵 指 定 。
llx, lly, urx, ury 如 果 字 体 的 colorized 选 项 为 false ( 默 认 值 ), 这 些 值 可 指 定 字 形 定 界 框
左 下 角 和 右 上 角 的 坐 标 。 为 避 免 出 现 PostScript 打 印 问 题 , 定 界 框 值 必 须 是 正 确 的 。 如 果 字
体 的 colorized 选 项 为 true, 所 有 四 个 值 都 必 须 为 0。
详 细 说 明
字 体 中 的 字 形 可 使 用 文 本 、 图 形 和 图 像 函 数 定 义 。 但 是 , 如 果 字 体 的 colorized 选 项 为 true,
或 者 已 使 用 mask 选 项 打 开 了 图 像 , 则 只 能 使 用 图 像 。 强 烈 建 议 使 用 内 嵌 图 像 功 能 定 义 Type 3
中 的 位 图 ( 参 见 第 115 页 上 的 第 5.1.1 节 “ 基 本 图 像 处 理 ”)。
因 为 colorized 选 项 为 true 时 , 字 形 定 义 将 继 承 所 处 页 面 的 整 个 图 形 状 态 , 所 以 字 形 定 义
应 显 式 设 置 图 像 状 态 与 字 形 定 义 相 关 的 各 个 方 面 ( 例 如 linewidth)。
范 围 页 面 , 字 体 ; 此 参 数 是 字 形 范 围 的 开 头 , 必 须 与 对 应 的 PDF_end_glyph( ) 调 用 成 对 使 用 。
C++ Java void end_glyph( )
Perl PHP PDF_end_glyph(resource p)
C void PDF_end_glyph(PDF *p)
终 结 Type 3 字 体 的 字 形 定 义 。
范 围 字 形 ; 此 函 数 终 结 字 形 范 围 , 必 须 与 对 应 的 PDF_begin_glyph( ) 调 用 成 对 使 用 。
190 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

8.3.3 编 码 定 义
C++ Java
Perl PHP
C
void encoding_set_char(String encoding, int slot, String glyphname, int uv)
PDF_encoding_set_char(resource p, string encoding, int slot, string glyphname, int uv)
void PDF_encoding_set_char(PDF *p,
const char *encoding, int slot, const char *glyphname, int uv)
向 自 定 义 编 码 添 加 字 形 名 称 和 / 或 Unicode 值 。
encoding 编 码 的 名 称 。 此 名 称 必 须 用 于 PDF_load_font( )。 编 码 名 称 必 须 不 同 于 任 何 内 置
编 码 以 及 所 有 以 前 使 用 过 的 编 码 。
slot 要 定 义 的 字 符 位 置 , 0 提 供 uv , 但 没 有 提 供 glyphname : 这 相 当 于 代 码 页 文 件 ;
> 提 供 glyphname 和 uv : 这 相 当 于 有 Unicode 值 的 编 码 文 件 ;
可 以 在 当 前 对 象 范 围 结 束 之 前 使 用 定 义 的 编 码 。
范 围
对 象 、 文 档 、 页 面 、 图 案 、 模 板 、 路 径 、 字 体 、 字 形
8.3.4 简 单 文 本 输 出
注 : 在 本 节 中 , 所 有 提 供 给 函 数 的 文 本 都 必 须 匹 配 用 PDF_load_font( ) 选 择 的 编 码 。 这 适 用 于 8 位
文 本 以 及 Unicode 或 其 他 通 过 CMap 选 择 的 编 码 。 由 于 Acrobat 中 的 限 制 , 文 本 字 符 串 的 长 度
不 能 超 过 32 KB。
表 8.18 列 出 了 本 节 的 相 关 参 数 及 相 应 的 值 。
表 8.18 文 本 函 数 的 参 数 和 值
函 数 关 键 字 说 明
set_parameter autospace 如 果 为 true, 且 当 前 字 体 兼 容 Unicode, PDFlib 将 在 每 个 用 show 操 作
生 成 的 文 本 输 出 后 添 加 一 个 空 格 字 符 (0x20)。 这 可 能 对 生 成 标 签 PDF 很
有 用 ( 参 见 第 158 页 上 的 第 7.5 节 “ 标 签 PDF”)。 请 注 意 , 在 show 操
作 后 添 加 空 格 会 改 变 当 前 文 本 位 置 。 默 认 值 :false)。 范 围 :
任 意
set_parameter charref 如 果 为 true, 将 启 用 数 字 和 字 符 实 体 引 用 的 替 换 ( 参 见 第 87 页 上 的
第 4.5.5 节 “ 字 符 引 用 ”)。 默 认 值 :false
set_value
get_value
charspacing
设 置 或 获 取 字 符 间 距 , 即 : 在 字 符 串 中 放 置 具 体 字 符 之 后 , 当 前 点 的 位
移 。 它 以 用 户 坐 标 系 统 的 单 位 指 定 , 并 将 在 每 页 的 开 头 和 结 尾 重 设 为 默
认 值 0。 要 扩 大 字 符 间 距 , 可 在 横 排 书 写 模 式 中 使 用 正 值 , 在 直 排 书 写
模 式 中 使 用 负 值 。 范 围 : 页 面 、 图 案 、 模 板 、 字 形 、 文 档 。
set_parameter glyphwarning 如 果 为 true, 由 于 字 体 不 包 含 相 应 的 字 形 描 述 而 无 法 显 示 字 形 时 , 将 引
发 异 常 。 如 果 为 false, 将 用 空 格 字 符 或 字 形 ID 0 替 换 缺 失 的 字 形 。 默
认 值 :false)。 范 围 : 任 意
8.3 文 本 函 数 191

表 8.18 文 本 函 数 的 参 数 和 值 ( 续 )
函 数 关 键 字 说 明
set_value
get_value
set_value
get_value
set_parameter
get_parameter
set_value
get_value
set_parameter
get_parameter
set_value
get_value
set_value
get_value
get_value
set_parameter
get_parameter
set_value
get_value
set_value
get_value
set_value
get_value
horizscaling
italicangle
kerning
leading
将 水 平 文 本 缩 放 比 例 设 定 为 给 定 的 百 分 比 , 或 获 取 相 关 设 置 。 文 本 缩 放
比 例 可 按 给 定 的 比 例 收 缩 或 扩 展 文 本 。 在 每 页 的 开 头 和 结 尾 , 此 参 数 将
设 为 默 认 值 100。 文 本 缩 放 比 例 始 终 与 水 平 坐 标 相 对 。 范 围 : 页 面 、 图
案 、 模 板 、 字 形 、 文 档 。
指 定 文 本 的 斜 体 ( 倾 斜 ) 角 度 的 度 数 , 范 围 在 -90° 和 90° 之 间 。 如 果
只 有 常 规 字 体 , 可 使 用 负 值 模 拟 斜 体 文 本 , 尤 其 是 CJK 字 体 ( 参 见 第
92 页 上 的 第 4.6.3 节 “ 文 本 变 体 ”)。 默 认 值 :0 ( 将 在 每 页 的 开 头 和 结
尾 重 设 此 参 数 )。 范 围 : 页 面 、 图 案 、 模 板 、 字 形 、 文 档
如 果 为 true, 将 为 已 用 kerning 选 项 打 开 的 字 体 启 用 字 距 微 调 ; 如 果 为
false, 则 停 用 字 距 微 调 。( 参 见 第 90 页 上 的 第 4.6 节 “ 文 本 规 格 和 文
本 变 体 ”)。 默 认 值 :true。 范 围 : 任 意
设 置 或 获 取 行 距 , 即 相 邻 文 本 行 的 基 线 之 间 的 距 离 。 leading 用 于 PDF_
continue_text( )。 使 用 PDF_setfont( ) 选 择 新 字 体 时 , 它 设 为 字 体 大 小 的
值 。 设 置 leading 等 于 字 体 大 小 将 导 致 密 集 行 距 (leading = 0 将 导 致 叠
印 行 )。 但 是 , 相 邻 行 的 字 母 上 缘 和 字 母 下 缘 通 常 不 会 重 叠 。 范 围 : 页
面 、 图 案 、 模 板 、 字 形 。
textformat 指 定 文 本 输 出 函 数 预 计 客 户 端 提 供 字 符 串 时 使 用 的 格 式 。 可 能 的 值 包 括
bytes、 utf8、 ebcdicutf8 ( 仅 用 于 iSeries 和 zSeries)、 utf16、 utf16le、
utf16be 和 auto ( 参 见 第 84 页 上 的 第 4.5.2 节 “ 内 容 字 符 串 、 超 文 本 字
符 串 和 名 称 字 符 串 ”)。 默 认 值 :auto。 范 围 : 任 意
textrendering 设 置 或 获 取 当 前 文 字 渲 染 模 式 。 在 每 页 的 开 头 , 它 设 为 默 认 值 0。
范 围 : 页 面 、 图 案 、 模 板 、 字 形 。
0 填 充 文 本
1 描 边 文 本 ( 轮 廓 )
2 填 充 和 描 边 文 本
3 不 可 见 文 本
4 填 充 文 本 并 将 其 添 加 到 剪 贴 路 径
5 描 边 文 本 并 将 其 添 加 到 剪 贴 路 径
6 填 充 并 描 边 文 本 并 将 其 添 加 到 剪 贴 路 径
7 将 文 本 添 加 到 剪 贴 路 径
textrise
textx
texty
underline
overline
strikeout
underlineposition
underlinewidth
wordspacing
设 置 或 获 取 文 本 抬 升 参 数 , 该 参 数 指 定 所 需 文 本 位 置 与 默 认 基 线 之 间 的
距 离 。 如 文 本 抬 升 参 数 为 正 值 , 将 向 上 移 动 文 本 。 文 本 抬 升 始 终 与 垂 直
坐 标 相 对 。 这 可 能 对 上 标 和 下 标 很 有 用 。 在 每 页 开 头 , 文 本 抬 升 设 为 默
认 值 0。 范 围 : 页 面 、 图 案 、 模 板 、 字 形 。
分 别 获 取 当 前 文 本 位 置 的 x 或 y 坐 标 。 范 围 : 页 面 、 图 案 、 模 板 、
字 形 。
设 置 或 获 取 当 前 下 划 线 、 上 划 线 和 删 除 线 模 式 ; 显 式 更 改 和 开 始 新 页 面
之 前 , 将 一 直 保 留 这 些 模 式 。 这 些 模 式 可 以 彼 此 独 立 设 置 , 并 在 每 页 开
头 重 设 为 false ( 参 见 第 90 页 上 的 第 4.6 节 “ 文 本 规 格 和 文 本 变 体 ”)。
范 围 : 页 面 、 图 案 、 模 板 、 字 形 。
true 下 划 线 / 上 划 线 / 删 除 线 文 本
false 不 使 用 下 划 线 / 上 划 线 / 删 除 线 文 本
下 划 线 文 本 的 描 边 线 相 对 于 基 线 的 位 置 ( 以 字 体 大 小 的 分 数 表 示 )。 可
提 供 值 1000000, 以 设 定 将 从 字 体 规 格 或 轮 廓 文 件 返 回 的 字 体 特 定 值 。
默 认 值 :1000000
下 划 线 文 本 的 绝 对 线 宽 。 可 提 供 值 0, 以 设 定 将 从 字 体 规 格 或 轮 廓 文 件
返 回 的 字 体 特 定 值 。 默 认 值 :0
设 置 或 获 取 字 间 距 , 即 : 在 字 符 串 中 放 置 具 体 单 字 之 后 , 当 前 点 的 位
移 。 换 言 之 , 当 前 点 将 水 平 移 至 每 个 空 格 字 符 (0x20) 之 后 。 间 距 值 以 文
本 间 隔 单 位 指 定 , 并 将 在 每 页 的 开 头 和 结 尾 重 设 为 默 认 值 0。 范 围 : 页
面 、 图 案 、 模 板 、 字 形 、 文 档 。
192 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java void set_text_pos(double x, double y)
Perl PHP PDF_set_text_pos(resource p, float x, float y)
C void PDF_set_text_pos(PDF *p, double x, double y)
设 置 文 本 输 出 在 页 面 上 的 位 置 。
x, y 要 设 置 的 当 前 文 本 位 置 。
详 细 说 明 在 每 页 开 头 , 文 本 位 置 设 为 默 认 值 (0, 0)。 图 形 输 出 的 当 前 点 和 当 前 文 本 位 置 将 单 独 维 护 。
范 围
页 面 、 图 案 、 模 板 、 字 形
参 数 参 见 表 8.18。
C++ Java
Perl PHP
C
C
void show(String text)
PDF_show(resource p, string text)
void PDF_show(PDF *p, const char *text)
void PDF_show2(PDF *p, const char *text, int len)
在 当 前 文 本 位 置 , 使 用 当 前 字 体 和 大 小 打 印 文 本 。
text ( 内 容 字 符 串 ) 要 打 印 的 文 本 。 在 C 语 言 中 , 因 为 假 定 以 null 终 结 , 所 以 使 用 PDF_
show( ) 时 ,text 不 能 包 含 null 字 符 ; 对 于 可 能 包 含 null 字 符 的 字 符 串 , 应 使 用 PDF_show2( )。
len ( 仅 用 于 PDF_show2( ))UCS-2 字 符 串 的 text 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0, 则
必 须 提 供 以 null 终 结 的 字 符 串 。
详 细 说 明 必 须 已 经 使 用 PDF_setfont( ) 设 置 了 字 体 。 当 前 文 本 位 置 移 至 打 印 文 本 的 结 尾 。
范 围
页 面 、 图 案 、 模 板 、 字 形
参 数 参 见 表 8.18。
绑 定
PDF_show2( ) 只 在 C 语 言 中 使 用 ; 这 是 因 为 , 在 所 有 其 他 语 言 绑 定 中 , 可 以 使 用
PDF_show( ) 提 供 任 意 字 符 串 内 容 。
C++
C
void xshow(String text, const double *xadvancelist)
void PDF_xshow(PDF *p, const char *text, int len, const double *xadvancelist)
使 用 具 体 的 水 平 位 置 , 以 当 前 字 体 和 大 小 打 印 文 本 。
text ( 内 容 字 符 串 ) 要 打 印 的 文 本 。
len ( 仅 用 于 C 语 言 绑 定 ) UCS-2 字 符 串 的 text 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0, 则
必 须 提 供 以 null 终 结 的 字 符 串 。
xadvancelist 一 组 用 于 设 定 文 本 中 的 字 形 的 x 预 置 值 。 每 个 值 都 指 定 放 置 字 形 后 的 相 对 水
平 置 换 ( 使 用 用 户 坐 标 )。 数 组 长 度 必 须 等 于 文 本 中 的 字 形 数 量 ( 不 必 与 字 节 数 len 相 等 )。
详 细 说 明 必 须 已 经 使 用 PDF_setfont( ) 设 置 了 字 体 。
范 围
页 面 、 图 案 、 模 板 、 字 形
参 数 参 见 表 8.18。
8.3 文 本 函 数 193

绑 定
仅 用 于 C 和 C++ 语 言 绑 定 。 其 他 语 言 绑 定 可 以 使 用 PDF_fit_textline( ) 中 的 xadvancelist 选
项 实 现 相 同 的 功 能 。
C++ Java void show_xy(String text, double x, double y)
Perl PHP PDF_show_xy(resource p, string text, float x, float y)
C void PDF_show_xy(PDF *p, const char *text, double x, double y)
C void PDF_show_xy2(PDF *p, const char *text, int len, double x, double y)
以 当 前 字 体 打 印 文 本 。
text ( 内 容 字 符 串 ) 要 打 印 的 文 本 。 在 C 语 言 中 , 因 为 假 定 以 null 终 结 , 所 以 使 用
PDF_show_xy( ) 时 , text 不 能 包 含 null 字 符 ; 对 于 可 能 包 含 null 字 符 的 字 符 串 ,
应 使 用 PDF_show_xy2( )。
x, y 用 户 坐 标 系 统 中 的 位 置 , 将 在 其 上 打 印 文 本 。
len ( 仅 用 于 PDF_show_xy2( )) UCS-2 字 符 串 的 text 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0,
则 必 须 提 供 以 null 终 结 的 字 符 串 。
详 细 说 明 必 须 已 经 使 用 PDF_setfont( ) 设 置 了 字 体 。 当 前 文 本 位 置 移 至 打 印 文 本 的 结 尾 。
范 围
页 面 、 图 案 、 模 板 、 字 形
参 数 参 见 表 8.18。
绑 定
PDF_show_xy2( ) 只 在 C 语 言 中 使 用 ; 这 是 因 为 , 在 所 有 其 他 语 言 绑 定 中 , 可 以 使 用
PDF_show_xy( ) 提 供 任 意 字 符 串 内 容 。
C++ Java
Perl PHP
C
C
void continue_text(String text)
PDF_continue_text(resource p, string text)
void PDF_continue_text(PDF *p, const char *text)
void PDF_continue_text2(PDF *p, const char *text, int len)
在 下 一 行 打 印 文 本 。
text ( 内 容 字 符 串 ) 要 打 印 的 文 本 。 如 果 是 空 字 符 串 , 文 本 位 置 仍 将 移 至 下 一 行 。 在 C 语
言 中 , 因 为 假 定 以 null 终 结 , 所 以 使 用 PDF_continue_text( ) 时 ,text 不 能 包 含 null 字 符 ;
对 于 可 能 包 含 null 字 符 的 字 符 串 , 应 使 用 PDF_continue_text2( )。
len ( 仅 用 于 PDF_continue_text2( ))UCS-2 字 符 串 的 text 长 度 ( 以 字 节 为 单 位 )。 如 果 len
= 0, 必 须 像 PDF_continue_text( ) 中 那 样 , 提 供 以 null 终 结 的 字 符 串 。
详 细 说 明 文 本 的 位 置 (x 和 y 位 置 ) 以 及 各 行 间 的 间 隔 由 leading 参 数 及 最 近 一 次 PDF_fit_textline( ),
PDF_show_xy( ) 或 PDF_set_text_pos( ) 调 用 决 定 。 当 前 点 将 移 至 打 印 文 本 的 结 尾 处 ; 此 函 数
后 续 调 用 的 x 位 置 将 不 会 更 改 。
范 围 页 面 、 图 案 、 模 板 、 字 形 ; 不 应 在 直 排 书 写 模 式 下 使 用 此 函 数 。
参 数 参 见 表 8.18。
绑 定
PDF_continue_text2( ) 只 在 C 语 言 中 使 用 ; 这 是 因 为 , 在 所 有 其 他 语 言 绑 定 中 , 可 以 使 用
PDF_continue_text( ) 提 供 任 意 字 符 串 内 容 。
194 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
void fit_textline(String text, double x, double y, String optlist)
PDF_fit_textline(resource p, string text, float x, float y, string optlist)
void PDF_fit_textline(PDF*p, const char *text, int len, double x, double y, const char *optlist)
根 据 各 种 选 项 , 在 位 置 (x, y) 上 放 置 单 行 文 本 。
text ( 内 容 字 符 串 ) 要 打 印 的 文 本 。
len ( 仅 用 于 C 语 言 绑 定 ) UCS-2 字 符 串 的 text 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0, 则
必 须 提 供 以 null 终 结 的 字 符 串 。
x, y 用 户 坐 标 系 统 中 的 参 考 点 坐 标 ; 将 根 据 各 种 选 项 , 在 此 坐 标 上 放 置 文 本 。
optlist 选 项 列 表 , 根 据 表 8.19 指 定 格 式 化 选 项 , 并 根 据 表 8.20 指 定 外 观 选 项 。
详 细 说 明
除 非 用 选 项 显 式 覆 盖 , 否 则 将 使 用 当 前 文 本 和 图 形 状 态 参 数 控 制 文 本 输 出 的 外 观 。 另 一 方
面 , 此 函 数 不 会 修 改 当 前 图 形 状 态 ( 尤 其 是 , 不 会 影 响 当 前 字 体 )。 但 是 , 当 前 文 本 位 置 将
调 整 到 指 向 生 成 文 本 输 出 的 结 尾 处 。
此 函 数 不 会 为 具 有 非 Unicode CMap 的 标 准 CJK 字 体 创 建 任 何 输 出 ( 参 见 第 95 页 上 的
“ 标 准 CJK 字 体 和 CMap 的 限 制 ”)。
范 围 页 面 、 图 案 、 模 板 、 字 形 ; 不 应 在 直 排 书 写 模 式 下 使 用 此 函 数 。
参 数 参 见 表 8.18。
表 8.19 PDF_fit_textline( ) 的 格 式 化 选 项
关 键 字 类 型 说 明
boxsize 浮 点 值 列 表 指 定 框 宽 度 和 高 度 的 两 个 值 , 将 相 对 于 这 两 个 值 放 置 并 可 能 缩 放 文 本 。 框 的 左
下 角 即 为 参 考 点 (x, y)。 放 置 文 本 并 使 其 填 充 此 框 的 操 作 由 position 和
fitmethod 选 项 控 制 。 如 果 width = 0, 只 考 虑 高 度 ; 如 果 height = 0, 则 只 考
虑 宽 度 。 在 这 些 情 况 下 , 将 分 别 相 对 于 (x, y) 到 (x, y+height) 的 垂 直 直 线 或 (x,
y) 到 (x+width, y) 的 水 平 直 线 放 置 文 本 。 默 认 值 :{0 0}
fitmethod 关 键 字 指 定 使 文 本 填 充 指 定 框 的 方 法 。 如 果 尚 未 指 定 框 , 将 忽 略 此 选 项 。
默 认 值 :nofit。
nofit 只 确 定 文 本 位 置 , 不 进 行 任 何 缩 放 或 剪 裁 处 理 。
clip 确 定 文 本 位 置 , 并 在 框 的 边 缘 剪 裁 文 本 。
meet 根 据 position 选 项 确 定 文 本 位 置 , 并 在 保 持 长 宽 比 的 同 时 进 行 缩 放
以 使 其 完 全 装 入 框 内 。 通 常 , 至 少 有 文 本 的 两 个 边 缘 与 框 的 对 应 边
缘 对 齐 。
auto 这 种 方 法 会 自 动 尝 试 将 文 本 完 全 置 于 框 内 。 具 体 讲 : 如 果 文 本 可 以
填 充 于 框 内 , 则 相 当 于 nofit。 否 则 , 将 计 算 缩 放 因 子 , 以 使 文 本 填
入 框 内 。 如 果 此 因 子 大 于 shrinklimit 选 项 , 将 扭 曲 文 本 以 填 充 框 ;
否 则 , 将 应 用 meet 方 法 。
slice 根 据 position 选 项 确 定 文 本 位 置 , 并 进 行 缩 放 以 使 其 覆 盖 整 个 框 ,
可 在 保 持 长 宽 比 的 同 时 确 保 至 少 文 本 的 一 个 尺 寸 可 完 全 包 含 在 框
内 。 通 常 , 文 本 的 某 些 其 他 尺 寸 会 延 伸 到 框 外 , 因 此 , 将 被 剪 裁 。
entire 根 据 position 选 项 确 定 文 本 的 位 置 , 并 进 行 缩 放 以 使 其 覆 盖 整 个
框 。 通 常 , 这 种 方 法 会 扭 曲 文 本 。 scale 选 项 将 被 忽 略 。
locallink 选 项 列 表 如 果 提 供 了 此 选 项 , 将 通 过 文 本 创 建 可 以 使 用 的 本 地 链 接 ; 即 : 将 destname
选 项 设 为 text 参 数 , 并 创 建 type=Link 的 批 注 。 此 文 本 必 须 匹 配 已 用 PDF_add_
nameddest( ) 创 建 的 命 名 目 标 的 名 称 。 可 提 供 下 列 选 项 ( 有 关 详 细 信 息 , 参 见
表 8.51): annotcolor、 borderstyle、 dasharray 和 highlight ( 将 自 动 设 置
action 和 usercoordinates 选 项 )。
margin 浮 点 值 列 表 一 个 或 两 个 浮 点 值 , 描 述 文 本 框 的 额 外 水 平 和 垂 直 扩 展 。 默 认 值 :0
8.3 文 本 函 数 195

表 8.19 PDF_fit_textline( ) 的 格 式 化 选 项
关 键 字 类 型 说 明
orientate 关 键 字 指 定 放 置 文 本 时 所 需 的 文 本 方 向 。 默 认 值 :north
north 向 上
east 指 向 右 侧
south 向 下
west 指 向 左 侧
position
浮 点 值 或 关
键 字 列 表
( 对 齐 方 式 控 制 ) 一 个 或 两 个 值 , 指 定 文 本 定 界 框 内 的 参 考 点 位 置 (x, y) ;
{0 0} 表 示 位 于 文 本 框 左 下 角 , {100 100} 表 示 位 于 右 上 角 。 如 果 已 经 指 定 了
boxsize 选 项 , 则 position 选 项 还 可 指 定 目 标 框 的 位 置 。 这 些 值 表 示 为 文 本 宽 度
和 高 度 的 百 分 比 。 如 果 两 个 百 分 比 相 等 , 指 定 一 个 浮 点 值 即 可 。
关 键 字 left、 center、 right (x 方 向 ) 或 者 bottom、 center、 top (y 方 向 ) 可
用 来 替 代 值 0、 50 和 100。 如 果 只 指 定 一 个 关 键 字 , 将 添 加 另 一 方 向 对 应 的 关
键 字 。 以 下 是 一 些 示 例 :
{0 50} 或 {left center} 生 成 左 对 齐 文 本 ;
{50 50} 或 {center} 生 成 居 中 文 本 ;
{100 50} 或 {right center} 生 成 右 对 齐 文 本 。
默 认 值 :0 ( 左 下 角 )
rotate 浮 点 型 旋 转 坐 标 系 统 , 将 中 心 用 作 参 考 点 并 将 指 定 的 值 用 作 以 度 数 表 示 的 旋 转 角 度 。
这 将 旋 转 框 和 文 本 。 放 置 文 本 时 , 会 重 设 旋 转 选 项 。 默 认 值 :0
weblink 选 项 列 表 如 果 提 供 了 此 选 项 , 将 通 过 文 本 创 建 可 以 使 用 的 weblink ; 即 : 将 使 用 默 认 选
项 或 选 项 列 表 中 提 供 的 选 项 创 建 type=Link 的 批 注 。 可 提 供 下 列 选 项 ( 有 关 详
细 信 息 , 参 见 表 8.51): annotcolor、 borderstyle、 dasharray、 highlight 和
linewidth ( 将 自 动 设 置 action 和 usercoordinates 选 项 )。 提 供 的 文 本 必 须 包 含
有 效 的 URL。
xadvancelist 浮 点 值 列 表 使 用 用 户 坐 标 , 指 定 文 本 中 所 有 字 形 的 预 置 宽 度 。 列 表 的 长 度 必 须 小 于 或 等 于
文 本 中 的 字 形 数 。 如 果 长 度 小 于 字 形 数 , 且 glyphwarning 设 为 true, 将 引 发 警
告 。 将 使 用 xadvance 值 替 代 标 准 字 形 宽 度 。 字 距 微 调 和 字 符 间 距 等 其 他 效 果
不 受 影 响 。
表 8.20 PDF_fit_textline( ) 的 外 观 选 项 及 PDF_create_textflow( ) 的 直 接 或 内 嵌 选 项
关 键 字 类 型 说 明
charref 布 尔 型 如 果 为 true, 将 启 用 数 字 和 字 符 实 体 引 用 的 替 换 ( 参 见 第 87 页 上 的 第 4.5.5
节 “ 字 符 引 用 ”)。 默 认 值 :false
charspacing
浮 点 型 或
百 分 比
字 符 间 距 ( 参 见 表 8.18)。 百 分 比 基 于 fontsize。 默 认 值 : 全 局 charspacing
参 数 。
fillcolor 颜 色 文 本 的 填 充 色 。 默 认 值 : 当 前 填 充 色
字 体 字 体 句 柄 PDF_load_font( ) 返 回 的 字 体 句 柄 。 默 认 值 : 当 前 字 体
fontsize 浮 点 型 ( 如 提 供 了 font 选 项 , 则 要 求 此 选 项 ) 字 体 的 大 小 , 以 当 前 用 户 坐 标 系 统 的
单 位 表 示 。 默 认 值 : 当 前 字 体 大 小
glyphwarning 布 尔 型 如 果 为 true, 由 于 字 体 不 包 含 相 应 的 字 形 描 述 而 无 法 显 示 字 形 时 , 将 引 发 异
常 。 如 果 为 false, 将 用 空 格 字 符 或 字 形 ID 0 替 换 字 体 中 缺 失 的 字 形 。 默 认
值 : 全 局 glyphwarning 参 数 。
horizscaling 浮 点 型 或
百 分 比
水 平 文 本 缩 放 ( 参 见 表 8.18)。 默 认 值 : 全 局 horizscaling 参 数 。
italicangle 浮 点 型 指 定 文 本 的 斜 体 ( 倾 斜 ) 角 度 的 度 数 ( 参 见 第 92 页 上 的 第 4.6.3 节 “ 文 本
变 体 ”)。 默 认 值 : 全 局 italicangle 参 数 。
kerning 布 尔 型 字 距 微 调 行 为 ( 参 见 表 8.18)。 默 认 值 : 全 局 kerning 参 数 。
overline 布 尔 型 上 划 线 模 式 ( 参 见 表 8.18)。 默 认 值 : 全 局 overline 参 数 。
strikeout 布 尔 型 删 除 线 模 式 ( 参 见 表 8.18)。 默 认 值 : 全 局 strikeout 参 数 。
strokecolor 颜 色 文 本 的 描 边 色 。 默 认 值 : 当 前 描 边 色
196 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.20 PDF_fit_textline( ) 的 外 观 选 项 及 PDF_create_textflow( ) 的 直 接 或 内 嵌 选 项
关 键 字 类 型 说 明
shrinklimit
浮 点 型 或
百 分 比
收 缩 因 子 的 下 限 , 将 用 来 调 整 文 本 。 默 认 值 :0.75
textformat 关 键 字 用 来 解 释 提 供 的 文 本 的 格 式 ( 参 见 第 84 页 上 的 第 4.5.2 节 “ 内 容 字 符 串 、
超 文 本 字 符 串 和 名 称 字 符 串 ”)。 默 认 值 : 全 局 textformat 参 数 。
textrendering 整 型 文 本 渲 染 模 式 ( 参 见 表 8.18)。 默 认 值 : 全 局 textrendering 参 数
textrise
浮 点 型 或
百 分 比
文 本 抬 升 模 式 ( 参 见 表 8.18)。 百 分 比 基 于 fontsize。 默 认 值 : 全 局 text rise
参 数
underline 布 尔 型 下 划 线 模 式 ( 参 见 表 8.18)。 默 认 值 : 全 局 underline 参 数 。
underlineposition 浮 点 型 、
百 分 比 或
关 键 字
underlinewidth 浮 点 型 、
百 分 比 或
关 键 字
wordspacing
浮 点 型 或
百 分 比
下 划 线 文 本 的 描 边 线 相 对 于 基 线 的 位 置 ( 绝 对 值 或 相 对 于 fontsize 的 值 ; 典
型 值 为 -10%)。 可 使 用 关 键 字 auto, 设 定 将 从 字 体 规 格 或 轮 廓 文 件 返 回 的 字
体 特 定 值 。 默 认 值 :auto
下 划 线 文 本 的 线 宽 ( 绝 对 值 或 相 对 于 fontsize 的 值 ; 典 型 值 为 5%)。 可 使 用
关 键 字 auto 或 值 0 设 定 , 将 从 字 体 规 格 或 轮 廓 文 件 返 回 的 字 体 特 定 值 。 默
认 值 :auto
字 间 距 ( 参 见 表 8.18)。 百 分 比 基 于 fontsize。 默 认 值 : 全 局 wordspacing
参 数
C++ Java
Perl PHP
C
C
double stringwidth(String text, int font, double fontsize)
float PDF_stringwidth(resource p, string text, int font, float fontsize)
double PDF_stringwidth(PDF *p, const char *text, int font, double fontsize)
double PDF_stringwidth2(PDF *p, const char *text, int len, int font, double fontsize)
以 任 意 字 体 返 回 text 的 宽 度 。
text ( 内 容 字 符 串 ) 请 求 其 宽 度 的 文 本 。 在 C 语 言 中 , 因 为 假 定 以 null 终 结 , 所 以 使 用
PDF_stringwidth( ) 时 , text 不 能 包 含 null 字 符 ; 对 于 可 能 包 含 null 字 符 的 字 符 串 , 应 使 用
PDF_stringwidth2( )。
len ( 仅 用 于 PDF_stringwidth2( )) UCS-2 字 符 串 的 text 长 度 ( 以 字 节 为 单 位 )。 如 果 len
= 0, 则 必 须 提 供 以 null 终 结 的 字 符 串 。
font PDF_load_font( ) 返 回 的 字 体 句 柄 。 具 有 非 Unicode CMap 的 标 准 CJK 字 体 不 能 使 用
字 体 规 格 。 如 果 font 引 用 这 种 字 体 , 此 函 数 将 返 回 0, 而 不 考 虑 text 和 fontsize 参 数 ( 除 非
已 经 在 载 入 字 体 时 提 供 了 monospace 选 项 )。
fontsize 字 体 的 大 小 , 以 用 户 坐 标 系 统 的 单 位 表 示 ( 参 见 PDF_setfont( ))。
返 回 值
使 用 任 意 字 体 的 text 的 宽 度 ; 该 字 体 用 PDF_load_font( ) 和 提 供 的 fontsize 选 择 。 返 回 的 宽
度 值 可 以 是 负 值 ( 例 如 , 已 设 置 负 值 的 水 平 缩 放 比 例 )。
详 细 说 明 宽 度 的 计 算 会 考 虑 下 列 文 本 参 数 的 当 前 值 : 水 平 缩 放 比 例 、 字 距 微 调 、 字 符 间 距 和 字 间 距 。
范 围
页 面 、 图 案 、 模 板 、 路 径 、 字 形 、 文 档
参 数 参 见 表 8.18。
绑 定
PDF_stringwidth2( ) 仅 用 于 C 语 言 ; 这 是 因 为 , 在 所 有 其 他 语 言 绑 定 中 , 可 以 使 用
PDF_stringwidth( ) 提 供 任 意 字 符 串 内 容 。
8.3 文 本 函 数 197

C int PDF_show_boxed(PDF *p, const char *text, double x, double y,
double width, double height, const char *mode, const char *feature)
不 常 用 , 对 于 单 行 文 本 , 可 使 用 PDF_fit_textline( ) , 多 行 格 式 化 可 使 用 PDF_*_textflow( )。
如 果 是 多 行 格 式 化 , 使 用 minspacing=100%、 maxspacing=10000%、 nofitlimit= 100% 和
shrinklimit= 100% 将 产 生 与 使 用 PDF_show_boxed( ) 相 同 的 结 果 。 格 式 化 后 剩 余 的 字 符 数
( 即 , PDF_show_boxed( ) 返 回 的 值 ) 可 使 用 PDF_info_textflow( ) 中 的 remainchars 选 项
返 回 。
8.3.5 使 用 文 本 流 的 多 行 文 本
C++ Java
Perl PHP
C
int create_textflow(String text, String optlist)
int PDF_create_textflow(resource p, string text, string optlist)
int PDF_create_textflow(PDF *p, const char *text, int len, const char *optlist)
预 处 理 文 本 以 便 稍 后 进 行 格 式 化 并 创 建 文 本 流 对 象 。
text ( 内 容 字 符 串 ) 文 本 流 的 内 容 。 它 可 能 包 含 表 8.21 和 表 8.24 中 列 出 的 各 种 编 码 、 内 嵌
选 项 列 表 ( 另 请 参 见 第 202 页 上 的 “ 文 本 流 的 内 嵌 选 项 列 表 ”) 以 及 各 种 宏 ( 参 见 第 202 页
上 的 “ 文 本 流 的 宏 选 项 ”) 所 产 生 的 文 本 。 不 过 , 如 果 文 本 为 空 字 符 串 , 将 返 回 有 效 的 文 本
流 句 柄 。
len ( 仅 用 于 C 语 言 绑 定 ) 以 字 节 为 单 位 的 文 本 长 度 , 以 null 终 结 的 字 符 串 的 长 度 为 0。
optlist 选 项 列 表 , 根 据 表 8.21 或 表 8.24 指 定 文 本 流 选 项 。 将 在 text 中 包 含 的 内 嵌 选 项 列
表 之 前 计 算 optlist 中 指 定 的 选 项 , 以 使 内 嵌 选 项 优 先 于 optlist 参 数 中 提 供 的 选 项 。
返 回 值
详 细 说 明
范 围
文 本 流 句 柄 , 可 在 PDF_fit_textflow( )、 PDF_info_textflow( ) 和 PDF_delete_textflow( ) 调 用
中 使 用 。 在 关 闭 文 档 范 围 结 束 和 用 该 句 柄 调 用 PDF_delete_textflow( ) 之 前 , 句 柄 将 一 直 有
效 。 如 果 出 现 错 误 , 如 果 textwarning 参 数 或 选 项 为 false, 此 函 数 将 返 回 错 误 代 码 -1 ( 在
PHP 中 : 返 回 0)。 如 果 设 为 true, 此 参 数 将 在 出 现 错 误 时 引 发 异 常 。
此 函 数 处 理 提 供 的 文 本 并 据 此 创 建 内 部 数 据 结 构 。 它 决 定 稍 后 将 由 文 本 格 式 器 使 用 的 文 本
部 分 ( 例 如 单 词 ), 处 理 内 嵌 选 项 列 表 , 在 可 能 的 情 况 下 将 文 本 转 换 为 Unicode 字 符 串 , 确
定 潜 在 的 换 行 符 并 基 于 字 体 和 文 本 选 项 计 算 文 本 部 分 的 宽 度 。 可 应 用 optlist 参 数 中 的
textlen 选 项 , 对 部 分 或 全 部 文 本 停 用 内 嵌 选 项 列 表 搜 索 ( 第 202 页 上 的 “ 文 本 流 的 内 嵌 选
项 列 表 ”)。
此 函 数 不 会 在 生 成 的 PDF 文 档 中 创 建 任 何 输 出 , 只 准 备 文 本 。 使 用 PDF_fit_textflow( ) ,
用 预 处 理 的 文 本 流 句 柄 创 建 输 出 。
默 认 情 况 下 , 将 用 VT、LS、LF、CR、CRLF、NEL、PS 和 FF 字 符 强 制 生 成 新 行 ( 有 关 这
些 字 符 的 描 述 , 参 见 表 4.5)。 除 VT 和 LS 之 外 , 所 有 这 些 字 符 都 可 强 制 生 成 新 段 落 ( 这 表
示 , parindent 选 项 将 有 效 ) 。 FF 立 即 停 止 使 文 本 填 充 fitbox 的 操 作 ( 将 退 出 PDF_fit_
textflow( ) 函 数 , 并 返 回 字 符 串 _nextpage)。
水 平 制 表 符 (HT) 设 置 后 续 文 本 的 新 起 点 。 具 体 由 hortabmethod 和 hortabsize 选 项 控 制 。
如 果 自 动 连 字 符 后 是 一 个 换 行 符 , 将 用 hyphenchar 选 项 中 指 定 的 字 符 替 换 自 动 连 字 符
(SHY)。 有 关 更 多 详 细 信 息 , 参 见 第 111 页 上 的 第 4.9.8 节 “ 控 制 换 行 算 法 ”。
不 支 持 直 排 书 写 模 式 。
任 意 , 对 象 除 外
198 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.21 PDF_create_textflow( ) 的 选 项
选 项 类 型 说 明
textwarning 布 尔 型 如 果 为 true, 选 项 列 表 或 PDF_load_font( ) ( 当 fontname 选 项 被 指 定 , 内 部 会
自 动 调 用 此 函 数 ) 中 发 现 错 误 时 , 将 引 发 异 常 。 textwarning 选 项 设
fontwarning 和 glyphwarning 选 项 为 缺 省 。 如 果 是 false, 此 函 数 将 返 回 错 误 代
码 -1 ( 在 PHP 中 : 返 回 0)。 默 认 值 :true
fixedtextfor
mat
布 尔 型 (Java 和 Tcl 等 识 别 Unicode 的 语 言 将 忽 略 此 选 项 ) 如 果 为 true, 所 有 文 本 片 段
和 内 嵌 选 项 列 表 将 使 用 相 同 的 textformat, 必 须 为 utf8、 utf16、 utf16be 或
utf16le 之 一 。
如 果 为 false, 包 括 分 隔 符 的 内 嵌 选 项 列 表 必 须 用 winansi 编 码 ( 在 基 于
EBCDIC 的 平 台 上 , 必 须 用 ebcdic 编 码 )。 作 为 此 规 则 的 一 项 例 外 , 如 果
此 文 本 片 段 使 用 兼 容 Unicode 的 8 位 编 码 方 式 , 且 没 有 提 供 textlen 选 项 ,
则 begoptlistchar 必 须 使 用 前 一 文 本 片 段 的 编 码 方 式 进 行 编 码 。
默 认 值 :false
C++ Java String fit_textflow(int textflow,
double llx, double lly, double urx, double ury, String optlist)
Perl PHP string PDF_fit_textflow(resource p,
int textflow, float llx, float lly, float urx, float ury, string optlist)
C
const char *PDF_fit_textflow(PDF *p,
int textflow, double llx, double lly, double urx, double ury, const char *optlist)
将 文 本 流 的 下 一 部 分 格 式 化 成 一 个 矩 形 区 域 。
textflow PDF_create_textflow( ) 调 用 返 回 的 文 本 流 句 柄 。
llx, lly, urx, ury 用 户 坐 标 系 统 中 , 目 标 矩 形 (fitbox) 左 下 角 和 右 上 角 的 x 和 y 坐 标 。 也 可
以 按 相 反 的 顺 序 指 定 左 下 角 和 右 上 角 坐 标 。
optlist 选 项 列 表 , 根 据 表 8.22 指 定 处 理 选 项 。
返 回 值 指 定 函 数 返 回 的 原 因 的 字 符 串 。
> _stop: 文 本 流 内 的 所 有 文 本 均 已 处 理 完 毕 。
> _nextpage: 等 候 下 一 页 ( 由 于 换 页 符 U+000C 导 致 )。 处 理 剩 余 文 本 要 求 再 次 调 用
PDF_fit_textflow( )。
> _boxfull: fitbox 中 的 空 间 已 全 部 用 完 , 或 框 中 已 设 置 了 最 大 行 数 ( 如 通 过 maxlines 指 定
的 行 数 )。 处 理 剩 余 文 本 要 求 再 次 调 用 PDF_fit_textflow( )。
> _boxempty: 在 处 理 后 fitbox 不 包 含 任 何 文 本 , 这 发 生 在 fitbox 太 小 而 不 能 装 任 何 文 本 时 。
为 了 避 免 无 穷 循 环 , 不 应 对 相 同 的 fitbox 再 次 调 用 PDF_fit_textflow( )。
> 任 何 其 他 字 符 串 : 在 内 嵌 选 项 列 表 中 , 提 供 给 return 命 令 的 字 符 串 。
如 果 同 时 由 多 种 原 因 导 致 返 回 , 将 报 告 列 表 中 的 第 一 项 ( 由 上 至 下 ) 。 在 下 次 调 用 此 函 数
前 , 返 回 的 字 符 串 将 一 直 有 效 。
详 细 说 明
范 围
当 前 文 本 和 图 形 状 态 不 影 响 用 此 函 数 创 建 的 文 本 输 出 ( 这 不 同 于 PDF_fit_textline( ))。 可 在
PDF_create_textflow( ) 中 使 用 fillcolor、 strokecolor 和 其 他 外 观 选 项 ( 参 见 表 8.20) 控 制 文
本 的 外 观 。 从 此 函 数 返 回 后 , 文 本 状 态 不 会 发 生 更 改 。 但 是 , 当 前 文 本 位 置 将 调 整 到 生 成 的
文 本 输 出 的 末 尾 ( 除 非 blind 选 项 已 设 为 true)。
页 面 、 图 案 、 模 板 、 字 形
8.3 文 本 函 数 199

表 8.22 PDF_fit_textflow( ) 的 选 项
选 项 类 型 说 明
blind 布 尔 型 不 生 成 输 出 , 但 将 执 行 所 有 计 算 , 并 可 使 用 PDF_info_textflow( ) 检 查 格 式 化 结
果 。 默 认 值 :false
firstlinedist 浮 点 型 、
百 分 比 或
关 键 字
由 用 户 坐 标 指 定 的 fitbox 顶 部 与 第 一 行 文 本 基 线 之 间 的 距 离 , 可 表 示 为 相 关 字
体 大 小 的 百 分 比 ( 如 果 fixedleading=true, 将 使 用 行 中 的 第 一 个 字 体 大 小 ; 否
则 , 使 用 行 中 最 大 的 字 体 大 小 ) 或 关 键 字 ( 默 认 值 :leading):
leading 为 第 一 行 确 定 的 行 距 值 ; À 等 典 型 的 变 音 字 符 将 与 fitbox 顶 部 相 接 。
ascender 为 第 一 行 确 定 的 字 母 上 缘 值 ; d 和 h 等 字 母 上 缘 较 高 的 典 型 字 符 将 与
fitbox 顶 部 相 接 。
capheight 为 第 一 行 确 定 的 大 写 高 度 值 ; H 等 典 型 的 大 写 字 符 将 与 fitbox 顶 部
相 接 。
xheight 为 第 一 行 确 定 的 xheight 值 ; x 等 典 型 的 小 写 字 符 将 与 fitbox 顶 部 相
接 。
如 果 fixedleading=false, 将 在 第 一 行 的 所 有 行 距 值 、 字 母 上 缘 值 和 大 写 高 度 值
中 , 选 取 最 大 值 。
fitmethod 关 键 字 指 定 使 文 本 填 充 fitbox 的 方 法 。 默 认 值 :clip
auto 将 在 隐 蔽 模 式 下 , 使 用 缩 小 的 字 体 大 小 及 其 他 字 体 相 关 选 项 ( 参 见
fontscale) 重 复 调 用 PDF_ fit_textflow( ), 直 至 全 部 文 本 可 填 充 于
fitbox 为 止 。
clip 文 本 将 在 fitbox 底 部 截 断 。
nofit 文 本 可 以 延 伸 到 fitbox 底 部 之 外 ( 但 只 能 延 伸 到 页 面 边 缘 )。
fontscale 浮 点 型 将 用 提 供 的 缩 放 因 子 乘 以 fontsize 的 值 以 及 leading、 minspacing、
maxspacing、 spreadlimit 和 space 的 绝 对 值 ( 而 非 百 分 比 )。 默 认 值 : 如 果
rewind=0, 默 认 值 为 1 ; 否 则 , 将 为 与 相 应 PDF_fit_textflow( ) 调 用 提 供 的 值 。
lastlinedist 浮 点 型 、
百 分 比 或
关 键 字
linespreadlimit
maxlines
浮 点 型 或
百 分 比
整 型 或 关
键 字
( 如 果 fitmethod=nofit, 将 忽 略 此 选 项 ) 由 用 户 坐 标 指 定 的 , 文 本 最 后 一 行 的
基 线 与 fitbox 底 部 之 间 的 最 小 距 离 , 可 表 示 为 字 体 大 小 的 百 分 比 ( 如 果
fixedleading= true, 则 使 用 行 中 的 第 一 个 字 体 大 小 ; 否 则 , 使 用 行 中 最 大 的 字
体 大 小 ) 或 关 键 字 ( 默 认 值 :0, 即 :fitbox 的 底 部 将 用 作 基 线 , 典 型 的 字 母 下
缘 将 延 伸 到 fitbox 下 方 ):
descender 为 第 一 行 确 定 的 字 母 下 缘 值 ; g 和 j 等 具 有 字 母 下 缘 的 典 型 字 符 将 与
fitbox 底 部 相 接 。
如 果 fixedleading=false, 将 于 最 后 一 行 所 有 的 字 母 下 缘 值 中 , 选 取 最 大 值 。
( 仅 用 于 verticalalign=justify 的 情 况 ) 用 户 坐 标 中 的 最 大 量 , 或 用 以 增 加 垂 直 对
齐 行 距 的 行 距 百 分 比 。 默 认 值 :200%
fitbox 中 的 最 大 行 数 , 或 关 键 字 auto ; auto 表 示 , 将 在 fitbox 内 放 置 尽 可 能 多
的 行 。 达 到 最 大 行 数 限 制 时 , PDF_fit_textflow( ) 将 返 回 字 符 串 _boxfull。 默 认
值 :auto
orientate 关 键 字 指 定 放 置 文 本 时 所 需 的 文 本 方 向 。 默 认 值 :north
north 向 上
east 指 向 右 侧
south 向 下
west 指 向 左 侧
rewind 整 型 :
-2、 -1、
0 或 1
提 供 文 本 流 的 状 态 重 设 为 另 一 PDF_fit_textflow( ) 调 用 之 前 的 状 态 。 目 前 支 持 下
列 值 ( 默 认 值 :0):
1 退 回 第 一 次 调 用 PDF_fit_textflow( ) 之 前 的 状 态 。
0 不 重 设 文 本 流 。
-1 退 回 上 一 次 调 用 PDF_fit_textflow( ) 之 前 的 状 态 。
-2 退 回 倒 数 第 二 次 调 用 PDF_fit_textflow( ) 之 前 的 状 态 。
rotate 浮 点 型 旋 转 坐 标 系 统 , 将 fitbox 的 左 下 角 用 作 中 心 并 将 指 定 的 值 用 作 以 旋 转 角 度 的 度
数 。 这 将 旋 转 框 和 文 本 。 放 置 文 本 时 , 会 重 设 旋 转 选 项 。 默 认 值 :0
200 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.22 PDF_fit_textflow( ) 的 选 项 ( 续 )
选 项 类 型 说 明
showborder 布 尔 型 如 果 为 true, 将 对 fitbox 的 边 框 做 描 边 处 理 ( 使 用 当 前 图 形 状 态 )。 这 可 能 对
开 发 和 调 试 很 有 用 。 默 认 值 :false
verticalalign 关 键 字 fitbox 中 文 本 使 用 的 垂 直 对 齐 方 式 ; 将 根 据 需 要 , 考 虑 firstlinedist 和 lastlinedist
选 项 ( 默 认 值 :top):
top 格 式 化 将 从 第 一 行 开 始 , 向 下 继 续 。 如 果 文 本 不 能 填 满 fitbox, 文 本
下 方 将 出 现 空 白 。
center 文 本 在 fitbox 中 垂 直 居 中 。 如 果 文 本 不 能 填 满 fitbox, 文 本 上 方 和 下
方 都 将 出 现 空 白 。
bottom 格 式 化 将 从 最 后 一 行 开 始 , 向 上 继 续 。 如 果 文 本 不 能 填 满 fitbox, 文
本 上 方 将 出 现 空 白 。
justify 文 本 与 fitbox 的 顶 部 和 底 部 对 齐 。 为 了 实 现 这 种 效 果 , 将 增 加 行 间
距 , 直 至 达 到 linespreadlimit 指 定 的 限 制 为 止 。 如 果
firstlinedist=leading, 将 只 增 加 第 一 行 的 高 度 。
C++ Java
Perl PHP
C
double info_textflow(int textflow, String keyword)
float PDF_info_textflow(resource p, int textflow, string keyword)
double PDF_info_textflow(PDF *p, int textflow, const char *keyword)
查 询 文 本 流 的 当 前 状 态 。
textflow PDF_create_textflow( ) 调 用 返 回 的 文 本 流 句 柄 。
keyword 根 据 表 8.23 指 定 请 求 的 信 息 的 关 键 字 。
返 回 值
范 围
参 数
keyword 请 求 的 、 某 些 文 本 流 参 数 的 值 。 即 使 在 隐 蔽 模 式 下 , 此 参 数 也 可 返 回 正 确 的 几 何 信
息 ( 不 同 于 textx/texty 参 数 )。
文 档 、 页 面 、 图 案 、 模 板 、 字 形
textx、 texty
表 8.23 PDF_info_textflow( ) 的 关 键 字
关 键 字
说 明
boxlinecount 最 后 一 个 fitbox 中 的 行 数 。
firstparalinecount fitbox 中 第 一 个 段 落 的 行 数 。
lastmark
最 后 一 个 fitbox 内 已 处 理 文 本 流 部 分 中 找 到 的 最 后 一 个 标 记 的 编 号 ( 可 用 mark 选 项
设 置 标 记 )。
leading leading 选 项 的 当 前 值 , 由 文 本 流 中 的 文 本 和 选 项 确 定 。
lastparalinecount fitbox 中 最 后 一 个 段 落 的 行 数 。
leftlinex, leftliney, 分 别 表 示 最 近 填 充 的 fitbox 内 、 从 最 左 边 开 始 的 行 和 在 最 右 边 结 束 的 行 的 x 和 y 坐 标 。
rightlinex, rightliney
minlinelength, 分 别 表 示 最 近 填 充 的 fitbox 中 、 最 短 和 最 长 文 本 行 的 长 度 。
maxlinelength
minliney
分 别 表 示 最 近 填 充 的 fitbox 中 、 最 短 和 最 长 文 本 行 的 基 线 y 坐 标 。
maxliney
remainchars ( 不 常 用 ) 尚 未 处 理 的 字 符 数 。 此 计 数 不 包 括 内 嵌 选 项 列 表 和 字 符 引 用 中 的 字 符 数 。
由 于 各 种 文 本 替 换 过 程 ( 例 如 CR/NL 组 合 ), 此 值 可 能 不 可 靠 。
textendx, textendy 放 置 文 本 后 , 当 前 点 的 x 或 y 坐 标 。
used 到 目 前 为 止 , 已 放 置 的 文 本 的 百 分 比 (0...100)。
8.3 文 本 函 数 201

C++ Java
Perl PHP
C
void delete_textflow(int textflow)
PDF_delete_textflow(resource p, int textflow)
void PDF_delete_textflow(PDF *p, int textflow)
删 除 文 本 流 及 其 相 关 数 据 结 构 。
textflow PDF_create_textflow( ) 调 用 返 回 的 文 本 流 句 柄 。
详 细 说 明 尚 未 使 用 此 函 数 删 除 的 文 本 流 将 在 关 闭 文 档 范 围 结 束 之 后 自 动 删 除 。
范 围
任 意
文 本 流 的 内 嵌 选 项 列 表 PDF_create_textflow( ) 的 text 参 数 中 提 供 的 内 容 可 以 包 括 任 意 数
量 的 选 项 列 表 ( 内 嵌 选 项 ) , 根 据 表 8.24 指 定 文 本 流 选 项 。 另 外 , 也 可 以 在 PDF_create_
textflow( ) 的 optlist 参 数 中 提 供 所 有 这 些 选 项 。 在 一 个 选 项 列 表 中 , 同 一 选 项 可 指 定 多 次 ;
这 时 , 将 只 考 虑 最 后 一 次 指 定 的 选 项 。
内 嵌 选 项 列 表 必 须 使 用 winansi 编 码 ( 在 基 于 EBCDIC 平 台 上 , 必 须 使 用 ebcdic 编 码 )
或 被 选 择 的 Unicode 格 式 ( 若 fixedtextformat=true) , 而 且 必 须 用 begoptlistchar 和
endoptlistchar 选 项 中 指 定 的 字 符 括 起 来 ( 默 认 值 :< 和 >)。 很 显 然 , 如 果 实 际 文 本 中 必 须
使 用 用 来 开 始 内 嵌 选 项 列 表 的 字 符 , 可 能 会 引 发 冲 突 。 有 几 种 方 法 可 以 解 决 这 个 冲 突 ; 具 体
取 决 于 文 本 是 否 包 含 任 何 内 嵌 选 项 列 表 。
如 果 文 本 不 包 含 任 何 内 嵌 选 项 列 表 , 可 以 通 过 下 列 一 种 方 法 完 全 停 用 搜 索 内 嵌 选 项 列 表
的 操 作 :
> 在 PDF_create_textflow( ) 的 optlist 参 数 中 , 设 置 begoptlistchar=none。
> 将 PDF_create_textflow( ) 的 optlist 参 数 中 的 textlen 选 项 设 为 文 本 的 长 度 。
如 果 文 本 确 实 包 含 内 嵌 选 项 列 表 , 可 通 过 下 列 一 种 方 法 避 免 文 本 内 容 与 开 始 内 嵌 选 项 列 表
的 begoptlistchar 之 间 的 冲 突 :
> 用 对 应 的 数 字 或 字 符 实 体 引 用 (&#x3C; 或 &lt;) 替 换 出 现 的 所 有 < 字 符 , 或 用 文 字 < 字
符 开 始 内 嵌 选 项 列 表 。
> 将 PDF_create_textflow( ) 的 optlist 中 的 begoptlistchar 选 项 设 为 文 本 中 没 有 使 用 的 字
符 , 并 使 用 该 字 符 开 始 内 嵌 选 项 列 表 。
> 在 每 个 内 嵌 选 项 列 表 中 , 使 用 textlen 选 项 指 定 下 一 文 本 片 段 的 长 度 ( 直 至 下 一 内 嵌 选 项
列 表 开 始 为 止 )。 有 些 情 况 下 , 实 际 上 要 求 这 种 设 置 ; 例 如 : 如 果 不 能 用 Unicode 解 释 内
嵌 选 项 列 表 间 的 某 些 文 本 片 段 等 ( 有 关 详 细 信 息 , 参 见 表 8.24 和 第 108 页 上 的 第 4.9.6 节
“ 控 制 字 符 、 字 符 映 射 和 符 号 字 体 ”)。
注 : 如 果 直 接 在 前 一 个 选 项 列 表 之 后 提 供 了 一 个 内 嵌 选 项 列 表 , 将 假 定 他 们 之 间 存 在 长 度 为 0 的
文 本 片 段 。 在 第 一 个 选 项 列 表 中 提 供 textlen 选 项 时 , 这 一 点 很 重 要 。
文 本 流 的 宏 选 项 文 本 流 的 选 项 列 表 ( 无 论 是 文 本 中 内 嵌 选 项 列 表 , 或 是 在 PDF_create_
textflow( ) 调 用 中 直 接 提 供 选 项 列 表 ) 可 以 包 含 宏 定 义 和 宏 调 用 ; 具 体 规 则 , 参 见 表 8.25。
宏 可 用 来 集 中 定 义 多 次 使 用 的 选 项 值 , 如 字 体 名 称 、 缩 进 量 等 。 解 析 选 项 列 表 之 前 , 将 用 宏
定 义 中 提 供 的 对 应 选 项 列 表 的 内 容 替 代 其 中 包 含 的 每 个 宏 。 然 后 , 会 解 析 由 此 生 成 的 选 项 列
表 。 以 下 是 两 个 宏 的 宏 定 义 示 例 :
202 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.24 PDF_create_textflow( ) 的 optlist 参 数 及 文 本 中 的 内 嵌 选 项 列 表 的 选 项
选 项 类 型 说 明
PDF_load_font( ) 的 所 有 选 项 和 参 数 ( 参 见 表 8.16):
encoding 字 符 串 ( 必 须 与 fontname 选 项 一 起 使 用 ) 编 码 的 名 称 。
fontname 名 称 字 符 串 ( 必 须 与 encoding 选 项 一 起 使 用 ) 字 体 的 名 称 ; 切 记 用 { 和 } 将 包 含 空 格 字
符 的 名 称 括 起 来 。
autocidfont
autosubsetting
embedding
fontstyle
fontwarning
monospace
subsetlimit
subsetminsize
subsetting
unicodemap
PDF_fit_textline( ) 的 所 有 外 观 选 项 ( 参 见 表 8.20):
charref
charspacing
dasharray
fillcolor
font
fontsize
glyphwarning
horizscaling
italicangle
kerning
overline
strikeout
strokecolor
strokewidth
textformat
textrendering
textrise
underline
underlineposition
underlinewidth
wordspacing
控 制 嵌 入 选 项 列 表 的 处 理 的 选 项 :
begoptlistchar
单 字 符 或 关
键 字
这 些 选 项 只 在 同 时 提 供 fontname 和 encoding 选 项 的 情 况 下 使 用 。 注 意 :
font- 将 用 textwarning 选 项 的 值 进 行 初 始 化 。
warning
font 如 果 同 时 指 定 fontname 和 encoding, 将 忽 略 此 选 项 。
fontsize 要 求 使 用 此 选 项 。
内 嵌 选 项 列 表 开 头 使 用 的 字 符 。 如 果 文 本 本 身 出 现 了 默 认 字 符 , 则 替 换 该
字 符 会 很 有 用 ( 参 见 第 202 页 上 的 “ 文 本 流 的 内 嵌 选 项 列 表 ”)。 可 使 用
关 键 字 none 完 全 停 用 搜 索 选 项 列 表 的 操 作 。 默 认 值 :U+003C ()
textlen
整 型 或
关 键 字
( 使 用 不 兼 容 Unicode 的 字 体 的 文 本 或 者 使 用 不 识 别 Unicode 语 言 且
fixedtextformat=false、 textformat=utf16xx 的 文 本 片 段 要 求 此 选 项 ) 字 节
数 或 ( 在 识 别 Unicode 的 语 言 中 ) 下 一 内 嵌 选 项 列 表 之 前 的 字 符 数 ( 另 请
参 见 第 202 页 上 的 “ 文 本 流 的 内 嵌 选 项 列 表 ”)。 字 符 数 在 解 析 字 符 引 用 之
前 计 算 。 例 如 :&#x2460;。 默 认 值 :0
8.3 文 本 函 数 203

表 8.24 PDF_create_textflow( ) 的 optlist 参 数 及 文 本 中 的 内 嵌 选 项 列 表 的 选 项 ( 续 )
选 项 类 型 说 明
文 本 语 义 的 选 项 :
charmapping 1
hyphenchar 1
列 出 两 个 单
字 符 对 或 一
个 字 符 和 一
个 整 数
单 字 符 或
关 键 字
用 一 个 或 多 个 另 一 字 符 的 实 例 替 代 具 体 字 符 。 选 项 列 表 包 含 一 对 或 多 对 单
字 符 。 每 对 中 的 第 一 个 字 符 将 由 第 二 个 字 符 替 代 。 每 对 中 的 第 二 个 元 素 可
以 是 包 含 一 个 单 字 符 和 一 个 计 数 的 选 项 列 表 , 而 非 一 一 对 应 :
count > 0 此 计 数 指 示 字 符 替 代 将 重 复 的 次 数 。
count < 0 多 个 字 符 示 例 的 序 列 将 缩 减 到 指 定 数 字 的 绝 对 值 。
count = 0 将 删 除 字 符 。
在 换 行 符 处 替 代 自 动 连 字 符 的 字 符 。 值 0 和 关 键 字 none 将 完 全 禁 用 连 字 符 。
默 认 值 : 如 果 自 动 连 字 符 (U+00AD) 存 在 于 字 体 中 , 默 认 值 为 U+00AD ; 否
则 , 为 U+002D ( 连 字 符 减 号 )。
tabalignchar 1 单 字 符 将 在 此 对 齐 小 数 制 表 符 的 字 符 。 默 认 值 :U+002E (.)
控 制 文 本 版 面 的 选 项 :
alignment 关 键 字 指 定 段 落 中 各 行 的 格 式 ( 默 认 值 :left):
left 左 对 齐 , 自 leftindent 处 开 始
center 在 leftindent 和 rightindent 之 间 居 中
right 右 对 齐 , 至 rightindent 处 止
justify 左 右 对 齐
avoidemptybegin 布 尔 型 如 果 为 true, 将 删 除 fitbox 开 头 的 空 行 。 默 认 值 :false
fixedleading 布 尔 型 如 果 为 true, 将 使 用 每 行 中 发 现 的 第 一 个 行 距 值 。 否 则 , 将 使 用 该 行 中 最
大 的 行 距 值 。 默 认 值 :false
hortabsize 1 浮 点 型 或
百 分 比
水 平 制 表 符 的 宽 度 2 。 具 体 解 释 取 决 于 hortabmethod 选 项 。 默 认 值 :7.5%
hortabmethod 1
关 键 字 文 本 中 水 平 制 表 符 的 处 理 方 式 。 如 果 计 算 的 位 置 在 当 前 文 本 位 置 的 左 侧 ,
将 忽 略 制 表 符 ( 默 认 值 :relative):
relative 位 置 将 向 前 移 动 hortabsize 中 指 定 的 量 。
typewriter 位 置 将 向 前 移 动 hortabsize 的 下 一 个 倍 数 值 。
ruler 位 置 将 向 前 移 动 至 ruler 选 项 中 的 第 n 个 制 表 符 值 ; 其 中 , n 等
于 迄 今 为 止 、 行 内 发 现 的 制 表 符 数 量 。 如 果 n 大 于 制 表 符 位 置 的
数 量 , 将 应 用 relative 方 法 。
lastalignment 关 键 字 段 落 中 最 后 一 行 的 格 式 化 处 理 。 支 持 alignment 选 项 的 所 有 关 键 字 , 以 及 下
列 关 键 字 ( 默 认 值 :auto):
auto 除 非 为 justify, 否 则 使 用 alignment 选 项 的 值 。 如 果 为 justify,
将 使 用 left。
leading
浮 点 型 或
百 分 比
相 邻 文 本 基 线 间 的 距 离 3 。 实 际 值 将 按 以 下 方 式 确 定 : 如 果 行 的 开 头 有 选 项
列 表 , 将 根 据 最 后 一 个 相 关 选 项 (font、 fontsize、 leading 等 ) 确 定 行 距 。
如 果 同 一 行 内 还 有 其 他 选 项 列 表 , 只 有 当 fixedleading=false 时 , 才 考 虑 其
任 何 与 行 距 相 关 的 选 项 。 如 果 行 内 没 有 选 项 列 表 , 将 考 虑 前 一 个 行 距 值 。
默 认 值 :100%
minlinecount 整 型 fitbox 中 最 后 一 个 段 落 的 最 小 行 数 。 如 果 行 数 小 于 该 值 , 将 置 于 下 一
fitbox。 值 2 可 用 来 防 止 在 fitbox 结 尾 处 出 现 单 行 (» 孤 行 «)。 默 认 值 :1
parindent 浮 点 型 或
百 分 比
段 落 第 一 行 的 左 缩 进
。 将 向 leftindent 添 加 此 值 。 在 行 中 指 定 此 选 项 就 相
当 于 使 用 制 表 符 。 默 认 值 :0
rightindent
leftindent
浮 点 型 或
百 分 比
所 有 文 本 行 的 右 缩 进 或 左 缩 进
。 如 果 在 行 内 指 定 了 leftindent, 且 确 定 的
位 置 在 当 前 文 本 位 置 左 侧 , 将 对 当 前 行 忽 略 此 选 项 。 默 认 值 :0
ruler 1
浮 点 值 或
百 分 比 列 表
hortabmethod=ruler 时 的 绝 对 制 表 符 位 置 列 表
。 此 列 表 最 多 可 包 含 32 个
按 升 序 排 序 的 非 负 值 条 目 。 默 认 值 :hortabsize 的 整 数 倍 数 值
204 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.24 PDF_create_textflow( ) 的 optlist 参 数 及 文 本 中 的 内 嵌 选 项 列 表 的 选 项 ( 续 )
选 项 类 型 说 明
tabalignment 1 关 键 字 列 表 制 表 位 的 对 齐 方 式 。 列 表 中 的 每 个 条 目 均 可 定 义 ruler 选 项 中 对 应 条 目 的 对
齐 方 式 ( 默 认 值 :left)
center 文 本 将 在 制 表 符 位 置 居 中 。
decimal 将 在 制 表 符 位 置 左 对 齐 第 一 个 tabalignchar 的 实 例 。 如 果 没 有 找
到 tabalignchar, 将 使 用 右 对 齐 。
left 文 本 将 在 制 表 符 位 置 左 对 齐 。
right 文 本 将 在 制 表 符 位 置 右 对 齐 。
控 制 换 行 算 法 的 选 项 :
adjustmethod 关 键 字 如 果 根 据 minspacing 和 maxspacing 选 项 指 定 的 限 制 压 缩 或 扩 展 两 个 字 之
间 的 距 离 后 , 文 本 部 分 不 能 置 于 一 行 中 , 则 使 用 此 选 项 调 整 该 行 。
默 认 值 :auto
auto 依 次 应 用 下 列 方 法 :shrink、 spread、 nofit 和 split。
clip 与 nofit 相 同 ; 但 是 , 会 剪 裁 fitbox 右 边 缘 处 较 长 的 部 分
( 考 虑 rightindent 选 项 )。
nofit 最 后 一 个 词 将 移 至 下 一 行 ; 条 件 是 , 剩 余 ( 较 短 ) 行 不 短 于
nofitlimit 选 项 中 指 定 的 百 分 比 。 即 使 经 过 对 齐 , 段 落 仍 可 能 略
显 不 齐 。
shrink 如 果 某 个 字 不 能 置 于 行 中 , 将 根 据 shrinklimit 压 缩 文 本 。 如 果 仍
无 法 置 于 行 中 , 将 应 用 nofit 方 法 。
split 最 后 一 个 字 不 移 至 下 一 行 , 但 将 强 制 使 用 连 字 符 连 接 。 对 于 文 本
字 体 , 将 插 入 连 字 符 ; 而 符 号 字 体 , 则 不 插 入 。
spread 最 后 一 个 字 将 移 至 下 一 行 , 剩 余 ( 较 短 ) 行 将 进 行 对 齐 , 根 据
spreadlimit 增 加 该 字 内 各 字 符 间 的 距 离 。 如 果 仍 无 法 实 现 对 齐 ,
将 应 用 nofit 方 法 。
avoidbreak 1 布 尔 型 如 果 为 true, 将 尝 试 避 免 任 何 换 行 符 , 直 至 avoidbreak 重 设 为 false 为 止 。
默 认 值 :false
maxspacing 1
minspacing 1 浮 点 型 或
百 分 比
两 个 字 之 间 的 最 大 或 最 小 距 离 ( 可 使 用 用 户 坐 标 , 或 空 格 字 符 宽 度 的 百 分
比 )。 计 算 的 字 间 距 将 受 提 供 的 值 限 制 ( 但 仍 将 添 加 wordspacing 选 项 )。
默 认 值 :minspacing=50%, maxspacing=500%
nofitlimit 浮 点 型 或 使 用 nofit 方 法 的 行 的 长 度 下 限
。 默 认 值 :75%
百 分 比
shrinklimit 百 分 比 使 用 shrink 方 法 时 的 文 本 压 缩 下 限 ; 计 算 的 收 缩 因 子 将 受 提 供 的 值 限 制 ,
但 将 乘 以 horizscaling 选 项 的 值 。 默 认 值 :85%
spreadlimit 1 浮 点 型 或
百 分 比
spread 方 法 中 , 两 个 字 符 之 间 的 距 离 上 限
; 计 算 的 值 将 与 charspacing 选
项 的 值 相 加 。 默 认 值 :0
用 作 命 令 的 选 项 :
comment 字 符 串 将 被 忽 略 的 任 意 文 本 , 对 注 释 选 项 列 表 或 宏 很 有 用
mark 整 型 作 为 标 记 , 在 内 部 存 储 提 供 的 值 。 稍 后 , 可 使 用 PDF_info_textflow( ) 调 用
最 近 一 次 存 储 的 标 记 。 这 可 能 对 确 定 文 本 的 哪 些 部 分 已 置 于 页 面 很 有 用 。
nextline
布 尔 型 强 制 生 成 新 行 或 新 段 落 ; 即 使 使 用 不 兼 容 Unicode 的 字 体 , 也 是 如 此 。
nextparagraph
resetfont 布 尔 型 将 font 和 fontsize 选 项 重 设 为 它 们 以 前 的 值 。 这 可 能 对 插 入 操 作 之 后 重 设
字 体 很 有 用 , 例 如 斜 体 文 本 。 font 选 项 优 先 于 此 选 项 。 只 有 在 第 二 次 设 置
任 何 字 体 相 关 参 数 后 , 才 能 使 用 此 命 令 ; 否 则 , 此 命 令 将 被 忽 略 。
return 字 符 串 退 出 PDF_create_textflow( ), 并 返 回 提 供 的 字 符 串 。 字 符 串 不 能 用 下 划 线 _
字 符 开 头 。
space
浮 点 型 或
百 分 比
文 本 位 置 将 向 前 移 动 提 供 的 值
3 。 这 同 样 适 用 于 不 兼 容 Unicode 的 字 体 。
1. 此 选 项 不 影 响 使 用 根 据 第 89 页 上 的 第 4.5.6 节 “Unicode 兼 容 的 字 体 ”、 不 兼 容 Unicode 的 字 体 的 文 本 。
2. 使 用 用 户 坐 标 , 或 fitbox 宽 度 的 百 分 比 。
3. 使 用 用 户 坐 标 , 或 字 体 大 小 的 百 分 比 。
8.3 文 本 函 数 205

这 些 宏 在 选 项 列 表 中 的 使 用 方 式 如 下 :
Chapter 1
This chapter talks about...
宏 的 定 义 和 使 用 应 遵 守 下 列 规 则 :
> 宏 的 嵌 套 可 达 到 任 意 深 度 ( 宏 定 义 可 以 包 含 对 其 他 宏 的 调 用 )
> 宏 不 能 直 接 在 定 义 他 们 的 选 项 列 表 中 使 用 。 但 是 , 可 以 在 定 义 宏 的 选 项 列 表 结 束 之 后 ,
立 即 开 始 使 用 该 宏 的 新 选 项 列 表 。
> 宏 名 称 不 区 分 大 小 写 。
> 未 定 义 的 宏 将 导 致 异 常 。
> 可 随 时 重 新 定 义 宏 。
表 8.25 PDF_fit_textflow( ) 的 选 项 列 表 宏 定 义 和 宏 调 用
选 项 类 型 说 明
macro 成 对 的 列 表 每 一 对 都 分 别 描 述 一 个 宏 的 名 称 和 定 义 ; 具 体 如 下 :
name ( 字 符 串 ) 稍 后 可 用 于 宏 调 用 的 宏 名 称 。 稍 后 可 重 新 定 义 已 经 定 义
的 宏 。 将 忽 略 特 殊 名 称 注 释 。
suboptlist 调 用 宏 时 , 将 实 际 替 代 宏 名 称 的 选 项 列 表 。 将 忽 略 前 导 空 白 和 尾 随
空 白 。
&name – 将 扩 展 具 有 指 定 名 称 的 宏 , 并 用 宏 的 内 容 替 代 宏 名 称 ( 包 括 & 字 符 ), 即 : 已
经 为 宏 定 义 的 子 选 项 列 表 ( 两 端 没 有 大 括 号 )。 宏 名 称 以 空 白 、 {、 }、 = 或 &
终 结 。 因 此 , 不 能 将 这 些 字 符 用 作 宏 名 称 的 一 部 分 。
将 扩 展 嵌 套 的 宏 , 且 没 有 任 何 嵌 套 限 制 。 同 时 , 还 将 扩 展 字 符 串 选 项 中 的 宏 。
宏 替 代 必 须 生 成 有 效 的 选 项 列 表 。
comment 字 符 串 将 被 忽 略 的 任 意 文 本 , 对 宏 注 释 很 有 用
8.4 图 形 函 数
8.4.1 图 形 状 态 函 数
在 页 面 开 头 , 所 有 图 形 状 态 参 数 都 将 还 原 为 默 认 值 。 相 关 函 数 说 明 中 记 录 了 这 些 默 认 值 。
第 186 页 上 的 第 8.3 节 “ 文 本 函 数 ” 中 列 出 了 与 文 本 状 态 相 关 的 函 数 。
注 : 路 径 范 围 内 不 能 使 用 任 何 图 形 状 态 函 数 ( 参 见 第 53 页 上 的 第 3.2 节 “ 页 面 说 明 ”)。
C++ Java void setdash(double b, double w)
Perl PHP PDF_setdash(resource p, float b, float w)
C void PDF_setdash(PDF *p, double b, double w)
设 置 当 前 虚 线 样 式 。
b, w 交 替 显 示 的 黑 白 单 位 的 数 量 。 b 和 w 必 须 为 正 值 数 值 。
详 细 说 明 要 生 成 实 线 , 应 设 置 b = w = 0。 在 每 页 的 开 头 , dash 参 数 将 设 为 实 线 。
范 围
页 面 、 图 案 、 模 板 、 字 形
206 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
void setdashpattern(String optlist)
PDF_setdashpattern(resource p, string optlist)
void PDF_setdashpattern(PDF *p, const char *optlist)
设 置 选 项 列 表 定 义 的 虚 线 样 式 。
optlist 根 据 表 8.26 提 供 的 选 项 列 表 。 空 列 表 将 生 成 实 线 。
表 8.26 PDF_setdashpattern( ) 的 选 项
选 项 类 型 描 述
dasharray 浮 点 值 列 表 一 个 由 2 至 8 个 交 替 值 组 成 的 列 表 , 指 示 虚 线 的 长 度 和 描 边 路 径 的 间 隔 ( 使 用
用 户 坐 标 系 统 表 示 )。 数 组 值 必 须 大 于 0。 这 些 值 将 循 环 使 用 , 直 至 整 个 描 边
路 径 完 成 为 止 。
dashphase 浮 点 型 虚 线 样 式 之 间 的 距 离 。 默 认 值 :0
详 细 说 明 在 每 页 的 开 头 , dash 参 数 将 设 为 实 线 。
范 围
页 面 、 图 案 、 模 板 、 字 形
C++ Java
Perl PHP
C
void setflat(double flatness)
PDF_setflat(resource p, float flatness)
void PDF_setflat(PDF *p, double flatness)
设 置 flatness 参 数 。
flatness
近 似 值 。
一 个 正 值 , 描 述 路 径 之 间 的 最 大 距 离 ( 以 设 备 像 素 为 单 位 ) 和 根 据 直 线 段 计 算 的
详 细 说 明 在 每 页 开 头 , flatness 参 数 设 为 默 认 值 1。
范 围
页 面 、 图 案 、 模 板 、 字 形
C++ Java
Perl PHP
C
void setlinejoin(int linejoin)
PDF_setlinejoin(resource p, int linejoin)
void PDF_setlinejoin(PDF *p, int linejoin)
设 置 linejoin 参 数 。
linejoin 指 定 描 边 路 径 拐 角 的 形 状 , 参 见 表 8.27。
详 细 说 明 在 每 页 开 头 , linejoin 参 数 设 为 默 认 值 0。
范 围
页 面 、 图 案 、 模 板 、 字 形
C++ Java
Perl PHP
C
void setlinecap(int linecap)
PDF_setlinecap(resource p, int linecap)
void PDF_setlinecap(PDF *p, int linecap)
设 置 linecap 参 数 。
linecap 对 于 描 边 , 控 制 路 径 端 点 的 形 状 , 参 见 表 8.28。
8.4 图 形 函 数 207

表 8.27 linejoin 参 数 的 值
value 描 述 ( 摘 自 《PDF Reference》) 示 例
0 斜 角 连 接 : 两 个 线 段 的 描 边 外 缘 继 续 延 伸 , 直 至 相 接 为 止 。 当 斜 角 外 延
超 出 斜 角 极 限 时 , 将 由 斜 削 连 接 取 代 。
1 圆 角 连 接 : 以 在 线 段 相 接 的 点 为 圆 心 , 绘 制 直 径 等 于 线 宽 的 圆 弧 , 并 填
充 圆 弧 , 生 成 圆 角 。
2 斜 面 连 接 : 绘 制 两 个 具 有 平 头 端 点 的 路 径 线 段 ( 参 见 有 关 linecap 参 数
的 讨 论 ), 用 三 角 形 填 充 生 成 的 线 段 端 点 以 外 的 切 口 。
详 细 说 明 在 每 页 开 头 , linecap 参 数 设 为 默 认 值 0。
范 围
页 面 、 图 案 、 模 板 、 字 形
表 8.28 linecap 参 数 的 值
value 描 述 ( 摘 自 《PDF Reference》) 示 例
0 平 头 端 点 : 描 边 在 路 径 端 点 处 切 成 方 形 。
1 圆 头 端 点 : 以 端 点 为 圆 心 , 绘 制 直 径 等 于 线 宽 的 半 圆 弧 , 并 填 充 圆 弧 。
2 方 形 突 出 终 端 点 : 描 边 延 伸 出 线 的 端 点 ( 距 离 为 线 宽 的 一 半 ), 并 以 方
形 结 束 。
C++ Java
Perl PHP
C
void setmiterlimit(double miter)
PDF_setmiterlimit(resource p, float miter)
void PDF_setmiterlimit(PDF *p, double miter)
设 置 斜 接 限 制 。
miter 一 个 大 于 或 等 于 1 的 值 , 控 制 斜 接 连 接 生 成 的 尖 端 。
详 细 说 明
如 果 linejoin 参 数 设 为 0( 斜 角 连 接 ), 以 小 角 度 连 接 的 两 个
线 段 将 生 成 很 尖 锐 的 尖 端 。 斜 接 长 度 和 线 宽 的 比 例 超 出 斜 接
限 制 时 , 将 用 垂 直 端 点 替 代 尖 端 ( 即 , 斜 接 连 接 将 改 为 斜 面
连 接 )。 在 每 页 开 头 , 斜 接 限 制 设 为 默 认 值 10。 这 大 约 相 当 于
11.5 度 角 。
Miter
length
Line width
范 围
页 面 、 图 案 、 模 板 、 字 形
C++ Java
Perl PHP
void setlinewidth(double width)
PDF_setlinewidth(resource p, float width)
C
void PDF_setlinewidth(PDF *p, double width)
设 置 当 前 线 宽 。
width 以 当 前 用 户 坐 标 系 统 的 单 位 设 置 的 线 宽 。
详 细 说 明 在 每 页 开 头 , width 参 数 设 为 默 认 值 1。
208 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

范 围
页 面 、 图 案 、 模 板 、 字 形
C++ Java void initgraphics( )
Perl PHP PDF_initgraphics(resource p)
C void PDF_initgraphics(PDF *p)
将 所 有 颜 色 和 图 形 状 态 参 数 重 设 为 他 们 的 默 认 值 。
详 细 说 明
范 围
color、linewidth、linecap、linejoin、miterlimit、dash 参 数 及 当 前 转 换 矩 阵 ( 但 不 包 括
文 本 状 态 参 数 ) 都 重 设 为 他 们 各 自 的 默 认 值 。 不 影 响 当 前 剪 切 路 径 。
在 程 序 流 不 允 许 方 便 地 使 用 PDF_save()/PDF_restore() 时 , 此 函 数 可 能 会 很 有 用 。
页 面 、 图 案 、 模 板 、 字 形
8.4.2 保 存 和 恢 复 图 形 状 态
C++ Java void save( )
Perl PHP PDF_save(resource p)
C void PDF_save(PDF *p)
将 当 前 图 形 状 态 保 存 到 一 个 堆 栈 。
详 细 说 明
图 形 状 态 包 含 控 制 各 种 类 型 的 图 形 对 象 的 参 数 。 PDF 不 要 求 保 存 图 形 状 态 ; 只 有 应 用 程 序
希 望 稍 后 返 回 某 些 特 定 图 形 状 态 ( 例 如 , 自 定 义 坐 标 系 统 ), 而 又 不 想 再 次 显 式 设 置 所 有 相
关 参 数 时 , 才 需 要 保 存 图 形 状 态 。 下 列 项 目 受 save/restore 控 制 :
> 已 经 使 用 相 应 函 数 设 置 的 图 形 参 数 : 剪 切 路 径 、 坐 标 系 统 、 当 前 点 、 平 滑 度 (flatness)、
线 条 端 点 样 式 、 虚 线 样 式 、 线 条 连 接 样 式 (line join style)、 线 宽 、 斜 接 限 制 ;
> 颜 色 参 数 : 填 充 色 和 描 边 色 ;
> 已 经 使 用 PDF_set_gstate( ) 和 显 式 图 形 状 态 设 置 的 图 形 参 数 ( 参 见 第 211 页 上 的 第 8.4.4
节 “ 显 式 图 形 状 态 ”);
> 文 本 位 置 及 大 多 数 与 文 本 相 关 的 参 数 ; 参 见 以 下 列 表 ;
> 某 些 PDFlib 参 数 ; 参 见 以 下 列 表 。
PDF_save( ) 和 PDF_restore( ) 可 以 嵌 套 成 对 。 尽 管 PDF 规 范 没 有 限 制 save/restore 对 的 嵌 套
深 度 , 但 应 用 程 序 必 须 保 持 嵌 套 深 度 小 于 26, 以 避 免 由 PDF 浏 览 器 所 生 成 的 带 有 限 制 的
PostScript 输 出 导 致 的 打 印 问 题 , 并 允 许 PDFlib 内 部 要 求 的 额 外 save 级 别 。
范 围 页 面 、 图 案 、 模 板 、 字 形 ; 必 须 与 对 应 的 PDF_restore( ) 调 用 成 对 使 用 。 在 每 个 页 面 、 图 案 、
模 板 和 字 形 描 述 中 , PDF_save( ) 和 PDF_restore( ) 调 用 必 须 成 对 出 现 。
参 数
下 列 参 数 受 save/restore 控 制 :charspacing、 wordspacing、 horizscaling、 italicangle、
leading、 font、 fontsize、 textrendering、 textrise ;
下 列 参 数 不 受 save/restore 控 制 :fillrule、 kerning、 underline、 overline、 strikeout。
C++ Java void restore( )
Perl PHP PDF_restore(resource p)
C void PDF_restore(PDF *p)
从 堆 栈 中 恢 复 最 近 一 次 保 存 的 图 形 状 态 。
详 细 说 明 必 须 是 已 经 在 同 一 页 面 、 图 案 或 模 板 上 保 存 了 的 相 应 的 图 形 状 态 。
8.4 图 形 函 数 209

范 围
页 面 、 图 案 、 模 板 、 字 形 ; 必 须 与 对 应 的 PDF_save( ) 调 用 成 对 使 用 。 在 每 个 页 面 、 图 案 、 模
板 和 字 形 描 述 中 , PDF_save( ) 和 PDF_restore( ) 调 用 必 须 成 对 出 现 。
8.4.3 坐 标 系 统 转 换 函 数
所 有 转 换 函 数 (PDF_translate( )、PDF_scale( )、PDF_rotate( )、PDF_skew( )、PDF_concat( )、
PDF_setmatrix( ) 和 PDF_initgraphics( )) 都 可 更 改 绘 制 后 续 对 象 使 用 的 坐 标 系 统 。 他 们 不 会
对 页 面 上 的 现 有 对 象 产 生 任 何 影 响 。
C++ Java
Perl PHP
C
void translate(double tx, double ty)
PDF_translate(resource p, float tx, float ty)
void PDF_translate(PDF *p, double tx, double ty)
转 换 坐 标 系 的 原 点 。
tx, ty 坐 标 系 统 的 新 原 点 为 旧 坐 标 系 统 中 的 (tx, ty) 点 。
范 围
页 面 、 图 案 、 模 板 、 字 形
C++ Java
Perl PHP
C
void scale(double sx, double sy)
PDF_scale(resource p, float sx, float sy)
void PDF_scale(PDF *p, double sx, double sy)
缩 放 坐 标 系 统 。
sx, sy x 和 y 方 向 上 的 缩 放 因 子 。
详 细 说 明
范 围
此 函 数 可 按 sx 和 sy 值 缩 放 坐 标 系 统 。 通 过 使 用 负 值 缩 放 因 子 , 还 可 用 此 函 数 实 现 对 称 ( 镜
像 ) 效 果 。 在 新 坐 标 系 统 中 ,x 方 向 上 的 一 个 单 位 等 于 旧 坐 标 系 统 中 x 方 向 上 的 sx 个 单 位 ,
y 坐 标 同 样 如 此 。
页 面 、 图 案 、 模 板 、 字 形
C++ Java
Perl PHP
C
void rotate(double phi)
PDF_rotate(resource p, float phi)
void PDF_rotate(PDF *p, double phi)
旋 转 坐 标 系 统 。
phi 旋 转 角 度 的 度 数 。
详 细 说 明
范 围
自 当 前 坐 标 系 统 的 正 x 轴 起 , 按 逆 时 针 方 向 测 量 角 度 。 将 旧 坐 标 轴 旋 转 phi 指 示 的 度 数 , 计
算 新 坐 标 轴 。
页 面 、 图 案 、 模 板 、 字 形
210 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
void skew(double alpha, double beta)
PDF_skew(resource p, float alpha, float beta)
void PDF_skew(PDF *p, double alpha, double beta)
歪 斜 坐 标 系 统 。
alpha, beta x 和 y 方 向 上 的 歪 斜 角 度 数 。
详 细 说 明 歪 斜 ( 或 剪 切 ) 会 在 x 和 y 方 向 上 按 指 定 的 角 度 扭 曲 坐 标 系 统 。 自 当 前 坐 标 系 统 的 正 x 轴 起 ,
按 逆 时 针 方 向 测 量 alpha ; 自 正 y 坐 标 起 , 按 顺 时 针 方 向 测 量 beta。 两 个 角 都 必 须 在 -360˚
< alpha, beta < 360˚ 范 围 内 , 且 必 须 不 同 于 -270˚、 -90˚、 90˚ 和 270˚。
范 围
页 面 、 图 案 、 模 板 、 字 形
C++ Java void concat(double a, double b, double c, double d, double e, double f)
Perl PHP PDF_concat(resource p, float a, float b, float c, float d, float e, float f)
C void PDF_concat(PDF *p, double a, double b, double c, double d, double e, double f)
将 一 个 矩 阵 连 接 到 当 前 转 换 矩 阵 。
a, b, c, d, e, f 转 换 矩 阵 的 元 素 。 这 六 个 值 以 PostScript 和 PDF 中 相 同 的 方 式 构 成 坐 标 系 统
( 参 见 相 关 参 考 )。 为 了 避 免 转 换 退 化 , a*d 不 能 等 于 b*c。
详 细 说 明 此 函 数 可 将 矩 阵 连 接 到 文 本 和 图 形 的 当 前 转 换 矩 阵 (CTM)。 它 允 许 大 多 数 常 规 的 转 换 形 式 。
使 用 此 函 数 需 对 转 换 矩 阵 很 熟 悉 , 否 则 建 议 另 用 PDF_translate( )、PDF_scale( ), PDF_rotate( )
和 PDF_skew( ) 函 数 。 在 每 页 开 头 , CTM 重 设 为 单 位 矩 阵 [1,0,0,1,0,0]。
范 围
页 面 、 图 案 、 模 板 、 字 形
C++ Java void setmatrix(double a, double b, double c, double d, double e, double f)
Perl PHP PDF_setmatrix(resource p, float a, float b, float c, float d, float e, float f)
C void PDF_setmatrix(PDF *p, double a, double b, double c, double d, double e, double f)
明 确 地 设 置 当 前 转 换 矩 阵 。
a, b, c, d, e, f 参 见 PDF_concat( )。
详 细 说 明 此 函 数 类 似 于 PDF_concat( )。 但 是 , 它 会 废 弃 当 前 转 换 矩 阵 , 并 用 新 的 矩 阵 完 全 替 代 旧 矩 阵 。
范 围
页 面 、 图 案 、 模 板 、 字 形
8.4.4 显 式 图 形 状 态
C++ Java
Perl PHP
C
int create_gstate(String optlist)
int PDF_create_gstate(resource p, string optlist)
int PDF_create_gstate(PDF *p, const char *optlist)
根 据 各 种 选 项 创 建 图 形 状 态 对 象 。
optlist 选 项 列 表 , 根 据 表 8.29 包 含 图 形 状 态 的 选 项 。
返 回 值 gstate 句 柄 ; 在 关 闭 的 文 档 范 围 中 , 可 在 后 续 PDF_set_gstate( ) 调 用 中 使 用 此 句 柄 。
8.4 图 形 函 数 211

详 细 说 明
范 围
此 选 项 列 表 可 以 包 含 任 何 数 量 的 图 形 状 态 参 数 。 并 非 所 有 参 数 都 可 用 于 所 有 PDF 版 本 。 表
中 列 出 了 要 求 的 最 低 PDF 版 本 。
文 档 、 页 面 、 图 案 、 模 板 、 字 形
PDF/X 除 非 具 有 值 1, 否 则 必 须 避 免 使 用 opacityfill 和 opacitystroke 选 项 。
表 8.29 PDF_create_gstate( ) 的 选 项
关 键 字 类 型 说 明 和 可 能 的 值
alphaisshape 布 尔 型 (PDF 1.4) 此 值 为 真 (true) 则 Alpha 的 数 据 描 述 形 状 , 若 为 假 (false) 则 描
述 不 透 明 度 。 默 认 值 :false
blendmode 关 键 字 列 表 (PDF 1.4) 混 合 模 式 的 名 称 。 可 指 定 多 个 混 合 模 式 。 可 能 的 值 :None、
Normal、Multiply、Screen、Overlay、Darken、Lighten、ColorDodge、
ColorBurn、 HardLight、 SoftLight、 Difference、 Exclusion、 Hue、
Saturation、 Color、 Luminosity。 默 认 值 :None
flatness 浮 点 型 路 径 与 其 近 似 值 之 间 的 最 大 距 离 ( 参 见 PDF_setflat( )), 必 须 > 0
linecap
linejoin
整 型 或 关 键
字
整 型 或 关 键
字
路 径 结 尾 处 的 形 状 ( 参 见 PDF_setlinecap( )), 必 须 为 0、 1 或 2
路 径 拐 角 处 的 形 状 ( 参 见 PDF_setlinejoin( )), 必 须 为 0、 1 或 2
linewidth 浮 点 型 线 宽 ( 参 见 PDF_setlinewidth( )), 必 须 > 0
miterlimit 浮 点 型 控 制 斜 接 连 接 生 成 的 尖 角 , 必 须 >= 1 ( 参 见 PDF_setmiterlimit( ))
opacityfill 浮 点 型 (PDF 1.4) 用 于 填 充 操 作 的 alpha 常 数 , 必 须 >= 0 并 且 = 0 并 且 = 0 并 且

8.4.5 路 径 构 建
表 8.30 列 出 了 本 节 的 相 关 参 数 及 其 相 应 值 。
表 8.30 路 径 段 函 数 的 参 数 和 值 ( 参 见 第 181 页 上 的 第 8.2.3 节 “ 参 数 处 理 ”)
函 数 关 键 字 说 明
get_value currentx
currenty
分 别 指 示 当 前 点 的 x 或 y 坐 标 ( 以 当 前 坐 标 系 统 的 单 位 表 示 )。 范 围 : 页 面 、
图 案 、 模 板 、 路 径
get_value ctm_a
ctm_b
ctm_c
ctm_d
ctm_e
ctm_f
矢 量 图 形 的 当 前 转 换 矩 阵 (CTM) 的 要 素 。 范 围 : 页 面 、 图 案 、 模 板 、 路 径
注 : 使 用 本 节 介 绍 的 函 数 之 后 , 一 定 要 调 用 第 216 页 上 的 第 8.4.6 节 “ 路 径 绘 制 和 剪 切 ” 中 的 一
个 函 数 ; 否 则 , 构 建 的 路 径 不 会 有 任 何 效 果 , 而 且 后 续 操 作 也 可 能 会 引 发 PDFlib 异 常 。
C++ Java void moveto(double x, double y)
Perl PHP PDF_moveto(resource p, float x, float y)
C void PDF_moveto(PDF *p, double x, double y)
设 置 图 形 输 出 的 当 前 点 。
x, y 新 当 前 点 的 坐 标 。
详 细 说 明 在 每 页 开 头 , 当 前 点 设 为 undefined 的 默 认 值 。 图 形 的 当 前 点 和 当 前 文 本 位 置 将 分 别 维 护 。
范 围 页 面 、 图 案 、 模 板 、 路 径 、 字 形 ; 此 函 数 是 路 径 范 围 的 开 头 。
参 数
currentx, currenty
C++ Java void lineto(double x, double y)
Perl PHP PDF_lineto(resource p, float x, float y)
C void PDF_lineto(PDF *p, double x, double y)
从 当 前 点 至 另 一 点 , 绘 制 一 条 直 线 。
x, y 直 线 第 二 个 端 点 的 坐 标 。
详 细 说 明
范 围
参 数
此 函 数 将 在 当 前 路 径 上 添 加 一 条 自 当 前 点 至 (x, y) 的 直 线 。 使 用 此 函 数 之 前 , 必 须 先 设 置 当
前 点 。 点 (x, y) 将 成 为 新 的 当 前 点 。
绘 制 的 直 线 将 围 绕 » 理 想 « 直 线 居 中 放 置 , 即 : 在 连 接 两 个 端 点 的 直 线 两 侧 分 别 绘 制 线
宽 的 一 半 ( 根 据 linewidth 参 数 的 值 确 定 )。 端 点 处 的 行 为 由 linecap 参 数 的 值 设 置 。
路 径
currentx, currenty
8.4 图 形 函 数 213

C++ Java void curveto(double x1, double y1, double x2, double y2, double x3, double y3)
Perl PHP PDF_curveto(resource p, float x1, float y1, float x2, float y2, float x3, float y3)
C void PDF_curveto(PDF *p, double x1, double y1, double x2, double y2, double x3, double y3)
使 用 另 外 三 个 控 制 点 , 自 当 前 点 起 , 绘 制 Bézier 曲 线 。
x1, y1, x2, y2, x3, y3 三 个 控 制 点 的 坐 标 。
详 细 说 明 将 (x1, y1) 和 (x2, y2) 用 作 控 制 点 , 在 当 前 路 径 上 添 加 一 条 从 当 前 点 至 (x3, y3) 的 Bézier 曲 线 。
使 用 此 函 数 之 前 , 必 须 先 设 置 当 前 点 。 该 曲 线 的 端 点 (x3, y3) 将 成 为 新 的 当 前 点 。
范 围
参 数
路 径
currentx, currenty
C++ Java void circle(double x, double y, double r)
Perl PHP PDF_circle(resource p, float x, float y, float r)
C void PDF_circle(PDF *p, double x, double y, double r)
绘 制 一 个 圆 形 。
x, y 圆 形 原 点 的 坐 标 。
r 圆 形 的 半 径 。
详 细 说 明
此 函 数 作 为 完 全 子 路 径 , 在 当 前 路 径 上 添 加 一 个 圆 形 。 点 (x + r, y) 将 成 为 新 的 当 前 点 。 生 成
的 形 状 将 为 使 用 用 户 坐 标 表 示 的 圆 形 。 如 果 坐 标 系 统 在 x 和 y 方 向 上 的 缩 放 比 例 不 同 , 生 成
的 曲 线 将 为 椭 圆 形 。
范 围 页 面 、 图 案 、 模 板 、 路 径 、 字 形 ; 此 函 数 是 路 径 范 围 的 开 头 。
参 数
currentx, currenty
C++ Java
Perl PHP
C
void arc(double x, double y, double r, double alpha, double beta)
PDF_arc(resource p, float x, float y, float r, float alpha, float beta)
void PDF_arc(PDF *p, double x, double y, double r, double alpha, double beta)
绘 制 一 个 逆 时 针 圆 弧 线 段 。
x, y 圆 弧 线 段 中 心 点 的 坐 标 。
r 圆 弧 线 段 的 半 径 。 r 必 须 为 非 负 值 。
alpha, beta 圆 弧 线 段 开 头 和 结 尾 角 度 的 度 数 。
详 细 说 明 此 函 数 将 在 当 前 路 径 上 , 按 逆 时 针 方 向 添 加 一 条 圆 弧 线 段 , 自 alpha 角 度 延 伸 至 beta 角 度 。
对 于 PDF_arc( ) 和 PDF_arcn( ), 都 自 当 前 坐 标 系 统 的 正 x 轴 起 , 按 逆 时 针 方 向 测 量 角 度 。 如
果 存 在 当 前 点 , 将 自 当 前 点 起 至 圆 弧 的 起 始 点 止 , 绘 制 另 一 条 直 线 。 该 圆 弧 的 端 点 将 成 为 新
的 当 前 点 。
圆 弧 线 段 将 为 使 用 用 户 坐 标 表 示 的 圆 形 。 如 果 坐 标 系 统 在 x 和 y 方 向 上 的 缩 放 比 例 不
同 , 生 成 的 曲 线 将 为 椭 圆 形 。
范 围 页 面 、 图 案 、 模 板 、 路 径 、 字 形 ; 此 函 数 是 路 径 范 围 的 开 头 。
参 数
currentx, currenty
214 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
void arcn(double x, double y, double r, double alpha, double beta)
PDF_arcn(resource p, float x, float y, float r, float alpha, float beta)
void PDF_arcn(PDF *p, double x, double y, double r, double alpha, double beta)
绘 制 一 个 顺 时 针 圆 弧 线 段 。
详 细 说 明
除 绘 制 方 向 外 , 此 函 数 的 行 为 与 PDF_arc( ) 完 全 相 同 。 尤 其 是 , 仍 将 自 正 x 轴 起 , 按 逆 时 针
方 向 测 量 角 度 。
8.4 图 形 函 数 215

C++ Java
Perl PHP
C
void rect(double x, double y, double width, double height)
PDF_rect(resource p, float x, float y, float width, float height)
void PDF_rect(PDF *p, double x, double y, double width, double height)
绘 制 一 个 矩 形 。
x, y 矩 形 左 下 角 的 坐 标 。
width, height 矩 形 的 大 小 。
详 细 说 明 此 函 数 作 为 完 全 子 路 径 , 在 当 前 路 径 上 添 加 一 个 矩 形 。 使 用 此 函 数 前 , 不 要 求 设 置 当 前 点 。
点 (x, y) 将 成 为 新 的 当 前 点 。 绘 制 的 直 线 段 将 围 绕 » 理 想 « 直 线 居 中 放 置 , 即 : 在 连 接 各 个
端 点 的 直 线 两 侧 分 别 绘 制 线 宽 的 一 半 ( 根 据 linewidth 参 数 的 值 确 定 )。
范 围 页 面 、 图 案 、 模 板 、 路 径 、 字 形 ; 此 函 数 是 路 径 范 围 的 开 头 。
参 数
currentx, currenty
C++ Java void closepath( )
Perl PHP PDF_closepath(resource p)
C void PDF_closepath(PDF *p)
关 闭 当 前 路 径 。
详 细 说 明 此 函 数 将 关 闭 当 前 子 路 径 , 即 : 添 加 一 条 自 当 前 点 起 、 至 子 路 径 起 始 点 止 的 直 线 。
范 围
参 数
路 径
currentx, currenty
8.4.6 路 径 绘 制 和 剪 切
表 8.31 列 出 了 本 节 的 相 关 参 数 及 相 应 的 值 。
表 8.31 路 径 绘 制 和 剪 切 函 数 的 参 数 和 值
函 数 关 键 字 说 明
set_parameter fillrule 将 当 前 填 充 规 则 设 为 winding 或 evenodd。 PDF 查 看 程 序 将 使 用 此 填 充 规 则 确
定 形 状 的 内 部 , 以 进 行 填 充 或 剪 切 。 因 为 对 于 简 单 形 状 而 言 , 这 两 种 算 法 将 产
生 相 同 的 结 果 , 所 以 大 多 数 应 用 程 序 都 无 需 更 改 填 充 规 则 。 在 每 页 开 头 , 填 充
规 则 将 重 设 为 默 认 的 winding。 范 围 : 页 面 、 图 案 、 模 板 、 字 形 。
注 : 本 节 内 的 大 多 数 函 数 都 将 清 除 路 径 , 而 不 定 义 当 前 点 。 因 此 , 调 用 其 中 一 个 函 数 之 后 , 后 续
的 绘 制 操 作 都 必 须 明 确 设 置 当 前 点 ( 例 如 , 使 用 PDF_moveto( ))。
C++ Java void stroke( )
Perl PHP PDF_stroke(resource p)
C void PDF_stroke(PDF *p)
使 用 当 前 线 宽 和 当 前 描 边 色 描 边 路 径 , 并 清 除 路 径 。
范 围 路 径 ; 此 函 数 终 结 路 径 范 围 。
216 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java void closepath_stroke( )
Perl PHP PDF_closepath_stroke(resource p)
C void PDF_closepath_stroke(PDF *p)
关 闭 路 径 , 并 描 边 。
详 细 说 明
此 函 数 关 闭 当 前 子 路 径 ( 添 加 一 条 自 当 前 点 起 、 至 路 径 起 点 止 的 直 线 段 ) 并 使 用 当 前 线 宽
和 当 前 描 边 色 描 边 整 个 当 前 路 径 。
范 围 路 径 ; 此 函 数 终 结 路 径 范 围 。
C++ Java void fill( )
Perl PHP PDF_fill(resource p)
C void PDF_fill(PDF *p)
使 用 当 前 填 充 色 填 充 路 径 的 内 部 。
详 细 说 明
此 函 数 使 用 当 前 填 充 色 填 充 当 前 路 径 的 内 部 。 路 径 的 内 部 可 由 其 中 一 种 算 法 确 定 ( 参 见
fillrule 参 数 )。 填 充 之 前 , 会 自 动 关 闭 仍 开 放 的 路 径 。
范 围 路 径 ; 此 函 数 终 结 路 径 范 围 。
参 数
fillrule
C++ Java void fill_stroke( )
Perl PHP PDF_fill_stroke(resource p)
C void PDF_fill_stroke(PDF *p)
使 用 当 前 填 充 色 和 描 边 色 , 填 充 并 描 边 路 径 。
范 围 路 径 ; 此 函 数 终 结 路 径 范 围 。
参 数
fillrule
C++ Java void closepath_fill_stroke( )
Perl PHP PDF_closepath_fill_stroke(resource p)
C void PDF_closepath_fill_stroke(PDF *p)
关 闭 路 径 , 填 充 并 描 边 路 径 。
详 细 说 明
此 函 数 关 闭 当 前 子 路 径 ( 添 加 一 条 自 当 前 点 起 、 至 路 径 起 点 止 的 直 线 段 ), 然 后 填 充 并 描 边
整 个 当 前 路 径 。
范 围 路 径 ; 此 函 数 终 结 路 径 范 围 。
参 数
fillrule
8.4 图 形 函 数 217

C++ Java void clip( )
Perl PHP PDF_clip(resource p)
C void PDF_clip(PDF *p)
将 当 前 路 径 用 作 剪 切 路 径 并 终 结 路 径 。
详 细 说 明
此 函 数 将 当 前 路 径 与 当 前 剪 贴 路 径 的 交 叉 部 分 用 作 后 续 操 作 的 剪 切 路 径 。 在 每 页 开 头 , 剪
切 路 径 设 为 页 面 大 小 的 默 认 值 。 剪 切 路 径 受 PDF_save()/PDF_restore() 影 响 。 只 能 通 过
PDF_save( )/PDF_restore( ) 的 方 式 放 大 剪 切 路 径 。
范 围 路 径 ; 此 函 数 终 结 路 径 范 围 。
C++ Java void endpath( )
Perl PHP PDF_endpath(resource p)
C void PDF_endpath(PDF *p)
结 束 当 前 路 径 , 既 不 填 充 也 不 描 边 。
详 细 说 明 此 函 数 不 会 在 页 面 上 显 式 任 何 效 果 。 它 会 在 页 面 上 生 成 不 可 见 的 路 径 。
范 围 路 径 ; 此 函 数 终 结 路 径 范 围 。
8.4.7 图 层 参 数
C++ Java
Perl PHP
C
int define_layer(String name, String optlist)
int PDF_define_layer(resource p, string name, string optlist)
int PDF_define_layer(PDF *p, const char *name, int len, const char *optlist)
创 建 新 的 图 层 定 义 ( 要 求 PDF 1.5)。
name ( 超 文 本 字 符 串 ) 图 层 的 名 称 。
len ( 仅 用 于 C 语 言 绑 定 )UCS-2 字 符 串 的 name 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0, 则
必 须 提 供 以 null 终 结 的 字 符 串 。
optlist 选 项 列 表 , 根 据 表 8.32 指 定 图 层 设 置 。
返 回 值
图 层 句 柄 , 可 用 于 PDF_begin_layer( ) 和 PDF_set_layer_dependency( ) 调 用 , 直 至 关 闭 文 档 范
围 结 束 为 止 。
详 细 说 明 如 果 定 义 了 图 层 , 但 未 在 文 档 中 使 用 , PDFlib 将 发 出 警 告 。
范 围
文 档 、 页 面
表 8.32 PDF_define_layer( ) 的 选 项
选 项 类 型 说 明
creatorinfo 选 项 列 表 描 述 内 容 和 创 建 应 用 程 序 的 选 项 列 表 。 如 果 使 用 此 选 项 , 要 求 同 时 提 供
以 下 两 个 条 目 :
creator ( 超 文 本 字 符 串 ) 创 建 图 层 的 应 用 程 序 名 称
subtype ( 字 符 串 ) 内 容 的 类 型 。 建 议 使 用 Artwork 和 Technical 值 。
defaultstate 布 尔 型 默 认 值 :true
218 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.32 PDF_define_layer( ) 的 选 项
选 项 类 型 说 明
hypertextencoding 关 键 字 指 定 name 参 数 和 creator 选 项 的 编 码 方 式 ( 参 见 第 85 页 上 的 第 4.5.4 节
“ 不 支 持 Unicode 的 语 言 中 的 字 符 串 处 理 ”)。 空 字 符 串 相 当 于 unicode。
默 认 值 : 全 局 hypertextencoding 参 数
hypertextformat 关 键 字 设 置 name 参 数 的 格 式 。 可 能 的 值 包 括 bytes、 utf8、 utf16、 utf16le、
utf16be 和 auto。 默 认 值 :hypertextformat 参 数 的 值
initialexportstate 布 尔 型 指 定 图 层 的 建 议 导 出 状 态 。 如 果 为 true, Acrobat 将 在 转 换 / 导 出 到 旧
PDF 版 本 或 其 他 文 档 格 式 时 包 括 图 层 。 默 认 值 :true
initialprintstate 布 尔 型 图 层 的 建 议 打 印 状 态 。 如 果 为 true, Acrobat 将 在 打 印 文 档 时 包 括 图 层 。
默 认 值 :true
initialviewstate 布 尔 型 图 层 的 建 议 查 看 状 态 。 如 为 true, Acrobat 将 在 打 开 文 档 时 显 示 图 层 。
默 认 值 :true
intent 关 键 字 查 看 或 设 计
language 选 项 列 表 指 定 图 层 的 语 言 :
lang ( 字 符 串 , 必 需 的 ) 在 表 8.5 中 描 述 的 lang 选 项 的 语 言 和 可 能
的 区 域 设 置 。
preferred ( 布 尔 型 ) 如 果 为 true, 且 图 层 语 言 只 部 分 匹 配 系 统 语 言 , 将
使 用 此 图 层 。 默 认 值 :false
onpanel 布 尔 型 如 果 为 false, 将 不 在 Acrobat 的 图 层 面 板 显 示 图 层 名 称 , 因 此 用 户 不 能
操 作 图 层 。 默 认 值 :true
pageelement 关 键 字 指 定 图 层 包 含 分 页 伪 像 :HF ( 页 眉 / 页 脚 )、 FG ( 前 景 图 像 或 图 形 )、
BG ( 背 景 图 像 或 图 形 ) 或 L ( 徽 标 ) 之 一 。
printsubtype 选 项 列 表 指 定 图 层 是 否 用 于 打 印 :
subtype ( 关 键 字 ) Trapping、 PrintersMarks 或 Watermark 之 一 , 指
定 图 层 内 容 的 类 型 。
printstate ( 布 尔 型 ) 如 果 为 true, Acrobat 将 在 打 印 时 启 动 图 层 内 容 。
zoom
浮 点 值 或 百
分 比 列 表
一 个 或 两 个 值 , 根 据 缩 放 因 子 指 定 图 层 的 可 见 性 (1.0 表 示 缩 放 因 子 为
100%)。 如 果 只 提 供 一 个 值 , 将 用 作 图 层 显 示 时 使 用 的 最 大 缩 放 因 子 ;
如 果 提 供 两 个 值 , 则 指 定 最 大 和 最 小 缩 放 因 子 。 可 使 用 关 键 字
maxzoom, 指 定 可 能 的 最 大 缩 放 因 子 。
C++ Java
Perl PHP
C
void set_layer_dependency(String type, String optlist)
PDF_set_layer_dependency(resource p, string type, string optlist)
void PDF_set_layer_dependency(PDF *p, const char *type, const char *optlist)
定 义 图 层 间 的 层 次 和 分 组 关 系 ( 要 求 PDF 1.5)。
type 依 存 关 系 的 类 型 , 必 须 为 下 列 值 之 一 :
> GroupAllOn: 如 果 group 选 项 中 指 定 的 所 有 图 层 都 可 以 显 示 , 将 显 示 depend 选 项 中 指 定
的 图 层 。
> GroupAnyOn: 如 果 group 选 项 中 指 定 的 任 一 图 层 可 以 显 示 , 将 显 示 depend 选 项 中 指 定
的 图 层 。
> GroupAllOff : 如 果 group 选 项 中 指 定 的 所 有 图 层 都 不 显 示 , 将 显 示 depend 选 项 中 指 定 的
图 层 。
> GroupAnyOff: 如 果 group 选 项 中 指 定 的 任 一 图 层 不 显 示 , 将 显 示 depend 选 项 中 指 定 的
图 层 。
> Parent : 指 定 parent 选 项 中 指 定 的 图 层 与 children 选 项 中 指 定 的 图 层 之 间 的 层 次 关 系 。
一 个 图 层 只 能 属 于 一 个 父 级 图 层 。
8.4 图 形 函 数 219

Radiobtn: 指 定 group 选 项 中 指 定 的 各 个 图 层 间 的 单 选 按 钮 关 系 。 这 表 示 , 一 次 最 多 只
能 显 示 该 组 中 的 一 个 图 层 ; 这 对 多 语 言 图 层 很 有 用 。
> Title:parent 选 项 中 指 定 的 图 层 句 柄 不 能 直 接 控 制 任 何 页 面 内 容 , 但 可 以 用 作 children
选 项 中 指 定 的 图 层 的 父 级 图 层 节 点 。
optlist 选 项 列 表 , 根 据 表 8.33 指 定 图 层 依 存 关 系 。
范 围
文 档 、 页 面
表 8.33 PDF_set_layer_dependency( ) 的 选 项
选 项 类 型 说 明
parent 图 层 句 柄 ( 仅 用 于 type=Parent 和 Title 的 情 况 ) children 选 项 中 指 定 的 图 层 的 父 级 图 层 。
children
图 层 句 柄
列 表
( 仅 用 于 type=Parent 和 Title 的 情 况 ) 一 个 或 多 个 图 层 句 柄 , 指 定 从 属 于 提 供
的 父 级 图 层 的 图 层 。
depend 图 层 句 柄 ( 仅 用 于 type=GroupAllOn、 GroupAnyOn、 GroupAllOff 和 GroupAnyOff 的 情
况 ) 由 group 选 项 中 指 定 的 图 层 控 制 的 图 层 。
group
图 层 句 柄
列 表
( 仅 用 于 type=GroupAllOn、 GroupAnyOn、 GroupAllOff、 GroupAnyOff 和
Radiobtn 的 情 况 ) 构 成 图 层 组 的 一 个 或 多 个 图 层 。
C++ Java
Perl PHP
C
void begin_layer(int layer)
PDF_begin_layer(resource p, int layer)
void PDF_begin_layer(PDF *p, int layer)
开 始 一 个 图 层 , 用 于 后 续 的 页 面 输 出 ( 要 求 PDF 1.5)。
layer 图 层 的 句 柄 , 必 须 用 PDF_define_layer( ) 返 回 。
详 细 说 明
范 围
在 此 调 用 之 后 、 但 在 任 何 后 续 PDF_begin_layer( ) 或 PDF_end_layer( ) 调 用 之 前 置 于 页 面 上 的
所 有 内 容 都 将 构 成 指 定 图 层 的 一 部 分 。 内 容 的 可 见 性 取 决 于 图 层 的 设 置 。
此 函 数 将 启 动 指 定 图 层 , 并 停 用 任 何 当 前 现 用 图 层 。
页 面
C++ Java void end_layer( )
Perl PHP PDF_end_layer(resource p)
C
void PDF_end_layer(PDF *p)
停 用 所 有 活 动 图 层 ( 要 求 PDF 1.5)。
详 细 说 明 此 调 用 之 后 置 于 页 面 上 的 内 容 不 属 于 任 何 图 层 。 所 有 图 层 都 必 须 在 页 面 结 尾 处 结 束 。
若 想 调 换 层 A 与 层 B 的 位 置 , 只 需 调 用 PDF_begin_layer( ) 即 可 。 并 不 需 要 专 门 调 用 PDF_
end_layer( ) 来 关 闭 层 A. PDF_end_layer( ) 只 在 创 建 无 条 件 内 容 时 ( 总 是 可 见 的 ), 和 在 页 尾
关 闭 所 有 层 时 才 使 用 。
范 围
页 面
220 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

8.5 颜 色 函 数
8.5.1 设 置 颜 色 和 色 彩 空 间
表 8.34 列 出 了 本 节 的 相 关 参 数 及 相 应 的 值 。
表 8.34 颜 色 函 数 的 参 数
函 数 关 键 字 说 明
set_parameter preserveoldpantonenames 如 果 为 false, 旧 版 Pantone 专 色 名 称 将 转 换 为 对 应 的 新 颜 色 名 称 ;
否 则 , 将 保 留 旧 名 称 。 默 认 值 :false)。 范 围 : 任 意
set_parameter spotcolorlookup 如 果 为 false, PDFlib 将 不 使 用 它 的 内 部 专 色 名 称 数 据 库 。 可 以 使 用
此 参 数 提 供 已 知 专 色 的 自 定 义 , 这 将 为 匹 配 其 他 应 用 程 序 提 供 的 定
义 提 供 了 变 通 方 式 。 使 用 此 功 能 时 要 小 心 , 建 议 不 使 用 此 功 能 。 默
认 值 :true。 范 围 : 任 意
C++ Java void setcolor(String fstype, String colorspace, double c1, double c2, double c3, double c4)
Perl PHP PDF_setcolor(resource p,
string fstype, string colorspace, float c1, float c2, float c3, float c4)
C void PDF_setcolor(PDF *p,
const char *fstype, const char *colorspace, double c1, double c2, double c3, double c4)
设 置 当 前 色 彩 空 间 和 颜 色 。
fstype
描 边 。
fill、stroke 或 fillstroke 之 一 , 指 定 是 否 将 颜 色 设 为 填 充 、 描 边 , 或 同 时 设 为 填 充 和
colorspace gray、rgb、cmyk、spot、 pattern、iccbasedgray、iccbasedrgb、iccbasedcmyk 或
lab 之 一 , 指 定 色 彩 空 间 。
c1, c2, c3, c4 所 选 色 彩 空 间 的 颜 色 组 件 ( 参 见 第 57 页 上 的 第 3.3 节 “ 使 用 颜 色 ”):
> 如 果 colorspace 为 gray, c1 指 定 灰 色 值 ;
> 如 果 colorspace 为 rgb, c1、 c2 和 c3 分 别 指 定 红 色 、 绿 色 和 蓝 色 值 ;
> 如 果 colorspace 为 cmyk, c1、 c2、 c3 和 c4 分 别 指 定 青 色 、 洋 红 、 黄 色 和 黑 色 值 ;
> 如 果 colorspace 为 spot,c1 指 定 PDF_makespotcolor( ) 返 回 的 专 色 句 柄 ,c2 指 定 介 于 0 和
1 之 间 的 色 调 值 。
> 如 果 colorspace 为 pattern, c1 指 定 PDF_begin_pattern( ) 或 PDF_shading_pattern( ) 返 回
的 图 案 句 柄 。
> 如 果 colorspace 为 iccbasedgray, c1 指 定 灰 色 值 ;
> 如 果 colorspace 为 iccbasedrgb, c1、 c2 和 c3 分 别 指 定 红 色 、 绿 色 和 蓝 色 值 ;
> 如 果 colorspace 为 iccbasedcmyk,c1、c2、c3 和 c4 分 别 指 定 青 色 、 洋 红 、 黄 色 和 黑 色 值 ;
> 如 果 colorspace 为 lab,c1、c2 和 c3 分 别 指 定 CIE L*a*b* 色 彩 空 间 中 的 颜 色 值 , 用 D50 标
准 光 源 解 释 。 c1 指 定 介 于 0 到 100 之 间 的 L* ( 亮 度 ), c2 和 c3 指 定 介 于 -127 到 128 之
间 的 a*, b* ( 色 度 ) 值 。
详 细 说 明
gray、 rgb 和 cmyk 色 彩 空 间 的 所 有 颜 色 值 以 及 spot 色 彩 空 间 的 tint 值 都 必 须 为 0 到 1 之 间
的 数 值 , 包 括 0 和 1。 不 使 用 的 参 数 应 设 为 0。
灰 度 、RGB 值 和 专 色 色 调 根 据 加 色 配 色 法 解 释 , 即 :0 表 示 没 有 颜 色 ,1 表 示 完 全 强 度 。
因 此 , 灰 色 值 0 和 (r, g, b) = (0, 0, 0) 的 RGB 值 代 表 黑 色 , 灰 色 值 1 和 (r, g, b) = (1, 1, 1) 的 RGB
值 代 表 白 色 。 但 是 ,CMYK 值 会 根 据 减 色 配 色 法 解 释 , 即 :(c, m, y, k) = (0, 0, 0, 0) 代 表 白 色 ,
(c, m, y, k) = (0, 0, 0, 1) 代 表 黑 色 。 介 于 0 到 255 之 间 的 颜 色 值 必 须 除 以 255, 计 算 出 介 于 0 到
1 之 间 的 值 。
8.5 颜 色 函 数 221

在 每 页 开 头 ,gray、rgb 和 cmyk 色 彩 空 间 的 填 充 和 描 边 颜 色 值 设 为 黑 色 的 默 认 值 。 专 色
和 图 案 颜 色 没 有 默 认 值 。
如 果 使 用 iccbasedgray/rgb/cmyk 色 彩 空 间 , 使 用 setcolor:iccprofilegray/rgb/cmyk 参 数 之
前 , 必 须 先 设 置 对 应 的 ICC 配 置 文 件 ( 参 见 表 8.36)。
范 围
PDF/X
参 数
页 面 、 图 案 ( 仅 限 于 图 案 的 绘 画 类 型 为 1 的 情 况 ) 、 模 板 、 字 形 ( 仅 限 于 Type 3 字 体 的
colorized 选 项 为 true 的 情 况 ) 和 文 档 ; 图 案 颜 色 不 能 在 自 己 的 定 义 中 使 用 。 在 文 档 范 围 中
设 置 颜 色 可 能 对 用 PDF_makespotcolor( ) 定 义 专 色 很 有 用 。
PDF/X-1 和 PDF/X-1a: 不 允 许 colorspace = rgb、 iccbasedgray/rgb/cmyk 和 lab。
PDF/X-3: 除 非 PDF/X 输 出 方 法 为 灰 度 或 CMYK 设 备 , 否 则 colorspace = gray 要 求 事 先 设 置
PDF_begin_page_ext( ) 中 的 defaultgray 选 项 。 除 非 PDF/X 输 出 方 法 为 RGB 设 备 , 否 则
colorspace = rgb 要 求 事 先 设 置 PDF_begin_page_ext( ) 中 的 defaultrgb 选 项 。 除 非 PDF/X 输
出 方 法 为 CMYK 设 备 , 否 则 colorspace = cmyk 要 求 事 先 设 置 PDF_begin_page_ext( ) 中 的
defaultcmyk 选 项 。 使 用 iccbasedgray/rgb/cmyk 和 lab 颜 色 要 求 在 输 出 方 法 中 的 提 供 ICC 配
置 文 件 ( 在 这 种 情 况 下 , 标 准 名 称 是 不 够 的 )。
setcolor:iccprofilegray/rgb/cmyk
C++ Java
Perl PHP
C
int makespotcolor(String spotname)
int PDF_makespotcolor(resource p, String spotname)
int PDF_makespotcolor(PDF *p, const char *spotname, int reserved)
查 找 内 建 专 色 名 称 , 或 通 过 当 前 填 充 色 创 建 命 名 专 色 。
spotname 内 建 专 色 的 名 称 , 或 要 定 义 的 专 色 的 任 意 名 称 。 此 名 称 最 长 不 得 超 过 126 字 节 。
专 色 名 称 只 支 持 单 字 节 (8 位 ) 字 符 , 不 支 持 Unicode 或 嵌 入 的 null 字 符 。
reserved ( 仅 用 于 C 语 言 绑 定 ) 保 留 , 必 须 为 0。
返 回 值
详 细 说 明
范 围
颜 色 句 柄 , 可 用 于 整 个 文 档 中 的 后 续 PDF_setcolor( ) 调 用 。 可 在 所 有 页 面 之 间 重 复 使 用 专 色
句 柄 , 但 不 能 跨 越 不 同 文 档 。 在 一 个 文 档 中 , 专 色 的 数 量 不 受 任 何 限 制 。
如 果 spotname 在 内 部 颜 色 表 中 是 已 知 的 , 并 且 spotcolorlookup 参 数 为 true ( 这 是 默 认
值 ), 将 使 用 提 供 的 专 色 名 称 。 否 则 , 将 使 用 当 前 填 充 色 的 (CMYK 或 其 他 ) 颜 色 值 定 义 新
专 色 的 外 观 。 这 些 替 代 值 只 用 于 屏 幕 预 览 和 低 端 打 印 。 提 供 的 专 色 名 称 将 用 来 生 成 分 色 , 而
不 使 用 替 代 值 。
如 果 已 在 前 一 个 PDF_makespotcolor( ) 调 用 中 使 用 了 spotname, 返 回 值 将 与 前 一 次 调 用
中 的 值 相 同 , 不 会 影 响 当 前 颜 色 。
可 使 用 特 殊 专 色 名 称 All 将 颜 色 应 用 到 所 有 分 色 , 这 对 绘 制 注 册 商 标 很 有 用 。 专 色 名 称
None 将 在 任 何 分 色 上 生 成 不 可 见 的 输 出 。
页 面 、 图 案 、 模 板 、 字 形 ( 仅 限 于 Type 3 字 体 的 colorized 选 项 为 true 的 情 况 )、 文 档 ; 如
果 定 义 自 定 义 颜 色 , 当 前 填 充 色 不 能 是 专 色 或 图 案 。
PDF/X PDF/X-1 和 PDF/X-1a 模 式 不 支 持 PANTONE® 专 色 。
参 数
spotcolorlookup, preserveoldpantonenames
222 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
int load_iccprofile(String profilename, String optlist)
int PDF_load_iccprofile(resource p, string profilename, string optlist)
int PDF_load_iccprofile(PDF *p, const char *profilename, int len, const char *optlist)
搜 索 ICC 配 置 文 件 (ICC Profile), 并 准 备 稍 后 使 用 。
profilename ( 名 称 字 符 串 ) ICCProfile 资 源 的 名 称 , 基 于 磁 盘 的 文 件 或 虚 拟 文 件 的 文 件
名 , 或 PDF/X 的 标 准 输 出 条 件 名 称 。 只 有 usage 选 项 设 为 outputintent 时 , 才 允 许 PDF/X
的 标 准 输 出 条 件 名 称 。
len ( 仅 用 于 C 语 言 绑 定 ) UTF-16 字 符 串 的 profilename 长 度 ( 以 字 节 为 单 位 )。 如 果 len
= 0, 则 必 须 提 供 以 null 终 结 的 字 符 串 。
optlist 选 项 列 表 , 根 据 表 8.35 描 述 配 置 文 件 处 理 的 各 个 方 面 。
表 8.35 PDF_load_iccprofile( ) 的 选 项
关 键 字 类 型 说 明 和 可 能 的 值
usage 关 键 字 描 述 ICC 配 置 文 件 的 预 期 用 途 ( 默 认 值 :iccbased):
iccbased ICC 配 置 文 件 将 用 来 定 义 基 于 ICC 的 色 彩 空 间 , 或 应 用 到 图 像 。
outputintent
ICC 配 置 文 件 将 用 来 定 义 PDF/X 输 出 方 法 。
描 述 字 符 串 只 有 usage = outputintent 时 , 才 使 用 此 选 项 。 它 包 含 对 CC 配 置 文 件 的 可 读 描
述 ; 此 配 置 文 件 将 与 PDF/X 输 出 方 法 一 起 使 用 。 默 认 值 : 如 果 profilename 指
标 准 输 出 方 法 , 将 从 内 部 列 表 中 提 取 此 描 述 ; 否 则 , 将 不 做 任 何 描 述 。
embedprofil
e
布 尔 型 只 有 usage = outputintent 时 , 才 使 用 此 选 项 。 强 制 使 用 嵌 入 的 ICC 配 置 文 件 ;
即 使 作 为 profilename 提 供 了 标 准 输 出 方 法 , 也 是 如 此 。 默 认 值 :false
返 回 值 配 置 文 件 句 柄 , 可 在 后 续 PDF_load_image( ) 调 用 中 使 用 , 或 用 来 设 置 配 置 文 件 相 关 的 参 数 。
必 须 检 查 返 回 值 是 否 为 -1 ( 在 PHP 中 : 返 回 0) ; 这 表 示 出 现 错 误 。 为 了 获 得 有 关 配 置 文 件
相 关 问 题 的 性 质 的 更 多 详 细 信 息 ( 未 找 到 文 件 、 不 支 持 的 格 式 等 ), 可 将 iccwarning 参 数 设
为 true。 不 能 在 多 个 PDF 文 档 之 间 使 用 返 回 的 配 置 文 件 句 柄 。 而 且 , 如 果 usage 选 项 为
outputintent, 则 不 能 将 返 回 句 柄 应 用 到 图 像 。 在 一 个 文 档 中 , ICC 配 置 文 件 的 数 量 不 受 任
何 限 制 。
详 细 说 明
如 果 usage 选 项 为 iccbased , 将 根 据 第 60 页 上 的 第 3.3.4 节 “ 色 彩 管 理 和 ICC 配 置 文 件 ” 中
讨 论 的 搜 索 策 略 搜 索 命 名 的 配 置 文 件 。 如 果 找 到 配 置 文 件 , 将 检 查 它 是 否 适 用 ( 例 如 , 颜
色 组 件 的 数 量 )。 sRGB 配 置 文 件 始 终 都 可 在 内 部 使 用 , 但 不 能 进 行 配 置 。
如 果 usage 为 outputintent , 将 首 先 在 内 部 标 准 输 出 方 法 列 表 中 搜 索 命 名 的 配 置 文 件 。 如
果 搜 索 不 成 功 , 将 在 用 户 配 置 的 输 出 方 法 列 表 中 搜 索 该 名 称 。 如 果 已 找 到 提 供 的 名 称 , 并 根
据 内 建 或 用 户 配 置 列 表 确 认 为 标 准 输 出 方 法 , 将 不 再 搜 索 ICC 配 置 文 件 ; 而 且 ,description
选 项 提 供 的 名 称 将 嵌 入 到 PDF 输 出 中 , 用 作 PDF/X 输 出 方 法 。 如 果 发 现 此 名 称 不 是 标 准 输
出 方 法 标 识 符 , 则 将 其 用 作 配 置 文 件 名 称 , 并 将 对 应 的 ICC 配 置 文 件 嵌 入 PDF, 用 作 PDF/X
输 出 方 法 。
范 围 文 档 ; 如 果 usage 选 项 为 iccbased , 将 允 许 下 列 范 围 : 页 面 、 图 案 、 模 板 、 字 形 。
参 数 参 见 表 8.36。
PDF/X
生 成 文 档 的 输 出 方 法 必 须 使 用 此 函 数 设 置 , 或 者 使 用 PDF_process_pdi( ) 复 制 导 入 文 档 的 输
出 方 法 。
8.5 颜 色 函 数 223

表 8.36 ICC 配 置 文 件 的 参 数 和 值
函 数 关 键 字 说 明
set_parameter ICCProfile
StandardOutputIntent
如 UPR 文 件 中 各 个 类 别 所 示 的 对 应 资 源 文 件 行 ( 参 见 第 49 页 上 的
第 3.1.5 节 “ 资 源 配 置 和 文 件 搜 索 ”)。 可 由 多 个 调 用 向 内 部 列 表 添
加 新 条 目 。( 另 请 参 见 表 8.3 中 的 resourcefile)。 范 围 : 任 意
set_parameter iccwarning 启 用 或 禁 用 与 ICC 配 置 文 件 相 关 的 警 告 ( 非 致 命 异 常 )。 可 能 的 值
为 true 和 false, 默 认 值 为 false。 范 围 : 任 意
get_value icccomponents 通 过 modifier 中 提 供 的 句 柄 返 回 ICC 配 置 文 件 内 的 颜 色 组 件 数 量 。
set_value setcolor:iccprofilegray 设 置 ICC 配 置 文 件 ; 该 配 置 文 件 指 定 用 于 PDF_setcolor( ) 的 灰 色 色
彩 空 间 。 范 围 : 文 档 、 页 面 、 图 案 、 模 板 、 字 形
set_value setcolor:iccprofilergb 设 置 ICC 配 置 文 件 ; 该 配 置 文 件 指 定 用 于 PDF_setcolor( ) 的 RGB 色
彩 空 间 。 范 围 : 文 档 、 页 面 、 图 案 、 模 板 、 字 形
set_value setcolor:iccprofilecmyk 设 置 ICC 配 置 文 件 ; 该 配 置 文 件 指 定 用 于 PDF_setcolor( ) 的 CMYK
色 彩 空 间 。 范 围 : 文 档 、 页 面 、 图 案 、 模 板 、 字 形
set_value
defaultgray
defaultrgb
defaultcmyk
不 常 用 , 在 PDF_begin/end_page_ext( ) 中 使 用 defaultgray、
defaultrgb 和 defaultcmyk 选 项 。
8.5.2 图 案 和 着 色
C++ Java int begin_pattern(double width, double height, double xstep, double ystep, int painttype)
Perl PHP int PDF_begin_pattern(resource p,
float width, float height, float xstep, float ystep, int painttype)
C int PDF_begin_pattern(PDF *p,
double width, double height, double xstep, double ystep, int painttype)
开 始 图 案 定 义 。
width, height 图 案 定 界 框 的 尺 寸 ( 以 点 数 为 单 位 )。
xstep, ystep 重 复 放 置 图 案 以 描 边 或 填 充 某 个 对 象 时 的 偏 移 量 。 大 多 数 应 用 程 序 会 将 他 们
分 别 设 为 图 案 的 width 和 height 值 。
painttype 如 果 painttype 为 1, 图 案 必 须 包 含 自 己 的 颜 色 规 范 ; 将 在 使 用 图 案 时 应 用 此 颜
色 图 案 ; 如 果 painttype 为 2, 图 案 不 能 包 含 任 何 颜 色 规 范 , 使 用 该 图 案 进 行 填 充 或 描 边 时
将 应 用 当 前 填 充 色 或 描 边 色 。
返 回 值 图 案 句 柄 ; 在 关 闭 的 文 档 范 围 内 , 可 在 后 续 PDF_setcolor( ) 调 用 中 使 用 此 句 柄 。
详 细 说 明
此 函 数 将 所 有 文 本 、 图 形 和 颜 色 状 态 参 数 重 设 为 他 们 的 默 认 值 。 图 案 定 义 过 程 中 , 不 能 使 用
超 文 本 函 数 和 打 开 图 像 的 函 数 , 但 可 以 使 用 所 有 文 本 、 图 形 和 颜 色 函 数 ( 正 在 定 义 过 程 中
的 图 案 除 外 )。
范 围 文 档 、 页 面 ; 此 函 数 是 图 案 范 围 的 开 头 , 必 须 与 对 应 的 PDF_end_pattern( ) 调 用 成 对 使 用 。
C++ Java void end_pattern( )
Perl PHP PDF_end_pattern(resource p)
C void PDF_end_pattern(PDF *p)
完 成 图 案 定 义 。
范 围 图 案 ; 此 函 数 结 束 图 案 范 围 , 必 须 与 对 应 的 PDF_begin_pattern( ) 调 用 成 对 使 用 。
224 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
int shading_pattern(int shading, String optlist)
int PDF_shading_pattern(resource p, int shading, string optlist)
int PDF_shading_pattern(PDF *p, int shading, const char *optlist)
使 用 着 色 对 象 定 义 着 色 图 案 ( 要 求 PDF 1.4 或 更 高 版 本 )。
shading PDF_shading( ) 返 回 的 着 色 句 柄 。
optlist 选 项 列 表 , 根 据 表 8.37 描 述 着 色 图 案 的 各 个 方 面 。
返 回 值 图 案 句 柄 ; 在 关 闭 的 文 档 范 围 内 , 可 在 后 续 PDF_setcolor( ) 调 用 中 使 用 此 句 柄 。
详 细 说 明 此 函 数 可 用 来 使 用 着 色 填 充 任 意 对 象 。 为 此 , 必 须 使 用 PDF_shading( ) 获 取 一 个 着 色 句 柄 ,
然 后 使 用 PDF_shading_pattern( ), 基 于 此 着 色 定 义 图 案 。 最 后 , 可 将 图 案 句 柄 应 用 到 PDF_
setcolor( ), 将 当 前 颜 色 设 为 着 色 图 案 。
范 围
文 档 、 页 面 、 字 体
表 8.37 PDF_shading_pattern( ) 的 选 项
关 键 字 类 型 说 明 和 可 能 的 值
gstate 句 柄 图 形 状 态 句 柄
C++ Java
Perl PHP
C
void shfill(int shading)
PDF_shfill(resource p, int shading)
void PDF_shfill(PDF *p, int shading)
基 于 着 色 对 象 , 使 用 着 色 填 充 某 个 区 域 ( 要 求 PDF 1.4 或 更 高 版 本 )。
shading PDF_shading( ) 返 回 的 着 色 句 柄 。
详 细 说 明
范 围
通 过 此 函 数 , 可 在 不 涉 及 PDF_shading_pattern( ) 和 PDF_setcolor( ) 的 情 况 下 使 用 着 色 。 但
是 , 这 只 适 用 于 简 单 的 形 状 ; 其 中 , 待 填 充 对 象 的 几 何 形 状 与 着 色 本 身 完 全 相 同 。 由 于 当 前
剪 切 区 域 将 被 着 色 ( 根 据 着 色 的 extend0 和 extend1 选 项 ), 此 函 数 通 常 会 与 PDF_clip( ) 结
合 使 用 。
页 面 、 图 案 ( 仅 限 于 图 案 的 绘 画 类 型 为 1 的 情 况 ) 、 模 板 、 字 形 ( 仅 限 于 Type 3 字 体 的
colorized 选 项 为 true 的 情 况 )、 文 档
C++ Java int shading(String shtype, double x0, double y0, double x1, double y1,
double c1, double c2, double c3, double c4, String optlist)
Perl PHP int PDF_shading(resource p, string shtype, float x0, float y0, float x1, float y1,
float c1, float c2, float c3, float c4, string optlist)
C int PDF_shading(PDF *p, const char *shtype, double x0, double y0, double x1, double y1,
double c1, double c2, double c3, double c4, const char *optlist)
通 过 当 前 填 充 色 定 义 与 另 一 颜 色 的 混 合 效 果 ( 要 求 PDF 1.4 或 更 高 版 本 )。
shtype
着 色 的 类 型 ; 对 于 线 性 着 色 , 必 须 是 axial, 或 对 于 圆 形 着 色 必 须 是 radial。
x0, y0, x1, y1 对 于 轴 向 着 色 ,(x0, y0) 和 (x1, y1) 是 着 色 起 点 和 端 点 的 坐 标 。 对 于 辐 射 着 色 ,
这 些 点 可 指 定 开 始 和 结 束 圆 形 的 圆 心 。
8.5 颜 色 函 数 225

c1, c2, c3, c4 着 色 端 点 的 颜 色 值 ; 在 当 前 填 充 色 色 彩 空 间 中 的 解 释 方 法 与 PDF_setcolor( )
中 的 颜 色 参 数 相 同 。 如 果 当 前 填 充 色 色 彩 空 间 为 专 色 色 彩 空 间 , 将 忽 略 c1, 且 c2 将 包 含 色
调 值 。
optlist 选 项 列 表 , 根 据 表 8.38 描 述 着 色 的 各 个 方 面 。
返 回 值
着 色 句 柄 ; 在 关 闭 的 文 档 范 围 内 , 可 在 后 续 PDF_shading_pattern( ) 和 PDF_shfill( ) 调 用 中 使
用 此 句 柄 。
详 细 说 明 当 前 填 充 色 将 用 作 起 始 颜 色 , 它 不 能 基 于 图 案 。
范 围
文 档 、 页 面 、 字 体
表 8.38 PDF_shading( ) 的 选 项
关 键 字 类 型 说 明 和 可 能 的 值
N 浮 点 型 颜 色 过 渡 函 数 的 指 数 , 必 须 > 0。 默 认 值 :1
r0 浮 点 型 ( 仅 用 于 辐 射 着 色 , 这 里 要 求 此 选 项 ) 起 始 圆 形 的 半 径 。
r1 浮 点 型 ( 仅 用 于 辐 射 着 色 选 项 , 这 里 要 求 此 选 项 ) 结 束 圆 形 的 半 径 。
extend0 布 尔 型 指 定 是 否 将 着 色 延 伸 出 起 点 。 默 认 值 :false
extend1 布 尔 型 指 定 是 否 将 着 色 延 伸 出 结 点 。 默 认 值 :false
antialias 布 尔 型 指 定 是 否 为 着 色 启 动 消 除 锯 齿 功 能 。 默 认 值 :false
226 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

8.6 图 像 和 模 板 函 数
表 8.39 列 出 了 本 节 的 相 关 参 数 及 相 应 的 值 。
表 8.39 图 像 函 数 的 参 数 和 值 ( 参 见 第 181 页 上 的 第 8.2.3 节 “ 参 数 处 理 ”)
函 数 关 键 字 说 明
get_value imagewidth
imageheight
分 别 获 取 图 像 的 宽 度 或 高 度 , 以 像 素 为 单 位 。 modifier 是 所 选 图 像 的
整 型 句 柄 。 范 围 : 页 面 、 图 案 、 模 板 、 字 形 、 文 档 、 路 径 。
get_value orientation 获 取 图 像 的 方 向 值 。 modifier 是 所 选 图 像 的 整 型 句 柄 。 对 于 包 含 方 向 标
记 的 TIFF 图 像 , 将 返 回 此 标 记 的 值 ; 在 所 有 其 他 情 况 下 , 将 返 回 1 ; 同
时 PDFlib 也 将 相 应 调 整 图 像 数 值 以 保 持 原 貌 。 范 围 : 页 面 、 图 案 、 模
板 、 字 形 、 文 档 、 路 径 。
get_value
resx
resy
分 别 获 取 图 像 的 水 平 或 垂 直 分 辨 率 。 modifier 是 所 选 图 像 的 整 型 句
柄 。 范 围 : 页 面 、 图 案 、 模 板 、 字 形 、 文 档 、 路 径 。
如 果 值 为 正 值 , 返 回 值 为 图 像 分 辨 率 , 单 位 是 像 素 / 英 寸 (dpi)。 如 果
返 回 值 为 负 值 , 可 使 用 resx 和 resy 查 找 非 方 形 像 素 的 长 宽 比 , 但 不 具
有 任 何 绝 对 意 义 。 如 果 返 回 值 为 零 , 则 表 示 图 像 的 分 辨 率 未 知 。
set_parameter honoriccprofile 读 取 图 像 内 嵌 入 的 ICC 配 置 文 件 , 并 将 其 应 用 到 图 像 数 据 。 默 认 值 :
true
set_parameter imagewarning 此 参 数 可 用 来 获 得 无 法 用 PDF_load_image( ) 成 功 打 开 图 像 的 原 因 的 相
关 详 细 信 息 。 默 认 值 :false)。 范 围 : 任 意
true 图 像 函 数 失 败 时 , 引 发 异 常 并 返 回 -1 ( 在 PHP 中 : 返 回
0) 异 常 提 供 的 消 息 可 能 对 调 试 很 有 用 。
false 图 像 函 数 失 败 时 , 不 引 发 异 常 。 相 反 , 此 函 数 只 是 简 单 地
返 回 -1 ( 在 PHP 中 : 返 回 0)
set_value image:iccprofile ICC 配 置 文 件 的 句 柄 ; 除 非 提 供 了 iccprofile, 否 则 该 配 置 文 件 将 应 用
到 所 有 相 关 图 像 。
get_value image:iccprofile 返 回 modifier 中 提 供 的 图 像 句 柄 引 用 的 图 像 内 所 嵌 入 的 ICC 配 置 文 件
句 柄 。
set_value renderingintent 图 像 的 渲 染 方 法 。 有 关 可 能 的 关 键 字 列 表 及 其 含 义 , 请 参 见 表 3.7。 默
认 值 :Auto。
8.6.1 图 像
C++ Java
Perl PHP
C
int load_image(String imagetype, String filename, String optlist)
int PDF_load_image(resource p, string imagetype, string filename, string optlist)
int PDF_load_image(PDF *p,
const char *imagetype, const char *filename, int len, const char *optlist)
根 据 各 种 选 项 打 开 基 于 磁 盘 的 或 虚 拟 的 图 像 文 件 。
imagetype 字 符 串 auto 指 示 PDFlib 自 动 检 测 图 像 文 件 类 型 ( 不 能 用 于 CCITT 和 原 始 图
像 )。 用 bmp、ccitt、gif、jpeg、jpeg2000、png、raw 或 tiff 字 符 串 之 一 显 式 指 定 图 像 格 式
可 使 性 能 略 有 提 高 ( 有 关 详 细 信 息 , 参 见 第 116 页 上 的 第 5.1.2 节 “ 受 支 持 的 图 像 文 件 格
式 ”)。 类 型 jpeg2000 要 求 PDF 1.5 或 更 高 版 本 。 类 型 ccitt 不 同 于 TIFF, 此 类 型 包 含 CCITT
压 缩 图 像 数 据 。
filename ( 名 称 字 符 串 ) 通 常 指 定 要 打 开 的 图 像 文 件 的 文 件 名 。 此 名 称 必 须 为 基 于 磁 盘 的
文 件 或 虚 拟 文 件 的 文 件 名 ; PDFlib 不 会 从 URL 提 取 图 像 数 据 。
8.6 图 像 和 模 板 函 数 227

len ( 仅 用 于 C 语 言 绑 定 。)UTF-16 字 符 串 的 filename 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0,
则 必 须 提 供 以 null 终 结 的 字 符 串 。
optlist 选 项 列 表 , 根 据 表 8.40 指 定 图 像 相 关 属 性 。
返 回 值 图 像 句 柄 , 可 用 于 后 续 的 图 像 相 关 调 用 。 必 须 检 查 返 回 值 是 否 为 -1 ( 在 PHP 中 : 返 回 0) ;
这 表 示 出 现 错 误 。 要 获 得 有 关 图 像 相 关 问 题 的 更 多 详 细 信 息 ( 图 像 文 件 名 错 误 、 不 支 持 格
式 、 图 像 数 据 错 误 等 等 ) , 应 将 imagewarning 参 数 或 选 项 设 为 true ( 参 见 表 8.39 和 表
8.40)。 不 能 在 多 个 PDF 文 档 之 间 使 用 返 回 的 图 像 句 柄 。
详 细 说 明
范 围
此 函 数 将 打 开 并 分 析 使 用 imagetype 参 数 中 确 定 的 一 种 支 持 格 式 的 光 栅 图 形 , 并 将 相 关 图 像
数 据 复 制 至 输 出 文 档 。 此 函 数 不 会 在 输 出 上 显 示 任 何 效 果 。 要 将 导 入 图 像 实 际 置 于 生 成 的 输
出 文 档 内 , 必 须 使 用 PDF_fit_image( )。 不 建 议 为 每 个 生 成 的 文 档 多 次 打 开 同 一 图 像 ; 因 为
这 样 , 实 际 的 图 像 数 据 将 向 输 出 文 档 复 制 多 次 。
PDFlib 将 根 据 filename 打 开 图 像 文 件 , 处 理 内 容 , 并 在 返 回 之 前 关 闭 文 件 。 尽 管 可 以 在
文 档 中 多 次 放 置 图 像 ( 参 见 PDF_fit_image( )) , 但 实 际 的 图 像 文 件 不 会 在 此 调 用 之 后 继 续
保 持 打 开 状 态 。
如 果 imagetype = raw 或 ccitt, PDFlib 不 能 根 据 图 像 数 据 推 算 出 width、 height、
components 和 bpc 选 项 的 值 , 故 必 须 提 供 其 相 应 值 用 户 应 负 责 提 供 与 图 像 实 际 匹 配 的 选 项
值 。 否 则 , 可 能 会 生 成 损 坏 的 PDF 输 出 , 且 Acrobat 可 能 返 回 图 像 数 据 不 足 的 错 误 信 息 。
如 果 imagetype = raw, 提 供 的 图 像 数 据 的 长 度 必 须 等 于 [width x components x bpc / 8] x
height ( 以 字 节 为 单 位 ) , 括 号 内 的 项 目 将 使 用 最 接 近 的 较 大 整 数 。 图 像 样 本 将 按 照 标 准
PostScript/PDF 的 顺 序 , 即 : 由 上 而 下 、 从 左 到 右 ( 假 定 没 有 坐 标 转 换 )。 必 须 提 供 16 位 样
本 , 首 先 提 供 最 重 要 的 字 节 (big-endian 或 »Mac« 字 节 顺 序 )。 像 素 值 的 极 性 将 在 第 57 页
上 的 第 3.3.1 节 “ 颜 色 和 色 彩 空 间 ” 讨 论 。 如 果 bpc 小 于 8, 则 每 个 像 素 行 都 以 字 节 边 界 开
头 , 且 颜 色 值 必 须 从 左 到 右 封 装 在 一 个 字 节 内 。 图 像 样 本 始 终 都 采 用 交 替 顺 序 , 即 : 首 先 提
供 第 一 个 像 素 的 所 有 颜 色 值 , 然 后 提 供 第 二 个 像 素 的 所 有 颜 色 值 , 依 此 类 推 。
如 果 未 提 供 inline 选 项 , 范 围 为 文 档 、 页 面 、 字 体 ; 而 且 , 此 函 数 必 须 与 对 应 的 PDF_close_
image( ) 调 用 成 对 使 用 。 在 文 档 或 字 体 范 围 载 入 图 像 , 而 不 在 页 面 范 围 载 入 , 可 在 某 种 程 度
上 优 化 输 出 大 小 。
如 果 提 供 了 inline 选 项 , 则 范 围 为 页 面 、 图 案 、 模 板 、 字 形 , 但 不 能 调 用 PDF_close_image( ) 。
PDF/X 所 有 PDF/X 规 范 等 级 :
> 不 允 许 OPI-1.3 和 OPI-2.0 选 项
> 如 果 蒙 版 指 向 1 位 图 像 , 则 只 允 许 masked 选 项 。
> 由 于 JPEG2000 图 像 要 求 PDF 1.5 或 更 高 版 本 , 所 以 不 允 许 这 些 选 项 。
PDF/X-1 和 PDF/X-1a: 不 允 许 RGB 图 像 。
PDF/X-3: 除 非 PDF/X 输 出 方 法 为 灰 度 或 CMYK 设 备 , 否 则 灰 度 图 像 要 求 事 先 设 置 PDF_
begin_page_ext( ) 中 的 defaultgray 选 项 。 除 非 PDF/X 输 出 方 法 为 RGB 设 备 , 否 则 RGB 图 像
要 求 事 先 设 置 PDF_begin_page_ext( ) 中 的 defaultrgb 选 项 。 除 非 PDF/X 输 出 方 法 为 CMYK
设 备 , 否 则 CMYK 图 像 要 求 事 先 设 置 PDF_begin_page_ext( ) 中 的 defaultcmyk 选 项 。
参 数
imagewidth、 imageheight、 resx、 resy、 imagewarning
表 8.40 PDF_load_image( ) 的 选 项
关 键 字 类 型 说 明
bitreverse 布 尔 型 ( 仅 用 于 imagetype=ccitt 的 情 况 ) 如 果 为 true, 则 对 压 缩 数 据 中 的 所 有 字 节
执 行 位 反 转 。 默 认 值 :false
bpc 整 型 ( 仅 用 于 imagetype=raw 的 情 况 且 是 必 需 的 ) 每 个 组 件 的 位 数 , 必 须 为 1、
2、 4 或 8。 在 PDF 1.5 中 , 也 允 许 bpc=16。
228 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.40 PDF_load_image( ) 的 选 项 ( 续 )
关 键 字 类 型 说 明
colorize
专 色 句 柄 ( 如 果 提 供 了 iccprofile 选 项 , 将 忽 略 此 选 项 ; 不 能 用 于
imagetype=jpeg2000 的 情 况 ) 用 专 色 句 柄 着 色 图 像 , 必 须 事 先 使 用
PDF_makespotcolor( ) 获 取 句 柄 。 图 像 必 须 为 黑 白 图 像 或 灰 度 图 像 。
components 整 型 ( 仅 用 于 imagetype=raw 的 情 况 且 是 必 需 的 ) 图 像 组 件 ( 通 道 ) 的 数 量 ,
必 须 为 1、 3 或 4。
height 整 型 ( 仅 用 于 imagetype = raw 和 ccitt 的 情 况 , 且 是 必 需 的 ) 以 像 素 为 单 位 的 图
像 高 度 。
honoriccprofile 布 尔 型 ( 仅 用 于 imagetype=jpeg、 png 和 tiff 的 情 况 , 如 果 提 供 了 colorize 选 项 ,
将 设 为 false) 读 取 嵌 入 的 ICC 配 置 文 件 ( 如 果 有 ) 并 将 其 应 用 到 图 像 。
默 认 值 :honoriccprofile 参 数 的 值 。
hypertextencoding 关 键 字 指 定 iconname 选 项 的 编 码 方 式 ( 参 见 第 85 页 上 的 第 4.5.4 节 “ 不 支 持
Unicode 的 语 言 中 的 字 符 串 处 理 ”)。 空 字 符 串 相 当 于 unicode。 默 认 值 : 全
局 hypertextencoding 参 数 的 值 。
iccprofile icc 句 柄 ( 仅 用 于 imagetype=jpeg、 png 和 tiff 的 情 况 ) 应 用 到 图 像 的 ICC 配 置 文 件 的
句 柄 。 Default: an embedded profile if one is present in the image and the
honoriccprofile option is true 默 认 值 : 若 在 图 像 中 带 有 ICC 配 置 文 件 且
honoriccprofile 选 项 为 true, 则 内 嵌 配 置 文 件
iconname
超 文 本 字
符 串
( 如 果 inline=true, 将 忽 略 此 选 项 ; 如 果 template=true, 则 是 必 需 的 ) 向 图
像 附 加 一 个 名 称 , 以 便 能 够 通 过 JavaScript 引 用 , 例 如 : 将 图 像 用 作 表 单 域
的 图 标 。
ignoremask 布 尔 型 忽 略 图 像 中 的 透 明 度 信 息 。 默 认 值 :false
ignoreorientation 布 尔 型 ( 仅 用 于 imagetype=tiff 的 情 况 ) 忽 略 图 像 中 的 所 有 方 向 标 记 。 这 可 能 对 弥
补 错 误 的 方 向 信 息 很 有 用 。 默 认 值 :false
imagewarning 布 尔 型 无 法 打 开 图 像 时 , 启 用 异 常 。 默 认 值 : 全 局 imagewarning 参 数 的 值 。
inline 布 尔 型 ( 仅 用 于 imagetype=ccitt、 jpeg 和 raw 的 情 况 ) 如 果 为 true, 图 像 将 直 接 写
入 页 面 、 图 案 、 模 板 或 字 形 描 述 的 内 容 流 中 ( 参 见 第 115 页 上 的 第 5.1.1 节
“ 基 本 图 像 处 理 ”)。
interpolate 布 尔 型 启 用 图 像 插 值 处 理 , 以 改 善 图 像 在 屏 幕 和 纸 张 上 的 显 示 效 果 。 这 对 使 用 Type
3 字 体 的 字 形 描 述 的 位 图 图 像 很 有 用 。 默 认 值 :false
invert 布 尔 型 ( 除 非 mask=true, 否 则 不 能 用 于 imagetype=jpeg2000 的 情 况 ) 对 图 像 进 行
反 相 处 理 ( 亮 色 和 暗 色 互 换 )。 这 可 用 作 一 种 变 通 方 法 , 处 理 应 用 程 序 会 有
不 同 解 释 的 图 像 。 默 认 值 :false
K 整 型 ( 仅 用 于 imagetype=ccitt 的 情 况 ) 用 于 编 码 方 案 选 择 的 CCITT 压 缩 参 数 。 默
认 值 :0
-1 G4 压 缩
0 一 维 G3 压 缩 (G3-1D)
1 混 合 1 维 和 2 维 压 缩 (G3, 2-D)
mask 布 尔 型 ( 仅 用 于 具 有 一 个 颜 色 组 件 的 图 像 , 包 括 索 引 颜 色 )。 图 像 将 用 作 蒙 版 ( 参
见 第 118 页 上 的 第 5.1.3 节 “ 图 像 蒙 版 和 透 明 度 ”)。 1 位 蒙 版 此 选 项 是 必 需
的 , 但 对 于 每 像 素 位 数 大 于 1 的 蒙 版 此 选 项 是 可 选 的 。 但 是 , 位 数 大 于 1 的
蒙 版 要 求 PDF 1.4。 默 认 值 :false。 蒙 版 有 两 种 用 途 :
> 对 另 一 图 像 蒙 版 : 返 回 的 图 像 句 柄 可 用 于 后 续 调 用 , 以 打 开 另 一 图 像 , 也
可 以 提 供 给 »masked« 选 项 。
> 放 置 一 个 着 色 透 明 图 像 : 将 图 像 中 的 0 位 像 素 视 为 透 明 , 并 使 用 当 前 填 充
色 对 1 位 像 素 着 色 。
masked 图 像 句 柄 作 为 蒙 版 应 用 到 当 前 图 像 的 图 像 句 柄 。 此 图 像 句 柄 是 由 前 一 个 PDF_load_
image( ) 调 用 返 回 的 ( 如 果 是 1 位 蒙 版 , 且 由 PDF 1.3 生 成 , 将 使 用
»masked« 选 项 ), 此 句 柄 尚 未 关 闭 。 在 PDF 1.3 兼 容 模 式 下 , 图 像 句 柄 必 须
指 向 一 个 1 位 图 像 ; 这 是 由 于 , 只 有 PDF 1.4 及 更 高 版 本 支 持 软 蒙 版 。
8.6 图 像 和 模 板 函 数 229

表 8.40 PDF_load_image( ) 的 选 项 ( 续 )
关 键 字 类 型 说 明
OPI-1.3 选 项 列 表 选 项 列 表 , 包 含 用 作 选 项 名 称 的 OPI 1.3 PostScript 注 释 ; 下 列 条 目 是 必 需 的 :
ALDImageFilename ( 字 符 串 )、 ALDImageDimensions ( 整 数 值 列 表 )、
ALDImageCropRect ( 具 有 整 数 值 的 矩 形 )、 ALDImagePosition ( 浮 点 值 列 表 )
下 列 条 目 是 可 选 的 :
ALDImageID ( 字 符 串 )、 ALDObjectComments ( 字 符 串 )、
ALDImageCropFixed ( 矩 形 )、 ALDImageResolution ( 浮 点 值 列 表 )、
ALDImageColorType ( 关 键 字 , Process、 Spot、 Separation ; 默 认 值 :
Spot)、 ALDImageColorType ( 介 于 0 到 1 之 间 的 4 个 颜 色 值 列 表 和 一 个 颜 色
名 称 、 ALDImageTint ( 浮 点 型 )、 ALDImageOverprint ( 布 尔 型 )
ALDImageType ( 整 数 值 列 表 )、 ALDImageGrayMap ( 整 数 值 列 表 )、
ALDImageTransparency ( 布 尔 型 )、 ALDImageAsciiTag ( 整 数 / 字 符 串 对 列
表 )
子 选 项 normalizefilename 控 制 文 件 名 的 处 理 : 如 果 为 true, 将 按 照 PDF 参
考 的 规 定 进 行 规 范 化 处 理 。 如 果 为 false, 将 复 制 至 输 出 , 而 不 做 任 何 修 改 。
后 者 可 能 对 使 用 某 些 无 法 正 确 处 理 规 范 化 文 件 名 的 OPI 服 务 器 很 有 用 。 默 认
值 :false
OPI-2.0 选 项 列 表 选 项 列 表 , 包 含 用 作 选 项 名 称 的 OPI 2.0 PostScript 注 释 ; 要 求 以 下 项 目 :
ImageFilename ( 字 符 串 )
应 同 时 提 供 或 同 时 省 略 下 列 条 目 :
ImageCropRect ( 矩 形 )、 ImageDimensions ( 浮 点 值 列 表 )
下 列 条 目 是 可 选 的 :
MainImage ( 字 符 串 )、 TIFFASCIITag ( 整 数 / 字 符 串 对 列 表 )、
ImageOverprint ( 布 尔 型 )、 ImageInks (full_color 字 符 串 、 registration 字
符 串 、 或 包 含 每 个 色 料 名 称 和 色 调 的 monochrome 字 符 串 和 字 符 串 / 浮 点 值
对 的 列 表 )、 IncludedImageDimensions ( 整 数 值 列 表 )、
IncludedImageQuality ( 具 有 1、 2 或 3 值 的 整 数 值 )
同 时 , 还 支 持 normalizefilename 选 项 ( 参 见 OPI-1.3)。
页 面 整 型 ( 仅 用 于 imagetype=gif 或 tiff 的 情 况 ; 如 果 使 用 其 他 格 式 , 则 必 须 为 1)
根 据 给 定 数 值 , 从 多 页 图 像 文 件 中 提 取 图 像 。 第 一 个 图 像 的 编 码 为 1。
默 认 值 :1
passthrough 布 尔 型 ( 仅 用 于 imagetype=tiff 或 jpeg 的 情 况 ) 控 制 图 像 数 据 的 处 理 ( 默 认 值 :
true):
tiff 如 果 为 true, 压 缩 的 TIFF 图 像 数 据 将 在 可 能 的 情 况 下 直 接 传 送 到
PDF 输 出 。 如 果 TIFF 图 像 包 含 的 数 据 受 到 破 坏 或 者 不 完 整 , 将 此
选 项 设 为 false 会 有 所 帮 助 。
jpeg 如 果 为 true, 将 JPEG 图 像 数 据 直 接 复 制 至 PDF 输 出 。 如 果 为
false, PDFlib 将 转 换 JPEG 图 像 数 据 的 代 码 , 以 清 理 数 据 , 使 其 兼
容 Acrobat。 将 此 参 数 设 为 false 可 帮 助 处 理 不 兼 容 Acrobat 的 图
像 数 据 。 对 于 multiscan 和 某 些 CMYK JPEG 图 像 , 此 选 项 将 强 制
设 为 false。 如 果 有 JPEG 图 像 要 求 passthrough=false, 请 向 我 们
的 支 持 部 门 报 告 , 以 便 我 们 能 够 自 动 检 测 这 种 方 式 。
renderingintent 关 键 字 图 像 的 渲 染 方 法 。 有 关 可 能 的 关 键 字 列 表 及 其 含 义 , 请 参 见 表 3.7。 默 认 值 :
全 局 renderingintent 参 数 的 值 。
template 布 尔 型 如 果 为 true, 生 成 嵌 入 在 表 单 XObject 中 的 PDF 图 像 XObject ( 在 PDFlib
中 , 称 为 模 板 ), 而 不 生 成 单 纯 的 图 像 XObject。 这 可 用 来 创 建 只 包 含 一 个 图
像 的 表 单 域 图 标 模 板 。 使 用 某 个 OPI-1.3 或 OPI-2.0 选 项 时 , 同 样 要 求 此 选
项 , 以 便 兼 容 某 些 OPI 服 务 器 。 默 认 值 :false)。 范 围 : 文 档
width 整 型 ( 仅 用 于 imagetype = raw 和 ccitt 的 情 况 , 且 是 必 需 的 ) 以 像 素 为 单 位 的 图
像 宽 度 。
230 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
void close_image(int image)
PDF_close_image(resource p, int image)
void PDF_close_image(PDF *p, int image)
关 闭 图 像 。
image 由 PDF_load_image( ) 返 回 的 有 效 图 像 句 柄 。
详 细 说 明
范 围
此 函 数 只 会 影 响 PDFlib 的 相 关 内 部 图 像 结 构 。 如 果 已 从 文 件 中 打 开 了 图 像 , 此 调 用 不 会 影 响
实 际 图 像 文 件 ; 这 是 因 为 , 已 经 在 对 应 的 PDF_load_image( ) 调 用 结 束 时 关 闭 了 图 像 。 由 于
此 函 数 会 断 开 PDFlib 与 图 像 的 内 部 关 联 , 所 以 用 此 函 数 关 闭 图 像 句 柄 后 , 将 无 法 继 续 使 用 。
文 档 、 页 面 、 字 体 ; 除 非 已 经 使 用 了 inline 选 项 , 否 则 必 须 与 对 应 的 PDF_load_image( ) 调
用 成 对 使 用 。
C++ Java
Perl PHP
C
void fit_image(int image, double x, double y, String optlist)
PDF_fit_image(resource p, int image, float x, float y, string optlist)
void PDF_fit_image(PDF *p, int image, double x, double y, const char *optlist)
根 据 各 种 选 项 , 将 图 像 或 模 板 置 于 页 面 上 的 位 置 (x, y) 。
image 由 PDF_load_image( ) 或 PDF_begin_template( ) 函 数 返 回 的 有 效 图 像 或 模 板 句 柄 。
x, y 用 户 坐 标 系 统 中 的 参 考 点 坐 标 ; 将 根 据 各 种 选 项 , 在 此 坐 标 上 放 置 图 像 或 模 板 。
optlist 选 项 列 表 , 根 据 表 8.41 指 定 详 细 的 放 置 信 息 。
详 细 说 明
范 围
将 相 对 于 参 考 点 (x, y) 放 置 图 像 或 模 板 ( 下 文 统 称 为 对 象 )。 默 认 情 况 下 , 对 象 的 左 下 角 将
置 于 参 考 点 上 。 但 是 , orientate、 boxsize、 position 和 fitmethod 选 项 可 修 改 此 行 为 。 默 认
情 况 下 , 将 根 据 其 分 辨 率 值 缩 放 图 像 。 可 使 用 dpi、 scale 和 fitmethod 选 项 修 改 此 行 为 。
页 面 、 图 案 、 模 板 、 字 形 ( 仅 用 于 Type 3 字 体 的 colorized 选 项 为 true 或 图 像 为 蒙 版 的
情 况 ); 只 要 尚 未 使 用 PDF_close_image( ) 关 闭 图 像 句 柄 , 便 可 在 任 意 页 面 上 多 次 调 用 此 函 数 ,
次 数 不 受 任 何 限 制 。
表 8.41 PDF_fit_image( ) 和 PDF_fit_pdi_page( ) 的 选 项
关 键 字 类 型 说 明
adjustpage 布 尔 型 ( 若 blind=true 忽 略 ) 将 当 前 页 面 的 尺 寸 调 整 为 对 象 的 尺 寸 , 以 使 页 面 的 右 上 角 与
图 像 的 右 上 角 加
(x, y) 的 点 重 叠 。 position 选 项 值 为 0 时 , 应 注 意 下 列 有 用 的 情 况 :
x >= 0 且 y >= 0
对 象 被 白 色 边 距 环 绕 。 边 距 的 水 平 宽 度 为 y, 垂 直 宽 度 为 x。
x < 0 且 y < 0
将 从 图 像 中 裁 切 水 平 和 垂 直 的 条 带 。
此 选 项 只 在 页 面 范 围 内 有 效 , 且 不 能 用 于 topdown 参 数 设 为 true 的 情 况 。
默 认 值 :false
blind 布 尔 型 如 果 为 true, 将 完 成 所 有 定 位 和 缩 放 计 算 , 但 不 会 将 对 象 置 于 输 出 页 面 之 上 。
这 可 用 于 处 理 页 面 上 的 块 , 而 不 实 际 使 用 页 面 的 内 容 。 默 认 值 :false
boxsize
浮 点 值
列 表
指 定 框 宽 度 和 高 度 的 两 个 值 , 将 相 对 于 这 两 个 值 放 置 并 可 能 缩 放 对 象 。 框 的 左
下 角 即 为 参 考 点 (x, y)。 放 置 图 像 并 使 其 填 充 此 框 的 操 作 由 position 和 fitmethod
选 项 控 制 。 如 果 width = 0, 只 考 虑 高 度 ; 如 果 height = 0, 则 只 考 虑 宽 度 。 在
这 些 情 况 下 , 将 分 别 相 对 于 (x, y) 到 (x, y+height) 的 垂 直 直 线 或 (x, y) 到
(x+width, y) 的 水 平 直 线 放 置 对 象 。 默 认 值 :{0 0}
8.6 图 像 和 模 板 函 数 231

表 8.41 PDF_fit_image( ) 和 PDF_fit_pdi_page( ) 的 选 项 ( 续 )
关 键 字 类 型 说 明
dpi
浮 点 值
列 表
一 个 或 两 个 值 , 指 定 水 平 和 垂 直 方 向 上 所 需 的 图 像 分 辨 率 , 以 像 素 / 英 寸 为 单
位 。 如 果 只 提 供 一 个 值 , 将 同 时 用 于 两 个 方 向 。 如 果 值 为 0, 将 使 用 图 像 的 内
部 分 辨 率 ( 如 果 有 ), 否 则 使 用 72 dpi。 除 值 0 外 , 也 可 提 供 关 键 字 internal。
由 此 选 项 得 到 的 缩 放 结 果 相 对 于 当 前 用 户 坐 标 ; 如 果 已 经 过 缩 放 , 则 生 成 的 物
理 分 辨 率 将 不 同 于 提 供 的 值 。
模 板 或 PDF 页 面 将 忽 略 此 选 项 ; 如 果 fitmethod 选 项 已 随 auto、meet、slice 或
entire 关 键 字 一 起 提 供 , 同 样 会 忽 略 此 选 项 。 默 认 值 :internal
fitmethod 关 键 字 给 出 使 对 象 填 充 指 定 框 的 方 法 。 如 果 尚 未 有 指 定 框 , 将 忽 略 此 选 项 。 默 认 值 :
nofit
nofit 只 确 定 对 象 位 置 , 不 进 行 任 何 缩 放 或 剪 裁 处 理 。
clip 确 定 对 象 位 置 , 并 在 框 的 边 缘 剪 裁 对 象 。
meet 根 据 position 选 项 确 定 对 象 位 置 , 并 在 保 持 长 宽 比 的 同 时 进 行 缩 放
以 使 其 完 全 装 入 框 内 。 通 常 , 至 少 有 对 象 的 两 个 边 缘 与 框 的 对 应 边
缘 对 齐 。 将 忽 略 dpi 和 scale 选 项 。
auto 相 当 于 meet。
slice 根 据 position 选 项 确 定 对 象 位 置 , 并 进 行 缩 放 以 使 其 覆 盖 整 个 框 ,
可 在 保 持 长 宽 比 的 同 时 确 保 至 少 对 象 的 一 个 尺 寸 可 完 全 包 含 在 框
内 。 通 常 , 对 象 的 某 些 其 他 尺 寸 会 延 伸 到 框 外 , 因 此 , 将 被 剪 裁 。
将 忽 略 dpi 和 scale 选 项 。
entire 根 据 position 选 项 确 定 图 像 的 位 置 , 并 进 行 缩 放 以 使 其 覆 盖 整 个
框 。 通 常 , 这 种 方 法 会 扭 曲 对 象 。 将 忽 略 dpi 和 scale 选 项 。
ignoreorientatio
n
布 尔 型
( 仅 用 于 TIFF 图 像 ) 忽 略 图 像 中 的 所 有 方 向 标 记 。 这 可 能 对 弥 补 错 误 的 方 向 信
息 很 有 用 。 默 认 值 :PDF_load_image( ) 中 ignoreorientation 选 项 的 值
orientate 关 键 字 指 定 放 置 对 象 时 的 所 需 对 象 方 向 。 默 认 值 :north
north 向 上
east 指 向 右 侧
south 向 下
west 指 向 左 侧
position
浮 点 值
或 关 键
字 列 表
一 个 或 两 个 值 , 指 定 对 象 内 的 参 考 点 位 置 (x, y) ; {0 0} 表 示 位 于 文 本 框 左 下
角 , {100 100} 表 示 位 于 右 上 角 。 如 果 已 经 指 定 了 boxsize 选 项 , 则 position 选
项 还 可 指 定 框 的 位 置 。 这 些 值 表 示 为 对 象 宽 度 和 高 度 的 百 分 比 。 如 果 两 个 百 分
比 相 等 , 只 指 定 一 个 浮 点 值 即 可 。 示 例 :
0 或 {0 0} 左 下 角
{50 100} 顶 部 边 缘 中 间
50 or {50 50} 对 象 中 央
关 键 字 left、 center、 right (x 方 向 ) 或 者 bottom、 center、 top (y 方 向 ) 可
用 来 替 代 值 0、 50 和 100。 如 果 只 指 定 一 个 关 键 字 , 将 添 加 另 一 方 向 对 应 的 关
键 字 。
默 认 值 :0 ( 左 下 角 )
rotate 浮 点 型 旋 转 坐 标 系 统 , 将 中 心 用 作 参 考 点 并 将 指 定 的 值 用 作 以 度 数 表 示 的 旋 转 角 度 。
这 将 旋 转 框 和 对 象 。 放 置 对 象 时 , 会 重 设 旋 转 选 项 。 默 认 值 :0
scale
浮 点 值
列 表
按 照 指 定 的 缩 放 因 子 ( 而 非 百 分 比 ), 在 水 平 和 垂 直 方 向 上 缩 放 对 象 。 如 果 两
个 因 子 相 等 , 指 定 一 个 浮 点 值 即 可 。 如 果 fitmethod 选 项 已 随 auto、 meet、
slice 或 entire 关 键 字 一 起 提 供 , 将 忽 略 此 选 项 。 默 认 值 :1
8.6.2 模 板
注 : 本 节 描 述 的 模 板 函 数 与 PDFlib 块 的 各 种 数 据 处 理 无 关 。 可 使 用 PDF_fill_textblock( )、
PDF_fill_imageblock( ) 和 PDF_fill_pdfblock( ) 填 充 用 PDFlib 块 增 效 工 具 准 备 的 块
( 参 见 第 240 页 上 的 第 8.8 节 “ 块 填 充 函 数 (PPS)”)。
232 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
int begin_template(double width, double height)
int PDF_begin_template(resource p, float width, float height)
int PDF_begin_template(PDF *p, double width, double height)
开 始 模 板 定 义 。
width, height 模 板 定 界 框 的 尺 寸 ( 以 点 数 为 单 位 )。
返 回 值 模 板 句 柄 , 可 用 于 后 续 的 图 像 相 关 调 用 , 尤 其 是 PDF_fit_image( )。 不 返 回 错 误 。
详 细 说 明
此 函 数 将 所 有 文 本 、 图 形 和 颜 色 状 态 参 数 重 设 为 他 们 的 默 认 值 。 定 义 模 板 期 间 , 不 能 使 用 超
文 本 函 数 或 打 开 图 像 的 参 数 , 但 可 以 使 用 所 有 文 本 、 图 形 和 颜 色 函 数 。
范 围 文 档 、 页 面 ; 此 参 数 是 模 板 范 围 的 开 头 , 必 须 与 对 应 的 PDF_end_template( ) 调 用 成 对 使 用 。
C++ Java void end_template( )
Perl PHP PDF_end_template(resource p)
C void PDF_end_template(PDF *p)
完 成 模 板 定 义 。
范 围 页 面 ; 此 函 数 终 结 模 板 范 围 , 必 须 与 对 应 的 PDF_begin_template( ) 调 用 成 对 使 用 。
8.6.3 缩 览 图
C++ Java
Perl PHP
C
void add_thumbnail(int image)
PDF_add_thumbnail(resource p, int image)
void PDF_add_thumbnail(PDF *p, int image)
作 为 缩 览 图 , 在 当 前 页 面 上 添 加 现 有 图 像 。
image 由 PDF_load_image( ) 获 取 的 有 效 图 像 句 柄 。
详 细 说 明 此 函 数 可 作 为 缩 览 图 , 在 当 前 页 面 上 添 加 提 供 的 图 像 。 缩 览 图 必 须 遵 守 以 下 限 制 :
> 图 像 不 能 大 于 106 x 106 像 素 。
> 图 像 必 须 使 用 灰 度 、 RGB 或 索 引 RGB 色 彩 空 间 。
> 由 于 缩 览 图 必 须 由 单 一 的 PDF 图 像 对 象 构 建 , multi-strip TIFF 不 能 构 建 缩 览 图 ( 参 见
第 116 页 上 的 第 5.1.2 节 “ 受 支 持 的 图 像 文 件 格 式 ”)。
此 函 数 不 会 生 成 用 于 页 面 的 缩 览 图 图 像 , 只 提 供 一 个 挂 钩 , 将 现 有 图 像 加 入 缩 览 图 中 。 实 际
的 缩 览 图 图 像 必 须 由 客 户 端 生 成 。 客 户 端 必 须 确 保 缩 览 图 的 颜 色 、 高 度 / 宽 度 比 例 和 缩 览 图
的 实 际 内 容 与 页 面 内 容 相 匹 配 。
由 于 Acrobat 5 及 更 高 版 本 可 即 时 生 成 缩 览 图 ( 尽 管 Acrobat 5 或 Adobe Reader 6 不 能
在 浏 览 器 中 生 成 缩 览 图 ), 且 缩 览 图 会 增 加 生 成 的 PDF 的 总 文 件 大 小 , 所 以 建 议 不 添 加 缩 览
图 , 而 由 客 户 端 生 成 缩 览 图 。
范 围 页 面 ; 每 页 只 能 调 用 一 次 。 并 非 所 有 页 面 都 需 要 附 加 缩 览 图 。
8.6 图 像 和 模 板 函 数 233

8.7 PDF 导 入 函 数 (PDI)
注 : 本 节 描 述 的 所 有 函 数 都 要 求 额 外 的 PDF 导 入 库 (PDI) ; PDI 要 求 PDFlib+PDI 或 PDFlib
Personalization Server (PPS), 但 PDFlib Lite 和 PDFlib 中 并 不 包 括 这 些 组 件 。 有 关 如 何 获 得 PDI
的 更 多 信 息 , 请 访 问 我 们 的 网 站 。
8.7.1 文 档 和 页 面
C++ Java
Perl PHP
C
int open_pdi(String filename, String optlist, int len)
int PDF_open_pdi(resource p, string filename, string optlist, len)
int PDF_open_pdi(PDF *p, const char *filename, const char *optlist, int len)
打 开 基 于 磁 盘 的 或 虚 拟 的 PDF 文 档 , 并 准 备 稍 后 使 用 。
filename ( 名 称 字 符 串 ) PDF 文 件 的 文 件 名 。
optlist 选 项 列 表 , 根 据 表 8.42 指 定 PDF 打 开 选 项 。
len ( 仅 用 于 C 语 言 绑 定 , 在 其 他 语 言 中 必 须 为 0) UTF-16 字 符 串 的 filename 长 度 ( 以 字
节 为 单 位 )。 如 果 len = 0, 则 必 须 提 供 以 null 终 结 的 字 符 串 。
返 回 值
详 细 说 明
文 档 句 柄 , 可 用 于 处 理 文 档 的 具 体 页 面 , 或 用 于 查 询 文 档 属 性 。 返 回 值 -1 ( 在 PHP 中 : 返
回 0), 表 示 无 法 打 开 页 面 。 可 同 时 打 开 任 意 数 量 的 PDF 文 档 。 可 以 在 关 闭 文 档 范 围 结 束 之
前 使 用 返 回 值 。
默 认 情 况 下 , 如 符 合 下 列 任 一 条 件 或 多 个 条 件 , 则 会 拒 绝 文 档 ( 有 关 详 细 信 息 , 参 见 第 122 页
上 的 第 5.2.3 节 “ 可 接 受 的 PDF 文 档 ”):
> 文 档 已 损 坏 。
> 文 档 使 用 的 PDF 版 本 比 当 前 PDF 文 档 的 版 本 高 。
> 文 档 加 密 , 但 未 在 password 选 项 中 提 供 相 应 的 口 令 。
> 文 档 不 符 合 当 前 PDF/X 输 出 规 范 等 级 。
> 文 档 为 加 标 签 的 PDF, 且 PDF_begin_document( ) 中 的 tagged 选 项 为 true。
但 除 第 一 个 原 因 外 , 均 可 使 用 infomode 选 项 打 开 文 档 。 这 可 能 对 查 询 PDF 的 相 关 信 息 很 有
用 , 例 如 加 密 或 PDF/X 状 态 、 文 档 信 息 域 等 。
为 了 获 得 PDF 导 入 相 关 问 题 的 性 质 的 更 多 详 细 信 息 (PDF 文 件 名 错 误 、 不 支 持 格 式 、PDF
数 据 错 误 , 等 ), 可 使 用 PDF_get_errmsg( ) 接 收 更 为 详 细 的 错 误 消 息 。
范 围 对 象 、 文 档 、 页 面 ; 在 对 象 范 围 内 , 只 能 使 用 PDI 文 档 句 柄 , 从 PDF 文 档 中 查 询 信 息 。
PDF/X 除 非 infomode 选 项 为 true, 否 则 导 入 的 文 档 必 须 符 合 当 前 PDF/X 输 出 规 范 等 级 。
参 数 参 见 表 8.45 和 表 8.46。
C
int PDF_open_pdi_callback(PDF *p, void *opaque, size_t filesize,
size_t (*readproc)(void *opaque, void *buffer, size_t size),
int (*seekproc)(void *opaque, long offset),
const char *optlist)
从 自 定 义 数 据 源 打 开 现 有 PDF 文 档 , 并 准 备 稍 后 使 用 。
opaque 一 个 指 针 , 指 向 某 些 可 能 与 输 入 PDF 文 档 相 关 联 的 用 户 数 据 。 此 指 针 将 作 为 第 一
个 参 数 传 递 给 回 调 函 数 , 并 能 以 任 何 方 式 使 用 。 PDI 不 会 以 其 他 方 式 使 用 opaque 指 针 。
234 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.42 PDF_open_pdi( ) 的 选 项
关 键 字 类 型 说 明
infomode 布 尔 型 如 果 为 true, 将 可 以 在 打 开 文 档 时 查 询 常 规 信 息 和 块 属 性 , 但 不 能 将 页 面 导 入
当 前 输 出 文 档 。 尤 其 是 , infomode=true 时 , 可 打 开 下 列 文 档 ( 默 认 值 :
false):
不 兼 容 当 前 PDF/X 模 式 的 PDF。
PDF 版 本 高 于 当 前 文 档 的 版 本 的 PDF。
不 知 道 口 令 的 加 密 PDF ( 例 外 : 创 建 PDF 1.6 文 档 时 使 用 Distiller 设 置 » 对 象 级
压 缩 : 最 大 «)
PDF_begin_document( ) 为 true 的 标 签 PDF。
inmemory 布 尔 型 如 果 为 true, PDI 将 整 个 文 件 载 入 内 存 , 并 在 内 存 中 处 理 文 件 。 在 有 些 系 统 中
( 尤 其 是 MVS), 这 么 做 能 够 极 大 地 提 高 性 能 , 但 会 加 大 内 存 消 耗 。 如 果 为
false, 将 根 据 需 要 从 磁 盘 中 读 取 文 档 的 各 个 部 分 。 默 认 值 :false
password 字 符 串 ( 最 大 字 符 串 长 度 :32 个 字 符 ) 打 开 待 导 入 的 受 保 护 文 档 所 要 求 的 许 可 口 令 。
如 果 infomode=true, 只 使 用 文 档 打 开 口 令 ( 甚 至 可 能 为 空 ) 即 可 查 询 文 档
信 息 。 如 果 根 本 没 有 为 加 密 文 档 提 供 口 令 , 则 只 能 用 文 档 句 柄 查 询 文 档 的 加
密 状 态 。
pdiwarning 布 尔 型 指 定 此 函 数 是 否 在 出 现 错 误 时 引 发 异 常 。 默 认 为 pdiwarning 参 数 的 值 ( 参 见
表 8.46)。
filesize 整 个 PDF 文 档 的 大 小 ( 以 字 节 为 单 位 )。
readproc 一 个 回 调 函 数 , 将 size 字 节 数 复 制 到 buffer 指 向 的 内 存 。 如 果 到 达 文 件 结 尾 , 它
复 制 的 数 据 可 能 少 于 要 求 的 字 节 数 。 此 函 数 必 须 返 回 复 制 的 字 节 数 。
seekproc 一 个 回 调 函 数 , 设 置 文 档 中 的 当 前 读 取 位 置 。 offset 指 示 从 文 档 开 头 起 的 位 置
(0 表 示 第 一 个 字 节 )。 如 果 运 行 成 功 , 此 函 数 必 须 返 回 0, 否 则 返 回 -1。
optlist 选 项 列 表 , 根 据 表 8.42 指 定 PDF 打 开 选 项 。
返 回 值
详 细 说 明
文 档 句 柄 , 可 用 于 处 理 文 档 的 单 独 页 面 , 或 用 于 查 询 文 档 属 性 。 返 回 值 -1 表 示 无 法 打 开 PDF
文 档 。 可 同 时 打 开 任 意 数 量 的 PDF 文 档 。 可 以 在 关 闭 文 档 范 围 结 束 之 前 使 用 返 回 值 。
这 是 个 特 殊 的 应 用 程 序 接 口 , 会 从 某 些 数 据 源 中 提 取 任 意 数 量 的 PDF 数 据 , 而 不 在 磁 盘 文
件 或 内 存 中 提 供 PDF 文 档 。
范 围 对 象 、 文 档 、 页 面 ; 在 对 象 范 围 内 , 只 能 使 用 PDI 文 档 句 柄 , 从 PDF 文 档 中 查 询 信 息 。
参 数 参 见 表 8.45 和 表 8.46。
绑 定 仅 用 于 C 语 言 绑 定 。
C++ Java
Perl PHP
C
void close_pdi(int doc)
PDF_close_pdi(resource p, int doc)
void PDF_close_pdi(PDF *p, int doc)
关 闭 所 有 打 开 的 PDI 页 面 句 柄 , 并 关 闭 输 入 PDF 文 件 。
doc 由 PDF_open_pdi*( ) 获 取 的 有 效 PDF 文 档 句 柄 。
详 细 说 明
此 函 数 关 闭 PDF 导 入 文 档 并 释 放 所 有 与 文 档 相 关 的 资 源 。 所 有 可 能 打 开 的 文 档 页 面 都 将 隐
式 关 闭 。 此 调 用 后 , 便 不 能 使 用 文 档 句 柄 。 如 果 还 要 导 入 其 他 页 面 , 则 不 应 关 闭 PDF 文 档 。
尽 管 可 以 多 次 打 开 和 关 闭 PDF 导 入 文 档 , 且 次 数 不 受 任 何 限 制 , 但 这 么 做 会 导 致 PDF 输 出
文 件 不 必 要 的 增 大 。
8.7 PDF 导 入 函 数 (PDI) 235

范 围
对 象 、 文 档 、 页 面
参 数 参 见 表 8.45 和 表 8.46。
C++ Java
Perl PHP
C
int open_pdi_page(int doc, int pagenumber, String optlist)
int PDF_open_pdi_page(resource p, int doc, int pagenumber, string optlist)
int PDF_open_pdi_page(PDF *p, int doc, int pagenumber, const char* optlist)
使 用 PDF_fit_pdi_page( ) 准 备 页 面 , 以 供 稍 后 使 用 。
doc 由 PDF_open_pdi*( ) 返 回 的 有 效 PDF 文 档 句 柄 。
pagenumber 要 打 开 的 页 面 的 页 码 。 第 一 页 的 页 码 为 1。
optlist 选 项 列 表 , 根 据 表 8.43 指 定 页 面 选 项 。
返 回 值
详 细 说 明
范 围
页 面 句 柄 , 可 与 PDF_fit_pdi_page( ) 结 合 使 用 , 以 放 置 页 面 。 返 回 值 -1 ( 在 PHP 中 : 返 回
0), 指 示 无 法 打 开 页 面 。 可 以 在 关 闭 文 档 范 围 结 束 之 前 使 用 返 回 值 。 如 果 infomode 选 项 为
true, 或 者 已 在 使 用 PDF_open_pdi( ) 打 开 文 档 时 设 为 true, 则 此 句 柄 只 能 与 PDF_get_pdi_
value( ) 和 PDF_get_pdi_parameter( ) 结 合 使 用 , 以 检 索 页 面 的 相 关 信 息 , 但 此 句 柄 不 能 用 于
PDF_fit_pdi_page( )。
此 函 数 会 把 构 成 导 入 页 面 的 所 有 数 据 复 制 到 输 出 文 档 , 但 不 会 在 输 出 中 显 示 任 何 效 果 。 要 将
导 入 页 面 实 际 置 于 生 成 的 输 出 文 档 内 , 必 须 使 用 PDF_fit_pdi_page( )。 为 了 获 得 PDF 导 入 相
关 问 题 的 更 多 详 细 信 息 ( 不 支 持 格 式 、 PDF 数 据 错 误 , 等 ), 应 将 pdiwarning 参 数 或 选 项
设 为 true。 如 果 已 在 infomode 选 项 设 为 true 的 情 况 下 打 开 页 面 , 则 不 会 向 输 出 文 件 复 制 任
何 数 据 。
如 果 导 入 文 档 的 PDF 版 本 号 高 于 生 成 的 PDF 输 出 文 档 的 PDF 版 本 号 , 此 函 数 将 会 失 败 。
可 同 时 打 开 任 意 数 量 的 页 面 。 如 果 多 次 打 开 同 一 页 面 , 将 返 回 不 同 的 句 柄 , 但 一 个 句 柄
只 能 关 闭 一 次 。
文 档 、 页 面
参 数 参 见 表 8.45 和 表 8.46。
表 8.43 PDF_open_pdi_page( ) 的 选 项
关 键 字 类 型 说 明
hypertextencoding 关 键 字 指 定 iconname 选 项 的 编 码 方 式 ( 参 见 第 85 页 上 的 第 4.5.4 节 “ 不 支 持
Unicode 的 语 言 中 的 字 符 串 处 理 ”)。 空 字 符 串 相 当 于 unicode。 默 认 值 : 全 局
hypertextencoding 参 数 的 值 。
iconname
超 文 本
字 符 串
向 导 入 页 面 附 加 一 个 名 称 , 以 便 能 够 通 过 JavaScript 引 用 页 面 , 例 如 , 将 页 面
用 作 表 单 域 的 图 标 。
infomode 布 尔 型 如 果 为 true, 将 可 以 在 打 开 页 面 时 查 询 常 规 信 息 , 但 不 能 将 页 面 导 入 当 前 输 出
文 档 。 默 认 值 : 提 供 给 对 应 PDF_open_pdi( ) 调 用 的 infomode 选 项 的 值 ( 默 认
为 false)。 对 于 使 用 infomode=true 打 开 的 文 档 , 将 忽 略 此 选 项 。
pdiusebox 关 键 字 指 定 将 用 在 确 定 导 入 页 面 大 小 的 框 尺 寸 。 有 关 详 细 信 息 , 参 见 第 121 页 上 的
第 5.2.2 节 “ 与 PDFlib 一 起 使 用 PDI 函 数 ”( 默 认 值 :crop):
media 使 用 媒 体 框 ( 始 终 提 供 此 框 )
crop 如 果 有 , 则 使 用 裁 剪 框 , 否 则 使 用 媒 体 框 。
bleed 如 果 有 , 则 使 用 出 血 框 , 否 则 使 用 裁 剪 框 。
trim 如 果 有 , 则 使 用 裁 切 框 , 否 则 使 用 裁 剪 框 。
art 如 果 有 , 则 使 用 作 品 框 , 否 则 使 用 裁 剪 框 。
pdiwarning 布 尔 型 指 定 此 函 数 是 否 在 出 现 错 误 时 引 发 异 常 。 默 认 为 pdiwarning 参 数 的 值 ( 参 见
表 8.46)。
236 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
void close_pdi_page(int page)
PDF_close_pdi_page(resource p, int page)
void PDF_close_pdi_page(PDF *p, int page)
关 闭 页 面 句 柄 , 并 释 放 所 有 页 面 相 关 的 资 源 。
page 由 PDF_open_pdi_page( ) 返 回 的 有 效 PDF 页 面 句 柄 ( 而 非 页 码 !)。
详 细 说 明
范 围
此 函 数 关 闭 与 page 确 定 的 页 面 句 柄 相 关 联 的 页 面 , 并 释 放 所 有 相 关 资 源 。 不 能 在 此 调 用 后
使 用 page。
文 档 、 页 面
参 数 参 见 表 8.45 和 表 8.46。
C++ Java
Perl PHP
C
void fit_pdi_page(int page, double x, double y, String optlist)
PDF_fit_pdi_page(resource p, int page, float x, float y, string optlist)
void PDF_fit_pdi_page(PDF *p, int page, double x, double y, const char *optlist)
根 据 各 种 选 项 , 在 页 面 上 放 置 导 入 的 PDF 页 面 。
page 由 PDF_open_pdi_page( ) 或 PDF_open_pdi_page( ) 返 回 的 有 效 PDF 页 面 句 柄 ( 而 非
页 码 !)。 打 开 文 档 和 页 面 时 , infomode 选 项 必 须 已 设 为 false。 不 能 事 先 关 闭 页 面 句 柄 。
x, y 用 户 坐 标 系 统 中 的 参 考 点 坐 标 ; 将 根 据 各 种 选 项 , 在 此 坐 标 上 放 置 页 面 。
optlist 选 项 列 表 , 根 据 表 8.44 指 定 详 细 的 放 置 信 息 。
详 细 说 明
范 围
此 函 数 类 似 于 PDF_fit_image( ), 但 在 导 入 的 PDF 页 面 上 操 作 。PDF 页 面 同 样 支 持 表 8.44 中
讨 论 的 大 多 数 缩 放 和 放 置 选 项 。
页 面 、 图 案 、 模 板 、 字 形
参 数 参 见 表 8.45 和 表 8.46。
PDF/X 被 导 入 页 面 的 文 档 必 须 遵 守 与 最 终 输 出 的 PDF/X 等 级 相 兼 容 的 PDF/X 等 级 ( 参 见 表 7.7),
且 必 须 使 用 与 生 成 文 档 相 同 的 输 出 方 法 。
8.7.2 其 他 PDI 处 理
C++ Java
Perl PHP
C
int process_pdi(int doc, int page, String optlist)
int PDF_process_pdi(resource p, int doc, int page, string optlist)
int PDF_process_pdi(PDF *p, int doc, int page, const char* optlist)
处 理 导 入 PDF 文 档 的 某 些 元 素 。
doc 由 PDF_open_pdi*( ) 返 回 的 有 效 PDF 文 档 句 柄 。
page 如 果 optlist 要 求 页 面 句 柄 ( 参 见 表 8.44),page 必 须 为 通 过 PDF_open_pdi_page( ) 返
回 的 有 效 PDF 页 面 句 柄 ( 而 非 页 码 !)。 不 能 事 先 关 闭 页 面 句 柄 。 如 果 optlist 不 要 求 任 何
页 面 句 柄 , page 必 须 为 -1。
optlist 选 项 列 表 , 根 据 表 8.44 指 定 处 理 选 项 。
返 回 值 如 果 此 函 数 成 功 , 返 回 值 1 ; 如 果 失 败 , 返 回 错 误 代 码 -1 ( 在 PHP 中 : 返 回 0) 。
8.7 PDF 导 入 函 数 (PDI) 237

范 围
文 档
参 数 参 见 表 8.46。
PDF/X
生 成 文 档 的 输 出 方 法 必 须 设 为 使 用 此 函 数 和 copyoutputintent 选 项 , 或 者 调 用 PDF_load_
profile( )。
表 8.44 PDF_process_pdi( ) 的 选 项
关 键 字 类 型 说 明
action 1 关 键 字 ( 必 需 的 , 尽 管 目 前 只 定 义 了 一 个 动 作 ) 指 定 PDF 处 理 的 方 式 :
copyoutputintent
将 导 入 文 档 的 PDF/X 输 出 方 法 复 制 到 输 出 文 档 。 将 忽 略 第 二 个 及 后
续 的 复 制 输 出 方 法 的 尝 试 。
pdiwarning 1 布 尔 型 指 定 此 函 数 是 否 在 出 现 错 误 时 引 发 异 常 。 默 认 值 为 pdiwarning 参 数 的 值
( 参 见 表 8.46)。
1. 不 要 求 页 面 句 柄
8.7.3 PDI 参 数 处 理
C++ Java
Perl PHP
C
double get_pdi_value(String key, int doc, int page, int reserved)
double PDF_get_pdi_value(resource p, string key, int doc, int page, int reserved)
double PDF_get_pdi_value(PDF *p, const char *key, int doc, int page, int reserved)
获 取 某 些 数 值 型 PDI 文 档 参 数 。
key 指 定 要 获 取 的 参 数 的 名 称 , 参 见 表 8.45 和 表 8.46。
doc 由 PDF_open_pdi( ) 返 回 的 有 效 PDF 文 档 句 柄 。
page 由 PDF_open_pdi_page( ) 返 回 的 有 效 PDF 页 面 句 柄 ( 而 非 页 码 !)。 对 于 与 页 面 无
关 的 关 键 字 , page 必 须 为 -1 ( 在 PHP 中 : 返 回 0)。
reserved 目 前 尚 未 使 用 , 必 须 为 0。
返 回 值 从 文 档 中 检 索 的 数 值 。
范 围
任 意
表 8.45 PDF 导 入 的 页 面 相 关 参 数 和 值
函 数 关 键 字 说 明
get_pdi_value width
height
分 别 获 取 导 入 页 面 的 宽 度 和 高 度 ( 使 用 默 认 单 位 )。 同 时 , 还 会 考 虑
裁 切 和 旋 转 问 题 。
get_pdi_value / 旋 转 以 度 数 表 示 页 面 旋 转 (0、 90、 180 或 270)
get_pdi_value
/CropBox,
/BleedBox,
/ArtBox,
/TrimBox,
/MediaBox
查 询 页 面 的 某 个 框 参 数 。 必 须 在 参 数 名 称 后 附 加 斜 线 ’/’ 字 符 并 附 加
llx、 lly、 urx 或 ury 之 一 , 例 如 :/CropBox/llx ( 有 关 详 细 信 息 , 参 见
第 55 页 上 的 第 3.2.2 节 “ 页 面 大 小 和 坐 标 限 制 ”)。 请 注 意 , 与 页 面 的
宽 度 和 高 度 值 不 同 , 它 们 已 体 现 了 页 面 旋 转 的 因 素 , 这 些 值 并 未 加 入
/Rotate 值 的 影 响 。
get_pdi_parameter isempty 如 果 页 面 是 空 的 , 将 返 回 字 符 串 true ; 如 果 页 面 不 是 空 的 , 将 返 回
false ; 如 果 页 面 包 含 不 支 持 的 滤 镜 , 将 返 回 unknown。
238 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
String get_pdi_parameter(String key, int doc, int page, int reserved)
string PDF_get_pdi_parameter(resource p, string key, int doc, int page, int reserved)
const char * PDF_get_pdi_parameter(PDF *p,
const char *key, int doc, int page, int reserved, int *len)
获 取 某 些 字 符 串 型 PDI 文 档 参 数 。
key ( 名 称 字 符 串 ) 指 定 要 获 取 的 参 数 名 称 , 参 见 表 8.45 和 表 8.46。
doc 由 PDF_open_pdi( ) 返 回 的 有 效 PDF 文 档 句 柄 。
page 由 PDF_open_pdi_page( ) 返 回 的 有 效 PDF 页 面 句 柄 ( 而 非 页 码 !)。 对 于 与 页 面 无
关 的 关 键 字 , page 必 须 为 -1 ( 在 PHP 中 : 返 回 0)。
reserved 目 前 尚 未 使 用 , 必 须 为 0。
len 指 向 一 个 整 数 的 C 语 言 指 针 , 将 接 收 返 回 字 符 串 的 长 度 ( 以 字 节 为 单 位 )。 如 果 指 针
为 NULL, 将 忽 略 指 针 。 只 有 C 语 言 绑 定 要 求 此 参 数 , 其 他 语 言 绑 定 不 允 许 使 用 此 参 数 。
返 回 值 作 为 超 文 本 字 符 串 , 从 文 档 中 检 索 的 字 符 串 参 数 。 如 果 没 有 信 息 , 将 返 回 空 字 符 串 。
在 下 次 调 用 此 参 数 之 前 , 或 所 属 对 象 范 围 结 束 之 前 , 此 字 符 串 的 内 容 将 一 直 有 效 ( 以 先
出 现 情 况 的 为 准 )。
详 细 说 明
此 函 数 可 获 取 某 些 与 导 入 PDF 文 档 相 关 的 字 符 串 参 数 ; 有 些 情 况 下 , 可 使 用 page 和 索 引 进
一 步 定 义 。 表 8.46 列 出 了 相 关 参 数 组 合 。
绑 定 C 和 C++: 必 须 提 供 len 参 数 。
其 他 绑 定 : 必 须 省 略 len 参 数 ; 将 返 回 适 当 长 度 的 字 符 串 对 象 。
范 围
任 意
表 8.46 PDF 导 入 的 文 档 相 关 参 数 和 值
函 数 关 键 字 说 明
get_parameter pdi 1
如 果 附 加 了 PDI 库 , 将 返 回 字 符 串 true (PDFlib Lite 不 附 加 PDI
库 ); 否 则 , 返 回 false。 范 围 : 任 意 、 空 2 。
get_pdi_value /Root/Pages/Count 1 导 入 文 档 的 总 页 数
get_pdi_parameter filename 1
导 入 PDF 文 件 的 文 件 名 ; 如 果 文 件 是 用 PDF_open_pdi_callback( )
打 开 的 , 将 返 回 虚 文 件 名 。
get_pdi_parameter /Info/ 1 抽 取 文 档 信 息 字 典 (document info dictionary) 中 某 个 关 键 字 的 字
符 串 值 ( 例 如 /Info/Title) 作 为 超 文 本 字 符 串 。 也 可 查 询 文 档 信
息 字 典 中 的 自 定 义 关 键 字 。 如 果 无 法 在 文 档 中 找 到 关 键 字 , 将
返 回 空 字 符 串 。 但 是 , 如 果 pdiwarning 设 为 true, 将 对 无 法 找
到 的 关 键 字 引 发 异 常 。
get_pdi_parameter tagged 如 果 文 档 为 标 签 PDF, 将 返 回 true ( 因 此 无 法 在 标 签 PDF 输 出
模 式 下 导 入 )。
get_pdi_parameter pdfx 1
返 回 导 入 文 档 的 PDF/X 规 范 等 级 。 其 结 果 可 为 »PDF/X-1:2001«、
»PDF/X-1a:2001«、 »PDF/X-3:2002«、 »none« 或 指 定 较 高 PDF/X
规 范 等 级 的 字 符 串 ( 参 见 第 155 页 上 的 第 7.4 节 “PDF/X”)。
get_pdi_value version 1 PDF 版 本 号 乘 以 10, 例 如 :15 指 PDF 1.5
8.7 PDF 导 入 函 数 (PDI) 239

表 8.46 PDF 导 入 的 文 档 相 关 参 数 和 值
函 数 关 键 字 说 明
set_parameter pdiwarning 1 此 参 数 可 用 来 获 得 有 关 无 法 打 开 PDF 或 页 面 的 原 因 的 更 多 详 细
信 息 。 默 认 值 :false
true PDI 函 数 失 败 时 , 引 发 非 致 命 异 常 。 异 常 提 供 的 信 息
字 符 串 可 能 对 调 试 导 入 相 关 的 问 题 很 有 用 。
false PDI 函 数 失 败 时 , 不 引 发 异 常 。 相 反 , 出 现 错 误 时 ,
此 函 数 只 是 返 回 -1 ( 在 PHP 中 : 返 回 0)。
set_parameter pdiusebox 1 不 常 用 , 使 用 PDF_open_pdi_page( ) 中 的 pdiusebox 选 项 。
get_pdi_parameter
get_pdi_value
vdp/Blocks//
或
vdp/Blocks//
Custom/
get_pdi_value vdp/blockcount 查 询 页 面 中 块 的 总 数 。
1. page 参 数 必 须 为 -1 ( 在 PHP 中 : 返 回 0)。
2. 可 用 PDF * 的 NULL 或 0 自 变 量 调 用 。
查 询 标 准 和 自 定 义 块 属 性 ( 参 见 第 145 页 上 的 第 6.5 节 “ 询 问 块
名 及 其 属 性 ”)。 只 能 用 于 PDFlib Personalization Server (PPS)。
8.8 块 填 充 函 数 (PPS)
PDFlib Personalization Server (PPS) 提 供 了 专 用 函 数 , 来 处 理 文 本 、 图 像 和 PDF 型 变 量 数 据
块 。 这 些 块 必 须 包 含 在 导 入 PDF 页 面 内 , 但 不 会 在 生 成 输 出 中 保 留 。 使 用 任 何 块 填 充 函 数
之 前 , 导 入 页 面 必 须 已 经 放 置 在 输 出 页 面 中 。 计 算 页 面 上 的 块 位 置 时 , 块 函 数 将 使 用 相 应 的
PDF 页 面 句 柄 提 供 给 最 近 一 次 PDF_fit_pdi_page( ) 调 用 的 缩 放 选 项 。
如 果 只 需 要 处 理 块 , 而 不 用 将 页 面 的 内 容 实 际 放 置 在 输 出 中 ( 即 , 导 出 页 面 只 用 作 块 容
器 ), 则 可 以 使 用 PDF_fit_pdi_page( ) 的 blind 选 项 。 如 果 希 望 将 块 放 置 在 原 始 页 面 的 内 容 的
下 方 , 这 可 能 很 有 用 。 要 实 现 这 一 点 , 应 在 PDF_fit_pdi_page( ) 中 使 用 blind 选 项 , 根 据 需
要 填 充 块 , 然 后 再 次 调 用 PDF_fit_pdi_page( ), 且 此 次 调 用 不 使 用 blind 选 项 。
注 : 本 节 讨 论 的 块 处 理 函 数 要 求 PDFlib Personalization Server(PPS)。 在 DPF 模 板 中 创 建 块 要 求 用
于 Adobe Acrobat 的 PDFlib 块 增 效 工 具 。 有 关 PDFlib 块 增 效 工 具 的 更 多 信 息 , 参 见 第 6 章 。
C++ Java
Perl PHP
C
int fill_textblock(int page, String blockname, String text, String optlist)
int PDF_fill_textblock(resource p, int page, string blockname, string text, string optlist)
int PDF_fill_textblock(PDF *p,
int page, const char *blockname, const char *text, int len, const char *optlist)
根 据 其 属 性 , 用 变 量 数 据 填 充 文 本 块 。
page 用 于 包 含 块 的 页 面 的 有 效 PDF 页 面 句 柄 。
blockname ( 名 称 字 符 串 ) 块 的 名 称 。
text ( 内 容 字 符 串 ) 要 填 充 到 块 中 的 文 本 ; 如 果 使 用 默 认 文 本 ( 如 块 属 性 的 定 义 ), 则 为
空 字 符 串 。
len ( 仅 用 于 C 语 言 绑 定 ) UCS-2 字 符 串 的 text 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0, 则
必 须 提 供 以 null 终 结 的 字 符 串 。
optlist 选 项 列 表 , 根 据 表 8.47 指 定 详 细 的 填 充 信 息 。
返 回 值
如 果 页 面 中 不 存 在 命 名 的 块 , 不 能 填 充 块 ( 例 如 , 由 于 字 体 问 题 ) 或 者 块 的 处 理 要 求 更 高
版 本 的 PDFlib, 则 返 回 -1 ( 在 PHP 中 : 返 回 0); 如 果 可 以 成 功 处 理 块 , 则 返 回 1。 使 用
pdiwarning 选 项 可 获 得 有 关 问 题 性 质 的 更 多 信 息 。
240 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

详 细 说 明
范 围
提 供 的 文 本 将 根 据 块 的 属 性 进 行 格 式 化 , 以 填 充 至 块 中 。 如 果 text 为 空 , 此 函 数 将 使 用 块 的
默 认 文 本 ( 如 果 存 在 ); 否 则 , 不 返 回 任 何 信 息 。 这 可 能 对 利 用 填 充 色 或 描 边 色 等 其 他 块
属 性 很 有 用 。
如 果 发 现 PDF 文 档 受 到 破 坏 , 将 根 据 pdiwarning 参 数 或 选 项 引 发 异 常 , 或 者 返 回 -1。
页 面 、 模 板
注 : 此 函 数 只 能 用 于 PDFlib Personalization Server (PPS)。
C++ Java
Perl PHP
C
int fill_imageblock(int page, String blockname, int image, String optlist)
int PDF_fill_imageblock(resource p, int page, string blockname, int image, string optlist)
int PDF_fill_imageblock(PDF *p,
int page, const char *blockname, int image, const char *optlist)
根 据 其 属 性 , 用 变 量 数 据 填 充 图 像 块 。
page 用 于 包 含 块 的 页 面 的 有 效 PDF 页 面 句 柄 。
blockname ( 名 称 字 符 串 ) 块 的 名 称 。
image 要 填 充 到 块 中 的 图 像 的 有 效 图 像 句 柄 ; 如 果 要 使 用 默 认 图 像 ( 如 块 属 性 的 定 义 ),
将 为 -1。
optlist 选 项 列 表 , 根 据 表 8.47 指 定 详 细 的 填 充 信 息 。
返 回 值 如 果 页 面 中 不 存 在 命 名 的 块 , 不 能 填 充 块 或 者 块 的 处 理 要 求 更 高 版 本 的 PDFlib, 则 返 回 -1
( 在 PHP 中 : 返 回 0); 如 果 可 以 成 功 处 理 块 , 则 返 回 1。 使 用 pdiwarning 选 项 可 获 得 有 关
问 题 性 质 的 更 多 信 息 。
详 细 说 明
范 围
根 据 块 的 属 性 , 将 提 供 的 图 像 句 柄 指 向 的 图 像 置 于 块 中 。 如 果 image 为 -1 ( 在 PHP 中 : 返 回
0), 此 函 数 将 使 用 块 的 默 认 图 像 ( 如 果 存 在 ); 否 则 不 返 回 任 何 信 息 。
如 果 发 现 PDF 文 档 受 到 破 坏 , 将 根 据 pdiwarning 参 数 的 设 置 或 选 项 引 发 异 常 , 或 者 返
回 -1。
页 面 、 模 板
注 : 此 函 数 只 能 用 于 PDFlib Personalization Server (PPS)。
C++ Java int fill_pdfblock(int page, String blockname, int contents, String optlist)
Perl PHP int PDF_fill_pdfblock(resource p,
int page, string blockname, int contents, string optlist)
C int PDF_fill_pdfblock(PDF *p,
int page, const char *blockname, int contents, const char *optlist)
根 据 其 属 性 , 用 变 量 数 据 填 充 PDF 块 。
page 用 于 包 含 块 的 页 面 的 有 效 PDF 页 面 句 柄 。
blockname ( 名 称 字 符 串 ) 块 的 名 称 。
contents 要 填 充 到 块 中 的 PDF 页 面 的 有 效 PDF 页 面 句 柄 ; 如 果 要 使 用 默 认 PDF 页 面 ( 如
块 属 性 的 定 义 ), 将 为 -1。
optlist 选 项 列 表 , 根 据 表 8.47 指 定 详 细 的 填 充 信 息 。
8.8 块 填 充 函 数 (PPS) 241

返 回 值 如 果 页 面 中 不 存 在 命 名 的 块 , 不 能 填 充 块 或 者 块 的 处 理 要 求 更 高 版 本 的 PDFlib, 则 返 回 -1
( 在 PHP 中 : 返 回 0); 如 果 可 以 成 功 处 理 块 , 则 返 回 1。 使 用 pdiwarning 选 项 可 获 得 有 关
问 题 性 质 的 更 多 信 息 。
详 细 说 明 根 据 块 的 属 性 , 将 提 供 的 页 面 句 柄 contents 指 向 的 PDF 页 面 置 于 块 中 。 如 果 contents 为 -1
( 在 PHP 中 : 返 回 0), 此 函 数 将 使 用 块 的 默 认 PDF 页 面 ; 否 则 不 返 回 任 何 信 息 。
如 果 发 现 PDF 文 档 受 到 破 坏 , 将 根 据 pdiwarning 参 数 或 选 项 引 发 异 常 , 或 者 返 回 -1。
范 围
页 面 、 模 板
注 : 此 函 数 只 能 用 于 PDFlib Personalization Server (PPS)。
表 8.47 PDF_fill_*block( ) 函 数 的 选 项
关 键 字 类 型 说 明
boxsize 浮 点 值 列 表 将 块 的 宽 度 和 高 度 更 改 为 指 定 的 值 ( 用 当 前 用 户 坐 标 系 统 中 的 坐 标 表
示 )。
默 认 值 : 如 块 Rect 属 性 中 所 指 定 的 值 。
charref 布 尔 型 ( 仅 用 于 PDF_fill_textblock( )) 参 见 表 8.20
encoding 字 符 串 PDF_load_font( ) 要 求 的 字 体 编 码 方 式 。 除 非 符 合 下 列 条 件 之 一 , 否 则
PDF_fill_textblock( ) 要 求 使 用 此 选 项 :
text 参 数 中 的 字 符 串 为 空 , 且 使 用 defaulttext 属 性 。
已 经 提 供 font 选 项 。
glyphwarning 布 尔 型 ( 仅 用 于 PDF_fill_textblock( )) 参 见 表 8.19
字 体 字 体 句 柄 ( 仅 用 于 PDF_fill_textblock( )) PDF_load_font( ) 返 回 的 字 体 句 柄 。 无 默 认
值 , 必 须 提 供 font 或 fontname。
fontwarning 布 尔 型 ( 仅 用 于 PDF_fill_textblock( )) 指 定 出 现 字 体 相 关 问 题 时 , 此 函 数 是 否 会
引 发 异 常 。 默 认 值 为 pdiwarning 选 项 的 值 。
ignoreorientation 布 尔 型 ( 仅 用 于 PDF_fill_imageblock( )) 如 果 为 true, 将 忽 略 TIFF 图 像 中 的 方 向
标 记 。 默 认 值 :false
imagewarning 布 尔 型 ( 仅 用 于 PDF_fill_imageblock( )) 指 定 出 现 图 像 相 关 问 题 时 , 此 函 数 是 否
会 引 发 异 常 。 默 认 为 pdiwarning 选 项 的 值 。
pdiwarning 布 尔 型 指 定 包 含 块 的 PDF 页 面 或 用 作 块 内 容 的 页 面 中 出 现 错 误 时 , 此 函 数 是 否 会
引 发 异 常 。 默 认 值 为 pdiwarning 参 数 的 值 ( 参 见 表 8.46)。
refpoint 浮 点 值 列 表 将 块 的 左 下 角 移 至 使 用 用 户 坐 标 指 定 的 点 上 。 默 认 值 : 如 块 Rect 属 性 中 所
指 定 的 值 。
shrinklimit
浮 点 型 或 百
分 比
( 仅 用 于 PDF_fill_textblock( )) 参 见 表 8.19
textformat 字 符 串 ( 除 非 使 用 defaulttext 属 性 , 否 则 仅 用 于 PDF_fill_textblock( )) 用 来 解 释
提 供 的 文 本 的 格 式 ( 参 见 第 84 页 上 的 第 4.5.2 节 “ 内 容 字 符 串 、 超 文 本
字 符 串 和 名 称 字 符 串 ” 和 表 8.19)。 默 认 值 :auto
PDF_load_font( )
的 所 有 选 项
几 乎 任 何 属 性 名 称
( 仅 用 于 PDF_fill_textblock( ), 但 仅 限 于 没 有 提 供 font 选 项 的 情 况 ) 参 见
表 8.16
将 用 来 覆 盖 块 定 义 内 对 应 名 称 和 值 的 属 性 名 称 和 值 ( 参 见 第 138 页 上 的 第
6.4 节 “ 用 于 自 动 化 处 理 的 标 准 属 性 ”)。 有 关 详 细 信 息 , 参 见 第 131 页 上
的 第 6.2.2 节 “ 块 属 性 ”。 下 列 块 属 性 不 能 覆 盖 :
Name、 Description、 Locked、 Subtype、 Type
defaulttext、 defaultimage、 defaultpdf、 defaultpdfpage
作 为 提 供 fontname 属 性 的 变 通 , 还 可 以 使 用 font 选 项 提 供 字 体 句 柄
( 此 时 , 将 忽 略 fontname)。
颜 色 属 性 支 持 下 列 色 彩 空 间 关 键 字 :none、 gray、 rgb、 cmyk、 spot、
spotname。
242 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

8.9 超 文 本 函 数
表 8.48 列 出 了 本 节 的 相 关 参 数 及 相 应 的 值 。
表 8.48 超 文 本 函 数 的 参 数 ( 参 见 第 181 页 上 的 第 8.2.3 节 “ 参 数 处 理 ”)
函 数 关 键 字 说 明
set_parameter
get_parameter
hypertextencoding 1 指 定 客 户 端 提 供 字 符 串 时 超 文 本 函 数 期 待 的 编 码 方 式 ( 参 见 第 85 页
上 的 第 4.5.4 节 “ 不 支 持 Unicode 的 语 言 中 的 字 符 串 处 理 ”)。 空 字
符 串 相 当 于 unicode。 默 认 值 :auto。 范 围 : 任 意
set_parameter
get_parameter
hypertextformat 1
1. Java 和 Tcl 等 支 持 Unicode 的 语 言 中 不 能 使 用 此 参 数 。
设 置 客 户 端 提 供 的 字 符 串 时 超 文 本 函 数 期 待 使 用 的 格 式 。 可 能 的 值
包 括 bytes、utf8、utf16、utf16le、utf16be 和 auto。 默 认 值 :auto。
范 围 : 任 意
set_parameter usercoordinates 如 果 为 false, 将 预 计 超 文 本 矩 形 的 坐 标 使 用 默 认 坐 标 系 统 ( 参 见
第 53 页 上 的 第 3.2.1 节 “ 坐 标 系 统 ”); 否 则 , 将 使 用 当 前 用 户 坐
标 系 统 。 默 认 值 :false)。 范 围 : 任 意
8.9.1 动 作
C++ Java
Perl PHP
C
int create_action(String type, String optlist)
int PDF_create_action(resource p, string type, string optlist)
int PDF_create_action(PDF *p, const char *type, const char *optlist)
创 建 一 个 动 作 , 可 将 其 提 供 给 各 种 对 象 和 事 件 。
type 动 作 的 类 型 , 用 下 列 一 个 关 键 字 指 定 :
> GoTo: 转 到 当 前 文 档 中 的 某 个 目 标 。
> GoToR: 转 到 另 一 ( 远 程 ) 文 档 中 的 某 个 目 标 。
> Launch: 启 动 应 用 程 序 或 文 档 。
> URI: 解 析 统 一 资 源 标 识 符 , 即 : 跳 转 到 某 个 Internet 地 址 。
> Hide: 隐 藏 或 显 示 批 注 或 表 单 域 。
> Named: 执 行 由 名 称 标 识 的 Acrobat 菜 单 项 。
> SubmitForm : 将 数 据 发 送 到 统 一 资 源 定 位 符 , 即 Internet 地 址 ( 请 注 意 , 不 能 在 Acrobat
中 使 用 要 求 基 本 身 份 验 证 的 提 交 操 作 )。
> ResetForm: 将 文 档 中 的 某 些 域 或 全 部 域 设 置 为 他 们 的 默 认 值 。
> ImportData: 从 文 件 中 导 入 域 值 。
> JavaScript: 执 行 用 JavaScript 代 码 编 写 的 脚 本 。
> SetOCGState:(PDF 1.5) 隐 藏 或 显 示 图 层 。
optlist 选 项 列 表 , 根 据 表 8.49 指 定 动 作 的 属 性 。
返 回 值
详 细 说 明
动 作 句 柄 , 可 用 来 将 动 作 附 加 到 文 档 内 的 对 象 。 可 以 在 关 闭 的 文 档 范 围 结 束 之 前 使 用 动 作
句 柄 。
此 函 数 将 创 建 单 一 动 作 。 可 为 一 个 或 多 个 动 作 提 供 各 种 对 象 ( 例 如 , 页 面 、 表 单 域 事 件 、 书
签 等 ), 但 是 必 须 使 用 单 独 的 PDF_create_action( ) 调 用 生 成 每 个 动 作 。 允 许 为 不 同 的 对 象 多
次 使 用 一 个 动 作 。
范 围 页 面 、 文 档 。 在 下 一 个 PDF_end_document( ) 调 用 之 前 , 可 以 一 直 使 用 返 回 的 句 柄 。
PDF/X 所 有 PDF/X 模 式 都 禁 止 使 用 动 作 。
8.9 超 文 本 函 数 243

表 8.49 PDF_create_action( ) 的 动 作 属 性 的 选 项
选 项 类 型 说 明
actionwarning 布 尔 型 如 果 为 true, 没 有 任 何 效 果 的 动 作 选 项 将 引 发 非 致 命 异 常 。 如 果 为 false, 将 忽
略 这 些 选 项 , 而 不 返 回 任 何 信 息 。 默 认 值 :true
canonicaldate 布 尔 型 (SubmitForm) 如 果 为 true, 可 将 任 何 表 示 日 期 的 提 交 域 值 转 换 为 标 准 格 式 。 域
本 身 不 会 专 门 指 定 将 域 解 释 为 日 期 , 只 会 在 处 理 域 的 JavaScript 代 码 中 指 定 。
默 认 值 :false
defaultdir 字 符 串 (Launch) 设 置 启 动 程 序 的 默 认 目 录 。 只 有 在 Windows 上 运 行 的 Acrobat 支 持 此
选 项 。 默 认 值 :none
destination
destname
选 项
列 表
超 文 本
字 符 串
(GoTo、 GoToR ; 除 非 提 供 了 destname, 否 则 是 必 需 的 ) 选 项 列 表 , 根 据 表
8.50 定 义 要 跳 转 到 的 目 标 。
(GoTo、 GoToR ; 除 非 提 供 了 destination, 否 则 是 必 需 的 ) 用 PDF_add_
nameddest( ) 指 定 的 目 标 名 称 ( 用 于 GoTo) 或 者 远 程 文 档 中 的 目 标 的 名 称
( 用 于 GoToR)。
exclude 布 尔 型 (SubmitForm) 如 果 为 true, namelist 选 项 指 定 要 排 除 的 域 ; 除 namelist 数 组 中
列 出 的 域 以 及 exportable 选 项 为 false 的 域 之 外 , 将 提 交 文 档 中 的 所 有 域 。 如
果 为 false, namelist 选 项 指 定 提 交 操 作 中 包 括 的 域 。 将 同 时 提 交 指 定 域 组 中 的
所 有 成 员 。 默 认 值 :false
(ResetForm) 如 果 为 true,namelist 选 项 指 定 要 排 除 的 域 ; 除 namelist 数 组 中 列
出 的 域 之 外 , 将 重 设 文 档 中 的 所 有 域 。 如 果 为 false, namelist 选 项 指 定 重 设 操
作 中 包 括 的 域 。 将 同 时 重 设 指 定 域 组 中 的 所 有 成 员 。 默 认 值 :false
exportmethod 关 键 字
列 表
(SubmitForm) 提 交 域 名 称 和 域 值 时 使 用 的 格 式 , 加 上 对 应 的 选 项
( 默 认 值 :fdf):
html 使 用 HTML 格 式
fdf 使 用 FDF 格 式
xfdf 使 用 XFDF 格 式
pdf 使 用 MIME 内 容 类 型 应 用 程 序 /pdf 的 PDF 格 式
getrequest( 仅 用 于 html 和 pdf) 使 用 HTTP GET 提 交 ; 否 则 使 用 HTTP POST
updates ( 仅 用 于 fdf) 包 括 基 础 PDF 文 档 中 所 有 增 量 更 新 的 内 容 。
exclurl ( 仅 用 于 fdf) 提 交 的 FDF 将 排 除 url 字 符 串 。
annotfields ( 仅 用 于 fdf) 包 括 所 有 批 注 和 域 。
onlyuser ( 仅 用 于 fdf 和 annotfields) 提 交 操 作 将 只 包 括 其 名 称 匹 配 当 前 用 户
名 称 的 批 注 ; 具 体 由 要 将 域 提 交 到 的 远 程 服 务 器 确 定 。
coordinate( 仅 用 于 html) 将 作 为 表 单 数 据 的 一 部 分 传 送 导 致 提 交 动 作 的 鼠 标
点 击 的 坐 标 。 坐 标 值 相 对 于 域 的 矩 形 的 左 上 角 。
选 项 组 合 的 示 例 :exportmethod {fdf updates onlyuser}
filename 字 符 串 (GoToR、 Launch ; 是 必 需 的 ) 触 发 动 作 时 将 打 开 的 外 部 (PDF 或 其 他 ) 文 件
或 应 用 程 序 的 名 称 。
(ImportData ; 必 需 的 ): 包 含 表 单 数 据 的 外 部 文 件 的 文 件 名 。
hide 布 尔 型 (Hide) 指 示 是 否 隐 藏 (true) 或 显 示 (false) 批 注 。 默 认 值 :true
hypertextencoding 关 键 字 指 定 提 供 文 本 的 编 码 方 式 ( 参 见 第 85 页 上 的 第 4.5.4 节 “ 不 支 持 Unicode 的 语
言 中 的 字 符 串 处 理 ”)。 空 字 符 串 相 当 于 unicode。 默 认 值 : 全 局
hypertextencoding 参 数 的 值
ismap 布 尔 型 (URI) 如 果 为 true, 解 析 url 时 将 向 目 标 URI 添 加 鼠 标 位 置 的 坐 标 。
默 认 值 :false
layerstate
选 项
列 表
(SetOCGState ; 是 必 需 的 ) 成 对 列 表 ; 其 中 , 每 对 都 由 一 个 关 键 字 和 一 个 图
层 句 柄 组 成 。 支 持 下 列 关 键 字 :
on 启 动 图 层 。
off
toggle
停 用 图 层
变 换 图 层 的 状 态 。 如 果 使 用 此 关 键 字 , preserveradio 选 项 应 设 为
false。
244 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.49 PDF_create_action( ) 的 动 作 属 性 的 选 项 ( 续 )
选 项 类 型 说 明
menuname 字 符 串 (Named ; 是 必 需 的 ) 要 执 行 的 菜 单 项 的 名 称 。 常 用 的 名 称 包 括 nextpage、
prevpage、 firstpage、 lastpage, 但 也 可 接 受 其 他 名 称 。 要 查 找 其 他 菜 单 项 的
名 称 , 可 在 Acrobat 的 JavaScript 控 制 台 或 调 试 程 序 中 执 行 以 下 代 码 :
function MenuList(m, level) {
console.println(m.cName);
if (m.oChildren != null)
for (var i = 0; i < m.oChildren.length; i++)
MenuList(m.oChildren[i], level + 1);
}
var m = app.listMenuItems();
for (var i=0; i < m.length; i++)
MenuList(m[i], 0);
namelist
字 符 串
列 表
(Hide ; 必 需 的 ) 要 隐 藏 或 显 示 的 批 注 或 域 的 名 称 ( 包 括 组 名 )。
(SubmitForm) 提 交 操 作 中 包 括 的 或 者 要 排 除 的 表 单 域 的 名 称 ( 包 括 组 名 ), 具
体 取 决 于 exclude 选 项 的 设 置 。 默 认 值 : 除 exportable 选 项 为 false 的 域 之 外 ,
将 提 交 所 有 域 。
(ResetForm) 重 设 操 作 中 包 括 的 或 者 要 排 除 的 表 单 域 的 名 称 ( 包 括 组 名 ), 具
体 取 决 于 exclude 选 项 的 设 置 。 默 认 值 : 将 重 设 所 有 域 。
newwindow 布 尔 型 (GoToR、 Launch) 一 个 标 志 , 指 定 是 否 在 新 窗 口 中 打 开 目 标 文 档 。 如 果 此 标
志 为 false, 目 标 文 档 将 在 同 一 窗 口 内 替 换 当 前 文 档 。 Launch: 如 果 文 件 不 是
PDF 文 档 , 将 忽 略 此 项 。 默 认 值 :Acrobat 的 行 为 取 决 于 当 前 用 户 首 选 项 。
operation 关 键 字 (Launch) 一 个 关 键 字 , 指 定 应 用 到 filename 选 项 中 指 定 文 档 的 操 作 。 只 有 在
Windows 上 运 行 的 Acrobat 支 持 此 选 项 。 如 果 filename 选 项 的 目 标 是 应 用 程
序 , 而 非 文 档 , 将 忽 略 此 选 项 , 并 启 动 应 用 程 序 ( 默 认 值 :open):
open 打 开 文 档
print 打 印 文 档
parameters 字 符 串 (Launch) 要 传 递 给 filename 选 项 指 定 的 应 用 程 序 的 参 数 字 符 串 。 只 有 在
Windows 上 运 行 的 Acrobat 支 持 此 选 项 。 可 用 空 格 字 符 分 隔 多 个 参 数 , 但 每 个
参 数 不 能 包 含 任 何 空 格 字 符 。 如 果 filename 的 目 标 是 文 档 , 应 省 略 此 选 项 。 默
认 值 :none
preserveradio 布 尔 型 (SetOCGState) 如 果 为 true, 将 保 留 图 层 间 的 单 选 按 钮 状 态 关 系 。 默 认 值 :true
script
scriptname
超 文 本
字 符 串
超 文 本
字 符 串
(JavaScript ; 必 需 的 ) 包 含 待 执 行 JavaScript 代 码 的 字 符 串 。
(JavaScript) 如 果 存 在 , 将 使 用 提 供 的 名 称 , 作 为 文 档 级 JavaScript 插 入 script
选 项 中 提 供 的 JavaScript。 如 果 文 档 中 多 次 提 供 了 相 同 的 scriptname, 将 使 用
最 后 一 个 脚 本 , 所 有 其 他 脚 本 都 将 忽 略 。 文 档 级 JavaScript 将 在 文 档 载 入
Acrobat 之 后 执 行 。 这 可 能 对 用 于 表 单 域 的 脚 本 很 有 用 。
submitemptyfields 布 尔 型 (SubmitForm ; PDF 1.4) 如 果 为 true, 将 提 交 namelist 和 exclude 选 项 确 定 的
所 有 域 , 而 不 考 虑 他 们 是 否 具 有 任 何 值 。 对 于 没 有 值 的 域 , 只 传 送 域 名 称 。 如
果 为 false, 将 不 提 交 没 有 值 的 域 。 默 认 值 :false
url 字 符 串 (URI ; 必 需 的 ) 用 7 位 ASCII 或 EBCDIC ( 但 只 能 包 含 ASCII 字 符 ) 编 码 的 统 一
资 源 定 位 器 , 指 定 链 接 目 标 。 它 可 指 向 任 意 (Web 或 本 地 ) 资 源 , 必 须 以 协
议 标 识 符 开 头 ( 例 如 http://)。 textx/texty、 currentx/currenty 和
imagewidth/imageheight 参 数 可 用 来 检 索 定 位 信 息 , 以 计 算 链 接 矩 形 尺 寸 。
(SubmitForm ; 必 需 的 ) 用 URL 格 式 给 出 将 , 将 用 于 在 Web 服 务 器 端 处 理 提
交 操 作 的 脚 本 的 统 一 资 源 定 位 器 ( 地 址 )。
8.9 超 文 本 函 数 245

8.9.2 命 名 目 标
C++ Java
Perl PHP
C
void add_nameddest(String name, String optlist)
PDF_add_nameddest(resource p, string name, string optlist)
void PDF_add_nameddest(PDF *p, const char *name, int len, const char *optlist)
在 当 前 文 档 的 任 意 页 面 上 创 建 命 名 目 标 。
name ( 超 文 本 字 符 串 ) 目 标 的 名 称 , 可 用 作 链 接 、 书 签 或 其 他 触 发 器 的 目 标 。 在 一 个 文
档 内 , 目 标 名 称 必 须 是 唯 一 的 。 如 果 文 档 中 多 次 提 供 了 同 一 名 称 , 将 只 使 用 最 后 一 个 定 义 ,
所 有 其 他 定 义 都 将 忽 略 , 而 不 返 回 任 何 信 息 。
len ( 仅 用 于 C 语 言 绑 定 )UCS-2 字 符 串 的 name 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0, 则
必 须 提 供 以 null 终 结 的 字 符 串 。
optlist 选 项 列 表 , 根 据 表 8.50 指 定 目 标 。 空 列 表 相 当 于 {type fitwindow page 0}。
详 细 说 明
范 围
目 标 详 细 信 息 必 须 在 optlist 中 指 定 , 且 目 标 可 位 于 当 前 文 档 中 的 任 一 页 面 之 上 。 提 供 的 name
可 与 destname 一 起 用 于 PDF_create_action( ), PDF_create_annotation( ), PDF_create_
bookmark( ), 和 PDF_begin/end_document( ) 函 数 。 这 种 方 式 可 将 定 义 与 使 用 目 标 分 成 两 步 。
若 在 使 用 时 已 知 目 标 , 可 将 定 义 与 使 用 合 并 , 直 接 在 以 上 函 数 中 使 用 已 命 名 的
destination 选 项 。 这 种 方 式 无 需 调 用 PDF_add_nameddest( ) 函 数 。
文 档 、 页 面
表 8.50 PDF_add_nameddest( ) 的 目 标 选 项 以 及 PDF_create_action( )、 PDF_create_annotation( )、
PDF_create_bookmark( ) 和 PDF_begin/end_document( ) 中 的 目 标 选 项
选 项 类 型 说 明
group 字 符 串 ( 如 果 已 指 定 了 page 选 项 , 且 文 档 使 用 页 面 组 , 则 是 必 需 的 ; 否 则 , 不 允
许 使 用 此 选 项 。) 目 标 页 面 所 属 页 面 组 的 名 称 。
hypertextencoding 关 键 字 指 定 name 参 数 的 编 码 方 式 ( 参 见 第 85 页 上 的 第 4.5.4 节 “ 不 支 持 Unicode
的 语 言 中 的 字 符 串 处 理 ”)。 空 字 符 串 相 当 于 unicode。 默 认 值 : 全 局
hypertextencoding 参 数 的 值
hypertextformat 关 键 字 设 置 name 参 数 的 格 式 。 可 能 的 值 包 括 bytes、 utf8、 utf16、 utf16le、
utf16be 和 auto。 默 认 值 :hypertextformat 参 数 的 值
类 型 关 键 字 指 定 目 标 页 面 上 的 窗 口 位 置 ( 默 认 值 :fitwindow):
fixed 使 用 left、 top 和 zoom 选 项 指 定 的 固 定 目 标 视 图 。 如 果 缺 少 任 一 选
项 , 将 保 留 其 当 前 值 。
fitwindow 将 整 个 页 面 填 充 至 窗 口 内 。
fitwidth 根 据 窗 口 调 整 页 面 宽 度 , y 坐 标 顶 部 与 窗 口 的 上 边 缘 对 齐 。
fitheight 根 据 窗 口 调 整 页 面 高 度 , x 坐 标 左 边 与 窗 口 的 左 边 缘 对 齐 。
fitrect 将 left、 bottom、 right 和 top 指 定 的 矩 形 填 充 至 窗 口 内 。
fitvisible 将 页 面 的 可 见 内 容 ( 作 品 框 ) 填 充 至 窗 口 内 。
fitvisiblewidth
将 页 面 的 可 见 内 容 填 充 至 窗 口 内 , y 坐 标 顶 部 与 窗 口 的 上 边 缘
对 齐 。
fitvisibleheight 将 页 面 的 可 见 内 容 填 充 至 窗 口 内 , x 坐 标 左 边 与 窗 口 的 左 边
缘 对 齐 。
nameddest 已 淘 汰
name
超 文 本
字 符 串
已 淘 汰
246 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.50 PDF_add_nameddest( ) 的 目 标 选 项 以 及 PDF_create_action( )、 PDF_create_annotation( )、
PDF_create_bookmark( ) 和 PDF_begin/end_document( ) 中 的 目 标 选 项 ( 续 )
选 项 类 型 说 明
页 面 整 型 目 标 页 面 的 页 码 ( 第 一 页 为 1)。 目 标 PDF 中 必 须 存 在 此 页 面 。 在 页 面 范 围
中 , Page 0 表 示 当 前 页 面 ; 在 文 档 范 围 中 , 表 示 第 1 页 。 请 注 意 , 由 于 存 在
错 误 , Acrobat 6.0 将 忽 略 页 码 , 始 终 都 会 跳 转 到 第 1 页 。 Acrobat 6.0.1 中 已
修 复 了 这 个 错 误 , 旧 版 本 中 亦 不 存 在 此 错 误 。 默 认 值 :0
zoom
浮 点 型 或
百 分 比
( 仅 用 于 type = fixed 的 情 况 ) 用 来 显 示 页 面 内 容 的 缩 放 因 子 (1 表 示
100%)。 如 果 此 选 项 缺 失 , 或 者 为 0, 将 保 留 启 用 路 径 时 生 效 的 缩 放 因 子 。
left 浮 点 型 ( 仅 用 于 type = fixed、fitheight、fitrect 或 fitvisibleheight 的 情 况 ) 页 面 的 x
坐 标 , 位 于 窗 口 左 边 缘 。 默 认 值 :0
right 浮 点 型 ( 仅 用 于 type = fitrect 的 情 况 ) 页 面 的 x 坐 标 , 位 于 窗 口 右 边 缘 。 默 认 值 :
1000
bottom 浮 点 型 ( 仅 用 于 type = fitrect 的 情 况 ) 页 面 的 y 坐 标 , 位 于 窗 口 的 底 边 。 默 认 值 :0
top 浮 点 型 ( 仅 用 于 type = fixed、 fitwidth、 fitrect 或 fitvisiblewidth 的 情 况 ) 页 面 的 y
坐 标 , 位 于 窗 口 上 边 缘 。 默 认 值 :1000
8.9.3 注 释
C++ Java void create_annotation(double llx, double lly, double urx, double ury,
String type, String optlist)
Perl PHP PDF_create_annotation(resource p,
float llx, float lly, float urx, float ury, string type, string optlist)
C
void PDF_create_annotation(PDF *p,
double llx, double lly, double urx, double ury, const char *type, const char *optlist)
在 当 前 页 面 上 创 建 一 个 矩 形 注 释 。
llx, lly, urx, ury 用 默 认 坐 标 ( 如 果 usercoordinates 参 数 或 选 项 为 false) 或 用 户 坐 标 ( 如
果 为 true) 确 定 的 注 释 矩 形 左 下 角 和 右 上 角 的 x 和 y 坐 标 。 Acrobat 会 将 注 释 的 左 上 角 与 指
定 矩 形 的 左 上 角 对 齐 。
请 注 意 , 注 释 坐 标 不 同 于 PDF_rect( ) 函 数 的 参 数 。 PDF_create_annotation( ) 直 接 设 置 两
个 角 的 参 数 , 而 PDF_rect( ) 只 设 置 一 个 角 的 坐 标 , 及 宽 度 和 高 度 值 。
type 注 释 的 类 型 , 用 下 列 一 个 关 键 字 指 定 :
> Circle: 圆 形 注 释
> FileAttachment: 文 件 附 件 注 释 。 Acrobat Reader 5 不 能 处 理 文 件 附 件 , 将 只 显 示 一 个 问
号 。 文 件 附 件 只 适 用 于 完 全 版 的 Acrobat 软 件 。
> FreeText: 自 由 文 本 注 释
> Highlight: 高 亮 注 释
> Ink: 油 墨 注 释
> Line: 线 条 注 释
> Link: 链 接 注 释
> Polygon:(PDF 1.5) 多 边 形 注 释 ( 用 直 线 连 接 顶 点 )
> PolyLine:(PDF 1.5) 折 线 (polyline) 注 释 ; 类 似 于 多 边 形 , 但 第 一 个 和 最 后 一 个 顶 点 没 有
连 接 在 一 起 。
> Popup: 弹 出 式 注 释
> Square: 正 方 形 注 释
> Squiggly:(PDF 1.4) 曲 线 下 划 线 注 释
> Stamp: 橡 皮 图 章 注 释
8.9 超 文 本 函 数 247

StrikeOut: 删 除 线 注 释
> Text: 文 本 注 释 。 在 Acrobat 中 , 此 类 型 称 为 附 注 注 释 。
> Underline: 下 划 线 注 释
optlist 选 项 列 表 , 根 据 表 8.51 指 定 注 释 属 性 。
范 围
PDF/X
页 面
在 所 有 PDF/X 模 式 下 , 只 有 注 释 完 全 位 于 出 血 框 之 外 ( 如 果 没 有 出 血 框 , 则 应 位 于 裁 切 框
/ 作 品 框 之 外 ), 才 允 许 使 用 注 释 。
表 8.51 PDF_create_annotation( ) 的 注 释 选 项
选 项 类 型 说 明
action 动 作 列 表 下 列 事 件 的 注 释 动 作 列 表 ( 默 认 值 : 空 列 表 ):
activate 启 动 注 释 时 执 行 的 动 作 。 允 许 所 有 动 作 类 型 。
alignment 关 键 字 ( 仅 用 于 type=FreeText) 注 释 中 的 文 本 对 齐 方 式 :left、 center、 right。 此 选 项
不 能 用 于 Acrobat 6, 它 一 直 使 用 left。 默 认 值 :left
annotcolor 颜 色 关 闭 时 的 注 释 图 标 背 景 颜 色 , 注 释 弹 出 窗 口 的 标 题 栏 颜 色 以 及 链 接 注 释 的 边 框
颜 色 。 支 持 的 色 彩 空 间 :none、 gray、 rgb。 默 认 值 :none
annotwarning 布 尔 型 如 果 为 true, 没 有 任 何 效 果 的 注 释 选 项 将 引 发 非 致 命 异 常 。 如 果 为 false, 将 忽
略 这 些 选 项 , 而 不 返 回 任 何 信 息 。 默 认 值 :true
borderstyle 关 键 字 注 释 边 框 样 式 或 多 边 形 、 多 边 线 条 、 线 条 、 正 方 形 、 圆 形 和 油 墨 型 注 释 的 线 条
样 式 。solid、beveled、dashed、inset、underline。 请 注 意 ,beveled、inset 和
underline 样 式 无 法 在 Acrobat 中 可 靠 运 行 。 默 认 值 :solid
cloudy 浮 点 型 ( 仅 用 于 type=Polygon 的 情 况 ; PDF 1.5) 指 定 用 来 渲 染 多 边 形 的 辉 撇 诗 效 果
的 强 度 。 可 能 的 值 包 括 0 ( 无 效 果 )、 1 和 2。 如 果 使 用 此 选 项 , 将 忽 略
borderstyle 选 项 。 默 认 值 :0
contents
超 文 本
字 符 串
( 当 type=Text、 FreeText、 Line、 Square、 Circle、 Highlight、 Underline、
PolyLine、Polygon、Squiggly、Strikeout、Stamp、Ink、FileAttachment 时 , 是
必 需 的 ; 当 type=Link、 PopUp 时 , 是 可 选 的 ; 如 果 type=FreeText, 此 选 项 必
须 为 字 符 串 型 ) 注 释 显 示 的 文 本 或 者 ( 如 果 注 释 不 显 示 文 本 ) 注 释 内 容 的 替 代
描 述 ( 必 须 使 用 用 户 可 读 的 形 式 )。 内 容 的 最 大 长 度 为 65535 字 节 。 可 使 用 回
车 符 或 换 行 符 强 制 生 成 新 段 落 。
createdate 布 尔 型 (PDF 1.5 或 更 高 版 本 ) 如 果 为 true, 将 为 注 释 创 建 日 期 和 时 间 条 目 。 默 认 值 :
false
custom
dasharray
选 项 列 表
的 列 表
浮 点 值
列 表
( 仅 面 向 高 级 用 户 ) 可 使 用 此 选 项 , 在 注 释 词 典 内 插 入 任 意 数 量 的 专 用 条 目 ,
这 可 能 对 特 殊 的 应 用 程 序 ( 如 为 数 字 打 印 机 插 入 处 理 指 令 )。 使 用 此 选 项 要 求
用 户 熟 悉 PDF 文 件 格 式 及 目 标 应 用 程 序 。 如 果 提 供 的 值 不 合 适 , 可 能 会 生 成 损
坏 的 PDF 输 出 。 每 个 列 表 都 必 须 包 含 3 个 选 项 :
key ( 字 符 串 ) 词 典 关 键 字 的 名 称 ( 不 包 括 / 字 符 )。 可 指 定 任 何 非
标 准 的 PDF 关 键 字 , 以 及 下 列 标 准 关 键 字 :Contents、 Name ( 选
项 iconname)、 NM ( 选 项 name) 和 Open。 此 时 , 将 忽 略 对 应 的
选 项 。
type ( 关 键 字 ) 对 应 值 的 类 型 , 必 须 为 布 尔 型 、 名 称 或 字 符 串 。
value ( 如 果 type=string, 为 超 文 本 字 符 串 ; 否 则 , 为 字 符 串 ) PDF 输 出
中 显 示 的 值 ; PDFlib 将 自 动 提 供 字 符 串 和 名 称 要 求 的 任 何 修 饰 效
果 。
( 仅 用 于 borderstyle=dashed 的 情 况 )。 虚 线 边 框 的 虚 线 和 间 隙 长 度 ( 以 默 认
单 位 表 示 )( 参 见 PDF_setdash( ))。 默 认 值 :3 3
destination 选 项 列 表 ( 仅 用 于 type=Link 的 情 况 ; 若 有 活 跃 的 动 作 被 指 明 将 忽 略 此 项 ) 定 义 要 跳 转 到
的 目 标 。
destname
超 文 本 字
符 串
( 仅 用 于 type=Link 的 情 况 ; 若 destination 选 项 被 指 明 将 忽 略 此 项 ) 用 PDF_
add_nameddest( ) 定 义 的 目 标 名 称 。 Destination 或 destname 动 作 将 优 先 于 此
选 项 。
248 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.51 PDF_create_annotation( ) 的 注 释 选 项 ( 续 )
选 项 类 型 说 明
display 关 键 字 在 屏 幕 和 纸 张 上 的 可 见 性 :visible、 hidden、 noview、 noprint。 默 认 值 :
visible
endingstyles
关 键 字
列 表
( 仅 用 于 type=Line、 PolyLine 的 情 况 ) 由 两 个 关 键 字 组 成 的 列 表 , 指 定 直 线 终
点 样 式 :none、 square、 circle、 diamond、 openarrow、 closedarrow。 默 认
值 :none none
filename 字 符 串 ( 仅 用 于 type=FileAttachment 的 情 况 , 要 求 此 选 项 ) 与 注 释 关 联 的 文 件 。 建 议
只 在 filename 中 使 用 ASCII 字 符 。
fillcolor 颜 色 ( 仅 用 于 type=FreeText 的 情 况 ) 文 本 的 填 充 色 。 支 持 的 色 彩 空 间 :gray、 rgb、
cmyk。 默 认 值 :gray 0 (=black)
字 体 字 体 句 柄 ( 仅 用 于 type=FreeText 的 情 况 ; 是 必 需 的 ) 指 定 注 释 使 用 的 字 体 。 只 允 许 使 用
PDF 核 心 字 体 以 及 下 列 编 码 方 式 : 任 何 8 位 编 码 、 UCS-2 CMaps、 内 置 编 码 。
fontsize 浮 点 型 ( 仅 用 于 type=FreeText 的 情 况 ; 必 需 的 ) 根 据 usercoordinates 选 项 或 参 数 , 确
定 字 体 大 小 的 单 位 为 默 认 坐 标 系 或 用 户 坐 标 系 。
highlight 关 键 字 ( 仅 用 于 type=Link 的 情 况 ) 用 户 点 击 注 释 时 显 示 的 高 亮 模 式 :none、 invert、
outline、 push。 默 认 值 :invert
hypertextencod
ing
关 键 字
指 定 提 供 的 文 本 的 编 码 方 式 ( 参 见 第 85 页 上 的 第 4.5.4 节 “ 不 支 持 Unicode 的
语 言 中 的 字 符 串 处 理 ”)。 空 字 符 串 相 当 于 unicode。 默 认 值 : 全 局
hypertextencoding 参 数 的 值
iconname 字 符 串 ( 仅 用 于 type=Text、 Stamp、 FileAttachment 的 情 况 ) 显 示 注 释 时 使 用 的 图 标
名 称 :
type=Text ( 默 认 值 :note): comment 、 key 、 note 、
help 、 newparagraph 、 paragraph 、 insert
type=Stamp ( 默 认 值 :draft): approved、 experimental、 notapproved、
asis、 expired、 notforpublicrelease、 confidential、 final 、 sold、
departmental、 forcomment、 topsecret、 draft、 forpublicrelease。
type=FileAttachment ( 默 认 值 :pushpin):
graph 、 pushpin 、 paperclip 、 tag
interiorcolor 颜 色 ( 仅 用 于 type=Line、 PolyLine、 Square、 Circle 的 情 况 ) 分 别 指 定 注 释 直 线 终
点 、 矩 形 或 椭 圆 形 的 颜 色 。 支 持 的 色 彩 空 间 :none、 gray、 rgb。 默 认 值 :
none
line
由 4 个 浮
点 值 组 成
的 列 表
仅 用 于 type=Line 的 情 况 ; 要 求 此 选 项 ) 由 4 个 数 值 x1、 y1、 x2 和 y2 组 成 的 列
表 , 指 定 线 条 的 起 点 和 终 点 坐 标 ; 如 果 usercoordinates 参 数 为 false, 使 用 默 认
坐 标 系 ; 如 果 此 参 数 为 true, 使 用 用 户 坐 标 系 。
linewidth 整 型 注 释 边 框 宽 度 或 线 条 、 折 线 、 多 边 形 、 正 方 形 、 圆 形 和 油 墨 型 注 释 的 线 条 宽
度 , 使 用 默 认 单 位 (= pointspoints)。 如 果 linewidth = 0, 将 不 显 示 边 框 。
默 认 值 :1
locked 布 尔 型 如 果 为 true, 无 法 在 Acrobat 中 编 辑 注 释 属 性 。 默 认 值 :false
mimetype
超 文 本 字
符 串
( 仅 用 于 type=FileAttachment 的 情 况 ) 文 件 的 MIME 类 型 。 启 动 注 释 时 ,
Acrobat 将 用 它 启 动 适 当 的 应 用 程 序 。
name 字 符 串 唯 一 标 识 注 释 的 名 称 。 有 些 动 作 必 须 具 有 名 称 , 且 在 页 面 上 必 须 是 唯 一 的 。
默 认 值 :none
opacity
浮 点 型 或
百 分 比
(PDF 1.4 或 更 高 版 本 ) 不 透 明 度 的 常 数 值 (0-1 或 0%-100%), 绘 制 注 释 时 会
使 用 此 常 数 值 。 默 认 值 :1
open 布 尔 型 ( 仅 用 于 type=Text、 Popup) 如 果 为 true, 注 释 的 初 始 状 态 显 示 为 打 开 。 默 认
值 :false
parentname 字 符 串 ( 仅 用 于 type=PopUp 的 情 况 ) 注 释 的 父 级 注 释 名 称 。
8.9 超 文 本 函 数 249

表 8.51 PDF_create_annotation( ) 的 注 释 选 项 ( 续 )
选 项 类 型 说 明
polylinelist
由 1 个 或
多 个 浮 点
列 表 组 成
的 列 表
( 仅 用 于 type=Polygon、 PolyLine、 Ink, Highlight、 Underline、 Squiggly、
Strikeout 的 情 况 ; 要 求 此 选 项 ) 折 线 是 一 个 指 定 成 对 坐 标 的 浮 点 值 列 表 。 如 果
usercoordinates 选 项 为 false, 将 使 用 默 认 坐 标 系 做 参 照 ; 如 果 此 选 项 为 true,
则 使 用 用 户 坐 标 系 做 参 照 。
type=Polygon、 PolyLine、 Ink
单 一 列 表 包 含 一 条 带 有 n 个 段 的 PolyLine ( 最 少 :n=2 )。 一 条
PolyLine 是 一 个 包 含 2xn 个 浮 点 值 ( 多 对 坐 标 值 ) 的 列 表 。 这 些 点
将 用 直 线 连 接 。
例 如 :n=3: {{10 20 30 40 50 60 }}
others 列 表 包 含 n 个 子 列 表 , 每 个 子 列 表 含 有 8 个 浮 点 值 。 该 列 表 用 于 指
定 n 个 四 边 形 ( 最 少 :n=1 )。 每 个 四 边 形 都 包 含 注 释 下 方 文 本 中
的 一 个 单 词 或 一 组 连 续 单 词 。 每 个 四 边 形 的 坐 标 都 以 x4 y4 x3 y3 x1
y1 x2 y2 的 形 式 给 出 , 按 逆 时 针 方 向 指 定 四 边 形 的 顶 点 (x4 y4 为 左
上 角 )。 文 本 的 方 向 取 决 于 边 缘 连 接 (x1, y1) 和 (x2, y2)。
例 如 :n=2: {{1 2 3 4 5 6 7 8} {10 20 30 40 50 60 70 80}}
popup 字 符 串 弹 出 式 注 释 的 名 称 , 用 于 输 入 或 编 辑 此 注 释 关 联 的 文 本 。 默 认 值 :none
readonly 布 尔 型 如 果 为 true, 将 不 允 许 注 释 与 用 户 交 互 。 可 以 显 示 或 打 印 注 释 , 但 不 能 响 应 鼠
标 点 击 操 作 或 者 根 据 鼠 标 动 作 更 改 注 释 外 观 。 默 认 值 :false
rotate 布 尔 型 如 果 为 true, 将 旋 转 注 释 , 以 配 合 页 面 的 旋 转 。 否 则 , 注 释 旋 转 将 保 持 固 定 不
变 。 文 本 注 释 的 图 标 会 忽 略 此 选 项 。 默 认 值 :true
subject
title
超 文 本
字 符 串
超 文 本
字 符 串
(PDF 1.5 或 更 高 版 本 ) 简 要 描 述 注 释 说 明 的 主 题 的 文 本 。 默 认 值 :none
打 开 注 释 或 处 于 活 动 状 态 时 , 注 释 弹 出 窗 口 标 题 栏 显 示 的 文 本 标 签 ( 在
Acrobat 中 , 此 标 签 将 显 示 蛔 髡 攉 )。 标 题 的 最 大 长 度 为 255 个 单 字 节 字 符 或
126 个 Unicode 字 符 。 但 是 , 建 议 将 标 题 的 实 际 限 制 设 置 为 32 个 字 符 。 此 字 符
串 与 Acrobat 中 的 蛔 髡 攉 域 相 对 应 。 默 认 值 :none
usercoordinates 布 尔 型 如 果 为 false, 将 预 计 注 释 坐 标 和 字 体 大 小 将 使 用 默 认 坐 标 系 统 ( 参 见 第 53 页
上 的 第 3.2.1 节 “ 坐 标 系 统 ”); 否 则 , 将 使 用 当 前 用 户 坐 标 系 统 。 默 认 值 : 全
局 usercoordinates 参 数 的 值
zoom 布 尔 型 如 果 为 true, 将 缩 放 注 释 , 以 配 合 页 面 的 放 大 。 否 则 , 注 释 大 小 将 保 持 固 定 不
变 。 文 本 注 释 的 图 标 会 忽 略 此 选 项 。 默 认 值 :true
8.9.4 表 单 域
C++ Java
Perl PHP
C
void create_field(double llx, double lly, double urx, double ury,
String name, String type, String optlist)
PDF_create_field(resource p, float llx, float lly, float urx, float ury,
string name, string type, string optlist)
void PDF_create_field(PDF *p, double llx, double lly, double urx, double ury,
const char *name, int len, const char *type, const char *optlist)
根 据 各 种 选 项 , 在 当 前 页 面 上 创 建 表 单 域 。
llx, lly, urx, ury 确 定 的 表 单 矩 形 左 下 角 和 右 上 角 的 x 和 y 坐 标 ; 如 果 usercoordinates 参
数 或 选 项 为 false, 用 默 认 坐 标 系 ; 如 果 为 true), 用 户 坐 标 系 。
请 注 意 , 表 单 域 坐 标 不 同 于 PDF_rect( ) 函 数 的 参 数 。 PDF_create_field( ) 直 接 设 置 两 个 角
的 参 数 , 而 PDF_rect( ) 只 设 置 一 个 角 的 坐 标 , 及 宽 度 和 高 度 值 。
250 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

name ( 超 文 本 字 符 串 ) 表 单 域 名 称 , 可 能 会 附 加 用 PDF_create_fieldgroup( ) 创 建 的 一 个 或
多 个 组 的 名 称 前 缀 。 组 名 称 必 须 用 句 点 ».« 字 符 相 互 隔 开 , 并 同 域 名 称 隔 开 。 在 一 个 页 面 上 ,
域 名 称 必 须 是 唯 一 的 , 且 不 能 以 句 点 ».« 字 符 结 尾 。
len ( 仅 用 于 C 语 言 绑 定 ) UCS-2 字 符 串 的 text 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0, 则
必 须 提 供 以 null 终 结 的 字 符 串 。
type 域 的 类 型 , 必 须 为 下 列 值 之 一 :
> pushbutton
> checkbox
> radiobutton。 由 于 单 选 按 钮 必 须 始 终 属 于 同 一 组 , 所 以 name 必 须 附 加 组 名 称 前
缀 。 对 于 所 有 其 他 域 类 型 , 组 关 系 是 可 选 的 。
> listbox
> combobox
> textfield
> signature
optlist 一 个 选 项 列 表 , 根 据 表 8.52 指 定 域 的 属 性 。 如 此 表 所 示 , 字 符 串 选 项 将 解 释 为 超 文
本 字 符 串 或 文 本 字 符 串 。
详 细 说 明
范 围
PDF/X
默 认 情 况 下 , 页 面 上 各 域 的 跳 位 顺 序 ( 按 Tab 键 时 , 各 个 域 接 收 焦 点 的 顺 序 ) 取 决 于 PDF_
create_field( ) 调 用 的 顺 序 , 但 可 以 使 用 taborder 选 项 指 定 不 同 的 顺 序 。 创 建 域 之 后 , 便 不 能
修 改 跳 位 顺 序 。
在 Acrobat 中 , 可 以 为 文 本 域 指 定 一 个 格 式 ( 数 值 、 百 分 比 等 )。 但 PDF Reference 中
没 有 相 关 规 定 , 而 是 使 用 自 定 义 JavaScript 实 施 的 。 将 JavaScript 动 作 附 加 到 指 向 Acrobat
中 预 定 义 的 ( 而 非 标 准 化 的 )JavaScript 函 数 的 表 单 域 , 可 异 曲 同 工 。 有 关 示 例 及 更 多 信
息 , 参 见 第 66 页 上 的 第 3.4.2 节 “ 文 本 域 的 格 式 化 选 项 ”。
页 面
在 所 有 PDF/X 模 式 下 , 只 有 表 单 域 完 全 位 于 出 血 框 之 外 ( 如 果 没 有 出 血 框 , 则 应 位 于 裁 切
框 / 作 品 框 之 外 ) 时 , 才 允 许 使 用 表 单 域 。
C++ Java
Perl PHP
C
void create_fieldgroup(String name, String optlist)
PDF_create_fieldgroup(resource p, string name, string optlist)
void PDF_create_fieldgroup(PDF *p, const char *name, int len, const char *optlist)
根 据 各 种 选 项 创 建 表 单 域 组 。
name ( 超 文 本 字 符 串 ) 表 单 域 组 的 名 称 , 也 可 作 为 另 一 组 的 前 缀 。 可 以 任 意 级 别 嵌 套 域
组 。 组 名 称 必 须 用 句 点 ».« 字 符 分 隔 。 在 一 个 文 档 中 , 组 名 称 必 须 是 唯 一 的 , 且 不 能 以 句 点
».« 字 符 结 尾 。
len ( 仅 用 于 C 语 言 绑 定 ) UCS-2 字 符 串 的 text 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0, 则
必 须 提 供 以 null 终 结 的 字 符 串 。
optlist 选 项 列 表 , 根 据 表 8.52 和 表 8.53 指 定 域 属 性 。
8.9 超 文 本 函 数 251

表 8.52 PDF_create_field( ) 和 PDF_create_fieldgroup( ) 的 表 单 属 性 选 项
选 项 类 型 说 明
action 动 作 列 表 下 列 一 个 或 多 个 事 件 的 域 动 作 列 表 。 所 有 域 类 型 都 允 许 启 动 事 件 ;
type=pushbutton、 checkbox 和 radiobutton 时 , 不 允 许 使 用 其 他 事 件
( 默 认 值 : 空 列 表 ):
activate 启 动 域 时 执 行 的 动 作 。
keystroke 用 户 在 文 本 域 或 组 合 框 内 键 入 内 容 或 修 改 滚 动 列 表 框 内 的
选 定 时 , 执 行 的 JavaScript 动 作 。
format 对 域 进 行 格 式 化 以 显 示 其 当 前 值 之 前 执 行 的 JavaScript 动
作 。 这 样 便 可 以 在 格 式 化 之 前 修 改 域 的 值 。
validate 更 改 域 的 值 时 执 行 的 JavaScript 动 作 。 这 样 便 可 以 检 查 新 值
的 有 效 性 。
calculate 另 一 个 域 的 值 发 生 更 改 时 执 行 的 JavaScript 动 作 ; 这 样 可 以
重 新 计 算 此 域 的 值 。
enter 鼠 标 进 入 域 的 区 域 时 执 行 的 动 作 。
exit 鼠 标 退 出 域 的 区 域 时 执 行 的 动 作 。
down 在 域 的 区 域 内 按 下 鼠 标 按 钮 时 执 行 的 动 作 。
up 在 域 的 区 域 内 释 放 鼠 标 按 钮 时 执 行 的 动 作 ( 这 通 常 用 来 启
动 域 )。
focus 域 收 到 输 入 焦 点 时 执 行 的 动 作 。
blur 域 失 去 输 入 焦 点 时 执 行 的 动 作 。
alignment 关 键 字 域 内 文 本 的 对 齐 方 式 :left、 center、 right。 默 认 值 :left
backgroundcolor
bordercolor
颜 色
域 背 景 或 边 框 的 颜 色 。 支 持 的 色 彩 空 间 :none、 gray、 rgb、 cmyk。 默
认 值 :none
borderstyle 关 键 字 域 边 框 的 样 式 , 可 以 是 solid、 beveled、 dashed、 inset 或 underline。
默 认 值 :solid
buttonlayout 关 键 字 ( 仅 用 于 type=pushbutton 的 情 况 ) 按 钮 标 题 相 对 于 按 钮 图 标 的 位 置 ;
条 件 是 , 同 时 指 定 了 按 钮 标 题 和 按 钮 图 标 :below、above、right、left
或 overlaid。 默 认 值 :right
buttonstyle 关 键 字 ( 仅 用 于 type=radiobutton 和 checkbox 的 情 况 ) 指 定 域 使 用 的 符 号 :
check、 cross、 diamond、 circle、 star、 square。 默 认 值 :check
calcorder 整 型 ( 仅 用 于 域 具 有 计 算 事 件 的 JavaScript 动 作 的 情 况 ) 指 定 此 域 相 对 于 其
他 域 的 计 算 顺 序 。 将 先 计 算 较 小 编 码 的 域 , 然 后 计 算 较 大 编 码 的 域 。
默 认 值 :10 加 上 当 前 页 面 上 使 用 的 最 大 calcorder ( 最 初 为 10)
caption 内 容 字 符 串 ( 仅 用 于 type=pushbutton 的 情 况 , 对 于 下 压 按 钮 , 必 须 提 供 一 个 标 题
或 图 标 选 项 ) 标 题 文 本 , 按 钮 没 有 输 入 焦 点 时 将 显 示 此 文 字 。 若 不 想
有 标 题 或 图 标 , 可 用 空 字 符 串 作 为 参 数 ( 即 : caption { }) 。 默 认 值 :
none
captiondown 内 容 字 符 串 ( 仅 用 于 type=pushbutton 的 情 况 ) 启 动 按 钮 时 显 示 的 标 题 文 字 。 默 认
值 :none
captionrollover 内 容 字 符 串 ( 仅 用 于 type=pushbutton 的 情 况 ) 按 钮 具 有 输 入 焦 点 时 显 示 的 标 题 文
字 。 默 认 值 :none
charspacing 1 浮 点 型 ( 不 能 用 于 type=radiobutton 和 checkbox 的 情 况 ; Acrobat 7 忽 略 此
项 ) 域 内 文 本 的 字 符 间 距 , 用 当 前 用 户 坐 标 系 统 的 单 位 表 示 。 默 认 值 :
0
comb 布 尔 型 ( 仅 用 于 type=textfield 的 情 况 ; PDF 1.5) 如 果 为 true, multiline、
fileselect 和 password 选 项 为 false, 且 为 maxchar 选 项 提 供 了 一 个 整 数
值 , 则 针 对 具 体 的 字 符 将 域 分 割 为 几 个 等 距 离 的 子 域 ( 根 据 maxchar
值 )。 默 认 值 :false
commitonselect 布 尔 型 ( 仅 用 于 type=listbox 和 combobox 的 情 况 ; PDF 1.5) 如 果 为 true, 选
中 后 将 立 即 提 交 在 列 表 中 选 中 的 项 目 。 如 果 为 false, 将 在 退 出 域 时 提
交 所 选 项 目 。 默 认 值 :false
252 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.52 PDF_create_field( ) 和 PDF_create_fieldgroup( ) 的 表 单 属 性 选 项 ( 续 )
选 项 类 型 说 明
currentvalue ( 各 种 类 型 ) ( 不 能 用 于 type=pushbutton 和 signature 的 情 况 ) 域 的 初 始 值 。 类 型
和 默 认 值 取 决 于 域 类 型 。
checkbox, radiobutton
( 字 符 串 ) 除 Off 之 外 的 任 何 字 符 串 均 表 示 按 钮 已 启 动 ; 如
果 指 定 了 itemname 并 且 / 或 者 unisonselect 为 true, 则
Acrobat 6 将 显 示 不 确 定 的 行 为 。 字 符 串 Off 表 示 按 钮 已 停
用 。 应 为 第 一 个 按 钮 设 置 此 选 项 。 默 认 值 :Off
textfield, combobox
( 内 容 字 符 串 ) 域 的 内 容 。 默 认 值 :empty
listbox ( 整 数 值 列 表 ) itemtextlist 内 所 选 项 目 的 索 引 。 默 认 值 :
none
dasharray 浮 点 值 列 表 ( 仅 用 于 borderstyle=dashed 的 情 况 )。 虚 线 边 框 的 虚 线 和 间 隙 长 度
( 以 默 认 单 位 表 示 )( 参 见 PDF_setdash( ))。 默 认 值 :3 3
defaultvalue ( 各 种 类 型 ) ( 仅 用 于 type=textfield 或 combobox 的 情 况 ; 此 选 项 的 类 型 为 内 容 字
符 串 ) reset 动 作 之 后 的 域 值 。 类 型 和 默 认 值 与 currentvalue 选 项 相
同 。 例 外 : 对 于 listbox, 只 允 许 一 个 整 数 值 。
display 关 键 字 在 屏 幕 和 纸 张 上 的 可 见 性 :visible、 hidden、 noview、 noprint。 默 认
值 :visible
editable 布 尔 型 ( 仅 用 于 type=combobox 的 情 况 ) 如 果 为 true, 可 以 编 辑 框 中 当 前 选
中 的 文 本 。 默 认 值 :false
exportable 布 尔 型 发 生 SubmitForm 动 作 时 , 将 导 出 域 。 默 认 值 :true
fieldwarning 布 尔 型 如 果 为 true, 没 有 任 何 效 果 的 域 选 项 将 引 发 非 致 命 异 常 。 如 果 为
false, 将 忽 略 这 些 选 项 , 而 不 返 回 任 何 信 息 。 默 认 值 :true
fileselect 布 尔 型 ( 仅 用 于 type=textfield 的 情 况 ) 如 果 为 true, 域 中 的 文 本 将 视 为 一 个
文 件 名 。 默 认 值 :false
fillcolor 颜 色 文 本 的 填 充 色 。 支 持 的 色 彩 空 间 :gray、 rgb、 cmyk。 默 认 值 :gray 0
(=black)
fitmethod 关 键 字 ( 仅 用 于 type=pushbutton 的 情 况 ) 用 按 钮 内 的 icon、 icondown 和
iconrollover 选 项 提 供 的 模 板 的 放 置 方 法 ( 默 认 值 :meet):
auto 如 果 模 板 可 放 入 按 钮 内 , 则 相 当 于 meet ; 否 则 , 相 当 于
clip。
nofit 相 当 于 clip。
clip 不 缩 放 模 板 , 而 在 域 边 框 处 剪 切 模 板 。
meet 将 按 比 例 缩 放 模 板 , 使 其 可 以 置 于 按 钮 内 。
slice 相 当 于 meet。
entire 将 缩 放 模 板 , 使 其 可 以 完 全 置 于 按 钮 内 。
字 体 字 体 句 柄 ( 必 需 的 , 除 type=radiobutton 和 checkbox 这 两 种 总 是 使 用
ZapfDingbats 的 情 况 外 ))。 指 定 域 使 用 的 字 体 。 必 须 已 在 相 应 的
PDF_load_font( ) 调 用 中 设 置 了 下 列 选 项 :embedding ( 不 需 要 嵌 入 的
核 心 字 体 除 外 )、 nosubsetting、 noautocidfont。 只 允 许 下 列 编 码 方
式 :8 位 编 码 、 Unicode CMaps、 内 置 编 码
fontsize
浮 点 型 或
关 键 字
字 体 大 小 以 用 户 坐 标 系 衡 量 。 如 果 提 供 了 关 键 字 auto, 而 非 浮 点 值 ,
Acrobat 将 自 动 确 定 字 体 大 小 。 默 认 值 :auto
highlight 关 键 字 用 户 点 击 域 时 显 示 的 高 亮 模 式 :none、 invert、 outline、 push。 默 认
值 :invert
hypertextencoding 关 键 字 指 定 name 参 数 的 编 码 方 式 ( 参 见 第 85 页 上 的 第 4.5.4 节 “ 不 支 持
Unicode 的 语 言 中 的 字 符 串 处 理 ”)。 空 字 符 串 相 当 于 unicode。 默 认
值 : 全 局 hypertextencoding 参 数 的 值
hypertextformat 关 键 字 设 置 name 参 数 的 格 式 。 可 能 的 值 包 括 bytes、 utf8、 utf16、 utf16le、
utf16be 和 auto。 默 认 值 :hypertextformat 参 数 的 值
8.9 超 文 本 函 数 253

表 8.52 PDF_create_field( ) 和 PDF_create_fieldgroup( ) 的 表 单 属 性 选 项 ( 续 )
选 项 类 型 说 明
icon 2
模 板 句 柄 ( 仅 用 于 type=pushbutton 的 情 况 , 且 必 须 提 供 一 个 标 题 或 图 标 选 项 )
模 板 的 句 柄 , 按 钮 没 有 输 入 焦 点 时 将 显 示 此 句 柄 。 默 认 值 :none
icondown
iconrollover
2
模 板 句 柄
2
模 板 句 柄
( 仅 用 于 type=pushbutton 的 情 况 ) 模 板 的 句 柄 , 启 动 按 钮 时 显 示 此 句
柄 。 默 认 值 :none
( 仅 用 于 type=pushbutton 的 情 况 ) 模 板 的 句 柄 , 按 钮 具 有 输 入 焦 点 时
显 示 此 句 柄 。 默 认 值 :none
itemname 超 文 本 字 符 串 ( 仅 用 于 type=radiobutton 和 checkbox 的 情 况 ; 如 果 导 出 值 不 是 Latin
1 字 符 串 , 是 必 需 的 ) 域 的 导 出 值 。 在 一 组 中 , 多 个 单 选 按 钮 可 具 有 相
同 的 项 目 名 称 。 Acrobat 6: 即 使 位 于 不 同 的 页 面 之 上 , 一 组 中 具 有 相
同 项 目 名 称 的 复 选 框 也 会 同 时 打 开 或 关 闭 。 默 认 值 :field name
itemnamelist 超 文 本 字 符 串 ( 仅 用 于 type=listbox 和 combobox 的 情 况 , 且 是 必 需 的 ) 列 表 项 目 的
导 出 值 。 多 个 项 目 可 以 具 有 相 同 的 导 出 值 。 默 认 值 :none
itemtextlist
内 容 字 符 串
列 表
( 仅 用 于 type=listbox 和 combobox 的 情 况 ; 这 些 情 况 下 , 要 求 此 选
项 ) 列 表 内 所 有 项 目 的 文 本 内 容 。 如 果 同 时 指 定 了 itemnamelist 和
itemtextlist, 则 它 们 必 须 包 含 相 同 数 量 的 字 符 串 。
linewidth 整 型 域 边 框 的 线 宽 , 用 默 认 单 位 表 示 (= points)。 默 认 值 :1
locked 布 尔 型 如 果 为 true, 无 法 在 Acrobat 中 编 辑 域 属 性 。 默 认 值 :false
maxchar 整 型 或 关 键 字 ( 仅 用 于 type=textfield 的 情 况 ) 域 内 文 本 字 符 数 量 的 上 限 ; 如 果 没 有
限 制 , 则 指 定 关 键 字 unlimited。 默 认 值 :unlimited
multiline 布 尔 型 ( 仅 用 于 type=textfield 的 情 况 ) 如 果 为 true, 文 本 将 根 据 需 要 自 动 换
行 , 生 成 多 行 。 默 认 值 :false
multiselect 布 尔 型 ( 仅 用 于 type=listbox 的 情 况 ) 如 果 为 true, 可 选 择 列 表 内 的 多 个 项
目 。 默 认 值 :false
orientate 关 键 字 域 矩 形 内 的 内 容 的 方 向 。 north、 west、 south、 east。 默 认 值 :north
password 布 尔 型 ( 仅 用 于 type=textfield 的 情 况 ) 如 果 为 true, 将 在 输 出 时 使 用 项 目 符
号 或 星 号 模 拟 文 本 。 默 认 值 :false
position
readonly 3
浮 点 值 或 关 键
字 列 表
布 尔 型
( 仅 用 于 type=pushbutton 的 情 况 ) 在 按 钮 中 , 用 icon... 选 项 提 供 的 模
板 的 相 对 位 置 。 默 认 值 :50 50
如 果 为 true, 域 不 允 许 任 何 输 入 。 默 认 值 :false
required 布 尔 型 如 果 为 true, 提 交 表 单 时 , 域 必 须 包 含 一 个 值 。 默 认 值 :false
richtext 布 尔 型 ( 仅 用 于 type=textfield 的 情 况 ; PDF 1.5) 允 许 丰 富 的 文 本 格 式 。 如 果
为 true, fontsize 不 能 为 0, 且 fillcolor 不 能 使 用 cmyk 色 彩 空 间 。 默 认
值 :false
scrollable 布 尔 型 ( 仅 用 于 type=textfield 的 情 况 ) 如 果 为 true, 且 文 本 不 能 完 全 置 于 域
内 , 文 本 将 移 至 域 外 的 隐 藏 区 域 。 如 果 为 false, 文 本 填 满 整 个 域 时 ,
将 不 能 接 受 任 何 更 多 的 输 入 。 默 认 值 :true
sorted 布 尔 型 ( 仅 用 于 type=listbox 和 combobox 的 情 况 ) 如 果 为 true, 将 对 列 表 的
内 容 进 行 排 序 。 默 认 值 :false
spellcheck 布 尔 型 ( 仅 用 于 type=textfield 和 combobox 的 情 况 ) 如 果 为 true, 将 在 域 中
启 动 拼 写 检 查 器 。 默 认 值 :true
strokecolor 颜 色 文 本 的 描 边 色 。 支 持 的 色 彩 空 间 :gray、 rgb、 cmyk。 默 认 值 :gray 0
(=black)。
submitname 超 文 本 字 符 串 ( 建 议 只 用 于 type=pushbutton 的 情 况 ) 表 单 将 提 交 到 的 Internet 地 址
的 URL 编 码 字 符 串 。 默 认 值 :None
taborder 整 型 指 定 此 域 相 对 于 其 他 域 的 跳 位 顺 序 。 将 先 移 到 较 小 编 码 的 域 , 然 后 到
达 较 大 编 码 的 域 。 默 认 值 :10 加 上 当 前 页 面 上 使 用 的 最 大 taborder
( 页 面 上 的 第 一 个 域 为 10); 使 用 此 默 认 值 的 结 果 是 , 创 建 顺 序 将 指
定 跳 位 顺 序 。
254 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

表 8.52 PDF_create_field( ) 和 PDF_create_fieldgroup( ) 的 表 单 属 性 选 项 ( 续 )
选 项 类 型 说 明
tooltip 3
超 文 本 字 符 串 在 域 的 工 具 提 示 中 显 示 的 文 本 。 对 于 单 选 按 钮 和 按 钮 组 , Acrobat 将 一
直 使 用 组 中 第 一 个 按 钮 的 工 具 提 示 ; 其 余 的 将 被 忽 略 。 默 认 值 :none
topindex 整 型 ( 仅 用 于 type=listbox 的 情 况 ) 第 一 个 显 示 的 条 目 的 索 引 。 第 一 个 项 目
的 索 引 为 0。 默 认 值 :0
usercoordinates 布 尔 型 如 果 为 false, 域 坐 标 将 使 用 默 认 坐 标 系 统 ( 参 见 第 53 页 上 的 第 3.2.1
节 “ 坐 标 系 统 ”); 否 则 , 将 使 用 当 前 用 户 坐 标 系 统 。 默 认 值 : 全 局
usercoordinates 参 数 的 值
1. Acrobat 7 中 会 忽 略 此 选 项 。
2. 可 用 PDF_begin_template( ) 函 数 创 建 图 标 的 模 板 ; 如 果 图 标 只 包 含 一 个 图 像 , 可 向 PDF_load_image( ) 提 供 此 选 项 , 以
创 建 模 板 。
3. 对 于 type=radiobutton 的 情 况 , 此 选 项 不 能 与 PDF_create_field( ) 一 起 使 用 , 只 能 与 PDF_create_fieldgroup( ) 一 起 使 用 。
如 果 fieldwarning=true, 且 此 选 项 与 PDF_create_field( ) 一 起 使 用 , 将 发 出 警 告 。
详 细 说 明
范 围
域 组 对 镜 像 一 个 或 多 个 其 他 域 中 的 域 内 容 很 有 用 。 如 果 域 组 的 名 字 将 作 为 用 PDF_create_
field( ) 创 建 的 域 名 称 的 前 缀 提 供 一 个 域 的 名 称 , 则 新 域 将 成 为 此 组 的 一 部 分 。 域 组 optlist
中 提 供 的 所 有 域 属 性 选 项 都 将 被 其 属 下 所 有 的 域 继 承 。
页 面 、 文 档
表 8.53 PDF_create_fieldgroup( ) 的 域 属 性 的 其 他 选 项
选 项 类 型 说 明
fieldtype 关 键 字 组 中 包 含 的 域 的 类 型 :mixed、 pushbutton、 checkbox、 radiobutton、 listbox、
combobox、 textfield 或 signature。 除 非 fieldtype=mixed, 否 则 组 中 只 能 包 含 指 定
类 型 的 域 。 如 果 已 经 为 组 指 定 了 特 定 fieldtype, 将 在 所 有 包 含 的 域 中 同 时 显 示 当
前 值 ; 即 使 这 些 域 位 于 不 同 的 页 面 上 , 也 是 如 此 。 如 果 fieldtype=radiobutton,
必 须 提 供 选 项 unisonselect。 必 须 在 域 组 选 项 中 指 定 itemtextlist、 itemnamelist、
currentvalue 和 defaultvalue 选 项 , 而 非 在 单 独 域 的 选 项 中 指 定 。 默 认 值 :mixed
toggle 布 尔 型 ( 仅 用 于 type=radiobutton 的 情 况 ) 如 果 为 true, 可 通 过 单 击 启 动 或 停 用 组 内
的 单 选 按 钮 。 如 果 为 false, 只 能 通 过 点 击 启 动 , 通 过 点 击 另 一 按 钮 停 用 。 默 认
值 :false
unisonselect 布 尔 型 ( 仅 用 于 type=radiobutton 的 情 况 ; PDF 1.5) 如 果 为 true, 将 同 时 选 中 具 有 相
同 域 名 称 或 项 目 名 称 的 单 选 按 钮 。 默 认 值 :false
8.9.5 书 签
C++ Java
Perl PHP
C
int create_bookmark(String text, String optlist)
int PDF_create_bookmark(resource p, string text, string optlist)
int PDF_create_bookmark(PDF *p, const char *text, int len, const char *optlist)
根 据 各 种 选 项 创 建 书 签 主 题 。
text ( 超 文 本 字 符 串 ) 包 含 书 签 的 文 本 。text 的 最 大 长 度 为 255 个 单 字 节 字 符 (8 位 编 码 )
或 126 个 Unicode 字 符 。 但 是 , 建 议 将 text 的 实 际 限 制 设 置 为 32 个 字 符 。
len ( 仅 用 于 C 语 言 绑 定 。)UCS-2 字 符 串 的 text 长 度 ( 以 字 节 为 单 位 )。 如 果 len = 0, 则
必 须 提 供 以 null 终 结 的 字 符 串 。
optlist 一 个 选 项 列 表 , 根 据 表 8.54 指 定 书 签 的 属 性 。
返 回 值 生 成 书 签 的 句 柄 , 可 在 后 续 调 用 中 与 parent 选 项 一 起 使 用 。
8.9 超 文 本 函 数 255

详 细 说 明
范 围
此 函 数 添 加 带 有 text 的 PDF 书 签 。 除 非 已 指 定 了 destination 选 项 , 否 则 书 签 将 指 向 当 前 页
( 如 果 用 于 文 档 范 围 , 将 指 向 最 后 一 页 ; 如 在 第 一 页 之 前 使 用 , 将 指 向 第 一 页 )。
除 非 已 经 专 门 设 置 了 另 一 种 模 式 , 否 则 创 建 书 签 的 操 作 可 将 PDF_begin/end_document( )
的 openmode 选 项 设 为 bookmarks。
文 档 、 页 面
表 8.54 PDF_create_bookmark( ) 的 选 项
选 项 类 型 说 明
action 动 作 列 表 下 列 事 件 的 书 签 动 作 列 表 ( 默 认 值 :GoTo 动 作 且 在 destination 选 项 中 指 定
目 标 ):
activate 启 动 书 签 时 执 行 的 动 作 。 允 许 所 有 动 作 类 型 。
destination 选 项 列 表 ( 若 一 活 跃 的 动 作 被 指 定 , 将 忽 略 此 项 ) 选 项 列 表 , 根 据 表 8.50 指 定 书 签 目
标 。 默 认 值 : 如 果 缺 少 destination、 destname 和 action, 默 认 值 :{type
fitwindow page 0}。
destname
超 文 本
字 符 串
( 可 以 为 空 ; 若 destination 选 项 被 指 定 将 忽 略 此 项 ) 用 PDF_add_
nameddest( ) 定 义 的 目 标 名 称 。 Destination 或 destname 动 作 将 优 先 于 此 选
项 。 如 果 destname 为 空 字 符 串 ( 即 {}), 且 未 指 定 destination 或 action 选
项 , 书 签 将 不 执 行 任 何 动 作 ; 如 果 将 书 签 用 作 分 隔 符 , 这 可 能 很 有 用 。
fontstyle 关 键 字 指 定 书 签 文 本 的 字 体 样 式 :normal、 bold、 italic、 bolditalic。 默 认 值 :
normal
hypertextencoding 关 键 字 指 定 提 供 的 文 本 的 编 码 方 式 ( 参 见 第 85 页 上 的 第 4.5.4 节 “ 不 支 持 Unicode
的 语 言 中 的 字 符 串 处 理 ”)。 空 字 符 串 相 当 于 unicode。 默 认 值 : 全 局
hypertextencoding 参 数 的 值
hypertextformat 关 键 字 设 置 提 供 的 文 本 的 格 式 。 可 能 的 值 包 括 bytes、 utf8、 utf16、 utf16le、
utf16be 和 auto。 默 认 值 : 全 局 hypertextformat 参 数 的 值
index 整 型 在 父 级 书 签 内 插 入 书 签 的 位 置 所 处 的 索 引 。 可 使 用 处 于 0 到 同 一 级 别 的 书
签 数 量 之 间 的 值 , 在 父 级 书 签 内 的 指 定 位 置 上 插 入 书 签 。 可 使 用 值 -1, 作 为
当 前 级 别 的 最 后 一 个 插 入 书 签 。 默 认 值 :-1. 但 是 , 对 于 插 入 和 恢 复 的 页 面 ,
放 置 书 签 时 会 假 定 已 经 按 照 其 物 理 顺 序 生 成 了 所 有 页 面 ( 书 签 将 反 映 页 面
顺 序 )。
open 布 尔 型 如 果 为 false, 将 不 显 示 从 属 书 签 。 如 果 为 true, 将 展 开 所 有 子 级 书 签 。 默
认 值 :false
parent 书 签 句 柄 新 书 签 将 为 句 柄 中 指 定 书 签 的 从 属 书 签 。 如 果 parent=0, 将 创 建 顶 级 书 签 。
默 认 值 :0
textcolor 颜 色 指 定 书 签 文 本 的 颜 色 。 支 持 的 色 彩 空 间 :none、 gray、 rgb。 默 认 值 :rgb
{0 0 0 } (=black)
8.9.6 文 档 信 息 域
C++ Java
Perl PHP
C
C
void set_info(String key, String value)
PDF_set_info(resource p, string key, string value)
void PDF_set_info(PDF *p, const char *key, const char *value)
void PDF_set_info2(PDF *p, const char *key, const char *value, int len)
用 value 填 充 信 息 域 key。
key ( 名 称 字 符 串 ) 文 档 信 息 域 的 名 称 , 可 使 用 任 何 标 准 名 称 或 任 意 的 自 定 义 名 称 ( 参 见
表 8.55) 。 自 定 义 域 的 数 量 没 有 任 何 限 制 。 对 于 自 定 义 文 档 信 息 域 的 使 用 和 语 义 , 建 议
PDFlib 用 户 参 阅 Dublin Core Metadata 元 素 集 。 1
256 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

value ( 超 文 本 字 符 串 ) key 将 设 为 的 字 符 串 。 Acrobat 会 将 value 的 最 大 长 度 强 制 设 为
255 字 节 。 请 注 意 , 由 于 Windows 版 Adobe Reader 6 中 的 错 误 , 无 法 在 某 些 信 息 字 符 串
中 正 确 显 示 & 字 符 。
len ( 仅 用 于 PDF_set_info2( ), 且 只 适 用 于 C 语 言 绑 定 )。UCS-2 字 符 串 的 value 长 度 ( 以
字 节 为 单 位 )。 如 果 len = 0, 则 必 须 提 供 以 null 终 结 的 字 符 串 。
详 细 说 明 提 供 的 信 息 值 将 只 用 于 当 前 文 档 , 不 能 用 于 在 同 一 对 象 范 围 内 生 成 的 所 有 文 档 。
范 围 对 象 、 文 档 、 页 面 。 如 果 在 对 象 范 围 内 使 用 , 提 供 的 值 将 只 用 于 下 一 文 档 。
表 8.55 文 档 信 息 域 关 键 字 的 值
关 键 字
Subject
说 明
文 档 的 主 题
Title
文 档 的 标 题
Creator 创 建 文 档 使 用 的 软 件 ( 而 非 PDF 的 制 作 程 序 , 它 始 终 为 PDFlib)。 Acrobat 6
会 将 此 条 目 显 示 为 »Application«。
Author
Keywords
文 档 的 作 者
描 述 文 档 内 容 的 关 键 字
Trapped
指 示 是 否 已 对 文 档 应 用 陷 印 。 允 许 的 值 包 括 True、 False 和 Unknown。
除 CreationDate、 Producer 用 户 定 义 域 。 PDFlib 可 支 持 任 意 数 量 的 域 。 自 定 义 域 名 称 只 能 应 用 一 次 。 如
和 ModDate 之 外 的 任 何 名 称 果 同 一 域 名 称 出 现 多 次 , 将 只 使 用 最 后 一 次 出 现 的 域 。 另 请 参 见 PDF_begin/
end_document( ) 的 moddate 选 项 。
8.9.7 不 常 用 的 超 文 本 参 数 和 函 数
表 8.56 列 出 了 不 常 用 的 超 文 本 功 能 参 数 和 值 。
表 8.56 不 常 用 的 文 档 和 超 文 本 参 数
函 数 关 键 字 说 明
set_parameter openaction 使 用 PDF_begin/end_document( ) 中 的 action 选 项 的 关 键 字 open
set_parameter openmode 使 用 PDF_begin/end_document( ) 中 的 openmode 选 项
set_parameter hidetoolbar
hidemenubar
hidewindowui
fitwindow
centerwindow
displaydoctitle
nonfullscreenpagemode
direction
viewarea, viewclip
printarea, printclip
使 用 PDF_begin/end_document( ) 中 的 viewerpreferences 选 项
set_parameter bookmarkdest 使 用 PDF_create_bookmark( ) 中 的 action、destination、fontstyle
和 textcolor 选 项 。
set_parameter transition 使 用 PDF_begin/end_page_ext( ) 中 的 transition 选 项
set_value duration 使 用 PDF_begin/end_page_ext( ) 中 的 duration 选 项
set_parameter base 使 用 PDF_begin/end_document( ) 中 的 uri 选 项
set_parameter
launchlink:parameters
launchlink:operation
launchlink:defaultdir
使 用 PDF_create_action( ) 中 的 parameters、 operation 和
defaultdir 选 项 。
1. 参 见 dublincore.org
8.9 超 文 本 函 数 257

int PDF_add_bookmark(PDF *p, const char *text, int parent, int open)
int PDF_add_bookmark2(PDF *p, const char *text, int len, int parent, int open)
不 常 用 , 使 用 PDF_create_bookmark( )。
void PDF_add_note(PDF *p, double llx, double lly, double urx, double ury,
const char *contents, const char *title, const char *icon, int open)
void PDF_add_note2(PDF *p, double llx, double lly, double urx, double ury,
const char *contents, int contents_len, const char *title, int title_len,
const char *icon, int open)
不 常 用 , 使 用 PDF_create_annotation( ), 且 type=Text。
void PDF_attach_file(PDF *p, double llx, double lly, double urx, double ury, const char
*filename, const char *description, const char *author, const char *mimetype,
const char *icon)
void PDF_attach_file2(PDF *p, double llx, double lly, double urx, double ury, const char
*filename, int len, const char *description, int desc_len, const char *author,
int author_len, const char *mimetype, const char *icon)
不 常 用 , 使 用 PDF_create_annotation( ), 且 type=FileAttachment。 description 参 数 对 应 于
contents 选 项 , author 参 数 对 应 title 选 项 , icon 参 数 对 应 iconname 选 项 。
void PDF_add_pdflink(PDF *p, double llx, double lly, double urx, double ury,
const char *filename, int page, const char *optlist)
不 常 用 , 使 用 PDF_create_action( ) (type=GoToR) 和 PDF_create_annotation( )
(type=Link)。
void PDF_add_locallink(PDF *p,
double llx, double lly, double urx, double ury, int page, const char *optlist)
不 常 用 , 使 用 PDF_create_action( )(type=GoTo) 和 PDF_create_annotation( )(type=Link)。
void PDF_add_launchlink(PDF *p, double llx, double lly, double urx, double ury,
const char *filename)
不 常 用 , 使 用 PDF_create_action( ) (type=Launch) 和 PDF_create_annotation( )
(type=Link)。
void PDF_add_weblink(PDF *p, double llx, double lly, double urx, double ury, const char *url)
不 常 用 , 使 用 PDF_create_action( )(type=URI) 和 PDF_create_annotation( )(type=Link)。
void PDF_set_border_style(PDF *p, const char *style, double width)
不 常 用 , 使 用 PDF_create_annotation( ) 中 的 borderstyle 和 linewidth 选 项 。
258 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

void PDF_set_border_color(PDF *p, double red, double green, double blue)
不 常 用 , 使 用 PDF_create_annotation( ) 中 的 annotcolor 选 项 。
void PDF_set_border_dash(PDF *p, double b, double w)
不 常 用 , 使 用 PDF_create_annotation( ) 中 的 dasharray 选 项 。
8.10 标 签 PDF 的 结 构 函 数
PDF_begin_document( ) 中 的 tagged 选 项 必 须 已 设 为 true, 方 可 生 成 标 签 PDF ; 同 时 , 还 必
须 提 供 lang 选 项 。
C++ Java
Perl PHP
C
int begin_item(String tag, String optlist)
int PDF_begin_item(resource p, string tag, string optlist)
int PDF_begin_item(PDF *p, const char *tag, const char *optlist)
用 作 为 选 项 提 供 的 属 性 打 开 结 构 元 素 或 其 他 内 容 项 目 。
tag 根 据 表 8.57 指 定 项 目 的 元 素 类 型 。 必 须 为 当 前 PDF 兼 容 级 别 所 允 许 的 一 种 标 准 结 构 类
型 或 者 是 伪 标 签 。
表 8.57 标 准 项 目 标 签
种 类
分 组
段 落 类 型
列 表
标 签
Document、 Part、 Art、 Sect、 Div、 BlockQuote、 Caption、 TOC、 TOCI、 Index、
NonStruct、 Private
P、 H、 H1-H6 (BLSE)
L、 LI、 Lbl、 LBody (BLSE)
表 Table (BLSE)、 TR、 TH、 TD、 THead 1 、 TBody 1 、 TFoot 1
内 嵌 级 别
1. 要 求 PDF 1.5 或 以 上
Span、 Quote、 Note、 Reference、 BibEntry、 Code、 (ILSE)
插 图
Figure、 Formula、 Form
日 语 Ruby 1 ( 分 组 )、 RB 1 、 RT 1 、 RP 1 、 Warichu 1 ( 分 组 )、 WT 1 、 WP 1
伪 标 签 下 列 标 签 可 创 建 不 属 于 结 构 元 素 的 项 目 :
Artifact 指 定 伪 像 , 以 区 分 实 际 的 页 面 内 容 。
ASpan
( 可 访 问 性 范 围 , 将 作 为 Span 写 入 PDF, 但 必 须 区 别 于 内 嵌 级 别 项 目
Span) 可 用 于 向 不 属 于 结 构 元 素 或 只 与 结 构 元 素 部 分 相 似 的 内 容 附 加 可 访
问 性 属 性 。
ReversedChars
指 定 从 右 到 左 书 写 的 语 言 的 文 本 使 用 相 反 的 字 符 顺 序 。 这 样 便 可 在 Acrobat
中 搜 索 希 伯 来 语 或 阿 拉 伯 语 文 本 。
Clip
指 定 标 记 的 剪 裁 顺 序 。 这 只 是 个 序 列 , 只 包 含 剪 切 路 径 或 以 渲 染 模 式 7 显
示 的 文 本 , 而 不 包 含 显 示 的 图 形 或 PDF_save( ) / PDF_restore( )。
optlist 选 项 列 表 , 根 据 表 8.58 指 定 项 目 的 详 细 信 息 。 子 级 元 素 将 继 承 所 有 可 继 承 的 设 置 ,
因 此 无 需 重 复 设 置 。 因 为 此 后 便 无 法 更 改 , 所 以 必 须 在 此 处 设 置 项 目 的 所 有 属 性 。
返 回 值 项 目 句 柄 , 可 用 于 后 续 的 项 目 相 关 调 用 。
8.10 标 签 PDF 的 结 构 函 数 259

详 细 说 明
范 围
此 函 数 可 生 成 文 档 的 结 构 树 , 这 是 标 签 PDF 的 根 本 。 新 元 素 在 结 构 树 中 的 位 置 可 用 parent
和 index 选 项 控 制 。 可 以 任 意 级 别 嵌 套 结 构 元 素 。 常 规 项 目 不 仅 限 于 已 在 其 上 打 开 的 页 面 ,
可 在 任 意 数 量 的 页 面 上 继 续 。
对 于 内 嵌 项 目 , 范 围 仅 限 于 页 面 ; 常 规 项 目 还 包 括 文 档 范 围 ; 必 须 始 终 与 对 应 的 PDF_end_
item( ) 调 用 成 对 使 用 。 只 允 许 在 标 签 PDF 模 式 下 使 用 此 函 数 。
表 8.58 PDF_begin_item( ) 的 结 构 和 伪 标 签 属 性 选 项
选 项 类 型 说 明
Alt 超 文 本 字 符 串 ( 除 具 有 ASpan 的 PDF 1.5 外 , 不 能 用 于 伪 标 签 ) 内 容 项 目 的 替 代 描
述 。 应 为 插 图 和 图 像 等 提 供 替 代 描 述 , 但 不 会 识 别 为 文 本 。 为 了 实 现
可 访 问 性 , 必 须 为 图 像 提 供 替 代 文 本 。 如 果 在 PDF 1.4 模 式 下 使 用 此 选
项 , inline 选 项 必 须 设 为 false。
ActualText 超 文 本 字 符 串 ( 除 具 有 ASpan 的 PDF 1.5 外 , 不 能 用 于 伪 标 签 ; 对 于 不 兼 容 Unicode
的 字 体 的 文 本 , 这 是 必 需 的 ) 与 内 容 项 目 相 当 的 替 换 文 本 。 对 于 以 某
些 非 标 准 的 方 式 显 示 的 文 本 内 容 , 应 提 供 此 选 项 , 例 如 连 字 、 插 图 中
的 花 饰 字 符 和 首 字 下 沉 等 。 如 果 在 PDF 1.4 模 式 下 使 用 此 选 项 , inline
选 项 必 须 设 为 false。
artifacttype 关 键 字 ( 仅 用 于 tag=Artifact 的 情 况 ) 标 识 内 容 项 目 的 伪 像 类 型 :
Pagination、 Layout 或 Page
Attached 关 键 字 列 表 ( 仅 用 于 tag=Artifact 和 artifacttype=Pagination 的 情 况 ) 一 个 列 表 ,
包 含 1 到 4 个 关 键 字 Top、 Bottom、 Left 和 Right。
BBox 矩 形 ( 仅 用 于 tag=Artifact 的 情 况 以 及 所 有 表 和 插 图 标 签 ; 可 选 , 但 建 议 进
行 重 排 时 使 用 ) 伪 像 的 定 界 框 ; 如 果 usercoordinates 为 false, 用 默 认
坐 标 系 做 参 照 ; 如 果 usercoordinates 为 true, 用 用 户 坐 标 系 做 参 照 。
如 果 未 提 供 此 选 项 , PDFlib 将 自 动 为 导 入 的 图 像 和 PDF 页 面 创 建 BBox
条 目 。
ColSpan 整 型 一 个 单 元 格 所 跨 的 表 列 数 。
E 超 文 本 字 符 串 ( 不 能 用 于 除 ASpan 的 伪 标 签 ; 结 构 标 签 要 求 PDF 1.5) 内 容 项 目 的 全
名 缩 写 的 扩 展 。 应 提 供 此 选 项 , 以 说 明 缩 写 。 Acrobat 的 Read Alound
功 能 会 把 扩 展 文 本 视 为 单 独 的 词 ; 即 使 缺 少 显 式 断 字 符 , 也 是 如 此 。
hypertextencoding 关 键 字 指 定 提 供 的 文 本 的 编 码 方 式 ( 参 见 第 85 页 上 的 第 4.5.4 节 “ 不 支 持
Unicode 的 语 言 中 的 字 符 串 处 理 ”)。 空 字 符 串 相 当 于 unicode。 默 认
值 : 对 于 支 持 Unicode 的 语 言 绑 定 , 为 空 字 符 串 ; 否 则 , 为 auto。
index 整 型 ( 不 能 用 于 伪 标 签 ) 在 父 级 元 素 内 插 入 元 素 的 位 置 所 处 的 索 引 。 可 使
用 处 于 0 到 当 前 子 级 元 素 数 量 之 间 的 值 , 在 父 级 元 素 内 的 指 定 位 置 上
插 入 项 目 。 可 使 用 值 -1, 作 为 最 后 一 个 项 目 插 入 此 元 素 。 默 认 值 :-1
inline 布 尔 型 ( 仅 用 于 tag=ASpan 的 情 况 以 及 所 有 内 嵌 级 别 标 签 ) 如 果 为 true, 将
以 内 嵌 方 式 写 入 内 容 项 目 , 而 不 创 建 结 构 元 素 。 默 认 值 :true
Lang 字 符 串 ( 不 能 用 于 除 ASpan 的 伪 标 签 ) 内 容 项 目 的 语 言 标 识 符 , 使 用 有 关
lang 选 项 的 表 8.5 中 描 述 的 格 式 。 此 选 项 可 用 来 覆 盖 具 体 内 容 项 目 的
文 档 主 要 语 言 。
parent 项 目 句 柄 ( 不 能 用 于 伪 标 签 ) 另 一 PDF_begin_item( ) 调 用 返 回 的 元 素 父 级 的 项
目 句 柄 。 值 0 指 结 构 树 的 根 部 。 -1 指 当 前 页 面 上 、 距 上 次 打 开 时 间 最
久 的 元 素 的 父 级 。 换 言 之 , parent=-1 可 打 开 当 前 元 素 的 同 级 元 素 。 默
认 值 :-1
RowSpan 整 型 一 个 单 元 格 所 跨 的 表 行 数 。
Title 超 文 本 字 符 串 ( 不 能 用 于 内 嵌 标 签 和 伪 标 签 ) 结 构 元 素 的 名 称
260 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

C++ Java
Perl PHP
C
void end_item(int id)
PDF_end_item(resource p, int id)
void PDF_end_item(PDF *p, int id)
关 闭 结 构 元 素 或 其 他 内 容 项 目 。
id 项 目 的 句 柄 , 必 须 由 PDF_begin_item( ) 返 回 。
详 细 说 明
所 有 内 嵌 项 目 都 必 须 在 页 面 结 束 之 前 关 闭 。 所 有 常 规 项 目 都 必 须 在 文 档 结 束 之 前 关 闭 。 但
是 , 强 烈 建 议 完 成 操 作 后 尽 快 关 闭 所 有 常 规 项 目 , 以 减 少 内 存 消 耗 。 只 有 先 关 闭 所 有 子 级 项
目 , 才 能 关 闭 当 前 项 目 。 如 果 项 目 关 闭 , 它 的 父 级 将 成 为 现 用 项 目 。
范 围 对 于 内 嵌 项 目 , 范 围 仅 限 于 页 面 ; 常 规 项 目 还 包 括 文 档 范 围 ; 必 须 始 终 与 对 应 的 PDF_
begin_item( ) 调 用 成 对 使 用 。 只 允 许 在 标 签 PDF 模 式 下 使 用 此 函 数 。
C++ Java
Perl PHP
C
void activate_item(int id)
PDF_activate_item(resource p, int id)
void PDF_activate_item(PDF *p, int id)
启 动 以 前 创 建 的 结 构 元 素 或 其 他 内 容 项 目 。
id 项 目 的 句 柄 , 必 须 由 PDF_begin_item( ) 返 回 , 且 尚 未 关 闭 。 不 能 启 动 伪 项 目 和 内 嵌 级 别
项 目 。
详 细 说 明
存 储 一 个 结 构 元 素 并 在 以 后 启 动 可 实 现 更 大 的 灵 活 性 , 以 便 高 效 地 创 建 标 签 PDF ; 即 使 页
面 上 由 多 个 平 行 的 结 构 分 支 。 例 如 : 中 断 主 文 本 的 多 列 版 面 或 文 本 插 入 等 。 有 关 更 多 详 细 信
息 , 参 见 第 161 页 上 的 第 7.5.3 节 “ 启 动 复 杂 布 局 的 项 目 ”。
范 围 文 档 、 页 面 ; 只 允 许 在 标 签 PDF 模 式 下 使 用 此 选 项 。
8.10 标 签 PDF 的 结 构 函 数 261

262 第 8 章 : 用 于 PDFlib、 PDI 和 PPS 的 API 参 考

A 相 关 文 献
[1] Adobe Systems Incorporated:《PDF Reference, Fifth Edition: Version 1.6》。 可 从
partners.adobe.com/public/developer/pdf/index_reference.html 下 载 PDF 版 本
[2] 以 下 图 书 由 PDFlib 的 主 要 作 者 编 撰 , 只 提 供 德 语 版 本 。 本 书 讨 论 了 各 种 PostScript、PDF
和 字 体 相 关 主 题 :
Thomas Merz, Olaf Drümmer:《 Die PostScript- & PDF-Bibel》。
Zweite Auflage。 ISBN 3-935320-01-9, PDFlib Edition 2002
PDFlib GmbH, 80331 München, Tal 40, 传 真 :+49 • 89 • 29 16 46 86
可 免 费 提 供 PDF 版 本 , 下 载 网 址 :www.pdflib.com
如 需 订 购 印 刷 版 本 , 请 发 邮 件 至 books@pdflib.com
A 相 关 文 献 263

BPDFlib 快 速 参 考
常 规 参 数
函 数 范 例
页 面
void PDF_boot(void) 171
void PDF_shutdown(void) 171
PDF *PDF_new(void) 171
PDF *PDF_new2(void (*errorhandler)(PDF *p, int errortype, const char *msg), void* (*allocproc)(PDF *p, size_t size,
const char *caller), void* (*reallocproc)(PDF *p, void *mem, size_t size, const char *caller), void (*freeproc)(PDF *p,
void *mem), void *opaque) 171
void PDF_delete(PDF *p) 172
int PDF_begin_document(PDF *p, const char *filename, int len, const char *optlist) 173
void PDF_begin_document_callback(PDF *p, size_t (*writeproc) (PDF *p, void *data, size_t size), const char
*optlist) 173
void PDF_end_document(PDF *p, const char *optlist) 175
PDF_begin_document( ) 和 PDF_end_document( ) 的 文 档 选 项 175
PDF_begin/end_document( ) 中 labels 选 项 和 PDF_begin/end_page_ext( ) 中 label 选 项 的 子 选 项 177
void PDF_end_page_ext(PDF *p, const char *optlist) 178
PDF_begin_page_ext( ) 的 选 项 178
void PDF_resume_page(PDF *p, const char *optlist) 180
double PDF_get_value(PDF *p, const char *key, double modifier) 181
void PDF_set_value(PDF *p, const char *key, double value) 181
const char * PDF_get_parameter(PDF *p, const char *key, double modifier) 181
void PDF_set_parameter(PDF *p, const char *key, const char *value) 182
void PDF_create_pvf(PDF *p, const char *filename, int len, const void *data, size_t size, const char *optlist) 182
int PDF_delete_pvf(PDF *p, const char *filename, int len) 183
int PDF_get_errnum(PDF *p) 183
PDF_create_pvf( ) 的 选 项 183
const char *PDF_get_apiname(PDF *p) 184
void *PDF_get_opaque(PDF *p) 184
const char *PDF_utf16_to_utf8(PDF *p, const char *utf16string, int len, int *size) 185
const char *PDF_utf8_to_utf16(PDF *p, const char *utf8string, const char *ordering, int *size) 185
字 体 函 数
函 数 范 例
页 面
int PDF_load_font(PDF *p, const char *fontname, int len, const char *encoding, const char *optlist) 187
void PDF_setfont(PDF *p, int font, double fontsize) 189
void PDF_begin_font(PDF *p, char *fontname, int reserved, double a, double b, double c, double d, double e,
double f, const char *optlist) 189
void PDF_end_font(PDF *p) 190
void PDF_begin_glyph(PDF *p, char *glyphname, double wx, double llx, double lly, double urx, double ury) 190
void PDF_end_glyph(PDF *p) 190
void PDF_encoding_set_char(PDF *p, const char *encoding, int slot, const char *glyphname, int uv) 191
B PDFlib 快 速 参 考 265

文 本 输 出 函 数
函 数 范 例
页 面
PDF_begin_font( ) 的 选 项 190
void PDF_show(PDF *p, const char *text) 193
void PDF_xshow(PDF *p, const char *text, int len, const double *xadvancelist) 193
void PDF_show_xy(PDF *p, const char *text, double x, double y) 194
void PDF_continue_text(PDF *p, const char *text) 194
void PDF_fit_textline(PDF*p, const char *text, int len, double x, double y, const char *optlist) 195
double PDF_stringwidth(PDF *p, const char *text, int font, double fontsize) 197
int PDF_create_textflow(PDF *p, const char *text, int len, const char *optlist) 198
const char *PDF_fit_textflow(PDF *p, int textflow, double llx, double lly, double urx, double ury, const char *optlist) 199
double PDF_info_textflow(PDF *p, int textflow, const char *keyword) 201
PDF_fit_textline( ) 的 格 式 化 选 项 195
图 形 函 数
函 数 范 例
页 面
void PDF_setdash(PDF *p, double b, double w) 206
void PDF_setdashpattern(PDF *p, const char *optlist) 207
void PDF_setflat(PDF *p, double flatness) 207
PDF_info_textflow( ) 的 关 键 字 201
void PDF_setlinecap(PDF *p, int linecap) 207
void PDF_setmiterlimit(PDF *p, double miter) 208
PDF_fit_textflow( ) 的 选 项 列 表 宏 定 义 和 宏 调 用 206
void PDF_initgraphics(PDF *p) 209
void PDF_save(PDF *p) 209
void PDF_restore(PDF *p) 209
void PDF_translate(PDF *p, double tx, double ty) 210
void PDF_scale(PDF *p, double sx, double sy) 210
void PDF_rotate(PDF *p, double phi) 210
void PDF_skew(PDF *p, double alpha, double beta) 211
void PDF_concat(PDF *p, double a, double b, double c, double d, double e, double f) 211
void PDF_setmatrix(PDF *p, double a, double b, double c, double d, double e, double f) 211
int PDF_create_gstate(PDF *p, const char *optlist) 211
void PDF_set_gstate(PDF *p, int gstate) 212
void PDF_moveto(PDF *p, double x, double y) 213
void PDF_lineto(PDF *p, double x, double y) 213
void PDF_curveto(PDF *p, double x1, double y1, double x2, double y2, double x3, double y3) 214
void PDF_circle(PDF *p, double x, double y, double r) 214
void PDF_arc(PDF *p, double x, double y, double r, double alpha, double beta) 214
void PDF_arcn(PDF *p, double x, double y, double r, double alpha, double beta) 215
void PDF_rect(PDF *p, double x, double y, double width, double height) 216
void PDF_closepath(PDF *p) 216
void PDF_stroke(PDF *p) 216
266 附 录 B: PDFlib 快 速 参 考

函 数 范 例
页 面
void PDF_closepath_stroke(PDF *p) 217
void PDF_fill(PDF *p) 217
void PDF_fill_stroke(PDF *p) 217
void PDF_closepath_fill_stroke(PDF *p) 217
void PDF_clip(PDF *p) 218
void PDF_endpath(PDF *p) 218
int PDF_define_layer(PDF *p, const char *name, int len, const char *optlist) 218
void PDF_set_layer_dependency(PDF *p, const char *type, const char *optlist) 219
void PDF_begin_layer(PDF *p, int layer) 220
void PDF_end_layer(PDF *p) 220
颜 色 函 数
函 数 范 例
void PDF_setcolor(PDF *p, const char *fstype, const char *colorspace, double c1, double c2, double c3, double c4) 221
int PDF_makespotcolor(PDF *p, const char *spotname, int reserved) 222
int PDF_load_iccprofile(PDF *p, const char *profilename, int len, const char *optlist) 223
PDF_define_layer( ) 的 选 项 218
void PDF_end_pattern(PDF *p) 224
int PDF_shading_pattern(PDF *p, int shading, const char *optlist) 225
void PDF_shfill(PDF *p, int shading) 225
int PDF_shading(PDF *p, const char *shtype, double x0, double y0, double x1, double y1, double c1, double c2,
double c3, double c4, const char *optlist) 225
页 面
图 像 函 数
函 数 范 例
页 面
int PDF_load_image(PDF *p, const char *imagetype, const char *filename, int len, const char *optlist) 227
void PDF_close_image(PDF *p, int image) 231
void PDF_fit_image(PDF *p, int image, double x, double y, const char *optlist) 231
int PDF_begin_template(PDF *p, double width, double height) 233
PDF_shading_pattern( ) 的 选 项 225
void PDF_add_thumbnail(PDF *p, int image) 233
PDF 导 入 函 数 (PDI)
函 数 范 例
页 面
PDF_shading( ) 的 选 项 226
int PDF_open_pdi_callback(PDF *p, void *opaque, size_t filesize, size_t (*readproc)(void *opaque, void *buffer,
size_t size), int (*seekproc)(void *opaque, long offset), const char *optlist) 234
void PDF_close_pdi(PDF *p, int doc) 235
PDF_load_image( ) 的 选 项 228
void PDF_close_pdi_page(PDF *p, int page) 237
B PDFlib 快 速 参 考 267

函 数 范 例
页 面
PDF_fit_image( ) 和 PDF_fit_pdi_page( ) 的 选 项 231
int PDF_process_pdi(PDF *p, int doc, int page, const char* optlist) 237
double PDF_get_pdi_value(PDF *p, const char *key, int doc, int page, int reserved) 238
const char * PDF_get_pdi_parameter(PDF *p, const char *key, int doc, int page, int reserved, int *len) 239
块 填 充 函 数 (PPS)
函 数 范 例
页 面
int PDF_fill_textblock(PDF *p, int page, const char *blockname, const char *text, int len, const char *optlist) 240
int PDF_fill_imageblock(PDF *p, int page, const char *blockname, int image, const char *optlist) 241
int PDF_fill_pdfblock(PDF *p, int page, const char *blockname, int contents, const char *optlist) 241
超 文 本 函 数
函 数 范 例
页 面
int PDF_create_action(PDF *p, const char *type, const char *optlist) 243
void PDF_add_nameddest(PDF *p, const char *name, int len, const char *optlist) 246
void PDF_create_annotation(PDF *p, double llx, double lly, double urx, double ury, const char *type, const char *optlist) 247
void PDF_create_field(PDF *p, double llx, double lly, double urx, double ury, const char *name, int len, const char
*type, const char *optlist) 250
void PDF_create_fieldgroup(PDF *p, const char *name, int len, const char *optlist) 251
int PDF_create_bookmark(PDF *p, const char *text, int len, const char *optlist) 255
void PDF_set_info(PDF *p, const char *key, const char *value) 256
加 标 签 PDF 和 结 构 函 数
函 数 范 例
页 面
PDF_create_annotation( ) 的 注 释 选 项 248
void PDF_end_item(PDF *p, int id) 261
void PDF_activate_item(PDF *p, int id) 261
参 数 和 值
种 类 函 数 关 键 字
设 置
set_
resourcefile、 SearchPath、 license、 licensefile、 warning、 asciifile、 trace、
parameter tracefile、 logmsg
set_value compress
版 本 get_value major、 minor、 revision
get_parameter version
页 面 get_value pagewidth、 pageheight
字 体
set_
parameter
get_parameter
set_value
get_value
FontAFM、 FontPFM、 FontOutline、 Encoding、 fontwarning、 kerning、
autosubsetting、 autocidfont、 textformat、 unicodemap
fontname、 fontencoding、 fontstyle、 textformat
subsetlimit、 subsetminsize
ascender、capheight、descender、font、fontsize、fontmaxcode、monospace
268 附 录 B: PDFlib 快 速 参 考

种 类 函 数 关 键 字
文 本 set_value leading、 textrise、 horizscaling、 textrendering、 charspacing、 wordspacing、
italicangle、 underlinewidth、 underlineposition
图 形
颜 色
get_value
set_
parameter
get_parameter
set_
parameter
get_parameter
get_value
set_
parameter
set_value
get_value
leading、 textrise、 horizscaling、 textrendering、 charspacing、 wordspacing、
textx、 texty、 italicangle、 underlinewidth、 underlineposition
autospace、 underline、 overline、 strikeout、 kerning、 glyphwarning
underline、 overline、 strikeout、 fontstyle
fillrule、 topdown
scope
currentx、 currenty、 ctm_a、 ctm_b、 ctm_c、 ctm_d、 ctm_e、 ctm_f
iccwarning、 honoriccprofile、 ICCProfile、 StandardOutputIntent、
renderingintent、 preserveoldpantonenames、 spotcolorlookup
defaultgray、 defaultrgb、 defaultcmyk、 setcolor:iccprofilegray、
setcolor:iccprofilergb、 setcolor:iccprofilecmyk
image:iccprofile、 icccomponents
图 形 get_value imagewidth、 imageheight、 orientation、 resx、 resy
set_
imagewarning
parameter
PDI get_parameter pdi
set_
pdiwarning
parameter
get_pdi_value /Root/Pages/Count、 /Rotate、 version、 width、 height
CropBox、BleedBox、ArtBox、TrimBox: 这 些 关 键 字 后 必 须 跟 随 斜 线 ’/’ 字 符 并
附 加 llx、 lly、 urx 或 ury 之 一 , 例 如 :CropBox/llx
超 文 本
get_pdi_
parameter
set_
parameter
get_parameter
filename、 /Info/、 vdp/Blocks//、
vdp/Blocks//Custom/
hypertextformat、 hypertextencoding、 usercoordinates
hypertextformat
B PDFlib 快 速 参 考 269

C 修 订 历 史 记 录
日 期
更 改
2006 年 2 月 23 日 > 有 关 PDFlib 6.0.3 的 各 种 更 新 和 修 正 , 并 增 加 RUBY 绑 定 的 扩 展
2005 年 8 月 9 日 > 有 关 PDFlib 6.0.2 的 各 种 更 新 和 修 正
2004 年 11 月 17 日 > 有 关 PDFlib 6.0.1 的 小 范 围 更 新 和 修 正
> 第 8 章 中 介 绍 了 语 言 特 定 函 数 范 例 的 新 格 式
> 第 3 章 增 加 了 超 文 本 示 例
2004 年 6 月 18 日 > 重 要 的 PDFlib 6 更 改
2004 年 1 月 21 日 > 有 关 PDFlib 5.0.3 的 小 范 围 内 容 增 加 和 修 正
2003 年 9 月 15 日 > 有 关 PDFlib 5.0.2 的 小 范 围 内 容 增 加 和 修 正 , 并 增 加 了 块 规 范
2003 年 5 月 26 日 > 有 关 PDFlib 5.0.1 的 小 范 围 更 新 和 修 正
2003 年 3 月 26 日 > 有 关 for PDFlib 5.0.0 的 小 范 围 更 改 和 内 容 改 写
2002 年 6 月 14 日 > 有 关 PDFlib 4.0.3 的 小 范 围 更 改 以 及 有 关 .NET 绑 定 的 扩 展
2002 年 1 月 26 日 > 有 关 PDFlib 4.0.2 的 小 范 围 更 改 以 及 有 关 IBM eServer 版 本 的 扩 展
2001 年 5 月 17 日 > 有 关 PDFlib 4.0.1 的 小 范 围 更 改
2001 年 4 月 1 日 > 增 添 PDFlib 4.0.0 的 PDI 及 其 他 功 能
2001 年 2 月 5 日 > 增 添 PDFlib 3.5.0 中 的 模 板 和 CMYK 功 能
2000 年 12 月 22 日 > ColdFusion 文 档 以 及 PDFlib 3.03 相 关 增 加 内 容 ; 编 制 专 门 的 COM 版 手 册
2000 年 8 月 8 日 > Delphi 文 档 及 有 关 PDFlib 3.02 的 小 范 围 内 容 增 加
2000 年 7 月 1 日 > 有 关 PDFlib 3.01 的 增 加 内 容 和 相 关 澄 清
2000 年 2 月 20 日 > 有 关 PDFlib 3.0 的 更 改
1999 年 8 月 2 日 > 有 关 PDFlib 2.01 的 小 范 围 更 改 及 内 容 增 加
1999 年 6 月 29 日 > 增 添 特 定 语 言 绑 定 的 专 门 章 节
> 有 关 PDFlib 2.0 的 扩 展
1999 年 2 月 1 日 > 有 关 PDFlib 1.0 的 小 范 围 更 改 ( 未 公 开 发 布 )
1998 年 8 月 10 日 > 有 关 PDFlib 0.7 的 扩 展 ( 仅 面 向 一 位 客 户 )
1998 年 7 月 8 日 > 第 一 次 尝 试 描 述 PDFlib 0.6 中 的 PDFlib 脚 本 支 持
1998 年 2 月 25 日 > 小 幅 扩 充 手 册 以 涵 盖 PDFlib 0.5
1997 年 9 月 22 日 > 第 一 次 公 开 发 布 PDFlib 0.4 及 本 手 册
270 附 录 C: 修 订 历 史 记 录

索 引
数 字
16 位 编 码 83
8 位 编 码 78
A
Adobe 字 体 规 格 (AFM) 72
AFM (Adobe 字 体 规 格 ) 72
All 专 色 名 称 222
alpha 通 道 118
alphaisshape gstate 选 项 212
antialias 选 项 226
API ( 应 用 程 序 编 程 接 口 )
参 考 167
ArtBox 55
AS/400 52
ascender 90
ascender 参 数 186
asciifile 参 数 52, 170
Author 域 257
auto 文 本 格 式 87
autocidfont 参 数 77, 78, 186
autospace 函 数 191
autosubsetting 参 数 77, 78, 186
安 全 性 152
B
Bezier 曲 线 214
Big 5 97
BleedBox 55
blendmode gstate 选 项 212
BMP 117
builtin 编 码 81
byte 文 本 格 式 87
bytes
请 参 见 hypertextformat
byteserving 154
绑 定 19
编 码 78
CJK 95
超 文 本 87
从 系 统 获 取 80
自 定 义 80
编 码 参 数 186
表 单 域
转 换 为 块 136
标 准 输 出 173
标 准 页 面 大 小 55
不 可 见 文 本 192
C
C 绑 定 24
内 存 管 理 27
C++ 绑 定 28
内 存 管 理 29
capheight 90
参 数 186
CCITT 117
CCSID 80
CFF (Compact Font Format) 69
charref 参 数 191
charspacing 参 数 191
CIE L*a*b* 色 彩 空 间 60
CJK ( 中 文 、 日 文 、 韩 文 )
标 准 字 体 93
Windows 代 码 页 97
自 定 义 字 体 97
CMap 93, 96
CMYK 颜 色 57
Cobol 绑 定 19
compress 参 数 170
COM ( 组 件 对 象 模 型 ) 绑 定 24
copyoutputintent 选 项 158
CPI ( 字 符 / 英 寸 ) 91
Creator 域 257
CropBox 55
currentx 和 currenty 参 数 90, 213
裁 剪 框 238, 240
裁 切 框 238, 240
参 数 处 理 函 数 181
超 文 本 字 符 串 84
在 不 支 持 Unicode 的 语 言 中 86
程 序 结 构 45
出 血 框 238, 240
垂 直 书 写 模 式 94, 95
错 误 处 理 46
API 172
D
defaultgray/rgb/cmyk 参 数 63
descender 90
descender 参 数 186
dpi 计 算 115
Dublin Core 256
打 印 机 字 体 ASCII (PFA) 72
打 印 机 字 体 二 进 制 (PFB) 72
打 印 机 字 体 规 格 (PFM) 72
代 码 页
基 于 Unicode 的 83
索 引 271

Microsoft Windows 1250-1258 79
单 位 53
当 前 点 56
导 入 PDF 文 档 中 的 信 息 关 键 字 239
等 宽 字 体 91
对 称 210
对 齐 方 式 (position 选 项 ) 196
多 页 图 像 文 件 120
E
EBCDIC 52
ebcdic 编 码 79
ebcdicutf8
请 参 见 hypertextformat
EJB (Enterprise Java Bean) 30
eServer zSeries and iSeries 52
EUDC 字 体 73
EUDC ( 终 端 用 户 定 义 的 字 符 ) 98
extend0 和 extend1 选 项 226
F
fillrule 参 数 216
flatness gstate 选 项 212
FontAFM 参 数 186
fontencoding 参 数 186
fontmaxcode 参 数 82, 186
fontname 参 数 186
FontOutline 参 数 186
FontPFM 参 数 186
fontsize 函 数 186
FontSpecific 编 码 81
fontstyle 参 数 186
fontwarning 参 数 47, 186
form XObjects 56
范 围 45
分 色 色 彩 空 间 57
附 件 84
G
gaiji 字 符 69
GBK 97
GIF 117
glyphwarning 参 数 191
grid.pdf 53
gstate 225
公 制 坐 标 53
光 栅 图 像
函 数 227
规 格 90
H
HKS 专 色 60
honoriccprofile 参 数 227
horizscaling 参 数 192
HostFont 参 数 186
HTML 字 符 引 用 87
hypertextencoding 参 数 87, 243
hypertextformat 参 数 86, 243
函 数 范 围 45
韩 文 93, 96, 97
行
虚 线 和 样 式 206
行 的 虚 线 样 式 206
行 间 距 90
毫 米 53
核 心 字 体 76
横 向 模 式 179
环 境 变 量 PDFLIBRESOURCE 51
J
Java 绑 定 29
包 29
EJB 30
javadoc 30
servlet 30
Java 应 用 程 序 服 务 器 30
IBM eServer 52
icccomponents 参 数 224
ICCProfile 参 数 224
iccwarning 参 数 224
JFIF 116
ignoremask 119
image:iccprofile 参 数 62, 227
imagewarning 参 数 227
imagewidth 和 imageheight 参 数 227
Johab 97
JPEG 116
JPEG2000 116
iSeries 52
ISO 10646 83
ISO 15930\n 155
ISO 8859-2 到 ISO 8859-15 79
italicangle 参 数 192
基 线 压 缩 116
基 于 ICC 的 颜 色 57
加 密 152
渐 变 58
剪 切 56
镜 像 210
K
kerning 参 数 91, 192
Keywords 域 257
可 移 植 文 档 格 式 (PDF) 参 考 手 册 263
口 令 152
块 129
属 性 131
增 效 工 具 129
块 的 变 量 数 据 处 理 240
快 速 Web 查 看 174
272 索 引

L
leading 90
leading 参 数 192
license 参 数 170
licensefile 参 数 170
linecap gstate 选 项 212
linejoin gstate 选 项 212
linewidth gstate 选 项 212
LWFN (LaserWriter 字 体 ) 72
利 用 块 进 行 数 据 变 量 处 理 129
临 时 磁 盘 空 间 要 求 154
路 径 56
绘 制 和 剪 切 216
轮 廓 文 本 192
M
Mac OS
UPR 配 置 49
macroman 编 码 78, 79
macroman_apple 编 码 82
major 参 数 170
makepsres 实 用 工 具 49
masterpassword 153
MediaBox 55
metadata 176
minor 参 数 170
miterlimit gstate 选 项 212
monospace 参 数 186
“ 每 次 一 页 ” 下 载 154
蒙 版 118
蒙 版 的 118
蒙 版 图 像 118
描 边 56
名 称 字 符 串 84
在 不 支 持 Unicode 的 语 言 中 86
模 板 56
默 认 坐 标 系 统 53
N
N 选 项 226
.NET 绑 定 32
None 专 色 名 称 222
内 存 管 理
API 172
使 用 C++ 29
用 C 27
内 嵌 图 像 115
内 容 字 符 串 84
在 不 支 持 Unicode 的 语 言 中 85
O
opacityfill gstate 选 项 212
opacitystroke gstate 选 项 212
OpenType 字 体 69
orientation 参 数 227
overline 参 数 92, 192
overprintfill gstate 选 项 212
overprintmode gstate 选 项 212
overprintstroke gstate 选 项 212
欧 元 字 符 82
P
PANTONE 专 色 59
PDF 导 入 函 数 234
PDF 导 入 库 (PDI) 121, 234
PDF 的 导 入 函 数 234
PDF/X 155
导 入 PDF 文 档 158
输 出 方 法 238
PDF/X 的 标 准 输 出 条 件 157
PDF/X 的 输 出 方 法 156
PDF/X 的 输 出 条 件 156
PDF_activate_item() 261
PDF_add_nameddest() 246
PDF_add_thumbnail() 233
PDF_arc() 214
PDF_arcn() 215
PDF_begin_document() 173
PDF_begin_font() 189
PDF_begin_glyph() 190
PDF_begin_item() 259
PDF_begin_layer() 220
PDF_begin_page_ext() 178
PDF_begin_pattern 224
PDF_begin_template() 233
PDF_boot() 171
PDF_circle() 214
PDF_clip() 218
PDF_close_image() 231
PDF_closepath() 216
PDF_closepath_fill_stroke() 217
PDF_closepath_stroke() 217
PDF_close_pdi() 235
PDF_close_pdi_page() 237
PDF_concat() 211
PDF_continue_text() 194
PDF_continue_text2() 194
PDF_create_action() 243
PDF_create_annotation() 247
PDF_create_bookmark() 255
PDF_create_field() 250
PDF_create_fieldgroup() 251
PDF_create_gstate() 211
PDF_create_pvf() 182
PDF_create_textflow() 198
PDF_curveto() 214
PDF_define_layer() 218
PDF_delete() 172
PDF_delete_dl( ) 172
PDF_delete_pvf() 183
PDF_delete_textflow() 202
PDF_encoding_set_char() 191
PDF_end_document() 175
PDF_end_font() 190
索 引 273

PDF_end_glyph() 190
PDF_end_item() 261
PDF_end_layer() 220
PDF_endpath() 218
PDF_end_pattern() 224
PDF_end_template() 233
PDF_fill() 217
PDF_fill_imageblock() 241
PDF_fill_pdfblock() 241
PDF_fill_stroke() 217
PDF_fill_textblock() 240
PDF_fit_image() 231
PDF_fit_pdi_page() 237
PDF_fit_textflow() 199
PDF_fit_textline() 195
PDF_get_apiname() 184
PDF_get_buffer() 51, 177
PDF_get_errmsg() 184
PDF_get_errnum() 183
PDF_get_opaque() 184
PDF_get_parameter() 181
PDF_get_pdi_parameter() 239
PDF_get_pdi_value() 238
PDF_get_value() 181
PDF_info_textflow() 201
PDF_initgraphics() 209
PDFlib
程 序 结 构 45
功 能 13
PDFlib 程 序 结 构 45
PDFlib 的 功 能 13
PDFlib 的 可 用 性 19
PDFlib Personalization Server 129, 240
pdflib.upr 51
PDFLIBRESOURCE 环 境 变 量 51
PDF_lineto() 213
PDF_load_font() 187
PDF_load_iccprofile() 223
PDF_load_image() 227
PDF_makespotcolor() 222
PDF_moveto() 213
PDF_new() 171
PDF_new2() 171
PDF_new_dl( ) 171
PDF_open_pdi() 234
PDF_open_pdi_callback() 234
PDF_open_pdi_page() 236
PDF_process_pdi() 237
PDF_rect() 216
PDF_restore() 209
PDF_resume_page() 180
PDF_rotate() 210
PDF_save() 209
PDF_scale() 210
PDF_setcolor() 221
PDF_setdash() 206
PDF_setdashpattern() 207
PDF_setflat() 207
PDF_setfont() 189
PDF_set_gstate() 212
PDF_set_info() 256
PDF_set_info2() 256
PDF_set_layer_dependency() 219
PDF_setlinecap() 207
PDF_setlinejoin() 207
PDF_setlinewidth() 208
PDF_setmatrix() 211
PDF_setmiterlimit() 208
PDF_set_parameter() 51, 182
PDF_set_text_pos() 193
PDF_set_value() 181
PDF_shading() 225
PDF_shading_pattern() 225
PDF_shfill() 225
PDF_show() 193
PDF_show2() 193
PDF_show_xy() 194
PDF_show_xy2() 194
PDF_shutdown() 171
PDF_skew() 211
PDF_stringwidth() 197
PDF_stringwidth2() 197
PDF_stroke() 216
PDF_suspend_page() 180
PDF_translate() 210
PDF_utf16_to_utf8() 185
PDF_utf8_to_utf16() 185
PDF_xshow() 193
PDI 121, 234
PDI 的 filename 参 数 239
PDI 的 pdfx 参 数 158, 239
PDI 的 vdp/Block 参 数 240
PDI 的 vdp/blockcount 参 数 240
PDI 的 version 参 数 239
PDI 的 宽 度 和 高 度 参 数 238
pdi parameter 239
pdiwarning 参 数 123, 240
pdiusebox 122
pdiusebox 参 数 240
Perl 绑 定 32
PFA ( 打 印 机 字 体 ASCII) 72
PFB ( 打 印 机 字 体 二 进 制 ) 72
PFM ( 打 印 机 字 体 规 格 ) 72
PHP 绑 定 33
PNG 116, 118
PostScript 字 体 69, 72
PPS (PDFlib Personalization Server) 129
PPS (PDFlib Personalization Server) 240
preserveoldpantonenames parameter 221
print_glyphs.ps 73
Python 绑 定 36
批 注 84
评 估 图 章 9
平 滑 混 合 58
平 台 19
274 索 引

Q
嵌 入 系 统 19
嵌 入 字 体 76
倾 斜 211
权 限 152, 153
R
r0 和 r1 选 项 226
REALbasic 绑 定 37
renderingintent 参 数 227
renderingintent gstate 选 项 212
renderingintent 选 项 61
resourcefile 参 数 51, 170
resx 和 resy 参 数 227
RGB 颜 色 57
RPG 绑 定
39
Ruby binding 37
日 文 93, 96, 97
软 蒙 版 118
S
S/390 52
scope 参 数 170
SearchPath 参 数 50, 170, 186
servlet 30
setcolor
iccprofilegray/rgb/cmyk parameters 62
setcolor:iccprofilegray/rgb/cmyk 参 数 224
Shift-JIS 97
smoothness gstate 选 项 212
SPIFF 116
spotcolorlookup 参 数 221
sRGB 色 彩 空 间 62
StandardOutputIntent 参 数 224
stdout 通 道 173
strikeout 参 数 92, 192
strokeadjust gstate 选 项 212
Subject 域 257
subsetlimit 参 数 78, 186
subsetminsize 参 数 78, 186
Symbol 字 体 81
上 标 90, 192
商 业 许 可 证 10
设 置 函 数 170
生 成 的 PDF 文 件 输 出 到 内 存 51
输 出 准 确 性 56
书 写 模 式 94, 95
水 平 书 写 模 式 94, 95
说 明 符 76
宿 主 编 码 78
宿 主 字 体 71
缩 放 图 像 115
缩 览 图 233
索 引 色 彩 空 间 58
T
Tcl 绑 定 43
textformat 参 数 86, 192
textknockout gstate 选 项 212
textrendering 参 数 93, 192
textrise 参 数 192
textx 和 texty 参 数 90, 95, 192
TIFF 117
多 页 120
Title 域 257
topdown 参 数 54, 172
ToUnicode CMap 71, 83
trace、 tracefile、 logmsg 参 数 170
Trapped 域 257
TrimBox 55
TrueType 字 体 69
TTC (TrueType 集 合 ) 73, 97, 98
TTF (TrueType 字 体 ) 69
Type 1 字 体 72
Type 3 ( 用 户 定 义 的 ) 字 体 74
提 示 标 记 9
填 充 56
透 明 度 118
问 题 119
图 案 58
图 层 和 PDI 122
图 像 函 数 227
图 像 蒙 版 118, 119
图 像 数 据 , 重 用 115
图 像 缩 放 115
图 像 文 件 格 式 116
图 形 函 数 206
图 形 状 态
显 式 211
图 形 状 态 函 数 206
W
U+XXXX 编 码 83
warning 参 数 47, 183
version 参 数 170
UHC 97
winansi 编 码 79
Windows 的 样 式 名 称 73
Windows 的 字 体 样 式 名 称 73
underline 参 数 92, 192
underlineposition 参 数 192
underlinewidth 参 数 192
Unicode 83
unicodemap 参 数 83, 186
wordspacing 参 数 192
UPR (Unix PostScript 资 源 ) 49
文 件 格 式 49
文 件 搜 索 51
usercoordinates 参 数 53, 243
userpassword 153
utf16
请 参 见 hypertextformat
索 引 275

utf16be
请 参 见 hypertextformat
utf16le
请 参 见 hypertextformat
utf8
请 参 见 hypertextformat
网 页 优 化 PDF 174
网 页 优 化 的 PDF 154
伪 字 体 样 式 92
文 本 变 体 90
文 本 规 格 90
文 本 函 数 186
文 本 流
内 嵌 选 项 列 表 202
文 本 流 的 内 嵌 选 项 列 表 202
文 本 位 置 90
文 档 和 页 面 函 数 172
文 档 信 息 域 84, 256
文 件 附 件 84
X
xheight 90
XMP 元 数 据 176
XObjects 56
系 统 编 码 支 持 80
下 标 90, 192
显 式 透 明 度 118
显 式 图 形 状 态 211
线 性 化 PDF 174
线 性 化 的 PDF 154
像 素 取 样 115
信 息 域 256
许 可 证 PDFlib 和 PDI 9
渲 染 方 法 61
选 项 列 表 168
选 项 列 表 中 的 布 尔 值 168
选 项 列 表 中 的 单 字 符 值 169
选 项 列 表 中 的 动 作 列 表 169
选 项 列 表 中 的 浮 点 型 和 整 型 值 169
选 项 列 表 中 的 关 键 字 169
选 项 列 表 中 的 句 柄 169
选 项 列 表 中 的 矩 形 169
选 项 列 表 中 的 列 表 值 169
选 项 列 表 中 的 颜 色 值 169
选 项 列 表 中 的 字 符 串 86
选 项 列 表 中 的 字 符 串 值 168
旋 转 导 入 PDF 页 面 中 的 项 目 238
旋 转 对 象 54
Y
亚 洲 字 体 包 93
颜 色 57
颜 色 函 数 221
演 示 图 章 9
页 120
页 格 式 55
页 面 大 小 格 式 55
Acrobat 中 的 限 制 55
页 面 说 明 53
异 常 46
隐 式 透 明 度 118
英 寸 53
用 户 定 义 的 (Type 3) 字 体 74
用 户 空 间 53
用 于 建 立 块 的 Acrobat 增 效 工 具 129
用 于 建 立 块 的 增 效 工 具 129
优 化 的 PDF 154
语 言 绑 定
请 参 见 绑 定
原 始 图 像 数 据 118
Z
ZapfDingbats 字 体 81
zSeries 52
在 内 存 中 生 成 PDF 文 档 51
着 色 58
值
参 见 参 数
中 文 93, 96, 97
注 解 84
专 色 ( 分 色 色 彩 空 间 ) 57, 58
自 定 义 编 码 80
字 符 / 英 寸 91
字 符 规 格 90
字 符 集 78
字 符 名 称 73
字 符 引 用 87
字 节 顺 序 标 记 (BOM) 86
字 距 调 整 91
子 路 径 56
自 上 而 下 的 坐 标 54
字 体
AFM 文 件 72
等 宽 91
OpenType 69
PDF 核 心 集 76
PFA 文 件 72
PFB 文 件 72
PFM 文 件 72
PostScript 69, 72
嵌 入 76
说 明 符 76
TrueType 69
Type 1 72
Type 3 74
Type 3 ( 用 户 定 义 的 ) 字 体 74
Unicode 支 持 83
亚 洲 字 体 包 93
用 户 定 义 的 (Type 3) 74
有 关 嵌 入 的 法 律 事 宜 77
字 形 名 称 73
资 源 配 置 49
字 体 参 数 186
字 体 规 格 90
字 体 样 式 92
276 索 引

字 体 子 集 化 77
字 形 ID 寻 址 82
资 源 的 类 别 49
资 源 类 别 49
坐 标 范 围 56
坐 标 系 统 53
公 制 53
自 上 而 下 54
作 品 框 238, 240
索 引 277

278 索 引