Rich Edit 控件 SDK 参考手册.docx
《Rich Edit 控件 SDK 参考手册.docx》由会员分享,可在线阅读,更多相关《Rich Edit 控件 SDK 参考手册.docx(27页珍藏版)》请在冰豆网上搜索。
RichEdit控件SDK参考手册
RichEdit控件SDK参考手册-1
默认分类2008-12-1701:
01:
23阅读50评论0字号:
大中小
摘要:
本文对RichEdit控件底层消息机制进行了讲解,以期读者对Windows平台下的RichEdit控件有一个更深入的认识,同时对于使用Win32SDK进行开发的人员具有一定参考价值。
因为文章的初衷是引领VB程序员通过Win32API调用来扩展VB下的RichEdit控件的功能,所以对于每个消息的详细说明和注意事项未作过多说明,感兴趣的朋友可以参考VisualStudio下的MSDNLibrary。
关键字:
RichEditControl、RTF、SDK、MSDN。
一、引言
RichEdit控件是一个可用于输入、编辑、格式化、打印和保存文本的窗体。
这些文本可以设置字符和段落格式,并且可以包含嵌入的COM对象。
RichEdit控件提供格式化文本的编程接口。
不过,应用程序必须实现这些用户接口组件,以便用户可以进行格式化操作。
RichEdit控件几乎支持所有用于多行Edit控件的消息和通知。
因此,已经使用了Edit控件的程序可以很容易的改为RichEdit控件。
额外的消息和通知使得应用程序可以访问RichEdit控件特有的功能。
获取更多关于Edit控件的信息,请参阅EditControls。
正如大家所熟知的,Windows控件是基础窗口,它处理那些控制窗口显示和特征的消息。
而ActiveX控件是把那些消息变成属性和方法的COM容器。
RichEditWindows控件是EditWindows控件的扩展集,TextBoxActiveX控件也是从它派生而来。
RichEdit能够识别Edit消息并且加入了自己特有的消息。
你可以在Win32帮助文件中认出Edit和RichEdit的消息常数,因为他们均采用EM_作为前缀。
ActiveXRichTextBox控件将绝大多数的这种消息映射为其属性。
例如,EM_LIMITTEXT与MaxLength属性相对应。
但是你同时会注意到一些感兴趣的消息并没有与之对应的RichTextBox属性。
为什么呢?
ActiveX控件为最通用的特性提供方法和属性,更具体讲,是提供给VB设计者最感兴趣的特性。
设计者们似乎喜欢每个新版本里更多的特征。
例如,TextBox和RichTextBox控件现在具备Locked属性。
在旧版本的VB中你不得不通过EM_SETREADONLY消息来模拟。
但是,还有许多其他隐藏的或者不是很明显的特性在ActiveX控件中尚未提供。
为了使用这些特性,我们就必须对RichEdit控件的底层消息机制进行较深入的了解。
二、关于RichEdit控件
RichEdit控件的最初规范为1.0版。
目前规范为2.0版。
(译者注:
目前最新版本为4.1版本!
)在创建一个RichEdit控件之前,你应该调用LoadLibrary函数来确认安装的RichEdit控件的版本。
下表显示了不同版本与其DLL间的对应关系。
RichEdit版本
DLL名称
版本号
1.0
RICHED32.DLL
2.0
RICHED20.DLL
低于5.30.23.1200
3.0
RICHED20.DLL
5.30.23.1200或更高
4.1
Msftedit.dll
下表给出了不同版本Windows下与其包含的不同版本的RichEdit对应关系:
WindowsXPSP1
包含RichEdit4.1,RichEdit3.0,和一个RichEdit1.0仿真程序。
WindowsXP
包含RichEdit3.0和一个RichEdit1.0仿真程序。
WindowsMe
包含RichEdit1.0和3.0。
Windows2000
包含RichEdit3.0和一个RichEdit1.0仿真程序。
WindowsNT4.0
包含RichEdit1.0和2.0。
Windows98
包含RichEdit1.0和2.0。
Windows95
只包含RichEdit1.0。
不过,Riched20.DLL与Windows95系统兼容,所以可以在正确安装后使用。
2.1RichEdit2.0
RichEdit2.0包含几个新特性,比如支持Unicode和远东语言,多级撤消,以及大量的增强用户接口。
RichEdit2.0采用与RichEdit1.0一致的Win32函数,结构和消息,极少例外。
他们的区别在于:
∙RichEdit1.0窗体类的名字叫“RichEdit”。
RichEdit2.0同时具有ANSI和Unicode窗体类,“RichEdit20A”和“RichEdit20W”分别表示对应的RichEdit窗体类,我们RichEdit.H文件定义的RICHEDIT_CLASS常数来区分,而具体采用哪一个取决于UNICODE编译标志。
∙在RichEdit2.0中,如果你创建一个Unicode控件,只需在任何发往控件的Window消息中给出Unicode数据。
同样的,如果创建了一个ANSI控件,只能发送ANSI或者DBCS数据。
你可以使用IsWindowUnicode函数来判断是否一个RichEdit控件是Unicode的。
∙RichEdit1.0采用CRLF(回车符和换行符)字符组合表示段落符号。
而RichEdit2.0只采用一个回车符号(‘\r’)。
∙RichEdit2.0包含以下新的消息:
消息
描述
EM_AUTOURLDETECT
是否开启/关闭自动URL检测。
EM_CANREDO
判断是否在Redo队列中有一些动作。
EM_GETIMECOMPMODE
获取当前输入方式编辑(IME)模式。
EM_GETLANGOPTIONS
获取IME和远东语言支持选项。
EM_GETREDONAME
获取Redo队列中的下一动作的类型名称。
EM_GETTEXTMODE
获取文本模式或者Undo级别。
EM_GETUNDONAME
获取Undo队列中的下一动作的类型名称。
EM_REDO
重做Redo队列中的下一动作。
EM_SETLANGOPTIONS
设置IME和远东语言支持选项。
EM_SETTEXTMODE
设置文本模式或者Undo级别。
EM_SETUNDOLIMIT
设置Undo队列的最大动作数目。
EM_STOPGROUPTYPING
终止当前Undo动作的连续键入动作的组合。
∙RichEdit2.0包含以下新的结构:
消息
描述
CHARFORMAT2
包含字符格式信息。
PARAFORMAT2
包含段落格式属性。
∙RichEdit2.0不支持以下这些在亚洲语言版本的RichEdit1.0中支持的消息:
EM_CONVPOSITION
EM_GETIMECOLOR
EM_GETIMEOPTIONS
EM_GETPUNCTUATION
EM_GETWORDWRAPMODE
EM_SETIMECOLOR
EM_SETIMEOPTIONS
EM_SETPUNCTUATION
EM_SETWORDWRAPMODE
2.2 创建RichEdit控件
可用通过CreateWindowEx函数中指定RichEdit窗体类来创建一个RichEdit控件。
如果使用1.0版本(RICHED32.DLL),窗体类参数应该为“RichEdit”。
如果采用2.0版本(RICHED20.DLL),窗体类参数应该为“RICHEDIT_CLASS”。
RichEdit控件支持大部分的Edit控件采用的窗体样式,同时也支持一些额外的样式。
你如果希望控件中的文本支持不止一行的话就应该给出ES_MULTILINE窗体样式。
2.3文本格式
应用程序可以通过给RichEdit控件发送消息来格式化字符和段落以及获取这些格式化信息。
段落格式属性包含对齐、跳格、缩进和编号。
对字符而言,你可以指定字体、尺寸、颜色以及如粗体、斜体和保护等效果。
你可以采用EM_SETPARAFORMAT消息来应用段落格式。
获取当前选中文本的段落格式属性,则采用EM_GETPARAFORMAT消息。
PARAFORMAT结构将会在这两个消息中用到,它用于描述段落格式属性。
你可以采用EM_SETCHARFORMAT消息来应用字符格式。
获取当前选中文本的字符格式属性,则采用EM_GETCHARFORMAT消息。
CHARFORMAT结构将会在这两个消息中用到,它用于描述字符格式属性。
你也可以采用EM_SETCHARFORMAT和EM_GETCHARFORMAT消息来设置和获取默认字体格式,它将应用于所有随后插入的字符。
例如,应用程序将默认字符格式设置为粗体,则用户随后敲入的字符都将为粗体。
只有在当前选择内容为空的时候默认字符格式才会被应用到新插入的文本上。
否则,新的文本将假定沿用其所替换的文本的格式。
如果选择内容改变,则默认字体格式将将采用该内容的首字符的格式。
保护(Protected)字符效果是唯一不改变其文本显示的例子。
如果用户试图修改保护文本,RichEdit控件将发送EN_PROTECTED通知到其父窗口,让其父窗体决定是否允许或者拒绝修改。
为了接收该通知,你必须使用EM_SETEVENTMASK消息来启用它。
前景色是一个字符属性,但是背景色是一个RichText控件属性。
要设置背景色,请采用EM_SETBKGNDCOLOR消息。
2.4RichEdit控件中的当前选择内容
用户可以在RichEdit控件中通过鼠标和键盘来选择文本。
当前选择内容指的是选中字符的范围,或者表示没有字符选中时的插入点位置。
应用程序可以获取选中内容的相关信息,设置当前选中内容,决定当前选中内容何时改变,显示或者隐藏当前高亮显示的选中内容等。
确定RichEdit控件中的当前选中内容,采用EM_EXGETSEL消息。
设置当前选择区域,采用EM_EXSETSEL消息。
CHARRANGE结构用于在这两个消息中描述字符范围。
获取当前选中内容的相关信息,你可以采用EM_SELECTIONTYPE消息。
应用程序可以通过处理EN_SELCHANGE通知来检测当前选中内容何时被改变。
该通知通过SELCHANGE结构给出新选中内容的相关信息。
RichEdit控件只有在你通过EM_SETEVENTMASK消息开启它之后才会发送该通知。
默认情况下,RichEdit控件在获取和失去焦点时将开启和隐藏选中文本的高亮显示。
你可以通过EM_HIDESELECTION消息在任何时候开启或者隐藏选中区域的高亮显示。
例如,某个应用程序可能提供一个查找对话框用于在RichEdit控件中查找文本,这种情况下就必须使用EM_HIDESELECTION消息来保持选中文本的高亮显示。
与Edit控件一样,你可以使用ES_NOHIDESEL窗体样式来防止RichEdit控件在失去焦点时隐藏选中区域的高亮显示。
你也可以在RichEdit控件创建之后使用EM_HIDESELECTION消息来改变窗体的ES_NOHIDESEL样式。
获取和设置当前选中内容使用EM_GETSEL和EM_SETSELEdit控件消息,而非EM_EXGETSEL和EM_EXSETSEL消息。
EM_GETSEL消息将两个16位字符索引压缩为它的32位返回值,因此,仅仅适用于选中区域的前64K字节。
然而,一个RichEdit控件不可能包含超过32K字节的文本,除非你使用EM_EXLIMITTEXT消息扩展了这个限制。
对于选中文本中超过前64K字节的文本,EM_GETSEL消息将返回-1。
2.5RichEdit文本操作
应用程序可以发送消息来获取或者查找RichEdit控件中的文本。
你既可以获取选中区域的文本也可以获取给定范围的文本。
获取RichEdit控件中的选中文本,使用EM_GETSELTEXT消息。
文本将被拷贝到指定字符数组中。
你必须确保数组大小足以容纳选中文本再加上一个终止NULL字符。
获取给定范围的文本,使用EM_GETTEXTRANGE消息。
该消息将使用TEXTRANGE结构,用于描述需要获得的文本范围以及用于获取该文本的字符数组指针。
在这里,同样的,你必须确保数组大小足以容纳选中文本再加上一个终止NULL字符。
你可以使用EM_FINDTEXT消息在一个RichEdit控件中查找字符串。
该消息将使用结构,用于描述文本查找范围及需要查找的字符串。
你也可以指定诸如是否区分大小写等搜索选项。
2.6断字与断行
RichEdit控件调用叫做“断字处理过程”的函数来查找单词间分隔符以及判断何处可以换行。
控件在执行自动换行操作时以及处理Ctrl+左箭头和Ctrl+右箭头的组合键时将利用这些信息。
应用程序可以通过向RichEdit控件发送消息来替换默认的“断字处理过程”,获取断字信息,以及判断一个给定字符属于哪一行。
RichEdit控件的断字处理过程与Edit控件相似,但是它拥有更多能力。
两种控件的断字处理过程均可以识别一个字符是否是一个分隔符,并且能够在找到给定位置的前一个或者后一个字分隔符。
分隔符指的是一个标志单词结束的字符,比如空格。
在Edit控件中,断字只出现在分隔符之后。
RichEdit控件的断字处理过程同时将字符组合为字符类,由到0x00的0x0F值来标识。
断字可以出现在分隔符之后或者在不同类的字符之间。
因此,在字符串“WIN.COM”中,由于字母数字和标点属于不同类别,断字程序将找到两个字分隔符。
一个字符类别可以由0个或者更多的字分隔符标志位组成一个8位的值。
当执行自动换行操作时,RichEdit控件使用这些分隔符标志位来决定何处可以换行。
有如下这些字分隔标志位:
WBF_BREAKAFTER
字符后面可以换行。
WBF_BREAKLINE
该字符为一个分隔符。
分隔符标记单词的结束。
也可以在分隔符后换行。
WBF_ISWHITE
该字符为一个白空格字符。
跟随的白空格字符在换行时不包含在行长度中。
WBF_BREAKAFTER表示允许在该字符后面折行,但是并不标记单词的结束,比如连字符-。
你可以使用EM_SETWORDBREAKPROC消息来替换RichEdit控件的默认断字处理过程。
获取更多关于断字处理过程的信息,请参阅EditWordBreakProc函数说明。
另外,你可以使用EM_SETWORDBREAKPROCEX消息来替换默认的扩展断字处理过程EditWordBreakProcEx函数。
该函数提供有关该文本的更多信息,比如字符集。
你可以使用EM_GETWORDBREAKPROCEX消息来获取当前扩展断字处理过程的地址。
你可以使用EM_FINDWORDBREAK消息来查找断字符或者确定一个字符类和断字标志位。
控件依次调用其断字处理过程,获取所需信息。
判断给定字符属于哪一行,你可以使用EM_EXLINEFROMCHAR消息。
2.7RichEdit剪贴板操作
应用程序可以粘贴剪贴板中内容到一个RichEdit控件中,采用最佳可用剪贴板格式或者指定的剪贴板格式。
你也可以决定是否一个RichEdit控件可以粘贴某种剪贴板格式。
对于一个Edit控件而言,你可以使用WM_COPY或者WM_CUT消息来拷贝或者剪切当前选中内容。
同样的,你可以使用WM_PASTE消息将这些剪贴板内容粘贴到一个RichEdit控件中。
控件将粘贴它所识别的第一个可用格式,这大概是最具描述性的格式。
你可以使用EM_PASTESPECIAL消息来粘贴指定的剪贴板格式。
这个消息对具有“特殊粘贴”命令的应用程序很有用,该命令可以让用户选择剪贴板格式。
你可以使用EM_CANPASTE消息来决定控件是否识别某种指定的格式。
你也可以使用EM_CANPASTE消息来决定RichEdit控件是否识别所有可用的剪贴板格式。
该消息在处理WM_INITMENUPOPUP消息时很有用。
应用程序可以启用或者屏蔽“粘贴”命令,取决于控件是否可以粘贴任一个可用类型。
RichEdit控件注册两种剪贴板格式:
“富文本格式(RTF)”和一种叫做“RichEdit文本与对象”的格式。
应用程序可以使用RegisterClipboardFormat函数来注册这些格式,其取值为CF_RTF与CF_RETEXTOBJ。
2.8流(Stream)
你可以使用流(Stream)向RichEdit控件传入或者传出数据。
流由EDITSTREAM结构所定义,该结构描述一个缓冲区及一个应用程序定义的回调函数。
将数据读入RichEdit控件(或者说,数据传入),使用EM_STREAMIN消息。
控件将重复调用应用程序的回调函数,该函数每次传入数据的一部分到缓冲区中。
保存RichEdit控件内容(或者说,数据传出),你可以使用EM_STREAMOUT消息。
控件将重复写入缓冲区然后调用应用程序的回调函数。
对于每次调用,回调函数将保存缓冲区中的内容。
2.9打印
你可以向RichEdit控件发送消息来将其输出重定向到指定设备,比如打印机。
你也可以指定一个用于RichText文本格式化的输出设备。
对于特殊设备而言,要格式化RichEdit控件中部分内容,你可以使用EM_FORMATRANGE消息。
FORMATRANGE结构用于在该消息中描述需要格式化的文本范围以及目标设备的设备场景。
在输出设备文本格式化完成后,你可以使用EM_DISPLAYBAND消息将输出发送至设备。
通过反复使用EM_FORMATRANGE和EM_DISPLAYBAND消息,打印RichText控件内容的应用程序可以实现条带化操作。
(条带化操作指的是将输出分割为较小部分用于打印目的的操作。
)
你可以使用EM_SETTARGETDEVICE消息来指定一个用于RichText文本格式化的目标设备。
该消息对于WYSIWYG(所见即所得)模式非常有用,在该模式下应用程序采用默认打印机字体规格而非屏幕字体规格来定位文本。
2.10无底的RichEdit控件
应用程序可以调整RichEdit控件的大小以便它总是与其内容大小匹配。
RichEdit控件支持这种所谓的“无底”特性,在任何时候若其内容大小改变,它将向其父窗体发送EN_REQUESTRESIZE通知。
在处理EN_REQUESTRESIZE通知时,应用程序应该调整控件尺寸为REQRESIZE结构所给出的大小。
应用程序同样可以变换控件相关的任何信息以适应控件的高度改变。
调整控件大小,你可以使用SetWindowPos函数。
你可以使用EM_REQUESTRESIZE消息强制一个无底RichEdit控件发送EN_REQUESTRESIZE通知。
该消息在处理WM_SIZE消息时很有用。
为了接收EN_REQUESTRESIZE通知,你必须采用EM_SETEVENTMASK消息来启用它。
2.11各种各样的通知
RichEdit控件父窗体可以处理通知,这些消息记录影响该控件的事件。
RichEdit控件支持所有Edit控件所使用的通知,同时具有几个新增的通知。
你可以通过设置它的事件掩码(EventMask)来判断RichEdit控件发送到其父窗体的是何种通知。
设置RichEdit控件的事件掩码,采用EM_SETEVENTMASK消息。
你可以使用EM_GETEVENTMASK消息来获取当前RichEdit控件的事件掩码。
RichEdit控件的父窗体可以通过处理EN_MSGFILTER通知来过滤所有的键盘和鼠标输入。
父窗体可以防止键盘和鼠标消息被处理,或者可以通过修改指定的MSGFILTER结构来修改这些消息。
应用程序可以处理EN_PROTECTED通知,用以检测何时用户试图修改受保护的文本。
为了置某个范围的文本为受保护状态,你可以设置受保护字符效果。
获取更多信息,请参阅文本格式。
你可以通过处理EN_DROPFILES通知来允许用户Drop一个文件到RichEdit控件中。
指定的ENDROPFILES结构包含了即将被Drop的文件的相关信息。
2.11不支持的Edit控件的特性
RichEdit控件支持绝大多数而并非全部的多行Edit控件的特性。
本节列举出RichEdit控件所不支持的Edit控件的消息和窗体样式。
下面的消息由Edit控件处理,而不被RichEdit控件所支持。
不支持的消息
注释
EM_FMTLINES
不支持。
EM_GETHANDLE
RichEdit控件并非将文本存储为简单的字符数组。
EM_GETMARGINS
不支持。
EM_GETPASSWORDCHAR
不支持ES_PASSWORD样式。
EM_SETHANDLE
RichEdit控件并非将文本存储为简单的字符数组。
EM_SETMARGINS
不支持。
EM_SETPASSWORDCHAR
不支持ES_PASSWORD样式。
EM_SETRECTNP
不支持。
EM_SETTABSTOPS
采用EM_SETPARAFORMAT消息。
WM_CTLCOLOR
采用EM_SETBKGNDCOLOR消息。
WM_GETFONT
采用EM_GETCHARFORMAT消息。
下面的窗体样式用于多行Edit控件,而不被RichEdit控件所支持:
ES_LOWERCASE
ES_PASSWORD
ES_OEMCONVERT
ES_UPPERCASE
三、RichEdit控件参考
3.1总索引
RichText控件相关的消息、通知和结构体分组汇总如下。
部分API元素也用于Edit控件。
∙ 格式化
oCHARFORMAT
oCHARFORMAT2
oEM_GETCHARFORMAT
oEM_GETPARAFORMAT
oEM_GETRECT
oEM_SETBKGNDCOLOR
oEM_SETCHARFORMAT
oEM_SETEVENTMASK
oEM_SETPARAFORMAT
oEM_SETRECT
oPARAFORMAT2
∙ 选中区域与Hit测试
oCHARRANGE
oEM_CHARFROMPOS
oEM_EXGETSEL
oEM_EXSETSEL
oEM_GETFIRSTVISIBLELINE
oEM_GETSEL
oEM_HIDESELECTION
oEM_POSFROMCHAR
oEM_SELECTIONTYPE
oEM_SETSEL
oEN_SELCHANGE
oSELCHANGE
∙ 文本操作
oEM_EXLIMITTEXT
oEM_FINDTEXT
oEM_GETLIMITTEXT
oEM_GETSELTEXT
oEM_GETTEXTRANGE
oEM_REPLACESEL
oEM_SETLIMITTEXT
oFINDTEXT
oTEXTRANGE
∙ 断字与断行
oEM_EXLINEFROMCHAR
oEM