PrintDocument supports the use of hyperlinks to jump from one location to other location within the document or outside the document. By creating hyperlinks you can not only navigate through the content easily but also make the document more interactive.

PrintDocument allows you to add hyperlinks in different ways:

• Hyperlinks to anchors within the same document
• Hyperlinks to any location within the current Document
• Hyperlinks to a page in the same Document
• Hyperlinks to anchors in a different PrintDocument
• Hyperlinks to external files/URLs
• Hyperlinks to User Event

Let us explore each way of adding hyperlink in detail in the following sections:

Add Hyperlink to Anchor within the Same Document

To link one part of your document to the other, you have to follow the steps below:

• Mark the anchor: Mark the location (anchor) where you want the link to point.
• Add a hyperlink: Add a link (hyperlink) to that location to another part of the document. Note that you can add several hyperlinks pointing to the same anchor.

To create an anchor on a render object, you can add an element (of the type C1Anchor) to the Anchors collection of that render object. For example, if rt is a RenderTable you can refer the following code snippet:

// make an anchor
RenderText rt1 = new RenderText("This is text with anchor1.");
// the name ("anchor1") will be used to jump to this link:
rt1.Anchors.Add(new C1Anchor("anchor1"));

This will define an anchor with the name anchor1 (the name used to reference the anchor) on the render table.

To link another render object, for example a RenderText, to that anchor, you can refer the following code snippet:

RenderText rt2 = new RenderText("Click here to go to anchor1.");
rt2.Hyperlink = new C1Hyperlink(new C1LinkTargetAnchor("anchor1"),
    "This is status text when the mouse hovers over link to anchor1");
doc.Body.Children.Add(rt2);

Add Hyperlink to any Location within Current Document

You can add a link to an object within the current document without creating an anchor. Instead, you can use the C1LinkTargetDocumentLocation link target created directly on a render object.

For instance, the code snippet below depicts ro1 as an arbitrary render object in the current document:

C1LinkTarget linkTarget = new C1LinkTargetDocumentLocation(ro1);

Setting this link target on a hyperlink will make that hyperlink jump to the specified render object when the object owning the hyperlink is clicked. If, for example, ro2 is a render object that you want to turn into a hyperlink, the following code will link it to the location of ro1 on which the linkTarget was created:

rt2.Hyperlink = new C1Hyperlink();
rt2.Hyperlink.LinkTarget = linkTarget;

Add Hyperlink to a Page in Same Document

You can add hyperlinks to other pages in the same document without defining anchors, using the C1LinkTargetPage link target. The following page jumps are supported:

• To the first page of the document.
• To the last page of the document.
• To the previous page.
• To the next page.
• To a page specified by its absolute page number.
• To a page specified by an offset relative to the current page.

For instance, to make a link target jumping to the first page in the document, the following line of code may be used:

C1LinkTarget linkTarget = new C1LinkTargetPage(PageJumpTypeEnum.First);

In the above code snippet, PageJumpTypeEnum specifies the type of the page jump (of course, for jumps requiring an absolute or a relative page number, you must use a variant of the constructor accepting that).

Add Hyperlink to Anchor in a Different PrintDocument

To link a location in one document to a location in the other, you have to follow the steps below:

• Add an anchor to the target document.
• Generate that document and save it as a C1D file on your disk. You can save the document using the Save button of the preview control, or in code using the Save method on the document itself.
• Add a link pointing to that anchor to another document, in a way very similar to how an internal link is added. The only difference is that in addition to the target' anchor name you must also provide the name of the file containing the document.

The code snippet below creates a document with an anchor in it, and saves it in a disk file (myDocument1.c1d). It then creates another document, adds a link to the anchor in the first document to it, and shows the second document in a preview dialog box:

// Make target document with an anchor.
C1PrintDocument targetDoc = new C1PrintDocument();
RenderText rt1 = new RenderText("This is anchor1 in myDocument1.");
rt1.Anchors.Add(new C1Anchor("anchor1"));
targetDoc.Body.Children.Add(rt1);
targetDoc.Generate();
targetDoc.Save(@"c:\myDocument1.c1d");
 
// Make document with a hyperlink to the anchor.
C1PrintDocument sourceDoc = new C1PrintDocument();
RenderText rt2 = new RenderText("This is hyperlink to myDocument1.");
C1LinkTarget linkTarget = new C1LinkTargetExternalAnchor(@"c:\myDocument1.c1d", "anchor1");
rt2.Hyperlink = new C1Hyperlink(linkTarget);
sourceDoc.Body.Children.Add(rt2);
sourceDoc.Generate();
 
// Show document with hyperlink in preview.
C1PrintPreviewDialog preview = new C1PrintPreviewDialog();
preview.Document = sourceDoc;
preview.ShowDialog();                   

As you can see from the code snippet, to save the document, the Save method is used. This method saves the document in native PrintDocument format, the default extension for which is C1D. Files saved in that format can be later loaded into a C1PrintDocument object for further processing, or previewed using the print preview control.    

Before creating the hyperlink, a link target object must be created which is then passed to the hyperlink constructor. Several link target types are provided, derived from the C1LinkTarget base class. For external anchors, the C1LinkTargetExternalAnchor type is used. The link target contains information needed to process the jump to the link, in this case the document filename and the name of the anchor in it.

Add Hyperlink to an External File

A hyperlink to an external file differs from a link to an external anchor by the link target. The C1LinkTargetFile is the link target class for an external file link. Clicking such a link will use the Windows shell to open that file.

The code snippet below depicts the use of C1LinkTargetFile class to add a hyperlink to an external file.

// Make document with a hyperlink to external file.
C1PrintDocument doc = new C1PrintDocument();
RenderText rt = new RenderText("Explore drive C:...");
C1LinkTarget linkTarget = new C1LinkTargetFile(@"c:\");
rt.Hyperlink = new C1Hyperlink(linkTarget);
doc.Body.Children.Add(rt);
doc.Generate();
 
// Show document with hyperlink in preview.
C1PrintPreviewDialog preview = new C1PrintPreviewDialog();
preview.Document = doc;

Add Hyperlink to User Event

PrintDocument also lets you add a hyperlink that will fire an event on the C1PreviewPane, to be handled by your code. For this, the C1LinkTargetUser class should be used. The code snippet below illustrates how to use a hyperlink to user event:

private void UserLinkSetup()
{
    // Make document with a user hyperlink.
    C1PrintDocument doc = new C1PrintDocument();
    RenderText rt = new RenderText("Click this to show message box...");
    C1LinkTarget linkTarget = new C1LinkTargetUser();
    rt.Hyperlink = new C1Hyperlink(linkTarget);
    rt.Hyperlink.UserData = "My hyperlnk user data";
    doc.Body.Children.Add(rt);
    doc.Generate();
 
    // Create the preview.
    C1PrintPreviewDialog preview = new C1PrintPreviewDialog();
 
    // Attach an event handler to the UserHyperlinkJump event.
    preview.PreviewPane.UserHyperlinkJump += new HyperlinkEventHandler(PreviewPane_UserHyperlinkJump);
 
    // Preview the document.
    preview.Document = doc;
    preview.ShowDialog();
}
 
private void PreviewPane_UserHyperlinkJump(object sender, HyperlinkEventArgs e)
{
    MessageBox.Show(e.Hyperlink.UserData.ToString());
}

The code snippet will show the message box with the string that was assigned to the UserData property of the hyperlink when the hyperlink is clicked (in this case, "My hyperlink user data").