ActiveX hyper linking

ActiveX hyper linking is a technology, which allows applications to provide navigation to different parts
of documents. If you go to the MSDN->Platform SDK->Internet/Intranet/Extranet Services->Internet
tools and technologies->Hyperlinks you will be able to read more comprehensive description of this
technology. Here I will just try to describe how I succeeded to add hyper linking capabilities to the
existing MFC sample – Drawcli. I have chosen this sample because my own report designer used in
ActiveX scripting hosts has been built starting from this sample. I though to myself – if I succeeded to
add hyper linking to Drawcli, probably it would be not difficult for myself to add this feature to my
report designer. This article is the result of my research work. And I think the results are not bad.
Having tried to understand the source code, probably, you will think that the sample has a lot of code,
which does not concern the technology itself. Well, I must admit that it is hard to provide a small code
to demonstrate hyper linking. Somewhere at the end of my research work I found an MFC sample in
the Microsoft knowledge base, which is probably much easier to understand than mine.

Here is the link to this sample:
http:// support.microsoft.com/download/support/mslfiles/Hlinkaxd.exe

I myself used a couple of functions (serializing hyperlinks) from that sample.

Why should you bother yourself with hyper linking? I think it is great technology and if you find a way to
add it to your products, I am sure you will not regret. For instance, you might provide:

a. navigation between logically bound reports;

b. between different parts of the same reports;

c. between a report and descriptions of the rules used to create the report prepared in HTML,
doc, xls or other format;

d. automatic opening of a form to edit data about an employee if someone clicks the employee’s
name in the report;

e. other approaches

You might want to provide capabilities to work inside a hyperlink frame like Microsoft Internet
Explorer.

Testing

In the Release folder you will find the following files:

1. Drawcli.exe

2. Drawcl1.dcl

3. Drawcl2.dcl

4. drawtool.doc

5. Sinus.xls

First run the Drawcli.exe. The program will register itself as a document server. Then run Microsoft
Internet Explorer 4.0 (I did not test the program with another browser). Open the Drawcl1.dcl file with
the explorer (File | Open) and maximize the explorer’s frame so that not to miss any part of the
document. You will see different pictures in the document with prompts to click some places to navigate
to another documents and bookmarks inside the documents. Try to click the places and see how
navigation occurs. Notice that you can use Go | Forward and Go | Back commands in IE.

Having tested the program inside a hyperlink frame (Internet Explorer is a hyperlink frame) you can try
to test the same navigation without the frame. Ensure that all programs participating in the navigation are
closed (Drawcli, Word, Excel). Then open Drawcl1.dcl file with the Drawcli program and try to follow
the links. You will see how navigation occurs between Drawcli’s MDI child windows and other
Microsoft Office documents. Notice that you can use navigation arrows on the navigation toolbars of
the programs, participating in the navigation process.

Then you can try one more way of testing. Create an empty document with Drawcli (File | New). Hyper
linking will not work until you save the file, so I recommend you to save it right away. Turn the
document into the design mode (View | Design mode). Select Draw | Hyper link menu item. Draw a
hyperlink. You can then edit the hyperlink properties by selecting Edit | Properties.

Properties:

1. Text – this one will be used to display a text. You can leave this blank if you do not want
anything to be displayed.

2. Link to file or URL – here provide a file name you want to link to. You can leave this blank if
you want to navigate to another place in the same document.

3. Named location in file – here you can use bookmark names in the Word documents, Excel
cell names, bookmark names of the Drawcli application and other location strings specific to the
document type you want to navigate to.

4. Friendly name of the hyperlink – IE will use this one in the Address prompt and also in the
history lists.

Having created the hyperlink you can turn the document in the run mode (View | Design mode) and try
to click the link. In the design mode you can also copy the hyperlink to the clipboard and then paste it in
a Word or Excel document by using Edit | Paste as Hyperlink. You can also select a block of text in a
Word document or a group of cells in an Excel document, copy them into the clipboard and then paste
them in the Drawcli document. This way of creation of hyperlinks is much faster. One restriction though.
You can create links only of the documents are saved.

Here is another approach to create a hyperlink. You can scroll a Drawcli document to a specific
location and then create a bookmark for this location (Bookmarks | Add). Then you can select
Bookmarks | Copy as hyperlink to clipboard. The bookmark will be copied as a hyperlink and you can
paste it into Microsoft Office documents or Drawcli documents or any other documents with hyper
linking support.

Implementation

First I added document server support to the existing Drawcli sample. I needed this because I wanted
the program to work inside Internet Explorer. You don’t have to implement this feature if you do not
want your documents to work inside a hyperlink frame. This step was easy to do. I just created a
document server application with MFC application wizard and ported some code. The code added to
the existing sample files is commented like the following:


//Doc server begin
m_server.UpdateRegistry(OAT_DOC_OBJECT_SERVER);
//Doc server end

