Contents Index Topic Contents
	Previous Topic: HTML Clipboard Format Next Topic: Reference

Hyperlinks

This topic describes ActiveX™ Hyperlinking and the interfaces involved in adding hyperlink navigation to your document or application.

Introduction

Reference

Introduction

One of the most compelling ease-of-use features of World Wide Web applications is the navigation-based user interface model that includes point-and-click hyperlink navigation, a History list (with commands such as Go Back and Go Forward), and a Favorites list. Like other ActiveX-based technologies, ActiveX Hyperlinks enable you to add this hyperlink functionality to your documents and applications, allowing you to integrate them seamlessly with other hyperlinking applications, including Web browsers. ActiveX Hyperlinks allow you to:

• Add hyperlinking support to existing documents, objects, and applications.
• Integrate the documents of your application into enabled World Wide Web browsers.
• Support and integrate with key features of ActiveX Hyperlink applications (History, Favorites, Go Back, Go Forward, Go Home).
• Support navigation to documents on the Internet or an intranet.

This section provides an overview of hyperlinks, a description of the ActiveX Hyperlinking architecture (including the interfaces required to add hyperlink support to an application), and examples. Applications can choose to support various degrees of integration with the ActiveX Hyperlinking architecture. Where applicable, this document describes how to provide minimal or simple hyperlinking support, and also how to extend this support for more complete hyperlinking integration. For basic COM information, refer to The Component Object Model.

What Is a Hyperlink?

A hyperlink is a COM object that implements, at a minimum, the IHlink interface and acts as a link to an object at another location (the target). This target can be a reference to a location in the same document/object that contains the hyperlink; a different (top-level or embedded) document/object of the same class; or a different document/object of a different class. A hyperlink is made up of four parts:

• A moniker that identifies the target's location
• A string for the location within the target
• A friendly, or displayable, name for the target
• A string that can contain additional parameters

The data of the document/object can be stored in file system files, computers on the Internet (referred to by URLs, or universal resource locators), or any arbitrary location that can be referenced through monikers. Navigation to the location can be done by binding to the target and then asking it to jump to the location. How a hyperlink is presented to the user is up to the hyperlink container and the context of the hyperlink. While there are no user interface requirements limiting the presentation of hyperlinks, guidelines suggest that the hyperlinks should be made clear through coloring and/or underlining the hyperlink text, or by changing the cursor when selecting the hyperlink with the mouse.

What Is Hyperlink Navigation?

Hyperlink navigation involves a transition from one document, object, or application (the hyperlink container) to another document, object, or application (the hyperlink target). Usually both the hyperlink container and target remain running, but the hyperlink target is displayed over the hyperlink container. Hyperlink containers and targets can be top-level documents or Active Document objects in a browser application. Because of this variation, there are many possible forms of navigation. These include navigating from:

• One top-level document to another top-level document (in the absence of a browser).
• A top-level document to an Active Document object in a browser (for example, navigating from a stand-alone application to an HTML document).
• One Active Document object in a browser to another Active Document object in the same browser (for example, navigating from one HTML document to another).
• An Active Document object in a browser to an Active Document object in a binder-like application (for example, if the hyperlink target is embedded in an Office Binder document).
• One location in an object/document to another location in the same object/document.

In the third and fifth cases above, the window is reused. In the other cases, the hyperlink target appears in a new window. The ActiveX Hyperlinks architecture suggests a mechanism for creating the illusion of window reuse in such cases: the hyperlink container passes its current window position to the hyperlink target, and the hyperlink target positions its window in the exact same location. Upon successful navigation, the hyperlink container hides its window.

What Is a Browse Context?

By looking at the possible forms of navigation, it is clear that multiple objects/documents (perhaps from different processes) share some global context. This context knows the order in which documents have been visited. All jumps are recorded with this context, and this context chains them together in a stack that can be navigated using Go Back and Go Forward operations. This global context is called the browse context.

Even though a browse context is global and spans multiple processes, it need not be global per user, such as History and Favorites lists. There can be multiple browse contexts active at once. For example, in certain Web browsers you can start a new browse context using the right-mouse pop-up menu item Open In New Window. ActiveX Hyperlinking defines the interface for the standard system browse context. This allows hyperlink-aware documents and applications to integrate the browse context's navigation stack through the standard hyperlinking interfaces and their methods.

