Persits Software, Inc. Web Site
 Navigator:  Home |  Manual |  Chapter 10: Interactive Features
Chapter 11: Form Creation Chapter 9: Working with Existing PDFs
  Chapter 10: Interactive Features
10.1 Destinations
10.2 Outlines
10.3 Annotations
10.4 Actions

10.1 Destinations

A destination defines a particular view of a document, consisting of the following:
  • The page of the document to be displayed;
  • The location of the document window on that page;
  • The magnification (zoom) factor to use when displaying the page.

A destination is represented by the PdfDest object creatable via PdfDocument's CreateDest method, or alternatively, via PdfPage's CreateDest method. Both CreateDest methods take an optional parameter object or parameter string as an argument.

Once a destination object is created, it can be assigned to PdfDocument's OpenAction property which controls which part of the document is to be displayed, and at what zoom factor, when the document is opened. A destination object can also be assigned to an outline item, annotation or action (all described below).

A destination created with no parameters, or with the Fit parameter set to True, displays a page magnified just enough to fit the entire page both horizontally and vertically:

PdfDest objDest = objPage.CreateDest() or
PdfDest objDest = objPage.CreateDest("Fit=true");

A destination created with the FitH parameter set to True displays a page magnified just enough to fit the entire width of the page within the window. An optional Top parameter specifies the vertical position of the page to be displayed at the top edge of the window:

PdfDest objDest = objPage.CreateDest("FitH=true");
PdfDest objDest = objPage.CreateDest("FitH=true; Top=100");

Similarly, a destination created with the FitV parameter set to True displays a page magnified just enough to fit the entire height of the page within the window. An optional Left parameter specifies the horizontal position of the page to be displayed at the left edge of the window:

PdfDest objDest = objPage.CreateDest("FitV=true");
PdfDest objDest = objPage.CreateDest("FitV=true; Left=130");

A destination created with the XYZ parameter set to True and additional optional parameters Left, Top and Zoom displays page with the coordinates (Left, Top) positioned at the top-left corner of the window and the content of the page magnified by the factor Zoom. A Zoom value of 1 means 100%, 2 - 200%, etc.

PdfDest objDest = objPage.CreateDest("XYZ=true; Left=100; Top=200; Zoom=2");

A destination created with the FitR parameter set to True and additional required parameters Left, Bottom, Right and Top displays a page magnified just enough to fit the rectangle specified by [Left, Bottom, Right, Top] entirely within the window both horizontally and vertically:

PdfDest objDest = objPage.CreateDest("FitR=true;Left=10;Bottom=10;Right=200;Top=100");

A destination created with the FitB parameter set to true displays a page magnified enough to fit its bounding box entirely within the window both horizontally and vertically. The FitB parameter can be used stand-alone as well as in conjunction with FitH and FitV parameters:

PdfDest objDest = objPage.CreateDest("FitB=true");
PdfDest objDest = objPage.CreateDest("FitB=true; FitV=true; Left=130");

The following code sample creates a document with gridlines, and sets the document's OpenAction property to various destinations based on passed URL parameters:

C#
PdfManager objPdf = new PdfManager();

// Create empty document
PdfDocument objDoc = objPdf.CreateDocument();

// Add a new page
PdfPage objPage = objDoc.Pages.Add();

// Select one of the standard PDF fonts
PdfFont objFont = objDoc.Fonts["Helvetica"];

// vertical grid
for( float x = 0; x < objPage.Width; x += objPage.Width / 20 )
{
   objPage.Canvas.DrawLine( x, 0, x, objPage.Height );
   objPage.Canvas.DrawText( x.ToString(), "angle=90;y=5;x=" + x.ToString(), objFont );
}

// horizontal grid
for( float y = 0; y <= objPage.Height; y += objPage.Height / 20 )
{
   objPage.Canvas.DrawLine( 0, y, objPage.Width, y );
   objPage.Canvas.DrawText( y.ToString(), "x=5;y=" + y.ToString(), objFont );
}

// Create destination based on URL param
PdfParam objParam = objPdf.CreateParam();

