Rich Edit Control

 

The original specification for rich edit controls is Microsoft Rich Edit 1.0; the current specification is Rich Edit 4.1. Each version of rich edit is a superset of the preceding one, except that only Asian builds of Rich Edit 1.0 have a vertical text option. Before creating a rich edit control, you should call the LoadLibrary function to verify which version of Rich Edit is installed.

 

The following table shows which DLL corresponds with which version of Rich Edit. Note that the name of the file did not change from version 2.0 to version 3.0. This allows version 2.0 to be upgraded to version 3.0 without breaking existing code.

 

Rich Edit version

DLL

1.0

Riched32.dll

2.0

Riched20.dll

3.0

Riched20.dll

4.1

Msftedit.dll

 

The following list describes which versions of Rich Edit are included in which releases of Microsoft Windows.

 

Windows XP SP1

Includes Rich Edit 4.1, Rich Edit 3.0, and a Rich Edit 1.0 emulator.

Windows XP

Includes Rich Edit 3.0 with a Rich Edit 1.0 emulator.

Windows Me

Includes Rich Edit 1.0 and 3.0.

Windows 2000

Includes Rich Edit 3.0 with a Rich Edit 1.0 emulator.

Windows NT 4.0

Includes Rich Edit 1.0 and 2.0.

Windows 98

Includes Rich Edit 1.0 and 2.0.

Windows 95

Includes only Rich Edit 1.0. However, Riched20.dll is compatible with Windows 95 and may be installed by an application that requires it.

 

On Windows 95/98/Me, Rich Edit 1.0 is localized so that it works with a particular operating system that is similarly localized. For example, on Japanese versions of an operating system, Rich Edit 1.0 can display Japanese, but not Arabic.

 

What's New in Rich Edit

 

The following topics describe the new features introduced in each version of Rich Edit.

 

Rich Edit Version 1.0

 

Rich Edit 1.0 includes the following features.

 

Text entry and selection

Mostly standard (system-edit control) selection and entry of text. Selection bar support (the selection bar is an unmarked area to the left of each paragraph that when clicked, selects the line). Word-wrap and auto-word-select options. Single-, double-, and triple-click selection.

ANSI (single-byte character set (SBCS) and multibyte character set (MBCS)) editing

However, there is no Unicode editing.

Basic set of character/paragraph formatting properties

See CHARFORMAT and PARAFORMAT.

Character formatting properties

Font name and size, bold, italic, solid underline, strike-out, protected, link, offset, and text color.

Paragraph formatting properties

Start indent, right indent, subsequent line offset, bullet, alignment (left, center, right), and tabs.

Find forward

Includes case-insensitive and match-whole-word options.

Message-based interface

Almost a superset of the system edit-control message set plus two interfaces, IRichEditOle and IRichEditCallback.

Embedded objects

Requires client collaboration based on IRichEditOle and IRichEditCallback interfaces.

Right-button menu support

Uses IRichEditCallback interface.

Drag-and-drop editing

Drag-and-drop editing is supported.

Notifications

WM_COMMAND messages sent to client plus a number of others. This is a superset of common-control notifications.

Single-level undo/redo

Behaves similarly to the system edit control. Selecting Undo reverses the last action, and that action then becomes the new Redo action.

Simple vertical text

(Asian builds only).

Input Method Editor (IME) support

(Asian builds only).

WYSIWYG editing using printer metrics

This feature is needed for Microsoft WordPad, in particular.

Cut / Copy / Paste / StreamIn / StreamOut

With plain text (CF_TEXT) or Rich Text Format (RTF) with and without objects.

C code base

The code is written in C, which provides a solid and versatile foundation.

Different builds for different scripts

Rich Edit 1.0 addresses localization issues with different builds.

 

Rich Edit Version 2.0

 

Rich Edit 2.0 incorporated several additional features, such as support for Unicode and Asian languages, multilevel Undo, Component Object Model (COM) interfaces, and numerous user interface (UI) enhancements.

 

Rich Edit 2.0 includes the following features in addition to the features provided by Rich Edit 1.0.

 

Unicode

Unicode eases the effort in handling international text. However effort is needed to maintain compatibility with existing non-Unicode documents—that is, the ability to convert to/from non-Unicode plain and rich text. Also, substantial effort is needed to run correctly on Windows 95/98/Me.

General international support

General line breaking algorithm (extension of Kinsoku rules), simple font linking, keyboard font switching.

Asian support

Level 2 (dialog box) and 3 (inline) is supported in IMEs.

Find Up/Find Down support

Searching forward and backward is supported.

Bidirectional support

This is included in Rich Edit 2.1

Multilevel undo

An extensible Undo architecture allows client to participate in application-wide Undo model.

Magellan mouse support

