第 7 章 - 1 富文本简介

介绍  

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将新注释保存到磁盘以及关闭注释和数据库的代码。  

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