if( Request["FitV"] != null )
{
   objParam["FitV"]	= 1; // true
   objParam["Left"]	= float.Parse(Request["Left"]);
}

if( Request["FitH"] != null )
{
   objParam["FitH"]	= 1;
   objParam["Top"]	    = float.Parse(Request["Top"]);
}

if( Request["XYZ"] != null )
{
   objParam["XYZ"]	    = 1;
   objParam["Top"] 	= float.Parse(Request["Top"]);
   objParam["Left"]	= float.Parse(Request["Left"]);
   objParam["Zoom"]	= float.Parse(Request["Zoom"]);
}

PdfDest objDest = objPage.CreateDest( objParam );

// Assign destination to Doc's OpenAction
objDoc.OpenAction = objDest;


// Save document to HTTP stream
objDoc.SaveHttp( "attachment;filename=destdemo.pdf" );
VB.NET
Dim objPdf As PdfManager = new PdfManager()

' Create empty document
Dim objDoc As PdfDocument = objPdf.CreateDocument()

' Add a new page
Dim objPage As PdfPage = objDoc.Pages.Add()

' Select one of the standard PDF fonts
Dim objFont As PdfFont = objDoc.Fonts("Helvetica")

' vertical grid
For x As Single = 0 To objPage.Width step objPage.Width / 20
   objPage.Canvas.DrawLine( x, 0, x, objPage.Height )
   objPage.Canvas.DrawText( x.ToString(), "angle=90;y=5;x=" + x.ToString(), objFont )
Next

' horizontal grid
For y As Single = 0 to objPage.Height step objPage.Height / 20
   objPage.Canvas.DrawLine( 0, y, objPage.Width, y )
   objPage.Canvas.DrawText( y.ToString(), "x=5;y=" + y.ToString(), objFont )
Next

' Create destination based on URL param
Dim objParam As PdfParam = objPdf.CreateParam()

If Request("FitV") <> Nothing Then
   objParam("FitV")	= 1 ' true
   objParam("Left")	= Single.Parse(Request("Left"))
End If

If Request("FitH") <> Nothing Then
   objParam("FitH")	= 1
   objParam("Top")	    = Single.Parse(Request("Top"))
End If

If Request("XYZ") <> Nothing Then
   objParam("XYZ")	    = 1
   objParam("Top") 	= Single.Parse(Request("Top"))
   objParam("Left")	= Single.Parse(Request("Left"))
   objParam("Zoom")	= Single.Parse(Request("Zoom"))
End If

Dim objDest As PdfDest = objPage.CreateDest( objParam )

' Assign destination to Doc's OpenAction
objDoc.OpenAction = objDest


' Save document to HTTP stream
objDoc.SaveHttp( "attachment;filename=destdemo.pdf" )

Click the links below to run this code sample:

http://localhost/asppdf.net/manual_10/10_dest.cs.aspx
http://localhost/asppdf.net/manual_10/10_dest.cs.aspx?FitV=true&left=100
http://localhost/asppdf.net/manual_10/10_dest.cs.aspx?FitH=true&top=500
http://localhost/asppdf.net/manual_10/10_dest.cs.aspx?XYZ=true&left=200&top=500&zoom=2

http://localhost/asppdf.net/manual_10/10_dest.vb.aspx
http://localhost/asppdf.net/manual_10/10_dest.vb.aspx?FitV=true&left=100
http://localhost/asppdf.net/manual_10/10_dest.vb.aspx?FitH=true&top=500
http://localhost/asppdf.net/manual_10/10_dest.vb.aspx?XYZ=true&left=200&top=500&zoom=2  Why is this link not working?

10.2 Outlines
A PDF document may optionally display a document outline on the screen, allowing the user to navigate interactively from one part of the document to another. The outline consists of a tree-structured hierarchy of outline items (sometimes called bookmarks).

The document outline is represented by the PdfOutline object obtainable via PdfDocument's Outline property. PdfOutline is a collection of PdfOutlineItem objects representing individual outline items (bookmarks).

