Etudes for Microsoft Word Programmers

Home ] Up ] Etude 1.1. Text Fit ] Etude 1.2. Symbol Case ] Etude 1.3. Finding and Painting Hyperlinks ] Etude 1.4. Styles ] Etude 1.5. Inserting Formatted Text ] Etude 1.6. Text in the Column. ] Etude 1.7. Formatting Headline. ]

Etude 1.3. Finding and Painting Hyperlinks

A hyperlink, or simply a link, is a reference in a hypertext document to another document or other resource. It is similar to a citation in literature. Combined with a data network and suitable access protocol, it can be used to fetch the resource referenced. This can then be saved, viewed, or displayed as part of the referencing document.

The most common type of hyperlink is the URL used in the World Wide Web. A web browser usually displays a hyperlink in some distinguishing way, e.g. in a different colour, font or style. ...

Hyperlinks were first described in 1945 in the landmark paper As We May Think, as well in the widely-known project Xanadu starting in the 1960s.

Task. "Find and Replace" Dialog. Find  Object and Replacement Object .

Convenient navigation across the document is one of the most important skills of any text processor. Any user should, without doubt, possess this skill. The convenience in navigation is especially actual for large (from tens to several hundred pages) documents. Among tools of navigation there are: the "Go To" function, which takes you to different objects of the document (bookmarks, pages, sections, lines, paragraphs, pictures, tables, boxes, elements of the table of contents and others) and also all ways to "Find and Replace", including the opportunity to make the attributes of text formatting the criterion of the search and the opportunity of their replacement.

If you are not acquainted with the objects "Find" and "Replacement" then now is the most suiting time for their studying. The functional part of the dialog "Find and Replace" is performed with the help of these objects. The study of the dialog is given in the Appendix. [Read]


Task. "Edit Hyperlink" Dialog. Hyperlink Object and Hyperlinks Collection.

It is difficult to imagine a useful text without hyperlinks nowadays. And you, are you sure that you  use every Microsoft Word capability concerning hyperlinks? If not, then all the capabilities of the dialog "Edit Hyperlink" are given in the Appendix. The properties and methods of the Hyperlink object and Hyperlinks collection, with the help of which Microsoft Word organizes the work of hyperlinks, are also there [Read].

Learn to put in and delete hyperlinks to different sites, to local documents, hyperlinks to bookmarks in the current document and other documents, and also the mail addresses. To study the process of putting in and deleting hyperlinks use the dialog "Edit Hyperlink" along with the automatic macros generator.

A hyperlink is an object with special functions. A piece of text, formatted like a hyperlink (usually it is colored blue and underlined), looks like a hyperlink, but it is not. It is just a piece of underlined text of blue color. The visible part of a hyperlink (the displayed text, TextToDisplay) is a piece of text formatted by the Hyperlink style. And the displayed text of a hyperlink doesn’t always coincide with the address of the hyperlink itself, i.e. a site in the web, the name of a document or e-mail address.

When you point the mouse cursor to the visible text of a hyperlink, the shape of the cursor changes. When you click on the text of a hyperlink, the process of the resolving and following begins. The address of the hyperlink is used in this case. The work of a hyperlink brings you to a site in the i-net, some document or the window of the mail program with the filled box "To:", if the hyperlink is a e-mail address.

Formatting of text by the Hyperlink style doesn’t make the text a hyperlink. It makes the text blue and underlined.


Template "", 28 Kb, ZIP,  [download].

Functional Specification


There is a document, in which all hyperlinks and e-mail addresses represent an "ordinary" text. Such text could be received by mail or imported from a text document, for instance. The task is to find in this text all entries like




and turn them into e-mail addresses.
It is also necessary to find all entries like




and turn them into working hyperlinks. The creation of a hyperlink will be called "painting" in this etude for the purpose of briefness. The term "painting" in this chapter means (specifically) the creation of Hyperlink objects.

It is necessary to create the "" template, in which there will be macros for the creation (search and painting) and removing of hyperlinks; and the toolbar "AhTextHyperlinks" which provides access to the operations of creation and removal of hyperlinks.

Toolbar "AhTextHyperlinks"

The toolbar "AhTextHyperlinks" looks like this.

The toolbar "AhTextHyperlinks" provides access to the following functions:






Brief prompt on the buttons of the toolbar.



Search and painting of hyperlinks.



Search and painting of e-mail addresses.

All Links


Search and painting of hyperlinks and e-mail addresses.



Removal of all hyperlinks from the current document.


When you push the button "Delete", ALL hyperlinks from the current document are deleted, including those which were possibly there before.


The brief prompt on the buttons of the toolbar looks like this:

Finding and Painting Hyperlinks

Here is the example of text before the use of the command of finding and painting of hyperlinks. The hyperlinks represent an "ordinary" text.

Here is the example of text AFTER the use of the command of finding and painting of hyperlinks. The hyperlinks are already painted. The e-mail addresses still represent "ordinary" text.

Finding and Painting e-mail Addresses

Here is the example of text after the use of the command of finding and painting of hyperlinks and e-mail addresses. Like the hyperlinks, the e-mail addresses are already painted.