There are a lot of ways to organize hyperlinks to the document. Microsoft Word for instance can
provide hyperlinks to the bookmarks in the document, Microsoft Excel provides links to some cells in
the workbook. For demo purposes I decided to implement bookmarks for Drawcli document class so
that later it would be possible to create hyperlinks to bookmarks. The code for bookmark support is
marked with the corresponding comments:


//Bookmarks begin
BOOL CreateBookmark(LPCTSTR lpstrBookmarkName,CPoint ptDoc,BOOL bHidden=FALSE);
BOOL DeleteBookmark(LPCTSTR lpstrBookmarkName);
CString CreateOrGetBookmarkAtCurrentPos(CDrawView* pView);

BOOL Navigate(LPCTSTR lpstrBookmarkName,CDrawView* pView);
//Bookmarks end

My third step was separating design mode from the run mode. You can add and edit objects only in the
design mode. In the run mode you can just click objects. Hyperlink objects provide navigation when
clicked.

Then I added new “draw” object to the sample – CDrawHLink. This object is used to display a
hyperlink in the document. The code for this object is commented with //Hlink begin and //Hlink end
marks. All other hyperlink related code is also commented with these marks.
Since there is a good description of hyper linking in MSDN I will provide just brief explanation of the
portions of code here.

The program besides the objects like rectangle, circle, line and polygon also deals with hyperlink COM
objects. A hyperlink is something that supports IHlink interface. The object is used to navigate to its
target location and since it supports IPersistStream and IDataObject it can be serialized and copied to
clipboard. It is up to your program how to display hyperlinks and when navigation should occur. A
hyperlink object is just used by COM in navigation process. Hyperlink objects are provided by the
system.

There are many ways to create a hyperlink object. Drawcli sample uses three different functions in three
corresponding situations.

1. When user manually completes the form for editing properties of a CDrawHLink object,
HlinkCreateFromString is used.

2. When user tries to paste objects from the clipboard and there is some data in the hyperlink
format, HlinkCreateFromData is used to create new hyperlink object.

3. When user invokes Bookmarks | Copy as hyperlink to clipboard menu item, a new object is
created with HlinkCreateFromMoniker function. Then the object is copied to clipboard.

A Drawcli document is a container of the hyperlink objects. This is why it supports IHlinkSite interface.
Since we also support navigation to different parts of our documents we have implemented the
IHlinkTarget interface for our document.

Each time a new hyperlink object is created it is associated with an instance of the CDrawHLink class
and connected to the hyperlink site, provided by the document. Each hyperlink object has an additional
site data of DWORD type.

While navigating, programs share a browse context where they put additional information about
completed navigation. Browse context is a system object accessible through the IHlinkBrowseContext
interface. The browse context object can be created by any program participating in navigation.
References to this object can be passed from one application to another. Usually if navigation occurs
inside a hyperlink frame, applications obtain reference to the browse context from the frame.
CDrawDoc::GetHlinkFrame() is used to obtain IHlinkFrame interface. IE exposes IHlinkFrame
interface through IServiceProvider not IOleInPlaceFrame.

CDrawDoc::GetBrowseContext() is used to obtain a pointer to the current browse context used by the
program. If the current context is NULL a new context will be created.
If navigation occurs outside any hyperlink frame, programs should act as if they share the same window.
This is why programs pass each other frame coordinates and hide themselves after navigation. Before
navigation occurs a hyperlink container program turn on some internal flags indicating that the program
should hide itself if the navigation succeed. If navigation occurs to the same document the flags are
turned off and the program does not hide itself. Drawcli uses two such flags:

1. CMainFrame:: m_bHidePending – is used to indicate that the main application window should
be hidden after navigation.

2. CDrawDoc:: m_bHidePending – is used to indicate that the document’s window should be
hidden after navigation.

Each hyperlink object has enough information to locate navigation target object – the one, which
supports IHlinkTarget interface. This process is documented well in MSDN. When the target is located,
the navigation process passes a location string to the target. The location string can be very complex. It
is up to target how to parse this string. Drawcli sample can process strings like Bookmark 10:25. In this
case the document will be scrolled to the 10:25 position. Also the sample understands location strings,
which are the names of the bookmarks added with the Bookmark | Add menu item.
If you develop rather complex systems you might want to combine hyperlinks with script hosting. For
instance, you could add hyperlink target support to your form designer. To let power users to create
additional kinds of hyperlinks to your forms you could fire event to the scripting engine to parse the
location string. For instance:


Sub EmployeeForm_OnNavigate(ByVal strLocation)

Power users would provide VBScript or JScript code to parse the location string and fill the form with
appropriate data. This process could include access to a database.

The combination of the two technologies can result in ability to parse location strings like: “Major
accountant”, “Best employee”, “Employee with ZIP” etc.

Again, here I do not explain any code because there is good explanation in MSDN. Take a look at the
source code and read MSDN documentation. Hyper linking will be an easy technology for you to
implement.

If you have questions drop me a message using andrew@skif.net. If you have anything to share with me
use the same address.

Download demo project – 389 KB

More by Author

Get the Free Newsletter!

Subscribe to Developer Insider for top news, trends & analysis

Must Read