An outline item is added to the outline via PdfOutline's Add method which takes the following arguments:

  • Title: a string specifying the item's caption in the hierarchy;
  • Dest: a PdfDest object to be associated with the item. This argument can be null (Nothing) if the item should be associated with an action rather than destination.
  • Parent: a PdfOutlineItem object which the new item will become a child of in the hierarchy. This argument can be null (Nothing) to indicate that the item is to be a top-level one.
  • InsertBefore: a PdfOutlineItem object at the same level of the hierarchy as the new one specifying the position of the new item relative to its siblings. This argument can be null (Nothing) to indicate that the new item is to be inserted after all its siblings.
  • Param: an optional parameter object or parameter string specifying the item's appearance options.

    The Expanded parameter is True by default which means the item is open. If set to False, the item will be shown closed.

    The Italic and Bold parameters are both False by default. If set to true, the item is shown in italic and/or bold, respectively.

    The R, G, B parameters specify the item's color (black by default). Each of the values must be a number between 0 and 1.

Once an outline item is created, it can be assigned either a destination or action via its SetDest and SetAction methods, respectively. Note that SetDest and SetAction are mutually exclusive - an item can be associated with either an action or destination but not both.

The following code sample creates a two-page document with a 6-item outline. The outline items (except the top-level one) point to various locations within the document. The outline hierarchy is organized as follows:

C#
PdfManager objPdf = new PdfManager();

// Create empty document
PdfDocument objDoc = objPdf.CreateDocument();

// Add new pages
PdfPage objPage1 = objDoc.Pages.Add();
PdfPage objPage2 = objDoc.Pages.Add();

// Make document fit window and show outlines
objDoc.OpenAction = objPage1.CreateDest();
objDoc.PageMode = pdfPageMode.pdfUseOutlines;


// Select one of the standard PDF fonts
PdfFont objFont = objDoc.Fonts["Helvetica"];

// Param string
string strParams = "x=0; y=650; width=612; alignment=center; size=50";

// Draw text on page
objPage1.Canvas.DrawText( "Page 1", strParams, objFont );
objPage2.Canvas.DrawText( "Page 2", strParams, objFont );

// Build outline hierarchy
PdfOutline objOutline = objDoc.Outline;
PdfOutlineItem objTitle = objOutline.Add("User Manual", 
	null, null, null, "Bold=true");

PdfOutlineItem objChapter1 = objOutline.Add("Chapter 1", 
	objPage1.CreateDest(), objTitle, null, "Bold=true; Italic=true");
PdfOutlineItem objSection11 = objOutline.Add("Section 1.1", 
	objPage1.CreateDest("XYZ=true;Zoom=2;Top=300"), objChapter1, null );

PdfOutlineItem objChapter2 = objOutline.Add("Chapter 2", 
	objPage2.CreateDest(), objTitle, null, "Bold=true; Italic=true");
PdfOutlineItem objSection21 = objOutline.Add("Section 2.1", 
	objPage2.CreateDest("XYZ=true;Zoom=2;Top=500"), objChapter2, null );
PdfOutlineItem objSection22 = objOutline.Add("Section 2.2", 
	objPage2.CreateDest("XYZ=true;Zoom=2;Top=200"), objChapter2, null );

// Save document, the Save method returns generated file name
string strFilename = objDoc.Save( Server.MapPath("outline.pdf"), false );
VB.NET
Dim objPdf As PdfManager = new PdfManager()

' Create empty document
Dim objDoc As PdfDocument = objPdf.CreateDocument()

' Add new pages
Dim objPage1 As PdfPage = objDoc.Pages.Add()
Dim objPage2 As PdfPage = objDoc.Pages.Add()

' Make document fit window and show outlines
objDoc.OpenAction = objPage1.CreateDest()
objDoc.PageMode = pdfPageMode.pdfUseOutlines


' Select one of the standard PDF fonts
Dim objFont As PdfFont = objDoc.Fonts("Helvetica")

