Automatic RichEdit Hyperlinks

  • Article

RichEdit has two kinds of hyperlinks, automatic hyperlinks (autoURLs) and friendly name hyperlinks. As its name suggests, the autoURL is automatically recognized by RichEdit as a hyperlink and is displayed as a URL. A friendly name hyperlink has a name, which is displayed, and a hidden instruction part that contains the actual URL. The present post describes autoURLs; a later post will describe friendly name hyperlinks.

The first autoURLs appeared in RichEdit 2.0, which shipped with Office 97, and have the usual web form, such as, https://www.msn.com. The permitted URL protocols were http:, file:, mailto:, ftp:, https:, gopher:, nntp:, prosper:, telnet:, news:, wais:, and outlook:. To include spaces in the URL, the whole URL needed to be enclosed in an angle bracket pair as in <https://www.xxx.com/fun computing>. RichEdit 3.0, which ships with Windows 2000 up through Windows 7, added the capability to recognize URLs of the form www.msn.com and ftp.unicode.org. RichEdit 4.1, which ships with Windows XP up through Windows 7, added friendly name hyperlinks as well as autoURLs of the form \\word\richedit2\murrays. RichEdit 7, which ships with Office 2010, adds recognition for spaces in URLs without needing enclosure in <>. It also adds recognition of telephone numbers, drive-letter paths, email addresses, and URLs enclosed in ASCII double quotes "". It makes all of these recognitions optional, since you might not want to recognize, for example, phone numbers, or you might want to recognize telephone numbers exclusively.

The recognition is dynamic, fast, and displayed with underline and a blue text color. The autoURL notifications can be sent to the client application by user actions such as typing the Enter key or clicking the left mouse button. Unlike in Word, a particular autoURL cannot be disabled, short of disabling the autoURL recognition functionality in general. This hasn’t been a problem for the most part, but it might be nice to be able to turn off trailing portions of an autoURL that are included incorrectly by RichEdit 7.0’s URL space recognition feature.

To enable or disable autoURL recognition in a RichEdit control, send the control the message EM_AUTOURLDETECT with lparam = 0 and wparam = 1 or 0, respectively. When autoURL recognition is enabled, mouse movement over a link or clicking on a link sends an EN_LINK notification to the client. In RichEdit 5.0, lparam = 1 enables East Asian URL recognition. In RichEdit 7.0 wparam can have any combination of the following values: AURL_ENABLEURL (1), AURL_ENABLEEMAILADDR (2), AURL_ENABLETELNO (4), AURL_ENABLEEAURLS (8), and AURL_ENABLEDRIVELETTERS (16). AURL_ENABLEEAURLS is a preferred alias for the lparam = 1 way of enabling East Asian URL recognition. The idea is that lparam could eventually be used to point to a client structure specifying more information, such as additional protocols.

In memory, autoURLs are identified by the CFE_LINK character formatting attribute. You can retrieve this attribute using the EM_GETCHARFORMAT. This approach can be cumbersome, so RichEdit 6.0 added support for the tomLink unit in the TOM (Text Object Model) ITextRange::StartOf(), EndOf(), and Expand() methods, and RichEdit 7.0 adds tomLink support in the ITextRange::Move(), MoveEnd(), and MoveStart() methods.

Comments

  • Anonymous
    August 31, 2009
    Thank You for this post! How to apply link attribute for range without selection (via TOM, without EM_SETCHAFORMAT and CFE_LINK)? tomLink not support for ITextFont?

  • Anonymous
    September 01, 2009
    The comment has been removed

  • Anonymous
    September 01, 2009
    To enable hyperlink tooltips in RichEdit 5.0 and later, send EM_SETEDITSTYLE with wparam = lparam = SES_HYPERLINKTOOLTIPS (8). The various underline types currently recognized are CFU_UNDERLINETHICKLONGDASH (18) // () display as dash CFU_UNDERLINETHICKDOTTED (17) // () display as dot CFU_UNDERLINETHICKDASHDOTDOT (16)// () display as dash dot dot CFU_UNDERLINETHICKDASHDOT (15) // () display as dash dot CFU_UNDERLINETHICKDASH (14) // () display as dash CFU_UNDERLINELONGDASH (13) // () display as dash CFU_UNDERLINEHEAVYWAVE (12) // () display as wave CFU_UNDERLINEDOUBLEWAVE (11) // () display as wave CFU_UNDERLINEHAIRLINE (10) // () display as single CFU_UNDERLINETHICK (9) CFU_UNDERLINEWAVE (8) CFU_UNDERLINEDASHDOTDOT (7) CFU_UNDERLINEDASHDOT (6) CFU_UNDERLINEDASH (5) CFU_UNDERLINEDOTTED (4) CFU_UNDERLINEDOUBLE  (3) // () display as single CFU_UNDERLINEWORD (2) // (*) display as single CFU_UNDERLINE (1) CFU_UNDERLINENONE (0)

  • Anonymous
    October 07, 2012
    Thanks for the post. Can you please let me know if there is a way to enable changing the color of the link when it is clicked upon?

  • Anonymous
    October 08, 2012
    RichEdit doesn't have a built-in way to change the color of an automatic hyperlink. The client can replace it with a friendly-name link with the friendly name having the same text as the underlying link. The client can use whatever color and formatting is desired for the friendly name. The only problem with this approach is that changing the friendly name doesn't change the actual link, which is hidden.

  • Anonymous
    October 16, 2013
    Which version of RichEdit supports custom URL schemes (lParam) recognized if AURL_ENABLEURL is active as described in: msdn.microsoft.com/.../bb787991(v=vs.85).aspx

  • Anonymous
    October 17, 2013
    RichEdit 8, which ships with Windows 8.