The Simple Hyperlinking API

There are two methods of dealing with hyperlinks, depending on the needed complexity of the hyperlink operation. The simple hyperlink navigation model is a helper API aimed at common navigation scenarios such as a control (like a pushbutton) embedded on a Web page that allows the user to jump to another page when it is clicked.

The simple hyperlink functions are an encapsulation of the more complex full hyperlinking interfaces. These full hyperlinking interfaces offer a much richer set of navigation operations. For example, you can use these interfaces for operations such as supporting navigation to a location within a new document type, or allowing the cutting and pasting or dragging and dropping of hyperlinks. The simple hyperlink navigation API allows hyperlink navigation without knowledge of any other hyperlink interfaces or objects (basically saying, "here is where I want to jump to, now go there"). This API includes the following functions:

• HlinkSimpleNavigateToString—Jumps to the location pointed to by a URL string.
• HlinkSimpleNavigateToMoniker—Jumps to the location pointed to by a URL moniker.
• HlinkGoBack—Jumps to the previous location on the History list (if object pointed to is hosted in an ActiveX hyperlink frame).
• HlinkGoForward—Navigates to the next location on the History list (if object pointed to is hosted in an ActiveX hyperlink frame).

These functions work within any ActiveX hyperlink frame application. A hyperlink frame is the outer container that contains the document processing the user's request to navigate (when a navigation action occurs). An application must expose the IHlinkFrame interface to be a hyperlink frame application. For example, Microsoft® Internet Explorer 3.0 is a hyperlink frame application that knows the user's current location in the navigation stack, and goes forward and backward properly.

The programmer is shielded from the architectural details of figuring out the History list to move forward and backward. An ActiveX Control or document hosted in a frame simply calls these functions to figure out where to go.

The calling object needs to know where in the navigation stack the user currently is so the user can go forward or backward properly. To do this, all that the calling object must pass in is the interface pointer to itself. In reality, this is the IUnknown pointer to the document or object that is initiating the hyperlink. (Note that this must be the pUnkOuter parameter for an aggregated COM object.) If the pointer is NULL, the hyperlink is assumed to originate from an ActiveX-unaware application (an application that does not expose the IHlinkFrame interface), and the navigation history list will not be updated. Using this object pointer, the API travels through the interface hierarchy of that object to locate its outer container to calculate navigation history and do the in-frame navigation.

The Hyperlink Architecture

The following sections describe the various components in the ActiveX Hyperlinks architecture and the interfaces they implement. Some of the components are standard, system-provided objects; the others are user-defined components that participate in ActiveX hyperlinking because they implement the appropriate interface(s).

The hyperlink target

A hyperlink target is a COM object that implements the IHlinkTarget interface and supplies its moniker, friendly name, and other information that other hyperlink objects will use to navigate to it. This can be a persisted ActiveX object that exposes IHlinkTarget, a persisted ActiveX object that exposes IOleObject, or any file that is viewed when its viewer application is launched through ShellExecute. An object (document) that wants to be targeted by hyperlinks can choose to implement all or part of the IHlinkTarget interface to integrate tightly with ActiveX Hyperlinks. If the object does not support IHlinkTarget, it can still act as a hyperlink target, but it won't be able to support internal navigation, and it will not have access to the common browse context that holds the navigation stack. A hyperlink target can be a top-level container document, an embedded object of arbitrary nesting, or, in general, any object that can be referenced through a moniker.

How to implement IHlinkTarget

An existing application that supports COM linking need only implement the IHlinkTarget interface on the same object that implements IPersistFile and IOleItemContainer. The application can also implement IPersistMoniker to support incremental rendering or asynchronous download as a persistence mechanism, rather than IPersistFile. Supporting IHlinkTarget from an Active Document object is the recommended way to make sure your document is viewable by browsers and participates in hyperlinking smoothly.

The hyperlink object

A hyperlink object implements the IHlink interface and encapsulates four pieces of reference information: a moniker to the hyperlink target; a string for the location within the target; a friendly name for the target; and additional parameters.