' Param string
Dim strParams As String = "x=0; y=650; width=612; alignment=center; size=50"

' Draw text on page
objPage1.Canvas.DrawText( "Page 1", strParams, objFont )
objPage2.Canvas.DrawText( "Page 2", strParams, objFont )

' Build outline hierarchy
Dim objOutline As PdfOutline = objDoc.Outline
Dim objTitle As PdfOutlineItem = objOutline.Add("User Manual", _
	Nothing, Nothing, Nothing, "Bold=true")

Dim objChapter1 As PdfOutlineItem = objOutline.Add("Chapter 1", _
	objPage1.CreateDest(), objTitle, Nothing, "Bold=true; Italic=true")
Dim objSection11 As PdfOutlineItem = objOutline.Add("Section 1.1", _
	objPage1.CreateDest("XYZ=true;Zoom=2;Top=300"), objChapter1, Nothing )

Dim objChapter2 As PdfOutlineItem = objOutline.Add("Chapter 2", _
	objPage2.CreateDest(), objTitle, Nothing, "Bold=true; Italic=true")
Dim objSection21 As PdfOutlineItem = objOutline.Add("Section 2.1", _
	objPage2.CreateDest("XYZ=true;Zoom=2;Top=500"), objChapter2, Nothing )
Dim objSection22 As PdfOutlineItem = objOutline.Add("Section 2.2", _
	objPage2.CreateDest("XYZ=true;Zoom=2;Top=200"), objChapter2, Nothing )

' Save document, the Save method returns generated file name
Dim strFilename As String = objDoc.Save( Server.MapPath("outline.pdf"), False )

Note that we set PdfDocument's PageMode property to pdfPageMode.pdfUseOutline to show the outline hierarchy automatically when the document opens.

Click the links below to run this code sample:

http://localhost/asppdf.net/manual_10/10_outline.cs.aspx
http://localhost/asppdf.net/manual_10/10_outline.vb.aspx  Why is this link not working?

10.3 Annotations
An annotation is an interactive object placed on a page, such as a text note or embedded file. PDF includes a wide variety of standard annotation types.

Many of the standard annotations may be displayed in either the open or closed state. When closed, they appear on the page in some distinctive form depending on the specific annotation type, such as an icon, a box or a rubber stamp. When the user activates the annotation by clicking it with the mouse, it exhibits its associated object, such as by opening a pop-up window displaying a text note, or by opening an embedded file in its respective application.

10.3.1 Code Sample

The Annots property of the PdfPage object returns a PdfAnnots collection of PdfAnnot objects representing individual annotations on the page. An annotation is added to a page via the PdfAnnots.Add method.

The following code sample puts a simple text annotation on a one-page document (most of the code omitted for brevity):

C#
PdfAnnot objAnnot = objPage.Annots.Add("This is a simple text annotation.", "x=10, y=700; width=200; height=50" );
VB.NET
Dim objAnnot As PdfAnnot = objPage.Annots.Add("This is a simple text annotation.", "x=10, y=700; width=200; height=50" )

Click the links below to run this code sample:

http://localhost/asppdf.net/manual_10/10_annot.cs.aspx
http://localhost/asppdf.net/manual_10/10_annot.vb.aspx  Why is this link not working?

10.3.2 Add Method Parameters

The overloaded PdfAnnots.Add methods take as many as 4 arguments:

10.3.3 Annotation Types

10.3.4 Changing Default Appearance of Annotations

By default, the way an annotation is displayed on the page is at the discretion of the viewer application. Acrobat Reader 5.0, for example, contains built-in appearances for only a few annotation types, others are displayed as gray boxes with a question mark.

AspPDF.NET enables you to specify an arbitrary appearance (and even a set of appearances) for an annotation via PdfAnnot's Graphics property which can be assigned an instance of the PdfGraphics object described in Chapter 5.

PdfAnnot.Graphics is a parameterized property returning or specifying a PdfGraphics object that defines this annotation's appearance. It accepts two arguments, the Type and optional State (the latter is only used in interactive form fields described in Chapter 11.)