This is the mouse with a roller for scrolling.

Dual-font support

The keyboard can automatically switch fonts when the active font is inappropriate for current keyboard, for example, Kanji characters in Times New Roman.

Smart font apply

Font change request does not apply Western fonts to Asian characters.

Improved display

An off-screen bitmap is used when multiple fonts occur on the same line. This allows, for example, the last letter of the word cool not to be chopped off.

Transparency support

Also in windowless mode.

System selection colors

Used for selecting text.

Automatic URL recognition

Can check for a number of URL formats (for example, http:)

Microsoft Word edit UI compatibility

Selection, cursor-keypad semantics.

Word standard EOP

The end-of-paragraph mark (CR) can also handle carriage return/line feed (CR/LF) (carriage return, line-feed).

Plain-text as well as rich-text functionality

Single-character format and single-paragraph format.

Single-line and multiline controls

Truncate at first end-of-paragraph and no wordwrap.

Accelerator keys

Accelerator keys are supported.

Password window style

Password edit controls are supplied through EM_GETPASSWORDCHAR and EM_SETPASSWORDCHAR.

Scalable architecture

To reduce instance size.

Windowless operation and interfaces

This is provided through the ITextHost and ITextServices interfaces.

COM dual interfaces

Text Object Model (TOM) interfaces.

CHARFORMAT2

Added font weight, background color, locale identifier, underline type, superscript and subscript (in addition to offset), disabled effect. For RTF roundtripping only, added amount to space between letters, twip size above which to kern character pair, animated-text type, various effects: font shadow/outline, all caps, small caps, hidden, embossed, imprint, and revised.

PARAFORMAT2

Added space before and after and Word line spacing. For RTF roundtripping only, added shading weight/style, numbering start/style/tab, border space/width/sides, tab alignment/leaders, various Word paragraph effects: RTL paragraph, keep, keep-next, page-break-before, no-line-number, no-widow-control, do-not-hyphenate, side-by-side.

More RTF roundtripping

All of the Word FormatFont and FormatParagraph properties.

Code stability and stabilization

Examples: parameter and object validation, function invariants, reentrancy guards, object stabilization.

Strong testing infrastructure

Including extensive regressions tests.

Improved performance

Smaller working set, faster load and redisplay times, etc.

C++ code base

The code is written in C++, which provides a solid foundation on which to build Rich Edit 3.0.

 

With a few exceptions, Rich Edit 2.0 uses the same functions, structures, and messages as Rich Edit 1.0. Note, however, the following differences:

 

The name of the Rich Edit 1.0 window class is RichEdit. Rich Edit 2.0 has both ANSI and Unicode window classes—RichEdit20A and RichEdit20W, respectively. To specify the appropriate rich edit window class, use the RICHEDIT_CLASS constant, which the Richedit.h file defines depending on the definition of the UNICODE compile flag.
In Rich Edit 2.0, if you create a Unicode rich edit control (one that expects Unicode text messages), you must specify only Unicode data in any window messages sent to the control. Similarly, if you create an ANSI rich edit control, send only ANSI or double-byte character set (DBCS) data. You can use the IsWindowUnicode function to determine whether a rich edit control uses Unicode text messages. Note that the rich edit COM interfaces use Unicode text unless they encounter a code page argument.
Rich Edit 1.0 used CR/LF character combinations for paragraph markers. Rich Edit 2.0 used only a carriage return character ('\r'). Rich Edit 3.0 uses only a carriage return character but can emulate Rich Edit 1.0 in this regard.
Rich Edit 2.0 introduced the following new messages.

 

Message

Description

EM_AUTOURLDETECT

Enables or disables automatic URL detection.

EM_CANREDO

Determines whether there are any actions in the redo queue.

EM_GETIMECOMPMODE

Retrieves the current input method editor (IME) mode.

EM_GETLANGOPTIONS

Retrieves options for IME and Asian language support.

EM_GETREDONAME

Retrieves the type name of the next action in the redo queue.

EM_GETTEXTMODE

Retrieves the text mode or undo level.

EM_GETUNDONAME

Retrieves the type name of the next action in the undo queue.

EM_REDO

Redoes the next action in the redo queue.

EM_SETLANGOPTIONS

Sets options for IME and Asian language support.

EM_SETTEXTMODE

Sets the text mode or undo level.

EM_SETUNDOLIMIT

Sets the maximum number of actions in the undo queue.

EM_STOPGROUPTYPING

Stops grouping consecutive typing actions into the current undo action.

 

Rich Edit 2.0 introduced the following new structures.

 

Structure

Description

CHARFORMAT2

Contains information about character formatting.

PARAFORMAT2

Contains information about paragraph formatting.

 

Rich Edit versions 2.0 and 3.0 do not support the following messages that were previously supported in Asian-language versions of Rich Edit 1.0.

 

