第 7 章 - 1 富文本简介

最新推荐文章于 2022-11-19 11:31:28 发布

weijiasihai

最新推荐文章于 2022-11-19 11:31:28 发布

阅读量991

点赞数

分类专栏： Domino 文章标签： Domino C API

Domino 专栏收录该内容

4 篇文章

订阅专栏

本文介绍了Domino和Notes中使用的富文本字段结构及其应用。富文本字段能够存储混合属性的文本、表格等对象。文章详细阐述了富文本字段的高级与低级访问方式，包括使用CAPI函数进行操作的方法。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

介绍

Domino和Notes使用富文本字段来存储各种对象，包括文本，表，文档链接，位图和OLE链接。相对于其他类型的字段，富文本字段具有以下几个优点：

富文本中的段落可以具有混合属性，例如缩进，对齐和间距
富文本中的文本即可具有混合属性，例如字体，颜色和点大小
单个富文本字段可以保存几兆字节的数据

本章介绍富文本格式的结构，并说明如何访问构成富文本字段的各个CD记录。后面的章节解释文档链接，OLE链接和其他对象的详细信息。

创建富文本

用于Domino和Notes的IBM C API提供了创建富文本的高级和低级方法。高层次的方式很简单但有限。低级方法很复杂，但可以访问高级功能，如表，弹出窗口和OLE链接。

高级访问富文本

CompoundTextxxx系列的C API函数提供了创建富文本的高级方法。这些函数实现富文本的抽象，允许C API代码将富文本字段视为对象。我们将这个富文本对象称为“复合文本上下文”。使用以下函数创建，删除和操作复合文本作为对象：

- CompoundTextCreate
  CompoundTextDefineStyle
  CompoundTextInitStyle
  CompoundTextAddText
  CompoundTextAddParagraph
  CompoundTextAddDocLink
  CompoundTextAddRenderedNote
  CompoundTextAssimilateItem
  CompoundTextAssimilateFile
  CompoundTextDiscard
  CompoundTextClose

使用这些高级功能创建包含文本和文档链接的富文本字段。文本可以有任何类型的面孔或段落样式。这些高级功能的一个优点是使用它们的C API程序不需要执行主机/规范转换以便移植到诸如UNIX之类的平台。

有关这些功能的更多信息，请参考。 例如用法，参见示例程序EASYRICH。

对富文本的低级访问

要利用富文本的高级功能（如表，弹出窗口和OLE链接），C API程序必须访问构成富文本字段的各个CD记录。

富文本的低级结构

注释中的富文本字段由一个或多个项目组成的数据类型TYPE_COMPOSITE。单个富文本字段可以由TYPE_COMPOSITE类型的多个项组成，只要所有项具有相同的名称即可。

项目中的数据类型TYPE_COMPOSITE由一系列记录称为CD记录组成。（“CD”代表“复合文件”或“复合数据”）

要将一个TYPE_COMPOSITE项目添加到注释中，请准备一个由一系列CD记录组成的缓冲区，然后使用NSFItemAppend将该缓冲区附加到注释。缓冲区中的数据必须是Domino规范格式。

注意：某些C API程序在访问富文本格式的低级结构时不会执行主机/规范转换。对于只在Intel架构平台（如Windows）上运行的程序，规范转换不是绝对必要的。但是，不执行主机/规范转换的源代码将不会在诸如UNIX之类的平台上运行。执行主机/规范转换的源代码将在Domino和Notes支持的任何平台上运行。有关规范格式要求的详细信息，请阅读本指南中的“Domino规范格式”一章。

要准备CD记录的缓冲区，依次初始化每个CD结构，然后使用ODSWriteMemory将每个CD结构转换为Domino规范格式。将规范格式结果存储在缓冲区中作为下一个CD记录。

Domino和Notes定义许多不同类型的CD记录。 C API头文件editods.h包含每个CD结构的类型定义。

每个CD记录都以标题开头，其以签名字节开始。签名字节标识报头的类型和后面的CD记录的类型。

在文件ods.h中定义的三种类型的头是BSIG，WSIG和LSIG。每个头部包括长度成员，其指定CD记录的整个长度，包括头部。代码可以使用此长度来从一个记录的开始偏移到下一个记录的开始。

注意：在复合数据缓冲器中，每个CD记录必须在偶数字节边界上开始。如果给定CD记录的长度成员是奇数，则下一个CD记录在给定记录的开始之后开始长度+ 1字节。

还要注意，您使用CD记录的ODSLength而不是数据结构的“sizeof”初始化CD记录头的长度成员。 length成员必须以Domino规范格式指定记录的长度。

富文本必须满足一组大小限制。首先，任何CD记录的总大小受标题中长度字段的大小限制。对于具有字节签名（BSIG）的记录，总大小限制为254字节。对于具有字签名的记录，总大小限制为大约64k。实际限制由常量MAXONESEGSIZE指定。

第二，任何富文本项的大小必须小于MAXONESEGSIZE。如果富文本项目超过此大小，则必须将其存储为具有相同名称的单独项目。 Domino或Notes将在从文件读取记录时按顺序汇编这些项目。

