Rich Edit 控件 SDK 參考手冊
摘要:本文對Rich Edit控件底層消息機制進行了講解,以期讀者對Windows平台下的Rich Edit控件有一個更深入的認識,同時對于使用Win32 SDK進行開發的人員具有一定參考價值。因為文章的初衷是引領VB程式員通過Win32 API調用來擴充VB下的Rich Edit控件的功能,是以對于每個消息的詳細說明和注意事項未作過多說明,感興趣的朋友可以參考Visual Studio下的MSDN Library。
關鍵字:Rich Edit Control、RTF、SDK、MSDN。
一、引言
Rich Edit控件是一個可用于輸入、編輯、格式化、列印和儲存文本的窗體。這些文本可以設定字元和段落格式,并且可以包含嵌入的COM對象。Rich Edit控件提供格式化文本的程式設計接口。不過,應用程式必須實作這些使用者接口元件,以便使用者可以進行格式化操作。
Rich Edit控件幾乎支援所有用于多行Edit控件的消息和通知。是以,已經使用了Edit控件的程式可以很容易的改為Rich Edit控件。額外的消息和通知使得應用程式可以通路Rich Edit控件特有的功能。擷取更多關于Edit控件的資訊,請參閱
Edit Controls。
正如大家所熟知的,Windows控件是基礎視窗,它處理那些控制視窗顯示和特征的消息。而ActiveX控件是把那些消息變成屬性和方法的COM 容器。RichEdit Windows控件是Edit Windows控件的擴充集,TextBox ActiveX控件也是從它派生而來。RichEdit能夠識别Edit消息并且加入了自己特有的消息。你可以在Win32幫助檔案中認出Edit和RichEdit的消息常數,因為他們均采用EM_作為字首。
ActiveX RichTextBox控件将絕大多數的這種消息映射為其屬性。例如,EM_LIMITTEXT與MaxLength屬性相對應。但是你同時會注意到一些感興趣的消息并沒有與之對應的RichTextBox屬性。為什麼呢?
ActiveX控件為最通用的特性提供方法和屬性,更具體講,是提供給VB設計者最感興趣的特性。設計者們似乎喜歡每個新版本裡更多的特征。 例如,TextBox 和RichTextBox控件現在具備Locked屬性。在舊版本的VB中你不得不通過EM_SETREADONLY消息來模拟。但是,還有許多其他隐藏的或者不是很明顯的特性在ActiveX控件中尚未提供。為了使用這些特性,我們就必須對Rich Edit控件的底層消息機制進行較深入的了解。
二、關于Rich Edit控件
Rich Edit控件的最初規範為1.0版。目前規範為2.0版。(譯者注:目前最新版本為4.1版本!)在建立一個Rich Edit控件之前,你應該調用
LoadLibrary函數來确認安裝的Rich Edit控件的版本。下表顯示了不同版本與其DLL間的對應關系。
Rich Edit 版本 | 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下與其包含的不同版本的Rich Edit對應關系:
Windows XP SP1 | 包含 Rich Edit 4.1, Rich Edit 3.0, 和一個 Rich Edit 1.0 仿真程式。 |
Windows XP | 包含Rich Edit 3.0和一個 Rich Edit 1.0 仿真程式。 |
Windows Me | 包含Rich Edit 1.0和3.0。 |
Windows 2000 | 包含Rich Edit 3.0和一個 Rich Edit 1.0 仿真程式。 |
Windows NT 4.0 | 包含Rich Edit 1.0和2.0。 |
Windows 98 | 包含Rich Edit 1.0和2.0。 |
Windows 95 | 隻包含Rich Edit 1.0。不過,Riched20.DLL與Windows 95系統相容,是以可以在正确安裝後使用。 |
2.1 Rich Edit 2.0
Rich Edit 2.0包含幾個新特性,比如支援Unicode和遠東語言,多級撤消,以及大量的增強使用者接口。
Rich Edit 2.0采用與Rich Edit 1.0一緻的Win32函數,結構和消息,極少例外。他們的差別在于:
- Rich Edit 1.0窗體類的名字叫“RichEdit”。Rich Edit 2.0同時具有ANSI和Unicode窗體類,“RichEdit 20A ”和“RichEdit20W”分别表示對應的Rich Edit窗體類,我們RichEdit.H檔案定義的RICHEDIT_CLASS常數來區分,而具體采用哪一個取決于UNICODE編譯标志。
- 在Rich Edit 2.0中,如果你建立一個Unicode控件,隻需在任何發往控件的Window消息中給出Unicode資料。同樣的,如果建立了一個ANSI控件,隻能發送ANSI或者DBCS資料。你可以使用 IsWindowUnicode 函數來判斷是否一個Rich Edit控件是Unicode的。
- Rich Edit 1.0 采用CRLF(回車符和換行符)字元組合表示段落符号。而RichEdit 2.0隻采用一個回車符号(‘/r’)。
- Rich Edit 2.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動作的連續鍵入動作的組合。 |
- Rich Edit 2.0 包含以下新的結構:
消息 | 描述 |
CHARFORMAT2 | 包含字元格式資訊。 |
PARAFORMAT2 | 包含段落格式屬性。 |
- Rich Edit 2.0 不支援以下這些在亞洲語言版本的Rich Edit 1.0中支援的消息:
EM_CONVPOSITION |
EM_GETIMECOLOR |
EM_GETIMEOPTIONS |
EM_GETPUNCTUATION |
EM_GETWORDWRAPMODE |
EM_SETIMECOLOR |
EM_SETIMEOPTIONS |
EM_SETPUNCTUATION |
EM_SETWORDWRAPMODE |
2.2 建立 Rich Edit 控件
可用通過CreateWindowEx函數中指定Rich Edit 窗體類來建立一個Rich Edit控件。如果使用1.0版本(RICHED32.DLL),窗體類參數應該為“RichEdit”。如果采用2.0版本(RICHED20.DLL),窗體類參數應該為“RICHEDIT_CLASS”。
Rich Edit控件支援大部分的Edit控件采用的窗體樣式,同時也支援一些額外的樣式。你如果希望控件中的文本支援不止一行的話就應該給出ES_MULTILINE窗體樣式。
2.3 文本格式
應用程式可以通過給Rich Edit控件發送消息來格式化字元和段落以及擷取這些格式化資訊。段落格式屬性包含對齊、跳格、縮進和編号。對字元而言,你可以指定字型、尺寸、顔色以及如粗體、斜體和保護等效果。
你可以采用EM_SETPARAFORMAT消息來應用段落格式。擷取目前選中文本的段落格式屬性,則采用EM_GETPARAFORMAT消息。PARAFORMAT結構将會在這兩個消息中用到,它用于描述段落格式屬性。
你可以采用EM_SETCHARFORMAT消息來應用字元格式。擷取目前選中文本的字元格式屬性,則采用EM_GETCHARFORMAT消息。CHARFORMAT結構将會在這兩個消息中用到,它用于描述字元格式屬性。
你也可以采用EM_SETCHARFORMAT和EM_GETCHARFORMAT消息來設定和擷取預設字型格式,它将應用于所有随後插入的字元。例如,應用程式将預設字元格式設定為粗體,則使用者随後敲入的字元都将為粗體。
隻有在目前選擇内容為空的時候預設字元格式才會被應用到新插入的文本上。否則,新的文本将假定沿用其所替換的文本的格式。如果選擇内容改變,則預設字型格式将将采用該内容的首字元的格式。
保護(Protected)字元效果是唯一不改變其文本顯示的例子。如果使用者試圖修改保護文本,Rich Edit控件将發送EN_PROTECTED通知到其父視窗,讓其父窗體決定是否允許或者拒絕修改。為了接收該通知,你必須使用EM_SETEVENTMASK消息來啟用它。
前景色是一個字元屬性,但是背景色是一個Rich Text控件屬性。要設定背景色,請采用EM_SETBKGNDCOLOR消息。
2.4 Rich Edit控件中的目前選擇内容
使用者可以在Rich Edit控件中通過滑鼠和鍵盤來選擇文本。目前選擇内容指的是選中字元的範圍,或者表示沒有字元選中時的插入點位置。應用程式可以擷取選中内容的相關資訊,設定目前選中内容,決定目前選中内容何時改變,顯示或者隐藏目前高亮顯示的選中内容等。
确定Rich Edit控件中的目前選中内容,采用EM_EXGETSEL消息。設定目前選擇區域,采用EM_EXSETSEL消息。
CHARRANGE結構用于在這兩個消息中描述字元範圍。擷取目前選中内容的相關資訊,你可以采用EM_SELECTIONTYPE消息。
應用程式可以通過處理EN_SELCHANGE通知來檢測目前選中内容何時被改變。該通知通過
SELCHANGE結構給出新選中内容的相關資訊。Rich Edit控件隻有在你通過EM_SETEVENTMASK消息開啟它之後才會發送該通知。
預設情況下,Rich Edit控件在擷取和失去焦點時将開啟和隐藏選中文本的高亮顯示。你可以通過EM_HIDESELECTION消息在任何時候開啟或者隐藏選中區域的高亮顯示。例如,某個應用程式可能提供一個查找對話框用于在Rich Edit控件中查找文本,這種情況下就必須使用EM_HIDESELECTION消息來保持選中文本的高亮顯示。
與Edit控件一樣,你可以使用ES_NOHIDESEL窗體樣式來防止Rich Edit控件在失去焦點時隐藏選中區域的高亮顯示。你也可以在Rich Edit控件建立之後使用EM_HIDESELECTION消息來改變窗體的ES_NOHIDESEL樣式。
擷取和設定目前選中内容使用EM_GETSEL和EM_SETSEL Edit控件消息,而非EM_EXGETSEL和EM_EXSETSEL消息。EM_GETSEL消息将兩個16位字元索引壓縮為它的32位傳回值,是以,僅僅适用于選中區域的前64K位元組。然而,一個Rich Edit控件不可能包含超過32K位元組的文本,除非你使用EM_EXLIMITTEXT消息擴充了這個限制。對于選中文本中超過前64K位元組的文本,EM_GETSEL消息将傳回-1。
2.5 Rich Edit 文本操作
應用程式可以發送消息來擷取或者查找Rich Edit控件中的文本。你既可以擷取選中區域的文本也可以擷取給定範圍的文本。
擷取Rich Edit控件中的選中文本,使用EM_GETSELTEXT消息。文本将被拷貝到指定字元數組中。你必須確定數組大小足以容納選中文本再加上一個終止NULL字元。
擷取給定範圍的文本,使用EM_GETTEXTRANGE消息。該消息将使用
TEXTRANGE結構,用于描述需要獲得的文本範圍以及用于擷取該文本的字元數組指針。在這裡,同樣的,你必須確定數組大小足以容納選中文本再加上一個終止NULL字元。
你可以使用EM_FINDTEXT消息在一個Rich Edit控件中查找字元串。該消息将使用結構,用于描述文本查找範圍及需要查找的字元串。你也可以指定諸如是否區分大小寫等搜尋選項。
2.6 斷字與斷行
Rich Edit 控件調用叫做“斷字處理過程”的函數來查找單詞間分隔符以及判斷何處可以換行。控件在執行自動換行操作時以及處理Ctrl+左箭頭和Ctrl+右箭頭的組合鍵時将利用這些資訊。應用程式可以通過向Rich Edit控件發送消息來替換預設的“斷字處理過程”,擷取斷字資訊,以及判斷一個給定字元屬于哪一行。
Rich Edit控件的斷字處理過程與Edit控件相似,但是它擁有更多能力。兩種控件的斷字處理過程均可以識别一個字元是否是一個分隔符,并且能夠在找到給定位置的前一個或者後一個字分隔符。分隔符指的是一個标志單詞結束的字元,比如空格。在Edit控件中,斷字隻出現在分隔符之後。
Rich Edit控件的斷字處理過程同時将字元組合為字元類,由到0x00的0x 0F 值來辨別。斷字可以出現在分隔符之後或者在不同類的字元之間。是以,在字元串“WIN.COM”中,由于字母數字和标點屬于不同類别,斷字程式将找到兩個字分隔符。
一個字元類别可以由0個或者更多的字分隔符标志位組成一個8位的值。當執行自動換行操作時,Rich Edit控件使用這些分隔符标志位來決定何處可以換行。有如下這些字分隔标志位:
WBF_BREAKAFTER | 字元後面可以換行。 |
WBF_BREAKLINE | 該字元為一個分隔符。分隔符标記單詞的結束。也可以在分隔符後換行。 |
WBF_ISWHITE | 該字元為一個白空格字元。跟随的白空格字元在換行時不包含在行長度中。 |
WBF_BREAKAFTER表示允許在該字元後面折行,但是并不标記單詞的結束,比如連字元-。
你可以使用EM_SETWORDBREAKPROC消息來替換Rich Edit控件的預設斷字處理過程。擷取更多關于斷字處理過程的資訊,請參閱
EditWordBreakProc函數說明。
另外,你可以使用EM_SETWORDBREAKPROCEX消息來替換預設的擴充斷字處理過程
EditWordBreakProcEx函數。該函數提供有關該文本的更多資訊,比如字元集。你可以使用EM_GETWORDBREAKPROCEX消息來擷取目前擴充斷字處理過程的位址。
你可以使用EM_FINDWORDBREAK消息來查找斷字元或者确定一個字元類和斷字标志位。控件依次調用其斷字處理過程,擷取所需資訊。
判斷給定字元屬于哪一行,你可以使用EM_EXLINEFROMCHAR消息。
2.7 Rich Edit 剪貼闆操作
應用程式可以粘貼剪貼闆中内容到一個Rich Edit控件中,采用最佳可用剪貼闆格式或者指定的剪貼闆格式。你也可以決定是否一個Rich Edit控件可以粘貼某種剪貼闆格式。
對于一個Edit控件而言,你可以使用WM_COPY或者WM_CUT消息來拷貝或者剪切目前選中内容。同樣的,你可以使用WM_PASTE消息将這些剪貼闆内容粘貼到一個Rich Edit控件中。控件将粘貼它所識别的第一個可用格式,這大概是最具描述性的格式。
你可以使用EM_PASTESPECIAL消息來粘貼指定的剪貼闆格式。這個消息對具有“特殊粘貼”指令的應用程式很有用,該指令可以讓使用者選擇剪貼闆格式。你可以使用EM_CANPASTE消息來決定控件是否識别某種指定的格式。
你也可以使用EM_CANPASTE消息來決定Rich Edit控件是否識别所有可用的剪貼闆格式。該消息在處理WM_INITMENUPOPUP消息時很有用。應用程式可以啟用或者屏蔽“粘貼”指令,取決于控件是否可以粘貼任一個可用類型。
Rich Edit控件注冊兩種剪貼闆格式:“富文本格式(RTF)”和一種叫做“RichEdit 文本與對象”的格式。應用程式可以使用
RegisterClipboardFormat函數來注冊這些格式,其取值為CF_RTF與CF_RETEXTOBJ。
2.8 流(Stream)
你可以使用流(Stream)向Rich Edit控件傳入或者傳出資料。流由
EDITSTREAM結構所定義,該結構描述一個緩沖區及一個應用程式定義的回調函數。
将資料讀入Rich Edit控件(或者說,資料傳入),使用EM_STREAMIN消息。控件将重複調用應用程式的回調函數,該函數每次傳入資料的一部分到緩沖區中。
儲存Rich Edit控件内容(或者說,資料傳出),你可以使用EM_STREAMOUT消息。控件将重複寫入緩沖區然後調用應用程式的回調函數。對于每次調用,回調函數将儲存緩沖區中的内容。
2.9 列印
你可以向Rich Edit控件發送消息來将其輸出重定向到指定裝置,比如列印機。你也可以指定一個用于Rich Text文本格式化的輸出裝置。
對于特殊裝置而言,要格式化Rich Edit控件中部分内容,你可以使用EM_FORMATRANGE消息。
FORMATRANGE結構用于在該消息中描述需要格式化的文本範圍以及目标裝置的裝置場景。
在輸出裝置文本格式化完成後,你可以使用EM_DISPLAYBAND消息将輸出發送至裝置。通過反複使用EM_FORMATRANGE和EM_DISPLAYBAND消息,列印Rich Text控件内容的應用程式可以實作條帶化操作。(條帶化操作指的是将輸出分割為較小部分用于列印目的的操作。)
你可以使用EM_SETTARGETDEVICE消息來指定一個用于Rich Text文本格式化的目标裝置。該消息對于WYSIWYG(所見即所得)模式非常有用,在該模式下應用程式采用預設列印機字型規格而非螢幕字型規格來定位文本。
2.10 無底的Rich Edit 控件
應用程式可以調整Rich Edit控件的大小以便它總是與其内容大小比對。Rich Edit控件支援這種所謂的“無底”特性,在任何時候若其内容大小改變,它将向其父窗體發送EN_REQUESTRESIZE通知。
在處理EN_REQUESTRESIZE通知時,應用程式應該調整控件尺寸為
REQRESIZE結構所給出的大小。應用程式同樣可以變換控件相關的任何資訊以适應控件的高度改變。調整控件大小,你可以使用
SetWindowPos函數。
你可以使用EM_REQUESTRESIZE消息強制一個無底Rich Edit控件發送EN_REQUESTRESIZE通知。該消息在處理WM_SIZE消息時很有用。
為了接收EN_REQUESTRESIZE通知,你必須采用EM_SETEVENTMASK消息來啟用它。
2.11 各種各樣的通知
Rich Edit控件父窗體可以處理通知,這些消息記錄影響該控件的事件。Rich Edit控件支援所有Edit控件所使用的通知,同時具有幾個新增的通知。你可以通過設定它的事件掩碼(Event Mask)來判斷Rich Edit控件發送到其父窗體的是何種通知。
設定Rich Edit控件的事件掩碼,采用EM_SETEVENTMASK消息。你可以使用EM_GETEVENTMASK消息來擷取目前Rich Edit控件的事件掩碼。
Rich Edit控件的父窗體可以通過處理EN_MSGFILTER通知來過濾所有的鍵盤和滑鼠輸入。父窗體可以防止鍵盤和滑鼠消息被處理,或者可以通過修改指定的
MSGFILTER結構來修改這些消息。
應用程式可以處理EN_PROTECTED通知,用以檢測何時使用者試圖修改受保護的文本。為了置某個範圍的文本為受保護狀态,你可以設定受保護字元效果。擷取更多資訊,請參閱文本格式。
你可以通過處理EN_DROPFILES通知來允許使用者Drop一個檔案到Rich Edit控件中。指定的
ENDROPFILES結構包含了即将被Drop的檔案的相關資訊。
2.11 不支援的Edit控件的特性
Rich Edit 控件支援絕大多數而并非全部的多行Edit控件的特性。本節列舉出Rich Edit控件所不支援的Edit控件的消息和窗體樣式。
下面的消息由Edit控件處理,而不被Rich Edit控件所支援。
不支援的消息 | 注釋 |
EM_FMTLINES | 不支援。 |
EM_GETHANDLE | Rich Edit控件并非将文本存儲為簡單的字元數組。 |
EM_GETMARGINS | 不支援。 |
EM_GETPASSWORDCHAR | 不支援ES_PASSWORD樣式。 |
EM_SETHANDLE | Rich Edit控件并非将文本存儲為簡單的字元數組。 |
EM_SETMARGINS | 不支援。 |
EM_SETPASSWORDCHAR | 不支援ES_PASSWORD樣式。 |
EM_SETRECTNP | 不支援。 |
EM_SETTABSTOPS | 采用EM_SETPARAFORMAT消息。 |
WM_CTLCOLOR | 采用EM_SETBKGNDCOLOR消息。 |
WM_GETFONT | 采用EM_GETCHARFORMAT消息。 |
下面的窗體樣式用于多行Edit控件,而不被Rich Edit控件所支援:
ES_LOWERCASE | ES_PASSWORD |
ES_OEMCONVERT | ES_UPPERCASE |
三、Rich Edit 控件參考
3.1 總索引
Rich Text控件相關的消息、通知和結構體分組彙總如下。部分API元素也用于Edit控件。
·
格式化-
- CHARFORMAT
- CHARFORMAT2
- EM_GETCHARFORMAT
- EM_GETPARAFORMAT
- EM_GETRECT
- EM_SETBKGNDCOLOR
- EM_SETCHARFORMAT
- EM_SETEVENTMASK
- EM_SETPARAFORMAT
- EM_SETRECT
- PARAFORMAT2
·
選中區域與 Hit 測試-
- CHARRANGE
- EM_CHARFROMPOS
- EM_EXGETSEL
- EM_EXSETSEL
- EM_GETFIRSTVISIBLELINE
- EM_GETSEL
- EM_HIDESELECTION
- EM_POSFROMCHAR
- EM_SELECTIONTYPE
- EM_SETSEL
- EN_SELCHANGE
- SELCHANGE
·
文本操作-
- EM_EXLIMITTEXT
- EM_FINDTEXT
- EM_GETLIMITTEXT
- EM_GETSELTEXT
- EM_GETTEXTRANGE
- EM_REPLACESEL
- EM_SETLIMITTEXT
- FINDTEXT
- TEXTRANGE
·
斷字與斷行-
- EM_EXLINEFROMCHAR
- EM_FINDWORDBREAK
- EM_GETWORDBREAKPROC
- EM_SETWORDBREAKPROC
- EM_GETWORDBREAKPROCEX
- EM_SETWORDBREAKPROCEX
- EditWordBreakProcEx
·
行與滾動條-
- EM_GETLINE
- EM_GETLINECOUNT
- EM_GETTHUMB
- EM_LINEFROMCHAR
- EM_LINEINDEX
- EM_LINELENGTH
- EM_LINESCROLL
- EM_SCROLL
- EM_SCROLLCARET
·
編輯操作-
- EM_CANPASTE
- EM_CANUNDO
- EM_EMPTYUNDOBUFFER
- EM_PASTESPECIAL
- EM_UNDO
·
流-
- EDITSTREAM
- EM_STREAMIN
- EM_STREAMOUT
·
列印-
- EM_DISPLAYBAND
- EM_FORMATRANGE
- EM_SETTARGETDEVICE
- FORMATRANGE
·
無底 Rich Edit 控件-
- EM_REQUESTRESIZE
- EN_REQUESTRESIZE
- REQRESIZE
·
OLE 接口-
- IRichEditOle
- IRichEditOleCallback
·
雜項-
- EM_GETEVENTMASK
- EM_GETIMECOLOR
- EM_GETIMEOPTIONS
- EM_GETMODIFY
- EM_GETOPTIONS
- EM_GETPUNCTUATION
- EM_GETWORDWRAPMODE
- EM_SETEVENTMASK
- EM_SETIMECOLOR
- EM_SETIMEOPTIONS
- EM_SETEVENTMASK
- EM_SETMODIFY
- EM_SETREADONLY
- EM_SETOPTIONS
- EM_SETPUNCTUATION
- EM_SETWORDWRAPMODE
- EN_CHANGE
- EN_CORRECTTEXT
- EN_DROPFILES
- EN_ERRSPACE
- EN_HSCROLL
- EN_IMECHANGE
- EN_KILLFOCUS
- EN_MAXTEXT
- EN_MSGFILTER
- EN_OLEOPFAILED
- EN_PROTECTED
- EN_SAVECLIPBOARD
- EN_SETFOCUS
- EN_STOPNOUNDO
- EN_UPDATE
- EN_VSCROLL
- WM_CONTEXTMENU
- WM_CTLCOLOREDIT
- COMPCOLOR
- ENCORRECTTEXT
- ENDROPFILES
- ENOLEOPFAILED
- ENPROTECTED
- ENSAVECLIPBOARD
- PUNCTUATION
- MSGFILTER
3.2 Rich Edit 回調函數
下列回調函數是Rich Edit控件所特有的:
EditStreamCallback |
EditWordBreakProcEx |
3.2.1 EditStreamCallback
EditStreamCallback函數是一個應用程式定義的回調函數,用于EM_STREAMIN和EM_STREAMOUT消息。它用于将資料傳入或者傳出一個Rich Edit控件。
EDITSTREAMCALLBACK類型定義了一個指向該回調函數的指針。
EditStreamCallback是一個用于該應用程式定義的函數名的占位符。
DWORD CALLBACK EditStreamCallback(
DWORD dwCookie , // application-defined value
LPBYTE pbBuff , // 緩沖區指針
LONG cb , // 讀或寫的位元組數
LONG *pcb // 實際傳輸的位元組數的指針
);
參數說明
dwCookie
指定
EDITSTREAM結構中的
dwCookie成員的值。應用程式在發送EM_STREAMIN和EM_STREAMOUT消息時将指定該值。
pbBuff
用于讀取或寫入的緩沖區指針。對于一個流入(讀)操作,回調函數将資料填入該緩沖區,再傳入Rich Edit控件。對于流出(寫)操作,緩沖區包含從控件中讀取的資料,回調函數負責将其寫入存儲器中。
cb
指出讀取和寫入的位元組數。
pcb
一個變量的指針,回調函數将設定該變量的值為實際讀取或寫入的位元組數。
傳回值
回調函數傳回0表示成功。.
回調函數傳回非0值表示發生錯誤。一旦發生錯誤,讀寫操作将終止,Rich Edit控件将放棄pbBuff緩沖區中的任何資料。如果一個回調函數傳回一個非0值,Rich Edit控件将采用
EDITSTREAM結構的
dwError成員将該值傳回應用程式。
備注
當你發送EM_STREAMIN和EM_STREAMOUT消息到一個Rich Edit控件時,需要為
EDITSTREAM結構的
pfnCallback成員指定一個
EditStreamCallback函數指針。Rich Edit控件将不斷調用該函數來輸出或者輸入資料。
當你發送EM_STREAMIN和EM_STREAMOUT消息時,你需要給出一個
EDITSTREAM結構的
dwCookie成員的值。Rich Edit控件使用dwCookie參數将該值傳遞到
EditStreamCallback函數中。例如,你可能使用
dwCookie來傳遞一個打開的檔案的句柄,回調函數就可以使用該dwCookie句柄來讀取和寫入檔案。
控件不斷調用回調函數,每次傳遞部分資料。控件不斷調用回調函數,直至出現如下情況之一為止:
- 回調函數傳回一個非0值。
- 回調函數在*pcb參數中傳回0值。
- *pcb參數傳回的值小于cb參數請求的位元組數。
- 發生錯誤,該錯誤拒絕Rich Edit控件資料的傳出或者傳入。例如記憶體溢出狀态,系統函數失敗,或者讀取緩沖區包含一個無效字元等。
- 對于一個流入操作,RTF代碼包含表示一個RTF塊結束的資料。
- 對于一個單行編輯控件的流入操作,回調函數讀取到一個CRLF。
3.2.2 EditWordBreakProcEx
EditWordBreakProcEx函數是一個應用程式定義的回調函數,用于EM_SETWORDBREAKPROCEX消息。它決定字元在某段給定文本中的字分隔符的字元索引,或者是字元類和字分隔符标志位。
EDITWORDBREAKPROCEX類型定義了一個回調函數的指針。
EditWordBreakProcEx是一個應用程式定義的函數名的占位符。
LONG EditWordBreakProcEx(
char *pchText ,
LONG cchText ,
BYTE bCharSet ,
INT code
);
參數
pchText
目前位置的文本的指針。如果code指定要向左移動,則文本為元素pchText[-1]到pchText[-cchText]的文本,pchText[0]未定義。對于其他所有操作,文本指的是pchText[0]到pchText[cchText - 1]的文本。
cchText
由code指定的搜尋方向上的緩沖區中的字元數。
bCharSet
文本的字元集。
code
所執行的斷字動作。可用的取值由EM_FINDWORDBREAK消息的code參數所描述。
傳回值
傳回字母分隔符的字元索引值,除非code參數是WB_CLASSIFY和WB_ISDELIMITER值。
備注
應用程式必須安裝回調函數,方法是在EM_SETWORDBREAKPROCEX消息中給出回調函數的位址。
3.3 Rich Edit 結構體
下列結構體用于Rich Edit控件:
CHARFORMAT |
CHARFORMAT2 |
CHARRANGE |
COMPCOLOR |
EDITSTREAM |
ENCORRECTTEXT |
ENDROPFILES |
ENLINK |
ENOLEOPFAILED |
ENPROTECTED |
ENSAVECLIPBOARD |
FINDTEXT |
FINDTEXTEX |
FORMATRANGE |
MSGFILTER |
PARAFORMAT |
PARAFORMAT2 |
PUNCTUATION |
REOBJECT |
REPASTESPECIAL |
REQRESIZE |
SELCHANGE |
TEXTRANGE |
3.4 Rich Edit 消息
以下消息由Rich Edit控件所獨有:
EM_AUTOURLDETECT |
EM_CANPASTE |
EM_CANREDO |
EM_DISPLAYBAND |
EM_EXGETSEL |
EM_EXLIMITTEXT |
EM_EXLINEFROMCHAR |
EM_EXSETSEL |
EM_FINDTEXT |
EM_FINDTEXTEX |
EM_FINDWORDBREAK |
EM_FORMATRANGE |
EM_GETCHARFORMAT |
EM_GETEVENTMASK |
EM_GETIMECOLOR |
EM_GETIMECOMPMODE |
EM_GETIMEOPTIONS |
EM_GETLANGOPTIONS |
EM_GETOLEINTERFACE |
EM_GETOPTIONS |
EM_GETPARAFORMAT |
EM_GETPUNCTUATION |
EM_GETREDONAME |
EM_GETSELTEXT |
EM_GETTEXTMODE |
EM_GETTEXTRANGE |
EM_GETUNDONAME |
EM_GETWORDBREAKPROCEX |
EM_GETWORDWRAPMODE |
EM_HIDESELECTION |
EM_PASTESPECIAL |
EM_REDO |
EM_REQUESTRESIZE |
EM_SELECTIONTYPE |
EM_SETBKGNDCOLOR |
EM_SETCHARFORMAT |
EM_SETEVENTMASK |
EM_SETIMECOLOR |
EM_SETIMEOPTIONS |
EM_SETLANGOPTIONS |
EM_SETOLECALLBACK |
EM_SETOPTIONS |
EM_SETPARAFORMAT |
EM_SETPUNCTUATION |
EM_SETTARGETDEVICE |
EM_SETTEXTMODE |
EM_SETUNDOLIMIT |
EM_SETWORDBREAKPROCEX |
EM_SETWORDWRAPMODE |
EM_STOPGROUPTYPING |
EM_STREAMIN |
EM_STREAMOUT |
WM_CONTEXTMENU |
3.5 Rich Edit 通知
Rich Edit控件支援絕大多數的Edit控件所使用的通知,同時增加了如下的通知。一個Rich Edit控件隻有在使用EM_SETEVENTMASK消息啟用了它之後才能發送下面的通知。
EN_CORRECTTEXT |
EN_DROPFILES |
EN_IMECHANGE |
EN_LINK |
EN_MSGFILTER |
EN_OLEOPFAILED |
EN_PROTECTED |
EN_REQUESTRESIZE |
EN_SAVECLIPBOARD |
EN_SELCHANGE |
EN_STOPNOUNDO |
3.6 Rich Edit OLE接口
Rich Edit 控件支援由OLE所定義的用戶端的支援。該控件為大多數的OLE用戶端提供完全的支援。它不支援連結到自身内容。用戶端負責處理對話框和錯誤消息、OLE對象的存儲處理,以及文檔和應用程式窗體級的實時激活支援。用戶端可以使用EM_GETOLEINTERFACE消息從Rich Edit控件擷取一個
IRichEditOle接口,該接口允許它控制OLE對象。用戶端使用EM_SETOLECALLBACK消息注冊一個
IRichEditOleCallback接口,控件将使用它擷取所需接口和存儲。
下列OLE接口用于Rich Edit控件:
IRichEditOle |
IRichEditOleCallback |
3.6.1 IRichEditOle
指定用于Rich Edit控件執行OLE相關操作的接口。
IRichEditOle接口有下列方法:
方法清單
IUnknown 方法 | 描述 |
QueryInterface | 傳回支援的接口的指針。 |
AddRef | 增加引用計數。 |
Release | 減少引用計數。 |
IRichEditOle 方法 | 描述 |
GetClientSite | 在建立一個新對象時擷取一個可用的 IOleClientSite 接口。 |
GetObjectCount | 擷取Rich Edit控件中包含的對象數目。 |
GetLinkCount | 擷取Rich Edit控件中連結的對象數目。 |
GetObject | 傳回Rich Edit控件中一個 REOBJECT 結構描述的對象資訊。 |
InsertObject | 将一個對象插入到Rich Edit控件中。 |
ConvertObject | 将一個對象轉換為一個新類型。 |
ActivateAs | 解除安裝屬于舊類的對象,告訴OLE将其看做新類對象,然後重新調入這些對象。 |
SetHostNames | 當對象插入到Rich Edit控件中時,設定一個“Host Names”給該對象。 |
SetLinkAvailable | 設定對象标志位中的可用連結位的值。 |
SetDvaspect | 設定Rich Edit控件用于繪制一個對象的特征。 |
HandsOffStorage | 告訴Rich Edit控件釋放其指定對象相關的通路存儲器接口。 |
SaveCompleted | 告訴Rich Edit控件最近的儲存操作已經完畢,應該繼續存儲該對象至不同存儲器。 |
InPlaceDeactivate | 告訴Rich Edit控件立即使目前激活的對象處于非激活狀态。 |
ContextSensitiveHelp | 告訴Rich Edit控件進入或者退出上下文相關幫助模式。 |
GetClipboardData | 擷取一個剪貼闆對象,用于Edit控件的某一區域。 |
ImportDataObject | 導入一個剪貼闆對象至Rich Edit控件,替換目前選中的内容。 |
3.6.2 IRichEditOleCallback
指定一個用于Rich Edit控件從用戶端擷取OLE相關資訊的接口。Rich Edit 控件的用戶端負責實作該接口,并通過EM_SETOLECALLBACK消息将其指派給一個控件。
IRichEditOleCallback接口包含如下方法:
方法清單
IUnknown 方法 | 描述 |
QueryInterface | 傳回支援的接口的指針。 |
AddRef | 增加引用計數。 |
Release | 減少引用計數。 |
IRichEditOleCallback 方法 | 描述 |
GetNewStorage | 為一個粘貼自剪貼闆或者從一個RTF流讀取的對象提供存儲。 |
GetInPlaceContext | 提供應用程式和檔案級的接口以及支援原地激活的必需的資訊。 |
ShowContainerUI | 告訴應用程式是否顯示其使用者接口容器。 |
QueryInsertObject | 詢問應用程式是否一個對象應該被插入。 |
DeleteObject | 通知某一對象将在Rich Edit中被删除。 |
QueryAcceptData | 通路一個粘貼或者拖拽,以決定是否其粘貼/拖拽的資料應該被接受。 |
ContextSensitiveHelp | 告訴應用程式應該進入或者退出上下文相關幫助模式。 |
GetClipboardData | 允許用戶端支援其自身剪貼闆對象。 |
GetDragDropEffect | 允許用戶端指定其拖放操作的執行結果。 |
GetContextMenu | 在一個滑鼠右鍵按下事件中,詢問應用程式提供一個上下文菜單。 |
3.7 Rich Edit枚舉類型
下列枚舉類型用于Rich Edit控件:
TEXTMODE |
UNDONAMEID |
3.7.1 TEXTMODE
TEXTMODE枚舉類型包含用于表示Rich Edit控件的文本模式的值。EM_SETTEXTMODE 和 EM_GETTEXTMODE m消息将使用這個枚舉類型。
typedef enum tagTextMode
{
TM_PLAINTEXT = 1,
TM_RICHTEXT = 2, // 預設值
TM_SINGLELEVELUNDO = 4,
TM_MULTILEVELUNDO = 8, // 預設值
TM_SINGLECODEPAGE = 16,
TM_MULTICODEPAGE = 32
} TEXTMODE;
常數 | 涵義 |
TM_PLAINTEXT | 純文字模式,這種模式下控件類似标準編輯控件。 |
TM_RICHTEXT | 富文本模式,這種模式下控件具備标準Rich Edit功能。為預設設定。 |
TM_SINGLELEVELUNDO | 控件隻允許撤銷Undo隊列中的最後一個動作。 |
TM_MULTILEVELUNDO | 控件支援多級撤銷操作。為預設屬性。使用EM_SETUNDOLIMIT消息來設定撤銷操作的最大級數。 |
TM_SINGLECODEPAGE | 不支援。 |
TM_MULTICODEPAGE | 不支援。 |
3.7.2 UNDONAMEID
UNDONAMEID枚舉類型包含訓示Rich Edit控件動作的常數,這些動作可以用于撤銷和重做操作。 EM_GETREDONAME 和 EM_GETUNDONAME 将使用該枚舉類型作為一個傳回值。
typedef enum _undonameid {
UID_UNKNOWN = 0,
UID_TYPING = 1,
UID_DELETE = 2,
UID_DRAGDROP = 3,
UID_CUT = 4,
UID_PASTE = 5
} UNDONAMEID;
常數 | 涵義 |
UID_UNKNOWN | Undo操作類型未知。 |
UID_TYPING | 鍵入操作。 |
UID_DELETE | 删除操作。 |
UID_DRAGDROP | 拖拽-放下操作。 |
UID_CUT | 剪切操作。 |
UID_PASTE | 粘貼操作。 |
3.8 Rich Edit 常數
3.8.1 Rich Edit控件樣式
下列窗體樣式屬于Rich Edit控件所獨有:
樣式 | 描述 |
ES_DISABLENOSCROLL | 在不需要滾動條時将它們置灰,而非隐藏。 |
ES_EX_NOCALLOLEINIT | 禁止控件在建立時調用 OleInitialize 函數。僅在對話框模式下有用,因為 CreateWindowEx 不支援該樣式。 |
ES_NOIME | 禁止輸入方式編輯(IME)操作。隻對亞洲語言有效。 |
ES_SAVESEL | 在控件失去焦點時保持標明區域。預設情況下,在控件重新擷取焦點時将選擇所有内容。 |
ES_SELFIME | 訓示Rich Edit控件允許應用程式控制所有的IME操作。隻對亞洲語言有效。 |
ES_SUNKEN | 控件顯示為下凹邊框樣式,看起來像是嵌入到其父窗體中。 Windows 95: Windows 95下的應用程式應該使用WS_EX_CLIENTEDGE,而非ES_SUNKEN。 |
ES_VERTICAL | 垂直繪制文本和對象。隻對亞洲語言有效。 |
Rich Edit 控件同樣支援下面的Edit控件樣式。為了允許多行文本,你就必須指定ES_MULTILINE樣式。
ES_AUTOHSCROLL | ES_NOHIDESEL |
ES_AUTOVSCROLL | ES_READONLY |
ES_CENTER | ES_RIGHT |
ES_LEFT | ES_WANTRETURN |
ES_MULTILINE |
Rich Edit控件不支援下面的Edit控件樣式:
ES_LOWERCASE | ES_PASSWORD |
ES_OEMCONVERT | ES_UPPERCASE |
3.8.2 Rich Edit控件事件掩碼标志
事件掩碼用于指定一個Rich Edit控件向父窗體發送何種通知。事件掩碼可以為0或下列多種取值:
值 | 涵義 |
ENM_CHANGE | 發送EN_CHANGE 通知。 |
ENM_CORRECTTEXT | 發送EN_CORRECTTEXT通知。 |
ENM_DROPFILES | 發送EN_DROPFILES通知。 |
ENM_KEYEVENTS | 發送EN_MSGFILTER鍵盤事件通知。 |
ENM_MOUSEEVENTS | 發送EN_MSGFILTER 滑鼠事件通知。 |
ENM_PROTECTED | 發送EN_PROTECTED通知。 |
ENM_RESIZEREQUEST | 發送EN_REQUESTRESIZE通知。 |
ENM_SCROLL | 發送EN_HSCROLL通知。 |
ENM_SELCHANGE | 發送EN_SELCHANGE通知。 |
ENM_UPDATE | 發送EN_UPDATE通知。 |
預設事件掩碼為ENM_NONE,這種情況下将不會發送任何通知到父窗體。你可以通過ENM_GETEVENTMASK和ENM_SETEVENTMASK消息來擷取和設定Rich Edit控件的事件掩碼。
四、參考文獻
1、MSDN Library Visual Studio6.0(CHS),我們在MSDN上可以找到最新版本的SDK文檔,位址如下: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/shellcc/platform/commctls/richedit/richeditcontrols/aboutricheditcontrols.asp
2、Wind32 SDK下的RICHEDIT.H頭檔案(2.0版本):包含了絕大多數函數聲明和結構體及常數的C定義。