第 7 章 - 1 富文本简介

介绍 

 相对于其他类型的字段,富文本字段具有以下几个优点:
  • 富文本中的段落可以 具有混合属性,例如缩进,对齐和间距
  • 富文本中的文本即可 具有混合属性,例如字体,颜色和点大小
  • 单个富文本字段可以 保存几兆字节的数据

本章介绍富文本格式的结构,并说明如何访问构成富文本字段的各个CD记录。  


创建富文本 

用于Domino和Notes的IBM C API提供了创建富文本的高级和低级方法。 高层次的方式很简单但有限。  


高级访问富文本 

CompoundTextxxx系列的C API函数提供了创建富文本的高级方法。 这些函数实现富文本的抽象,允许C API代码将富文本字段视为对象。 我们将这个富文本对象称为“复合文本上下文”。 使用以下函数创建,删除和操作复合文本作为对象: 
      CompoundTextCreate 
      CompoundTextDefineStyle 
      CompoundTextInitStyle 
      CompoundTextAddText 
      CompoundTextAddParagraph 
      CompoundTextAddDocLink 
      CompoundTextAddRenderedNote 
      CompoundTextAssimilateItem 
      CompoundTextAssimilateFile 
      CompoundTextDiscard 
      CompoundTextClose

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

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


对富文本的低级访问 

 


富文本的低级结构 

注释中的富文本字段由一个或多个项目组成 的数据类型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将新注释保存到磁盘以及关闭注释和数据库的代码。 
-------------------------------------------------- -------------------------------------------------- ------

相关内容推荐