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



Comments

  • Invalid Link (comment posted for Sam Hobb)

    Posted by Brad Jones on 03/22/2004 08:15am

    The link in the article for HLINKAXD.exe is now not valid. However it is described in Microsoft Knowledge Base Article - 178853 ("SAMPLE: HLINKAXD Demonstrates a Hyperlinking Active Document") and is available from there

    Reply
  • I ask you some quesstion

    Posted by Legacy on 04/19/1999 12:00am

    Originally posted by: maqi

    I can link to other site use follow :
    
    HlinkSimpleNavigateToString(L"/",
    NULL,NULL,NULL, 0, NULL, NULL, 0);
    But I can't implent:
    CString url = "/"
    HlinkSimpleNavigateToString(url,
    NULL,NULL,NULL, 0, NULL, NULL, 0);

    I have seen you do it like this:
    hr = HlinkCreateFromMoniker(pMoniker,
    T2OLE(strBookmarkName),
    T2OLE(strBookmarkName),
    NULL,
    0,
    NULL,
    IID_IHlink,
    (void**) &pHlink);

    But I can't use like this:
    HlinkSimpleNavigateToString(T2OLE(url),
    NULL,NULL,NULL, 0, NULL, NULL, 0);

    By the way,how can I link to the frame name what I need?
    What shall I do?
    Thank you a lot!

    Reply
  • You are great!

    Posted by Legacy on 04/15/1999 12:00am

    Originally posted by: maqi

    You are great!
    
    But I don't know to use implement Interface like IHlinkTarget?
    I look a topic like implement Interface like this:

    CLISID clsid;
    LPCLASSFACTORY pClf;
    LPUNKNOWN pUnk;
    IMotion * pMot;
    IVisual * pVis;

    if((hr = ::CLSIDFromProgID(L"Spaceship",&Clisd))!=NOERROR)
    {
    ...
    }
    if(hr = ::CoGetClassObject(clsid,CLSCTX_INPROC_SERVER,NULL,IID_IClassFactory,(void**)&pClf))!= NOERROR)
    {
    ...
    }

    pClf->CreateInstance(..,(void**)&pUnk);
    pUnk->QueryInterface(IID_IMotion,(void**)&pMot));
    pMot->QueryInterface(IID_IVisual,(void**)&pVis));

    pMot->Fly();
    ...
    ..


    That I can use COM just like this.
    I look your demo n times.But I can't understand How to implent it.

    Thank you.

    Reply
Leave a Comment
  • Your email address will not be published. All fields are required.

Top White Papers and Webcasts

  • Today's agile organizations pose operations teams with a tremendous challenge: to deploy new releases to production immediately after development and testing is completed. To ensure that applications are deployed successfully, an automatic and transparent process is required. We refer to this process as Zero Touch Deployment™. This white paper reviews two approaches to Zero Touch Deployment--a script-based solution and a release automation platform. The article discusses how each can solve the key …

  • On-demand Event Event Date: December 18, 2014 The Internet of Things (IoT) incorporates physical devices into business processes using predictive analytics. While it relies heavily on existing Internet technologies, it differs by including physical devices, specialized protocols, physical analytics, and a unique partner network. To capture the real business value of IoT, the industry must move beyond customized projects to general patterns and platforms. Check out this webcast and join industry experts as …

Most Popular Programming Stories

More for Developers

RSS Feeds