EM_CONVPOSITION

EM_GETIMECOLOR

EM_GETIMEOPTIONS

EM_GETPUNCTUATION

EM_GETWORDWRAPMODE

EM_SETIMECOLOR

EM_SETIMEOPTIONS

EM_SETPUNCTUATION

EM_SETWORDWRAPMODE

 

Rich Edit Version 3.0

 

Rich Edit 3.0 is a single, scalable, world-wide DLL that offers high performance and compatibility with Word in a small package. New features for Rich Edit 3.0 include richer text, zoom, font binding, more powerful IME support, and rich complex script support (bidirectional, Indic, and Thai).

 

Rich Edit 3.0 includes the following features in addition to the features provided by Rich Edit Version 2.0.

 

Zoom

The zoom factor is given by a ratio.

Paragraph numbering (single-level)

Numeric, upper and lower alphabetic, or Roman numeral.

Simple tables

Deleting and inserting rows is possible, but not resizing nor wrapping inside cells. With advanced typography turned on (see EM_GETTYPOGRAPHYOPTIONS), Rich Edit 3.0 can align columns centered or flush right, and include decimals. Cells are simulated by tabs, so text tabs and carriage returns are replaced by blanks.

Normal and heading styles

Built-in normal style and heading styles 1 through 9 are supported by the EM_SETPARAFORMAT and Text Object Model (TOM) interfaces.

More underline types

Dashed, dash-dot, dash-dot-dot, and dot underlining has been added.

Underline coloring

Underlined text can be tagged with one of 15 document choices for underline colors.

Hidden text

Marked by CHARFORMAT2 attribute. Handy for roundtripping (writing out to a file what was read in) of information that ordinarily should not be displayed.

More default hot keys

These hot keys function the same as those in Word. For example, European accent dead keys (U.S. keyboards only). Number hot key (CTRL+L) cycles through numbering options available, starting with bullet.

HexToUnicode IME

Allows a user to convert between hexadecimal and Unicode by using hot keys.

Smart quotes

This feature is toggled on and off by CTRL+ALT+' for U.S. keyboards.

Soft hyphens

For plain text, use 0xAD. For RTF, use \-.

Italics cursor

In addition, the mouse cursor changes to a hand when over URLs.

Advanced typography option

Rich Edit 3.0 can use an advanced typography option for line breaking and display (see EM_GETTYPOGRAPHYOPTIONS). This elegant option was added primarily to facilitate handling complex scripts (bidirectional, Indic, and Thai). In addition, a number of improvements occur for simple scripts. Examples are:

Center, right, decimal tabs
Fully justified text
Underline averaging, which provides a uniform underline even when adjacent text runs have different font sizes.

Complex script support

Rich Edit 3.0 supports bidirectional (text with Arabic and/or Hebrew mixed with other scripts), Indic (Indian scripts like Devangari), and Thai text. For support of these complex scripts, the advanced typography and Uniscribe components are used.

Font binding

Rich Edit 3.0 will automatically choose an appropriate font for characters that clearly do not belong to the current character set stamp. This is done by assigning character sets to text runs and associating fonts with those character sets. For more information, see Font Binding.

Charset-specific plain-text read/write options

This allows reading a file using one charset, and writing with a different charset.

UTF-8 RTF

This is recommended for cutting, copying, and pasting operations. This file format is more compact than ordinary RTF, faster, and compatible with Unicode.

Microsoft Office 9 IME support (IME98)

This more powerful IME capability has been separated into an independent module. Features include:

Reconversion

In the earlier versions, the user needed to delete the final string first and then type in a new string to get to the correct candidate. This new feature enables the user to convert the final string back to composition mode, thereby allowing easy selection of a different candidate string.

Document feed

This feature provides IME98 with the text for the current paragraph, which helps IME98 perform more accurate conversion during typing.

Mouse operation

This feature provides better control over the candidate and UI windows during typing.

Caret position

This feature provides the current caret and line information, which IME98 uses to position UI windows (for example, a candidate list).

Active Input Method Manager (IMM) support

Users can invoke the Active IMM object, which enables users to enter Asian characters on U.S. systems.

HexToUnicode support

Users can convert between hexadecimal notation and Unicode by using hot keys.

More RTF roundtripping

RTF text that is read in from a file will be written back out intact.

Improved 1.0 compatibility mode

Rich Edit 3.0 can emulate Rich Edit 1.0 behavior. For example, it is possible to change between MBCS and Unicode character-position (cp) mappings. This feature emulates Rich Edit 1.0 in Windows 2000.

Increased freeze control

The display can be frozen over multiple API calls and then unfrozen to display the updates.

Increased undo control

Undo can be suspended and resumed (an IME requirement).

