HlinkHlink*
*Contents  *Index  *Topic Contents
*Previous Topic: Interfaces
*Next Topic: IHlink::GetAdditionalParams

Hlink

The IHlink interface enables a COM object known as a hyperlink to completely encapsulate the behavior of navigating to its target location.

Hyperlinks are managed by COM hyperlink container objects, which support the IHlinkSite interface for hyperlinks within the container, and the IHlinkTarget interface for hyperlinks referring to documents or document objects within it.

IHlink provides methods for a hyperlink object to navigate to its target, access a friendly name for display purposes, and identify itself to its container and frame.

Implementing IHlink

Typically, you don't need to implement this interface. A standard implementation of a hyperlink component is provided as part of 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 capability of navigating, saving, loading, dragging, dropping, cutting, and pasting hyperlinks. The standard hyperlink object implements IHlink, IPersistStream, and IDataObject interfaces.

The support for IPersistStream means that hyperlink objects can be saved to or loaded from a stream, and the support for IDataObject means that hyperlink objects can be cut and pasted.

Using IHlink

IHlink interfaces are typically called by an application's hyperlink container as part of a user interface for creating new hyperlinks. Standard hyperlink objects are created through the HlinkCreateFromData, HlinkCreateFromMoniker, HlinkCreateFromString, and OleLoadFromStream functions.

While the hyperlink object provides many useful functions that are needed for general-purpose uses, often applications are only interested in navigating to a hyperlink target. For simple navigation needs, there are a number of "helper" functions, such as HlinkSimpleNavigateToString, HlinkSimpleNavigateToMoniker, and HlinkNavigateToStringReference, that allow simple hyperlink navigation without any knowledge of other hyperlink interfaces or objects.

Hyperlink navigation involves transitioning from one document/object/application—a hyperlink container—to another document/object/application—a hyperlink target. Usually, both remain running, but the hyperlink target visually replaces the hyperlink container (from which the navigation originated). There are three "flavors" of hyperlink containers and targets:

  1. Top-level documents.
  2. Active Document objects in a browser.
  3. Active Document objects in an Office Binder-like application that does not support OLE in-place/DocObj server functionality, and, therefore, can't be shown in-place in a browser.

The following are possible forms of navigation:

IHlink Methods in Vtable Order

IHlink methods Description
SetHlinkSite Saves the interface pointer on the site object.
GetHlinkSite Retrieves the interface pointer on the site object.
SetMonikerReference Sets the moniker reference of the target.
GetMonikerReference Retrieves the moniker and location portions of the target.
SetStringReference Sets the name and location portions of the target.
GetStringReference Retrieves the name and location portions of the target.
SetFriendlyName Sets the friendly name of the target.
GetFriendlyName Retrieves the friendly name of the target.
SetTargetFrameName Sets the name of the target frame.
GetTargetFrameName Retrieves the name of the target frame.
GetMiscStatus Queries if hyperlink is absolute or relative.
Navigate Navigates to the given target.
SetAdditionalParams Sets additional hyperlink parameters.
GetAdditionalParams Retrieves additional hyperlink parameters.

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