第三，一个富文本段的总大小也限制为MAXONESEGSIZE。但是，大型元素（如位图，元文件和文件附件）不包括在段落的存储大小中，并且不会计入此限制。创建富文本时，必须插入CDPARAGRAPH记录，以确保段数据（如CDTEXT记录）不超过此限制。

最后，存储在磁盘上的富文本记录的大小可能与Domino或Notes在内部操作记录时所需的存储空间不同。其他存储可用于仅适用于Notes用户界面的信息。为了允许这种扩展，对富文本项或段落的大小的实际限制是大约40k。

C API提供了EnumCompositeBuffer函数来简化CD记录的缓冲区解析。

例

包含文本的简单富文本字段中的数据由一系列四个CD记录组成。

- CDPABDEFINITION
  CDPARAGRAPH
  CDPABREFERENCE
  CDTEXT

CDPABDEFINITION结构定义段落的“样式”。此结构包含用于指定边距，线对齐，制表符和其他样式属性的字段。每个CDPABDEFINITION都有一个唯一的ID。富文本字段中的后续段落使用此ID来标识定义其样式的CDPABDEFINITION。每个CDPABDEFINITION结构可以由富文本字段中的许多段落使用。

CDPARAGRAPH结构标记每个新段落的开始。富文本字段由一个或多个段落组成。

CDPABREFERENCE结构指定在当前段落中使用哪个段落样式。如果没有为段落指定CDPABREFERENCE，则使用上一段落的样式。

注意：CDPABREFERENCE结构仅引用已定义的样式。不允许转发对样式定义的引用。虽然不是必需的，但我们建议您在缓冲区的开头定义所有样式，以便可以根据需要引用样式。

CDTEXT结构定义文本运行的开始。 CDTEXT的FontID成员指定此文本行的颜色，大小和字体。实际的文本字符串被追加到紧跟在CDTEXT结构之后的缓冲区。

在文档中写入富文本字段

本节检查示例程序DYNAMIC。 DYNAMIC在数据库中创建一个文档，并将多个字段附加到文档，包括一个富文本字段。

以下代码片段通过设置包含四个CD记录的缓冲区在文档中创建一个富文本字段。它通过初始化数据结构，然后将结构转换为Domino规范格式来创建每个CD记录。它将转换后的规范数据存储在缓冲区中。准备缓冲区后，它调用NSFItemAppend将缓冲区附加到文档作为富文本字段的数据值。

下图描述了由代码片段创建的缓冲区中的数据。该图不是按比例绘制的。富文本字段中的结构大小变化很大。

段定义 - CDPABDEFINITION

段标题 - CDPARAGRAPH

段落参考 - CDPABREFERENCE

文本标题 - CDTEXT

“你好，世界... ”

在示例程序DYNAMIC中创建CDPABDEFINITION结构

字 wBuffLen; / *所需缓冲区长度* / BYTE * rt_field; / *分配的rich-text字段* / BYTE * buff_ptr; / *分配内存中的位置* / CDPABDEFINITION pabdef; / *富文本段落样式* /

/ * ...步骤丢失... * /

rt_field =（BYTE *）malloc（wBuffLen）;

if（rt_field ==（BYTE *）NULL） { API_RETURN（NOERROR）; }} / *保留指向缓冲区中当前位置的指针。 * / buff_ptr = rt_field; / *初始化一个CDPABDEFINITION结构。我们使用所有默认值， 除了中心对齐。 * /

pabdef.Header.Signature = SIG_CD_PABDEFINITION; pabdef.Header.Length = ODSLength（_CDPABDEFINITION）; pabdef.PABID = PARA_STYLE_ID; pabdef.JustifyMode = JUSTIFY_CENTER; pabdef.LineSpacing = DEFAULT_LINE_SPACING; pabdef.ParagraphSpacingBefore = DEFAULT_ABOVE_PAR_SPACING; pabdef.ParagraphSpacingAfter = DEFAULT_BELOW_PAR_SPACING; pabdef.LeftMargin = DEFAULT_LEFT_MARGIN; pabdef.RightMargin = DEFAULT_RIGHT_MARGIN; pabdef.FirstLineLeftMargin = DEFAULT_FIRST_LEFT_MARGIN; pabdef.Tabs = DEFAULT_TABS; pabdef.Tab [0] = DEFAULT_TAB_INTERVAL; pabdef.Flags = 0;

/ *调用ODSWriteMemory将CDPABDEFINITION结构转换为 Domino规范格式并将转换后的结构写入 缓冲区在位置buff_ptr。 这会将buff_ptr前进到 下一个字节在缓冲区后的规范格式结构。 * / ODSWriteMemory（＆buff_ptr，_CDPABDEFINITION，＆pabdef，1）;

此代码动态分配用于构建富文本项的缓冲区。然后它填充CDPABDEFINITION结构的所有字段。 PABID成员是此样式定义的唯一标识符。在上面的代码中，此参数设置为1.如果在同一个富文本字段中定义了其他CDPABDEFINITION结构，则每个结构必须将其PABID成员设置为唯一值。