Increase/decrease font size

Increases or decreases font size to one of six standard values (12, 28, 36, 48, 72, and 80 points).

 

Rich Edit Version 4.1

 

New features for Rich Edit 4.1 include hyphenation, page rotation, and Text Services Framework (TSF) support.

 

Rich Edit 4.1 includes the following features in addition to the features provided by Rich Edit Version 3.0.

 

Hyphenation

Hyphenation is supported through the following APIs: HyphenateProc, EM_SETHYPHENATEINFO, and EM_GETHYPHENATEINFO.

Page rotation

Top-to-bottom and bottom-to-top layout is supported through EM_SETPAGEROTATE and EM_GETPAGEROTATE.

Text Services Framework support

To turn on TSF and certain TSF features, use the following styles in EM_SETEDITSTYLE: SES_USECTF, SES_CTFALLOWEMBED, SES_CTFALLOWPROOFING, and SES_CTFALLOWSMARTTAG.
To set and get the TSF mode bias, use EM_SETCTFMODEBIAS and EM_GETCTFMODEBIAS.
To set and get the TSF keyboard status, use EM_SETCTFOPENSTATUS and EM_GETCTFOPENSTATUS.

Additional IME support

To set and get the IME mode bias, use EM_SETIMEMODEBIAS and EM_GETIMEMODEBIAS.
To get the properties and capabilities of the IME, use EM_GETIMEPROPERTY.
To get the IME composition text, use EM_GETIMECOMPTEXT.
To determine whether the locale is an East Asian locale, use EM_ISIME.

Additional EM_SETEDITSTYLE settings

Besides the TSF settings, there are new settings that exclude IMEs, set bidirectional text flow, use draftmode fonts, and more.

Additional EM_SETCHARFORMAT settings

New flags allow the client to set the default font and font sizes for a given LCID or charset, to set the default font for the control, to prevent keyboard switching to match the font, and more.

Restricting input to ANSI text

Using TM_SINGLECODEPAGE in EM_SETTEXTMODE prevents Unicode input from entering a Rich Edit control.

Unsupported RTF keyword notification

EN_LOWFIRTF warns an application when there is an unsupported RTF keyword.

Additional language support

Additional languages include Armenian, Divehi, Telugu, and others.

Improved table support

Features include: wrapping within cells, improved handling via RTF, and improved navigation.

ES_VERTICAL

The ES_VERTICAL windows style is supported.

WM_UNICHAR Notification support

To send or post Unicode characters to ANSI windows, use WM_UNICHAR Notification. It is equivalent to WM_CHAR, but it uses (UTF)-32.

 

Creating a Rich Edit Control

 

To create a rich edit control, call the CreateWindowEx function, specifying the rich edit window class. If you are using Rich Edit 1.0 (Riched32.dll), specify RichEdit for the window class parameter. If you are using Rich Edit 2.0 or later (Riched20.dll), specify RICHEDIT_CLASS for the window class parameter.

 

Rich edit controls support most of the window styles used with edit controls as well as additional styles. You should specify the ES_MULTILINE window style if you want to allow more than one line of text in the control.

 

Note   To use visual styles with these controls, an application must include a manifest and must call InitCommonControls at the beginning of the program. For information on visual styles, see Visual Styles. For information on manifests, see Using Windows XP Visual Styles.

 

Text Formatting

 

An application can send messages to a rich edit control to format characters and paragraphs to retrieve formatting information. Paragraph formatting attributes include alignment, tabs, indents, numbering, and simple tables. For characters, you can specify font name, size, color, and effects such as bold, italic, and protected.

 

You can apply paragraph formatting by using the EM_SETPARAFORMAT message. To determine the current paragraph formatting for the selected text, use the EM_GETPARAFORMAT message. The PARAFORMAT or PARAFORMAT2 structure is used with both messages to specify paragraph formatting attributes.

 

You can apply character formatting by using the EM_SETCHARFORMAT message. To determine the current character formatting for the selected text, you can use the EM_GETCHARFORMAT message. The CHARFORMAT or CHARFORMAT2 structure is used with both messages to specify character attributes.

 

You can also use EM_SETCHARFORMAT and EM_GETCHARFORMAT messages to set and retrieve the character formatting of the insertion point, which is the formatting applied to any subsequently inserted characters. For example, if an application sets the default character formatting to bold and the user then types a character, that character is bold.

 

The character formatting of the insertion point is applied to newly inserted text only if the current selection is empty (if the current selection is an insertion point). Otherwise, the new text assumes the character formatting of the text it replaces. If the selection changes, the default character formatting changes to match the first character in the new selection.

 

