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.

http://www.websters-online-dictionary.org/definition/hyperlink

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.

Resource

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

Functional Specification

Task

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

SOMETHING[AT]DOMAIN[DOT]HOST

èëè

mailto:SOMETHING[AT]DOMAIN[DOT]HOST

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

SOMETHING[DOT]DOMAIN[DOT]HOST

èëè

http://SOMETHING[DOT]DOMAIN[DOT]HOST

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 "AhTextHyperlinks.dot" 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:

Button

Macros

Description

Help

AhHyperlinksHelp

Brief prompt on the buttons of the toolbar.

Hyperlinks

AhFindAndPaintHyperLinks

Search and painting of hyperlinks.

E-Mails

AhFindAndPaintEMails

Search and painting of e-mail addresses.

All Links

AhFindAndPaintAllLinks

Search and painting of hyperlinks and e-mail addresses.

Delete

AhHyperlinksDelete

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.

Help

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 "AhTextHyperlinks.dot"

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

Module AhTextHyperlinks

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

'
' Variables
'
Private iSelStart, iSelEnd As Long

Constants

'
' Constants
'
Private Const cStrAhTextHyperlinksHelp As String = _
"Etudes for Microsoft Word Programmers." & vbCrLf & _
"Etude 1.3. Finding and Painting Hyperlinks." & vbCrLf & _
"http://www.transcriber.ru" & vbCrLf & vbCrLf & _
"Template AhTextHyperlinks.dot - 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

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

Search Patterns

'
' Regular expressions
'
Private Const cStrRegExpMail = _
"([A-Za-z0-9]{3,31})[\@]([A-Za-z0-9]{2,31})[.]([A-Za-z0-9]{2,31})"
Private Const cStrRegExpHttp = _
"([A-Za-z0-9]{3,31})[.]([A-Za-z0-9]{2,31})[.]([A-Za-z0-9/]{2,31})"

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
        ActiveDocument.Hyperlinks(1).Delete
    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
ErrorLabel:
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
ErrorLabel:
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
   
    Selection.Find.ClearFormatting
    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:="", _
            TextToDisplay:=strLinkText
           
        Selection.Start = Selection.End
    Else
        ' 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)
    Loop
   
    Selection.HomeKey Unit:=wdStory ' move to the document.start
    Do While AhHyperlinkFindAndAdd(strPrefix, strPattern)
    Loop
   
    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

Summary

The template "AhTextHyperlinks.dot" 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.

Tasks

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 "Name.Family@domain.host
" 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 https://www.transcriber.ru:8080 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 http://www.joelonsoftware.com/printerFriendly/articles/DevelopmentAbstraction.html.

 

If you need regular expressions in your C++ programs try the Boost library http://www.boost.org/libs/regex/doc/introduction.html.

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.
www.transcriber.ru | E-mail the Author