Deleting All Hyperlinks

On the pressing the "Delete" button the program prompts for the user’s confirmation (as important information may be lost).

If the user presses "No" then the removal is canceled. After pressing "Yes" all hyperlinks and e-mail addresses are deleted from the current document, including those which were possibly there before the use of the command of finding and painting.

The hyperlinks are removed exactly as the Microsoft Word Hyperlinks collection objects. The visible text of a hyperlink (which sometimes coincides with the address and sometimes not) remains on its place. But the information about the address is completely lost if the visible text doesn’t coincide with this address. Be careful about it.

Implementation - Template ""

The operations of finding, painting and removal of hyperlinks are implemented in the  "" template. The toolbar "AhTextHyperlinks" represents a simple interface to these operations.

Module AhTextHyperlinks

' File|AhTextHyperlinks
' Etudes for Microsoft Word Programmers.
' Etude
1.3. Finding and Painting Hyperlinks.
' First published on
' © 2000-2007. Evgeny Akhundzhanov. All rights reserved worldwide.
Option Explicit

' Variables
Private iSelStart, iSelEnd As Long


' Constants
Private Const cStrAhTextHyperlinksHelp As String = _
"Etudes for Microsoft Word Programmers." & vbCrLf & _
"Etude 1.3. Finding and Painting Hyperlinks." & vbCrLf & _
"" & vbCrLf & vbCrLf & _
"Template - working with hyperlinks." & vbCrLf & vbCrLf & _
"Hyperlinks - find and paint hyperlinks" & vbCrLf & _
"E-Mails - find and paint e-mail addresses" & vbCrLf & _
"All links - find and paint both hyperlinks and e-mail addresses" & vbCrLf & _
"Delete - clean Hyperlinks collection." & vbCrLf & vbCrLf & _
"All functions effect active document." & vbCrLf & _
"Paint means add to Hyperlinks collection."
Private Const cStrAhTextHyperlinksConfirmDelete As String = _
 "You are about to delete all hyperlinks and e-mail addresses" & vbCrLf & _
 "from the current document. Some information could be lost." & vbCrLf & vbCrLf & _
 "Press 'Yes' button to continue with deletion. Continue?"


' Prefixes
Private Const cStrPrefixMail = "mailto:"
Private Const cStrPrefixHttp = "http://"
Private Const cStrPrefixFtp = "ftp://"

Search Patterns

' Regular expressions
Private Const cStrRegExpMail = _
Private Const cStrRegExpHttp = _

Subroutine AhHyperlinksHelp

' AhHyperlinksHelp
Sub AhHyperlinksHelp()
    MsgBox cStrAhTextHyperlinksHelp
End Sub

Subroutine AhHyperlinksDelete

' AhHyperlinksDelete
Sub AhHyperlinksDelete()
If Documents.Count = 0 Then Exit Sub
    If vbYes <> MsgBox(cStrAhTextHyperlinksConfirmDelete, vbYesNo) Then Exit Sub
    Dim dwLink, dwLinkCount As Long
    dwLinkCount = ActiveDocument.Hyperlinks.Count
    For dwLink = 1 To dwLinkCount
    Next dwLink
End Sub

Function AhHyperlinkExists

' AhHyperlinkExists
Private Function AhHyperlinkExists(ByVal strLinkTextToDisplay As String) As Boolean
    AhHyperlinkExists = False
    If Documents.Count = 0 Then Exit Function
    On Error GoTo ErrorLabel
    Dim hl As Hyperlink
    For Each hl In ActiveDocument.Hyperlinks
        If hl.TextToDisplay = strLinkTextToDisplay Then
            AhHyperlinkExists = True
            Exit For
        End If
    Next hl
    Exit Function
End Function

Function AhHyperlinkRangeExists

' AhHyperlinkRangeExists
Private Function AhHyperlinkRangeExists(ByVal rng As Range) As Boolean
    AhHyperlinkRangeExists = False
    If Documents.Count = 0 Then Exit Function
    On Error GoTo ErrorLabel
    Dim hl As Hyperlink
    For Each hl In ActiveDocument.Hyperlinks
        If hl.Range = rng Then
            AhHyperlinkRangeExists = True
            Exit For
        End If
    Next hl
    Exit Function
End Function

Subroutine AhHyperlinksDump

' AhHyperlinksDump
Private Sub AhHyperlinksDump()
Dim cnt As Long
Dim cntTotal As Long
Dim hl As Hyperlink
If Documents.Count = 0 Then Exit Sub
    cntTotal = ActiveDocument.Hyperlinks.Count
    For cnt = 1 To cntTotal
        Set hl = ActiveDocument.Hyperlinks(cnt)
        Debug.Print "<" & hl.TextToDisplay & "> = [" & hl.Address & "]"
    Next cnt
End Sub

Function AhHyperlinkFindAndAdd