The protected character effect is unique in that it does not change the appearance of text. If the user attempts to modify protected text, a rich edit control sends its parent window an EN_PROTECTED notification message, allowing the parent window to allow or prevent the change. To receive this notification message, you must enable it by using the EM_SETEVENTMASK message.

 

Foreground color is always a character attribute. In Rich Edit 1.0, background color is only a property of the rich edit control. To set the default background color, use the EM_SETBKGNDCOLOR message. Note, Rich Edit does not support the WM_CTLCOLOREDIT message.

 

Current Selection in a Rich Edit Control

 

The user can select text in a rich edit control by using the mouse or the keyboard. The current selection is the range of selected characters, or the position of the insertion point if no characters are selected. An application can get information about the current selection, set it, determine when it changes, and show or hide the selection highlight.

 

To determine the current selection in a rich edit control, use the EM_EXGETSEL message. To set the current selection, use the EM_EXSETSEL message. The CHARRANGE structure is used with both messages and specifies a range of characters. To retrieve information about the contents of the current selection, you can use the EM_SELECTIONTYPE message.

 

An application can detect when the current selection changes by processing the EN_SELCHANGE notification message. The notification message specifies a SELCHANGE structure containing information about the new selection. A rich edit control sends this notification message only if you enable it by using the EM_SETEVENTMASK message.

 

By default, a rich edit control shows and hides the selection highlight when it gains and loses the focus. You can show or hide the selection highlight at any time by using the EM_HIDESELECTION message. For example, an application might provide a Search dialog box to find text in a rich edit control. The application might select matching text without closing the dialog box, in which case it must use the EM_HIDESELECTION message to highlight the selection.

 

As with edit controls, you can specify the ES_NOHIDESEL window style to prevent a rich edit control from hiding the selection highlight when it loses the focus.

 

As an alternative to using the EM_EXGETSEL and EM_EXSETSEL messages, you can retrieve and set the current selection by using the EM_GETSEL and EM_SETSEL edit control messages. The EM_GETSEL message packs two 16-bit character indexes into its 32-bit return value and therefore, works only for selections that fall entirely within the first 64K. However, a rich edit control will never contain more than 32K characters of text, unless you extend this limit by using the EM_LIMITTEXT or EM_EXLIMITTEXT message. For selections that extend beyond the first 64KB of text, the EM_GETSEL message returns – 1. In such a case you can still use the values returned in wParam and lParam to find the start and end characters of the selection.

 

Rich Edit Text Operations

 

An application can send messages to retrieve or find text in a rich edit control. You can retrieve either the selected text or a specified range of text.

 

To get the selected text in a rich edit control, use the EM_GETSELTEXT message. The text is copied to the specified character array. You must ensure that the array is large enough to hold the selected text plus a terminating null character.

 

To retrieve a specified range of text, use the EM_GETTEXTRANGE message. The TEXTRANGE structure used with this message specifies the text range to retrieve and points to a character array that receives the text. Here again, the application must ensure that the array is large enough for the specified text plus a terminating null character.

 

You can search for a string in a rich edit control by using the EM_FINDTEXT message. The FINDTEXT structure used with this message specifies the text range to search and the string to search for. You can also specify such options as whether the search is case sensitive.

 

Rich Edit 3.0 also supports the HexToUnicode IME, which allows a user to convert between hexadecimal and Unicode by using hot keys. For more information, see HexToUnicode.

 

Word and Line Breaks

 

A rich edit control calls a function called a word-break procedure to find breaks between words and to determine where it can break lines. The control uses this information when performing word-wrap operations and when processing CTRL+LEFT ARROW key and CTRL+RIGHT ARROW key combinations. An application can send messages to a rich edit control to replace the default word-break procedure, to retrieve word-break information, and to determine what line a given character falls on.

 

Word-break procedures for rich edit controls are similar to those for edit controls, but they have additional capabilities: word-break procedures for both kinds of controls can determine whether a character is a delimiter and can find the nearest word break before or after the specified position. A delimiter is a character that marks the end of a word, such as a space. Usually, in an edit control, a word break occurs only after delimiters. However, different rules apply to most Asian languages.

Word-break procedures for rich edit controls also group characters into character classes, each identified by a value in the range &H00 through &H0F. Breaks occur either after delimiters or between characters of different classes. Thus, a word-break procedure with different classes for alphanumeric and punctuation characters would find two word breaks in the string "Win.doc" (before and after the period).

 

A character's class can be combined with zero or more word-break flags to form an 8-bit value. When performing word-wrap operations, a rich edit control uses word-break flags to determine where it can break lines. Rich Edit uses the following word-break flags.

 

Flags

Description

WBF_BREAKAFTER

Lines may be broken after the character.

WBF_BREAKLINE

The character is a delimiter. Delimiters mark the ends of words. Lines may be broken after delimiters.

WBF_ISWHITE