设置结构的所有成员后，代码调用ODSWriteMemory将CDPABDEFINITION结构转换为Domino规范格式，并将结果存储在分配的缓冲区中。 ODSWriteMemory提前buff_ptr指向转换的CDPABDEFINITION记录后分配的缓冲区中的下一个字节。

在示例程序DYNAMIC中创建CDPARAGRAPH结构

CDPARAGRAPH para; / * rich-text段头* /

/ *在字段中放置段头。 * / para.Header.Signature = SIG_CD_PARAGRAPH; para.Header.Length =（BYTE）ODSLength（_CDPARAGRAPH）;

ODSWriteMemory（＆buff_ptr，_CDPARAGRAPH，＆para，1）;

此代码初始化CDPARAGRAPH结构，然后将其转换为Domino规范格式，将结果存储在缓冲区中。 ODSWriteMemory将缓冲区指针推进到缓冲区中的下一个可用字节。

在示例程序DYNAMIC中创建CDPABREFERENCE结构

CDPABREFERENCE ref;

/ *在字段中放置段落引用块。 指定 PARA_STYLE_ID，以便本段使用样式 定义。 * /

ref.Header.Signature = SIG_CD_PABREFERENCE; ref.Header.Length =（BYTE）ODSLength（_CDPABREFERENCE）; ref.PABID = PARA_STYLE_ID; ODSWriteMemory（＆buff_ptr，_CDPABREFERENCE，＆ref，1）;

此代码初始化CDPABREFERENCE结构，然后将其转换为Domino规范格式，将结果存储在缓冲区中。 ODSWriteMemory将缓冲区指针推进到下一个可用字节。

在示例程序DYNAMIC中创建两个CDTEXT结构

CDTEXT cdtext; / *富文本文本标题* / char szString1 [] =“Hello world ...”; WORD wString1Len = strlen（szString1）; FONTIDFIELDS * pFontID; / *文本标题中的字体定义* /

/ *将CDTEXT记录添加到字段。 CDTEXT记录由 的CDTEXT结构，后跟一系列文本。 初始化 CDTEXT结构通过填充签名和长度。 CDTEXT结构也包含字体信息 控制Domino或Notes如何显示此第一批文本。 * /

cdtext.Header.Signature = SIG_CD_TEXT; cdtext.Header.Length = ODSLength（_CDTEXT）+ wString1Len;

pFontID =（FONTIDFIELDS *）＆（cdtext.FontID）; pFontID-> Face = FONT_FACE_SWISS; pFontID-> Attrib = ISBOLD; pFontID-> Color = NOTES_COLOR_BLUE; pFontID-> PointSize = 24;

ODSWriteMemory（＆buff_ptr，_CDTEXT，＆cdtext，1）;

/ *将第一个文本运行的实际字符写入缓冲区。 由于文本的运行可能包含嵌入的空字符，请使用 memcpy，而不是strcpy。 无需使用a终止文本的运行 null因为Header.Length成员的CDTEXT结构 明确指定长度。 * /

memcpy（（char *）buff_ptr，szString1，wString1Len）; buff_ptr + = wString1Len;

此代码段将CDTEXT记录添加到缓冲区。 CDTEXT记录由一个CDTEXT结构和一个文本字符串组成。记录的CDTEXT部分定义文本的某些属性，包括字体面，颜色和点大小，并且必须转换为Domino规范格式。紧接着这个结构，我们添加将与指定的属性一起显示的文本字符的运行。字符串不会转换为规范格式。

附加Rich 文本缓冲区到示例程序DYNAMIC中的注释

DWORD rt_size; / * rich-text字段的大小* / STATUS错误; / *从API调用返回代码* /

/ *我们完成用CD记录填充缓冲区。 现在追加 缓冲区的注释作为富文本字段。 首先找到大小 缓冲区。 然后通过调用将rich-text字段添加到注释 NSFItemAppend。 NSFItemAppend将数据从缓冲区中复制 由rt_field指定。 因此，在调用NSFItemAppend之后，我们 可以释放缓冲区。 * /

rt_size =（DWORD）（buff_ptr - rt_field）;

error = NSFItemAppend（note_handle， 0， “RICH_TEXT”，strlen（“RICH_TEXT”）， TYPE_COMPOSITE， rt_field，rt_size）;

free（rt_field）;

此代码片段获取缓冲区中数据的总长度，并调用NSFItemAppend。

NSFItemAppend将一个项添加到note_handle指定的注释。注释中的字段名称为“RICH_TEXT”。数据类型参数TYPE_COMPOSITE指定这是一个富文本字段。指针rt_field指定数据的缓冲区，它必须是Domino规范格式。 rt_size参数指定缓冲区中有多少数据。

上面未显示的是随后调用NSFNoteUpdate将新注释保存到磁盘以及关闭注释和数据库的代码。

-------------------------------------------------- -------------------------------------------------- ------