In a simple scenario, an annotation only has one ("normal") appearance. An annotation may also have two more optional appearances displayed when the mouse is clicked on, or moved over, the active area, referred to as "down" and "rollover" appearances, respectively. The Type argument specifies the type of appearance. Possible values are: 0 (normal), 1 (down) and 2 (rollover).

The following code sample creates an annotation of the type Stamp and sets its appearance to an image displaying the word "Paid".

C#
PdfManager objPdf = new PdfManager();

// Create empty document
PdfDocument objDoc = objPdf.CreateDocument();

// Add a new page
PdfPage objPage = objDoc.Pages.Add();

// Add annotation with custom appearance
string strNotice = "This invoice was paid on June 10, 2003.";
PdfAnnot objAnnot = 
	objPage.Annots.Add(strNotice, "x=10, y=600; width=182; height=131; Type=Stamp");

// Create a graphics object for this annotation containing an image    
PdfGraphics objPaidGraph = 
	objDoc.CreateGraphics("left=0; bottom=0; right=182; top=131");

PdfImage objImage = objDoc.OpenImage( Server.MapPath("paid.gif") );
objPaidGraph.Canvas.DrawImage(objImage, "x=0, y=0");

// Use this graphics object as the annotation's appearance
objAnnot.Graphics[0] = objPaidGraph;


// Save document, the Save method returns generated file name
string strFilename = objDoc.Save( Server.MapPath("appearance.pdf"), false );
VB.NET
Dim objPdf As PdfManager = New PdfManager()
        
' Create empty document
Dim objDoc As PdfDocument = objPdf.CreateDocument()

' Add a new page
Dim objPage As PdfPage = objDoc.Pages.Add()

' Add annotation with custom appearance
Dim strNotice As String = "This invoice was paid on June 10, 2003."
Dim objAnnot As PdfAnnot = _
	objPage.Annots.Add(strNotice, "x=10, y=600; width=182; height=131; Type=Stamp")

' Create a graphics object for this annotation containing an image    
Dim objPaidGraph As PdfGraphics = _
	objDoc.CreateGraphics("left=0; bottom=0; right=182; top=131")

Dim objImage As PdfImage = objDoc.OpenImage(Server.MapPath("paid.gif"))
objPaidGraph.Canvas.DrawImage(objImage, "x=0, y=0")

' Use this graphics object as the annotation's appearance
objAnnot.Graphics(0) = objPaidGraph


' Save document, the Save method returns generated file name
Dim strFilename As String = objDoc.Save(Server.MapPath("appearance.pdf"), False)

Click the links below to run this code sample:

http://localhost/asppdf.net/manual_10/10_appearance.cs.aspx
http://localhost/asppdf.net/manual_10/10_appearance.vb.aspx  Why is this link not working?

10.4 Actions
An action is a set of instructions or commands the viewer application must carry out in response to a certain event, such a mouse click, document opening, push of a button, etc. Some examples of actions are jumping to another PDF document, playing a sound, launching an application or executing a JavaScript script.

An action is represented by the PdfAction object creatable via PdfDocument's CreateAction method. This method takes two arguments: a parameter object or parameter string specifying the action Type as well as other type-specific parameters, and a string value which has different meanings depending on the action type (and may be ignored altogether by some action types).

The action types currently supported are:

goto (1), gotor (2), launch (3), uri (5), named (9), submit (10), reset (11) and javascript (13).

The GoTo and GoToR actions require that a destination be associated with them, the others are fully defined by the CreateAction arguments.

Once an action object is created, it is usually assigned to an annotation, outline item, or interactive form item (such as a pushbutton) via their respective SetAction methods.

10.4.1 Action Types

Chapter 11: Form Creation Chapter 9: Working with Existing PDFs
Search AspPDF.net

Newsletter Signup

Other Products
AspPDF
AspUpload
AspJpeg
AspEmail
AspEncrypt
AspGrid
AspUser
  This site is owned and maintained by Persits Software, Inc. Copyright © 2003 - 2014. All Rights Reserved.