The character is a white-space character. Trailing white-space characters are not included in the length of a line when wrapping.

 

The WBF_BREAKAFTER value is used to allow wrapping after a character that does not mark the end of a word, such as a hyphen.

 

You can replace the default word-break procedure for a rich edit control, with your own procedure by using the EM_SETWORDBREAKPROC message. For more information about word-break procedures, see the description of the EditWordBreakProc function.

 

Note  This replacement is not recommended for Rich Edit control 2.0 and later, due to the complexity of multilingual word breaking.

 

For Rich Edit 1.0, you can use the EM_SETWORDBREAKPROCEX message to replace the default extended word-break procedure with an EditWordBreakProcEx function. This function provides additional information about the text, such as the character set. You can use the EM_GETWORDBREAKPROCEX message to retrieve the address of the current extended word-break procedure. Note that Rich Edit 2.0 and later do not support EditWordBreakProcEx, EM_GETWORDBREAKPROCEX, and EM_SETWORDBREAKPROCEX.

 

You can use the EM_FINDWORDBREAK message to find word breaks or to determine a character's class and word-break flags. In turn, the control calls its word-break procedure to get the requested information.

 

To determine which line a given character falls on, you can use the EM_EXLINEFROMCHAR message.

 

Rich Edit Clipboard Operations

 

An application can paste the contents of the clipboard into a rich edit control using either the best available clipboard format or a specific clipboard format. You can also determine whether a rich edit control is capable of pasting a clipboard format.

 

As with an edit control, you can copy or cut the contents of the current selection by using the WM_COPY or WM_CUT message. Similarly, you can paste the contents of the clipboard into a rich edit control by using the WM_PASTE message. The control pastes the first available format that it recognizes, which presumably is the most descriptive format.

 

To paste a specific clipboard format, you can use the EM_PASTESPECIAL message. This message is useful for applications with a Paste Special command that enables the user to select the clipboard format. You can use the EM_CANPASTE message to determine whether a given format is recognized by the control.

 

You can also use the EM_CANPASTE message to determine whether any available clipboard format is recognized by a rich edit control. This message is useful when processing the WM_INITMENUPOPUP message. An application might enable or gray its Paste command depending on whether the control can paste any available format.

 

Rich edit controls register two clipboard formats:

 

RTF
RichEdit Text and Objects

 

An application can register these formats by using the RegisterClipboardFormat function, specifying the CF_RTF and CF_RETEXTOBJ values.

 

Streams

 

You can use streams to transfer data into or out of a rich edit control. A stream is defined by an EDITSTREAM structure, which specifies a buffer and an application defined–callback function.

 

To read data into a rich edit control (that is, stream in the data), use the EM_STREAMIN message. The control repeatedly calls the application's callback function, which transfers a portion of the data into the buffer each time.

 

To save the contents of a rich edit control (that is, stream out the data), you can use the EM_STREAMOUT message. The control repeatedly writes to the buffer and then calls the application's callback function. For each call, the callback function saves the contents of the buffer.

 

Printing

 

You can send messages to a rich edit control to render its output for a specified device, such as a printer. You can also specify the output device for which a rich edit control formats its text.

 

To format part of a rich edit control's contents for a specific device, you can use the EM_FORMATRANGE message. The FORMATRANGE structure used with this message specifies the range of text to format as well as the device context for the target device.

 

After formatting text for an output device, you can send the output to the device by using the EM_DISPLAYBAND message. By repeatedly using the EM_FORMATRANGE and EM_DISPLAYBAND messages, an application that prints the contents of a rich edit control can implement banding. (Banding is the division of output into smaller parts for printing purposes.)

 

You can use the EM_SETTARGETDEVICE message to specify the target device for which a rich edit control formats its text. This message is useful for WYSIWYG formatting, in which an application positions text using the default printer's font metrics instead of the screen's.

 

Bottomless Rich Edit Controls

 

An application can resize a rich edit control as needed so that it is always the same size as its contents. A rich edit control supports this so-called bottomless functionality by sending its parent window an EN_REQUESTRESIZE notification message whenever the size of its content changes.

 

When processing the EN_REQUESTRESIZE notification message, an application should resize the control to the dimensions in the specified REQRESIZE structure. An application might also move any information near the control to accommodate the control's change in height. To resize the control, you can use the SetWindowPos function.

 

You can force a bottomless rich edit control to send an EN_REQUESTRESIZE notification message by using the EM_REQUESTRESIZE message. This message can be useful when processing the WM_SIZE message.

 

To receive EN_REQUESTRESIZE notification messages, you must enable the notification by using the EM_SETEVENTMASK message.

 

Miscellaneous Notification Messages

 