The hyperlink object completely encapsulates the behavior of navigating to a referenced location. It also supports the ability to save and load itself through the IPersistStream interface, and the ability to be transferred through the clipboard or through drag-and-drop operations by means of IDataObject. A standard hyperlink object implementation is provided with the system, and it is not advisable to implement another version. A document can use the standard hyperlink object to represent hyperlinks within itself, thus encapsulating the work of navigating, saving, loading, dragging, dropping, cutting, and pasting hyperlinks. Standard hyperlink objects are created through the HlinkCreateFromData, HlinkCreateFromMoniker, HlinkCreateFromString, and OleLoadFromStream functions. The standard hyperlink object implements the IHlink, IPersistStream, and IDataObject interfaces.

The hyperlink container

A hyperlink container is a document or application that contains hyperlinks. The container supports hyperlinks by implementing the IHlinkSite interface and, if the container's objects can be targets of other hyperlinks, the IHlinkTarget interface.

Note Generally, an object that acts as a hyperlink container can also act as a hyperlink target.

The hyperlink site

A hyperlink site is a COM object that implements the IHlinkSite interface and supplies either the moniker or interface identifier of its hyperlink container. One hyperlink site can serve multiple hyperlinks. The moniker supplied by the hyperlink site is used to evaluate relative monikers to the hyperlink target. If the relative moniker is NULL, the target of the link is in the same container object, and IHlink::Navigate can result in an efficient internal jump

Note The standard hyperlink object performs internal jumps by retrieving the container's IHlinkTarget interface using IHlinkSite::GetInterface (which avoids an unnecessary moniker bind). The object then asks the container to navigate directly through the IHlinkTarget::Navigate method.

The hyperlink frame

A hyperlink frame is a COM object that implements the IHlinkFrame interface and controls the top-level navigation and display of hyperlinks for the frame's container and the hyperlink target's server. Browser applications such as Microsoft Internet Explorer and the Microsoft Office Binder are examples of hyperlink frames. Ideally, a hyperlink frame also serves as an Active Document object frame, allowing it to support browsing and hyperlinking between various document objects.

The hyperlink browse context

The hyperlink browse context maintains the navigation stack that is passed during navigation from one document or application to another. As with the hyperlink object, the browse context is a standard object provided with the system.

In addition to maintaining the navigation stack, the browse context knows whether or not to enable Go Back and Go Forward commands. For example, if you navigate from A to B, A would create an instance of the browse context object (if it had not been given one before) and pass it to B. Next, if you navigate to C, B would pass the same browse context pointer to C. At this moment, the navigation stack of the browse context contains A, B, and C. Go Back is enabled but Go Forward is disabled. Now if you do Go Back, you will navigate to B and the navigation stack still contains the same three items. Now both Go Back and Go Forward are enabled. If you Go Back again, you will navigate to A, and again the navigation stack contains the same three elements. But now Go Back is disabled and only Go Forward is enabled.

In addition to maintaining the navigation stack, the browse context object manages the hyperlink frame window and hyperlink target object's window. This window position information allows hyperlinking from one top-level window to another while giving the illusion of window reuse (by positioning the windows on top of each other). Each hyperlink target is passed a browse context (through IHlinkTarget::SetBrowseContext) the first time it is navigated to. The hyperlink target registers with the browse context (through IHlinkBrowseContext::Register) and holds a reference to it. The target must also notify the browse context each time it is navigated to through IHlinkBrowseContext::OnNavigateHlink. The browse context uses this information to maintain the navigation stack, to remember the current item in the stack, and to manage the lifetimes of registered hyperlink target applications.

An Example of Simple Hyperlinking

The navigation in this example takes place between simple hyperlink containers and simple hyperlink targets, none of which understand how to use the hyperlinking browse context. For ActiveX Controls or Active Document objects hosted within a browser such as Microsoft Internet Explorer, this is the only hyperlinking support that is necessary to integrate fully in the navigation stack and history list. The following pseudo-code outlines the order or execution of methods among the various objects during navigation.