' AhHyperlinkFindAndAdd
Private Function AhHyperlinkFindAndAdd(ByVal strPrefix As String, ByVal strFindPattern As String) As Boolean
    AhHyperlinkFindAndAdd = False
    If Documents.Count = 0 Then Exit Function
    With Selection.Find
        .Text = strFindPattern
        .Replacement.Text = ""
        .Forward = True
        .Wrap = wdFindStop
        .Format = False
        .MatchCase = False
        .MatchWholeWord = False
        .MatchWildcards = True
        .MatchSoundsLike = False
        .MatchAllWordForms = False
    End With
    If Selection.Find.Execute Then
        Dim strLinkText As String
        strLinkText = Selection.Range.Text
        Dim bExists As Boolean
        bExists = AhHyperlinkRangeExists(Selection.Range)
        Debug.Print "<" & strLinkText & "> exists = " & bExists
        AhHyperlinkFindAndAdd = True
        Dim strLinkFull As String
        strLinkFull = strPrefix + strLinkText
        On Error Resume Next
        ActiveDocument.Hyperlinks.Add Anchor:=Selection.Range, _
            Address:=strLinkFull, SubAddress:="", ScreenTip:="", _
        Selection.Start = Selection.End
        ' do nothing
    End If

End Function

Subroutine AhFindAndPaintLinks

' AhFindAndPaintLinks
Private Sub AhFindAndPaintLinks(ByVal strPrefix As String, ByVal strPattern As String)
If Documents.Count = 0 Then Exit Sub
    Application.ScreenUpdating = False
    Debug.Print "AhFindAndPaintHyperLinks START"
    Selection.HomeKey Unit:=wdStory ' move to the document.start
    Do While AhHyperlinkFindAndAdd("", strPrefix + strPattern)
    Selection.HomeKey Unit:=wdStory ' move to the document.start
    Do While AhHyperlinkFindAndAdd(strPrefix, strPattern)
    Debug.Print "AhFindAndPaintHyperLinks END" & vbCrLf
    Application.ScreenUpdating = True
End Sub

Subroutine AhFindAndPaintHyperLinks

' AhFindAndPaintHyperLinks
Sub AhFindAndPaintHyperLinks()
    AhFindAndPaintLinks cStrPrefixHttp, cStrRegExpHttp
End Sub

Subroutine AhFindAndPaintEMails

' AhFindAndPaintEMails
Sub AhFindAndPaintEMails()
    AhFindAndPaintLinks cStrPrefixMail, cStrRegExpMail
End Sub

Subroutine AhFindAndPaintAllLinks

' AhFindAndPaintAllLinks
Sub AhFindAndPaintAllLinks()
If Documents.Count = 0 Then Exit Sub
    AhFindAndPaintLinks cStrPrefixHttp, cStrRegExpHttp  ' HTTP
    AhFindAndPaintLinks cStrPrefixFtp, cStrRegExpHttp   ' FTP
    AhFindAndPaintLinks cStrPrefixMail, cStrRegExpMail  ' E-MAIL
End Sub


The template "" is created on the basis of specification in this etude. Its module "AhTextHyperlinks" contains macros for working with hyperlinks. The created toolbar "AhTextHyperlinks” provides a simple interface to the operations of creation (finding and painting) and removal of hyperlinks.

Simple macros for working with hyperlinks and e-mail addresses are implemented in this etude. The macro of the creation of hyperlinks uses regular expressions for pattern search and adds the found hyperlinks and e-mail addresses to the Microsoft Word Hyperlinks collection of the current document. The macro of the removal of hyperlinks deletes all hyperlinks from the current document with preliminary confirmation prompt.


Task 1. Selection.

Change the macros in order for the program to work with the selected text, if any. If not – then to work with the whole document. In both cases it is necessary to restore the initial selection after the completion.


Task 2. Search Patterns.

The rules of the e-mail addresses composition are much more complicated then it may seem. Thus, the above-given templates don’t admit IP-address for the host name.
Addresses like "
" are also dropped out.

The search pattern for hyperlinks ignores the number of the HTTP port and also the prefix https://.
Thus, the address like won’t be found.

Improve the search patterns that are used in the "AhTextHyperlinks" module.
Consult the "RFC 822" document if necessary.


Task 3 Find and Replace.

With the help of the dialog "Find and Replace" paint blue all entries of any word ("he", for instance). The result should look something like this:


Special note for those who are reading this text on paper, in black and white colors. In the above-given text all entries of the word "he" are painted blue.

Repeat the same thing in the macros recording mode. Run the recorded macros and make sure that the painting doesn’t work. The reason is in the error in Microsoft Word automatic macros generation. Now, when you got acquainted with the properties of Find and Replacement objects (you did, didn’t you?) can you correct the bug yourself?

If not, take it easy. In the next etude I’ll tell you how to fix the bug in the automatically generated macros of Find and Replacement.

The text of the example is taken from the essay of Joel Spolsky "The Development Abstraction Layer", published on


If you need regular expressions in your C++ programs try the Boost library

See also MSDN page "How to: Verify That Strings are in Valid E-Mail Format".


Etudes for Microsoft Word Programmers. Etude 1.3.

Unless otherwise noted, all materials on this site are
© 2000-2009 Evgeny Akhundzhanov, All Rights Reserved Worldwide
Microsoft is in no way affiliated with, nor offers endorsement of, this site. | E-mail the Author