A rich edit control's parent window can process notification messages to monitor events affecting the control. Rich edit controls support all of the notification messages used with edit controls as well as several additional ones. You can determine which notification messages a rich edit control sends its parent window by setting its event mask.

 

To set the event mask for a rich edit control, use the EM_SETEVENTMASK message. You can retrieve the current event mask for a rich edit control by using the EM_GETEVENTMASK message. For a list of event mask flags, see Rich Edit Control Event Mask Flags.

 

A rich edit control's parent window can filter all keyboard and mouse input to the control by processing the EN_MSGFILTER notification message. The parent window can prevent the keyboard or mouse message from being processed or can change the message by modifying the specified MSGFILTER structure.

 

An application can process the EN_PROTECTED notification message to detect when the user attempts to modify protected text. To mark a range of text as protected, you can set the protected character effect. For more information, see Text Formatting.

 

You can enable the user to drop files in a rich edit control by processing the EN_DROPFILES notification message. The specified ENDROPFILES structure contains information about the files being dropped.

 

Font Binding

 

Rich Edit 3.0 will assign a charset to plain-text characters depending on their context. Some examples are:

 

Hangul symbols get HANGUL_CHARSET
Non-neutral ANSI characters get ANSI_CHARSET in any event
Chinese characters get SHIFTJIS_CHARSET if kana characters are found nearby or GB2312_CHARSET if no kana are found nearby.
Greek characters get GREEK_CHARSET

 

Note  The Rich Edit control uses Unicode internally, so this use of charset differs from the original one used in font specifications. But CHARFORMAT has a well-defined place for the charset.

 

Neutral characters like blanks and digits are assigned a charset depending on their context. For example, a blank surrounded by characters of the same charset gets that charset. Neutrals and digits used for bidirectional text are assigned charsets in a way based on the Unicode bidirectional algorithm.

 

Once charsets are assigned, Rich Edit scans the text around the insertion point forward and backward to find the nearest fonts that have been used for the charsets. If no font is found for a charset, rich edit uses the font chosen by the client for that charset. If the client hasn't specified a font for the charset, rich edit uses the default font for that charset. If the client wants some other font, the client can always change it, but this approach will work most of the time. The current default font choices are based on the following table. Note that the default fonts are set per-process, and there are separate lists for UI usage and for non-UI usage.

 

Language

UI font name

UI font size

non-UI font name

non-UI font size

Western, CE, ME, Vietnamese

Tahoma

8

Arial

10

Japanese

MS UI Gothic

9

MS P Gothic

10

Korean

Gulim

9

Gulim

9

Simplified Chinese

Simsun

9

SimSun

10

Traditional Chinese

PMingLiU

9

PMingLiU

9

Thai

MS Sans Serif

8

Tahoma

14

Symbols

Wingdings

8

Wingdings

10

Devanagari

Mangal

8

Mangal

10

Tamil

Latha

8

Latha

10

Georgian, Armenian

Arial Unicode

8

Arial Unicode

10

 

Therefore, in the default font-binding table (entries have charset, font name, size), Rich Edit allows ANSI_CHARSET to match several charsets, while the appropriate charset matches other fonts on a one-to-one basis. More precisely, rich edit uses the ANSI_CHARSET choice whenever no other alternative is found. You will be able to specify a finer granularity than this, for example: assign a specific ARABIC_CHARSET for Arabic runs, a specific Greek font for Greek runs, for example. This finer granularity will also be used if a font with the desired charset stamp is found somewhere in the document before the area being font-bound.

 

Note that Rich Edit does not currently handle a missing glyph in a font that claims to support a charset but is incomplete. At display time in a complex script, Rich Edit does end up knowing that such a glyph is missing, but it does not cause the backing store to use a new font. Normally, the underlying font linking of the OS will accomplish this.

 

Rich Edit 4.1: To set the default font for a script, call EM_SETCHARFORMAT with CHARFORMAT2, specifying yHeight, bCharSet, bPitchAndFamily, szFaceName, and lcid. Also, to get the default font for a specific code page, call EM_GETCHARFORMAT with CHARFORMAT2 specifying bCharSet and lcid.

 

Unsupported Edit Control Functionality

 

Rich edit controls support most but not all functionality for multiline edit controls. This section lists the edit control messages and window styles that are not supported by rich edit controls.

 

The following messages are processed by edit controls but not by rich edit controls.

 

Unsupported message

Comments

EM_FMTLINES

Not supported.

EM_GETHANDLE

Rich edit controls do not store text as a simple array of characters.

EM_GETIMESTATUS

Not supported.

EM_GETMARGINS

Not supported.

EM_SETHANDLE

Rich edit controls do not store text as a simple array of characters.

EM_SETIMESTATUS

Not supported.

EM_SETMARGINS

Supported in Rich Edit 3.0.