Note Simple hyperlinking is simple mainly for the hyperlink container and the hyperlink target, particularly if both are document objects hosted in a document object frame. In these cases, the frame takes over all responsibility for providing a navigation stack and integrated history/favorites. Note that there is no definition of simple hyperlinking for hyperlink frames.

Starting with a hyperlink container

The hyperlink container (for example, a document or an ActiveX Control embedded within a document) initiates the hyperlink navigation using one of the simple hyperlinking functions.

// do the navigation
HlinkSimpleNavigateToString( "http://www.microsoft.com/foo.htm", NULL,  NULL, 
    punkMe, 0, pbc, pbsc, 0);

The hyperlink frame (for example, Microsoft Internet Explorer) is called from within the simple navigation API (which packages up the call into a full call to HlinkNavigate). This is the frame's chance to provide an integrated user interface, progress feedback, cancellation options, and so forth. Often the hyperlink frame simply sets some flags and defers to the IHlink::Navigate method. Other frames might choose to do more work. For instance, a frame might decide to provide its own IBindStatusCallback in order to listen in on progress notifications during navigation.

Calling the hyperlink target

Usually, the system-provided hyperlink object gains control to do the navigation on behalf of the container or frame, resulting in a call to the hyperlink target.The hyperlink target then receives control to navigate to the specific location within the target. Notice that support for "sublocations" is optional. Also, the interpretation of location strings is left to the interpretation of the target object.

STDMETHODIMP
IHlinkTarget::Navigate(DWORD grfHLNF, LPCWSTR szLocation)
{
    IHlinkFrame* phlFrame = NULL;
    // if szLocation is not visible show it

    // if this hyperlink target is an Active Document object, try to
    // retrieve the hyperlink frame pointer from the IOleInPlaceFrame
    if (m_poleinplaceframe)
        m_poleinplaceframe->QueryInterface(IID_IHlinkFrame, (void**)&phlFrame);

    // notify the hlink frame and the browse context that the navigation
    // is complete. Note: either phlFrame or m_phlbc may be NULL
    HlinkOnNavigate(phlFrame, NULL, grfHLNF, m_pmk, szLocation, szFriendlyName);

    m_fHide = FALSE;
    m_fHideFrame = FALSE; 
}  // IHlinkTarget::Navigate

Receiving success notification

The hyperlink frame next receives notification of a successful navigation from IHlinkTarget::Navigate in order to reposition its windows and update its windows' visibility. If this is the same frame that hosted the hyperlink container that initiated the navigation, the flags set will ensure that the frame remains visible.

An Example of Complex Hyperlinking

The navigation in this example takes place between hyperlink containers and hyperlink targets that understand how to use the hyperlinking browse context. The following pseudo-code outlines the order or execution of methods among the various objects during navigation.

Starting with a hyperlink container

Before any navigation occurs, the container starts with a hyperlink object that has either been created (using HlinkCreateFromData, HlinkCreateFromMoniker, or HlinkCreateFromString) or loaded from persistent data (using OleLoadFromStream). The hyperlink container might initialize the hyperlink through the IHlink::SetHlinkSite method by passing in an IHlinkSite interface and hyperlink-specific data (dwSiteData), which allows the hyperlink container to use the same hyperlink site to service multiple hyperlinks.

When the container decides to navigate the link as a result of user action, it does the following:

// retrieve the hyperlink frame pointer
if (!m_fTriedToGetFrame && m_poleinplaceframe && m_phlFrame == NULL) {
    m_fTriedToGetFrame = TRUE;
    m_poleinplaceframe->QueryInterface(IID_IHlinkFrame, 
    (void**)&m_phlFrame);
    }

if (m_phlbc == NULL) {
    // get the browse context pointer
    if (m_phlFrame)
        m_phlFrame->GetBrowseContext(&m_phlbc);
    else 
        HlinkCreateBrowseContext(&m_phlbc);
    if (m_phlbc == NULL)
        return E_FAIL;

    // register with the browse context
    m_phlbc->Register(pmkThis, phls, &m_dwRegister);

    // because we want the user to be able to come back to this
    // object via GoBack functionality add self to the 
    // navigation stack. This effectively tells the browse context
    // that the current hyperlink container referred to by pmkThis 
    // is a member (at the top) of the navigation stack
    m_phlbc->OnNavigateHlink(NULL, pmkThis, szLocation, szFriendlyName);
    }

    if (m_phlFrame == NULL)    {
        HLBWINFO hlbwinfo;

        // initialize hlbwinfo with window locations and flags

        // register the browse window info in the browse context 
        // so it is later available to the hyperlink target and
        m_phlbc->SetBrowseWindowInfo(&hlbwinfo)
    
        // set the flag indicating that this window should be
        // hidden after navigation. But this flag is cleared in the 
        // IHlinkTarget::Navigate and IHlinkFrame::OnNavigate methods.
        m_fHide = TRUE;
        v_fHideAppFrame = TRUE;  // only the MDI applications need this 
                                 //separate flag
        }
    else {
        m_fHide = FALSE;
        v_fHideAppFrame = FALSE; 
    }

    hr = HlinkNavigate(pkl, m_phlFrame, NULL,  pbc /* could be NULL */, 
    pibsc, m_phlbc);
    
    if (hr == NOERROR) {
        if (m_fHide)
            // Hide this document
        if (m_vfHideAppFrame)
            // Hide/Minimize application's frame window
        }

Calling the hyperlink frame

The hyperlink frame is called from within HlinkNavigate. This is the frame's chance to provide an integrated user interface, progress feedback, cancellation ability, and so forth. Often the hyperlink frame simply sets some flags and defers to the IHlink::Navigate method.

STDMETHODIMP
IHlinkFrame::Navigate(DWORD grfHLNF, IBindCtx* pbc,  
    IBindStatusCallback* pbsc,  IHlink* phlDest)
{
    // This flag gets cleared in IHlinkFrame::OnNavigate().
    // Thus if the Navigation is within the same frame window 
    // then we will get the right behavior as this flag gets
    // cleared in the OnNavigate() method.
    m_fHide = TRUE;  

    // some frames need only the following function so that 
    // they can properly show and hide themselves.
    // others may hook themselves into the IBindStatusCallback
    // for progress notification
    hr = IHlink::Navigate(NULL, pbc, pbsc, phlDest);
    if (SUCCEEDED(hr) && m_fHide)
        // Hide the frame window
}  // IHlinkFrame::Navigate

Other frames might choose to do more work. For instance, a frame may decide to provide its own IBindStatusCallback in order to listen in on progress notifications during navigation.

Jumping to the hyperlink target

When called by the hyperlink frame, the system hyperlink object gains control to do most of the navigation work and to integrate the results with the browse context. The following code is a sample implementation of a hyperlink object. The system-provided hyperlink object uses similar code.