EM_SETRECTNP

Supported in Rich Edit 3.0.

EM_SETTABSTOPS

The EM_SETPARAFORMAT message is used instead.

Supported in Rich Edit 3.0.

WM_CTLCOLOR

The EM_SETBKGNDCOLOR message is used instead.

WM_GETFONT

The EM_GETCHARFORMAT message is used instead.

 

The following window styles are used with multiline edit controls but not with rich edit controls: ES_LOWERCASE, ES_UPPERCASE, and ES_OEMCONVERT.

 

Rich Edit Shortcut Keys

 

Rich edit controls support the following shortcut keys.

 

Keys

Operations

Comments

Shift+Backspace

Generate a LRM/LRM on a bidi keyboard

BiDi specific

Ctrl+Tab

Tab


Ctrl+Clear

Select all


Ctrl+Number Pad 5

Select all


Ctrl+A

Select all


Ctrl+E

Center alignment


Ctrl+J

Justify alignment


Ctrl+R

Right alignment


Ctrl+L

Left alignment


Ctrl+C

Copy


Ctrl+V

Paste


Ctrl+X

Cut


Ctrl+Z

Undo


Ctrl+Y

Redo


Ctrl+'+' (Ctrl+Shift+'=')

Superscript


Ctrl+'='

Subscript


Ctrl+1

Line spacing = 1 line.


Ctrl+2

Line spacing = 2 lines.


Ctrl+5

Line spacing = 1.5 lines.


Ctrl+' (apostrophe)

Accent acute

After pressing the short cut key, press the appropriate letter (for example a, e, or u). This applies to English, French, German, Italian, and Spanish keyboards only.

Ctrl+` (grave)

Accent grave

See Ctrl+' comments.

Ctrl+~ (tilde)

Accent tilde

See Ctrl+' comments.

Ctrl+; (semicolon)

Accent umlaut

See Ctrl+' comments.

Ctrl+Shift+6

Accent caret (circumflex)

See Ctrl+' comments.

Ctrl+, (comma)

Accent cedilla

See Ctrl+' comments.

Ctrl+Shift+' (apostrophe)

Activate smart quotes


Backspace

If text is protected, beep and do not delete it. Otherwise, delete previous character.


Ctrl+Backspace

Delete previous word. This generates a VK_F16 code.


F16

Same as Backspace.


Ctrl+Insert

Copy


Shift+Insert

Paste


Insert

Overwrite

DBCS does not overwrite.

Ctrl+Left Arrow

Move cursor one word to the left.

On bidi keyboard, this depends on the direction of the text.

Ctrl+Right Arrow

Move cursor one word to the right.

See Ctrl+Left Arrow comments.

Ctrl+Left Shift

Left alignment

In BiDi documents, this is for left-to-right reading order.

Ctrl+Right Shift

Right alignment

In BiDi documents, this is for right-to-left reading order.

Ctrl+Up Arrow

Move to the line above.


Ctrl+Down Arrow

Move to the line below.


Ctrl+Home

Move to the beginning of the document.


Ctrl+End

Move to the end of the document.


Ctrl+Page Up

Move one page up.

If in SystemEditMode and Single Line control, do nothing.

Ctrl+Page Down

Move one page down.

See Ctrl+Page Up comments.

Ctrl+Delete

Delete the next word or selected characters.


Shift+Delete

Cut the selected characters.








Esc

Stop drag-drop.

While doing a drag-drop of text.

Alt+Esc

Change the active application.


Alt+X

Converts the Unicode hexadecimal value preceding the insertion point to the corresponding Unicode character.


Alt+Shift+X

Converts the Unicode character preceding the insertion point to the corresponding Unicode hexadecimal value.


Alt+0xxx (Number Pad)

Inserts Unicode values if xxx is greater than 255. When xxx is less than 256, ASCI range text is inserted based on the current keyboard.

Must enter decimal values.







Alt+Shift+Ctrl+F12

Hex to Unicode.

In case Alt+X is already taken for another use.

Alt+Shift+Ctrl+F11

Selected text will be output to the debugger window and saved to %temp%\DumpFontInfo.txt.

For Debug only (need to set Flag=8 in Win.ini)

Ctrl+Shift+A

Set all caps.


Ctrl+Shift+L

Fiddle bullet style.


Ctrl+Shift+Right Arrow

Increase font size.

Font size changes by 1 point in the range 4pt-11pt; by 2points for 12pt-28pt; it changes from 28pt -> 36pt -> 48pt -> 72pt -> 80pt; it changes by 10 points in the range 80pt - 1630pt; the maximum value is 1638.

Ctrl+Shift+Left Arrow

Decrease font size.

See Ctrl+Shift+Right Arrow comments.

 

Valid XHTML 1.0 Transitional