STDMETHODIMP
IHlink::Navigate(DWORD grfHLNF, IBindCtx* pbc,  IBindStatusCallback* 
    pbsc, IHlinkBrowseContext* phlbc)
{
    IHlinkTarget* phlTarget = NULL;
    IMoniker* pmkLeft = NULL;

    if (grfHLNF & HLNF_USEBROWSECONTEXTCLONE) {
        grfHLNF &= ~HLNF_USEBROWSECONTEXTCLONE;
        phlbc->Clone(NULL, IID_IHlinkBrowseContext, &phlbc);
        }
    else {
        hr = m_phlSite->GetMoniker(m_dwSiteData, 
        OLEGETMONIKER_ONLYIFTHERE, OLEWHICHMK_CONTAINER, &pmkLeft);
        if (FAILED(hr) || m_pmkTarget->IsEqual(pmkLeft)) {
            hr = m_phlSite->GetInterface(dwSiteData, 0, IID_IHlinkTarget,
                (void**)&phlTarget);
            if (FAILED(hr))
                phlbc->GetObject(m_pmkTarget, &phlTarget);
            }
        
    if (phlTarget == NULL) {
        // Set the pbsc in the pbc to get asynch and notification
        // binding behavior requested by caller
        m_pmkTarget->BindToObject(pmkLeft, IID_IHlinkTarget, &phlTarget);
        phlTarget->SetBrowseContext(phlbc);
        }
        
    phlTarget->Navigate(grfHLNF, m_szLocation);
}  // IHlink::Navigate

Setting the browse context

During the execution of the above code, the hyperlink target receives the browse context for the navigation. This provides information about the hyperlink navigation stack and window positions for the hyperlinking.

Note This function is not called in all hyperlinking circumstances, for example in the Simple Hyperlinking example above. A simple hyperlink target need not implement this function.

STDMETHODIMP
CHlinkTarget::SetBrowseContext(IHlinkBrowseContext* phlbc)
{
    if (m_phlbc != NULL) {
        m_phlbc->Revoke(m_dwRegister);
        m_phlbc->Release();
        }
    m_phlbc = phlbc;
    if (m_phlbc != NULL) {
        m_phlbc->AddRef();
        m_phlbc->Register(0, (IUnknown*)this, m_pmk, &m_dwRegister);
        }

    return S_OK;
}  // CHlinkTarget::SetBrowseContext

The hyperlink target then receives control to navigate to the specific location within the target.

STDMETHODIMP
IHlinkTarget::Navigate(DWORD grfHLNF, LPCWSTR szLocation)
{
    IHlinkFrame* phlFrame = NULL;

    // if the object is not visible, activate it and show it.
    // jump to the location indicated by szLocation

    // if this hyperlink target is an Active Document object,
    // try to retrieve the hyperlink frame pointer
    // from the IOleInPlaceFrame
    if (m_poleinplaceframe)
        m_poleinplaceframe->QueryInterface(IID_IHlinkFrame,
        (void**)&phlFrame);

    // notify the hlink frame and the browse context that 
    //the navigation is complete.
    // Note: either phlFrame or m_phlbc may be NULL
    HlinkOnNavigate(phlFrame, m_phlbc, grfHLNF, m_pmk, szLocation, 
    szFriendlyName);

    if (phlFrame == NULL && !(grfHLNF & HLNF_INTERNALJUMP)) {
        HLBWINFO hlbwi;
        phlbc->GetBrowseWindowInfo(&hlbwi);

        // adjust the document and frame windows according 
        // to the dimensions in HLBWI
    }

    m_fHide = FALSE;    
    m_fHideFrame = FALSE; 
}  // IHlinkTarget::Navigate

Receiving success notification

The hyperlink frame next receives notification of a successful navigation from within IHlinkTarget::Navigate in order to reposition its windows and update their visibility. If this is the same frame that hosted the hyperlink container that initiated the navigation, the m_fHide flag set below will ensure that the frame remains visible.

STDMETHODIMP
IHlinkFrame::OnNavigate(DWORD grfHLNF)
{
    if (!(grfHLNF & HLNF_INTERNALJUMP)) {
        HLBWINFO hlbwi;
        m_phlbc->GetBrowseWindowInfo(&hlbwi);
        // Adjust this document/frame windows according to the
        // dimensions in hlbwi
    }    
    m_fHide = FALSE;    
}  // IHlinkFrame::OnNavigate

Finally, the browse context receives notification of a successful navigation from IHlinkTarget::Navigate in order to update the navigation stack.

STDMETHODIMP
IHlinkBrowseContext::OnNavigateHlink(DWORD grfHLNF, IMoniker* 
    pmkTarget, LPCWSTR szLocation, LPCWSTR szFriendlyName)
{
    // if CreateNoHistory or NavigatingToStackItem, return immediately
    // unless NavigatingBack or NavigatingForward is also set
    if (grfHLNF & (HLNF_CREATENOHISTORY | HLNF_NAVIGATINGTOSTACKITEM)) {
        if (!(grfHLNF & (HLNF_NAVIGATINGBACK | HLNF_NAVIGATINGFORWARD)))
            return NOERROR;
        }
    if (grfHLNF & HLNF_NAVIGATINGBACK)
        --m_iCurrent;
    else if (grfHLNF & HLNF_NAVIGATINGFORWARD)
        ++m_iCurrent;
    else {
        // Add this hyperlink to the navigation stack at m_iCurrent+1;
        // remove all items greater than m_iCurrent+1,

        ++m_iCurrent;
        }
}  // IHlinkBrowseContext::OnNavigateHlink

---

 Top of Page
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.