Persits Software, Inc. Web Site
 Navigator:  Home |  Manual |  Chapter 10: Interactive Features
Chapter 11: Forms 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:

Set Dest = Page.CreateDest or
Set Dest = Page.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:

Set Dest = Page.CreateDest("FitH=true")
Set Dest = Page.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:

Set Dest = Page.CreateDest("FitV=true")
Set Dest = Page.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.

Set Dest = Page.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:

Set Dest = Page.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:

Set Dest = Page.CreateDest("FitB=true")
Set Dest = Page.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:

VBScript
Set Pdf = Server.CreateObject("Persits.Pdf")
Set Doc = Pdf.CreateDocument
Set Page = Doc.Pages.Add
Set Font = Doc.Fonts("Helvetica")

' vertical grid
For x = 0 to Page.Width step Page.Width / 20
   Page.Canvas.DrawLine x, 0, x, Page.Height
   Page.Canvas.DrawText x, "angle=90;y=5;x=" & x, Font
Next

' horizontal grid
For y = 0 to Page.Height step Page.Height / 20
   Page.Canvas.DrawLine 0, y, Page.Width, y
   Page.Canvas.DrawText y, "x=5;y=" & y, Font
Next

' Create destination based on URL param
Set Param = Pdf.CreateParam
If Request("FitV") <> "" Then
   Param("FitV") = True
   Param("Left") = Request("Left")
End If

If Request("FitH") <> "" Then
   Param("FitH") = True
   Param("Top") = Request("Top")
End If

If Request("XYZ") <> "" Then
   Param("XYZ") = True
   Param("Top") = Request("Top")
   Param("Left") = Request("Left")
   Param("Zoom") = Request("Zoom")
End If

Set Dest = Page.CreateDest(Param)

' Assign destination to Doc's OpenAction
Doc.OpenAction = Dest

' Save to HTTP stream
Doc.SaveHttp "attachment;filename=destdemo.pdf"

C#
IPdfManager objPdf = new PdfManager();
IPdfDocument objDoc = objPdf.CreateDocument(Missing.Value);
IPdfPage objPage = objDoc.Pages.Add(Missing.Value, Missing.Value, Missing.Value);
IPdfFont objFont = objDoc.Fonts["Helvetica", Missing.Value];

// 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
IPdfParam objParam = objPdf.CreateParam( Missing.Value );

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

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

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

IPdfDest objDest = objPage.CreateDest( objParam );

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

// Save document to HTTP stream
objDoc.SaveHttp( "attachment;filename=destdemo.pdf", Missing.Value );

Click the links below to run this code sample:

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

http://localhost/asppdf/manual_10/10_dest.aspx
http://localhost/asppdf/manual_10/10_dest.aspx?FitV=true&left=100
http://localhost/asppdf/manual_10/10_dest.aspx?FitH=true&top=500
http://localhost/asppdf/manual_10/10_dest.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 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 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 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:

VBScript
Set Pdf = Server.CreateObject("Persits.Pdf")
Set Doc = Pdf.CreateDocument
Set Page1 = Doc.Pages.Add
Set Page2 = Doc.Pages.Add

' Make document fit window and show outlines
Doc.OpenAction = Page1.CreateDest
Doc.PageMode = pdfUseOutlines

Set Font = Doc.Fonts("Helvetica")
Params = "x=0; y=650; width=612; alignment=center; size=50"
Page1.Canvas.DrawText "Page 1", Params, Font
Page2.Canvas.DrawText "Page 2", Params, Font

' Build outline hierarchy
Set outline = Doc.Outline
Set Title = outline.Add("User Manual", Nothing, Nothing, Nothing, "Bold=true")

Set Chapter1 = outline.Add("Chapter 1", Page1.CreateDest, Title, Nothing, "Bold=true; Italic=true")
Set Section11 = outline.Add("Section 1.1", Page1.CreateDest("XYZ=true;Zoom=2;Top=300"), Chapter1, Nothing )

Set Chapter2 = outline.Add("Chapter 2", Page2.CreateDest, Title, Nothing, "Bold=true; Italic=true")
Set Section21 = outline.Add("Section 2.1", Page2.CreateDest("XYZ=true;Zoom=2;Top=500"), Chapter2, Nothing )
Set Section22 = outline.Add("Section 2.2", Page2.CreateDest("XYZ=true;Zoom=2;Top=200"), Chapter2, Nothing )

' Save document, the Save method returns generated file name
Filename = Doc.Save( Server.MapPath("outline.pdf"), False )

C#
IPdfManager objPdf = new PdfManager();
IPdfDocument objDoc = objPdf.CreateDocument(Missing.Value);
IPdfPage objPage1 = objDoc.Pages.Add(Missing.Value, Missing.Value, Missing.Value);
IPdfPage objPage2 = objDoc.Pages.Add(Missing.Value, Missing.Value, Missing.Value);

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

IPdfFont objFont = objDoc.Fonts["Helvetica", Missing.Value];
String strParams = "x=0; y=650; width=612; alignment=center; size=50";
objPage1.Canvas.DrawText( "Page 1", strParams, objFont );
objPage2.Canvas.DrawText( "Page 2", strParams, objFont );

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

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

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

// Save document, the Save method returns generated file name
String strFilename = 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/manual_10/10_outline.asp
http://localhost/asppdf/manual_10/10_outline.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):

VBScript
...
Set Annot = Page.Annots.Add("This is a simple text annotation.", _
   "x=10, y=700; width=200; height=50")
...
C#
...
IPdfAnnot objAnnot=objPage.Annots.Add("This is a simple text annotation.",
   "x=10, y=700; width=200; height=50", Missing.Value, Missing.Value );
...

Click the links below to run this code sample:

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

10.3.2 Add Method Parameters

The PdfAnnots.Add method takes 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 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.

Annot.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".

VBScript
...

' Add annotation with custom appearance
Notice = "This invoice was paid on June 10, 2003."
Set Annot = Page.Annots.Add(Notice, "x=10,y=600;width=182;height=131; Type=Stamp")

' Create a graphics object for this annotation containing an image
Set PaidGraph = Doc.CreateGraphics("left=0; bottom=0; right=182; top=131")
Set image = Doc.OpenImage( Server.MapPath("paid.gif") )
PaidGraph.Canvas.DrawImage image, "x=0, y=0"

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

' Save document, the Save method returns generated file name
Filename = Doc.Save( Server.MapPath("annot.pdf"), False )

C#
...

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

// Create a graphics object for this annotation containing an image
IPdfGraphics objPaidGraph = objDoc.CreateGraphics("left=0; bottom=0; right=182; top=131");
IPdfImage objImage = objDoc.OpenImage( Server.MapPath("paid.gif"), Missing.Value );
objPaidGraph.Canvas.DrawImage( objImage, "x=0, y=0" );

// Use this graphics object as the annotation's appearance
objAnnot.set_Graphics(0, Missing.Value, objPaidGraph );

// Save document, the Save method returns generated file name
String strFilename = objDoc.Save(Server.MapPath("appearance.pdf"), false);

Note that in C# direct assignment to the Graphics property is not allowed, so the syntax objAnnot.set_Graphics(...) is used.

Click the links below to run this code sample:

http://localhost/asppdf/manual_10/10_appearance.asp
http://localhost/asppdf/manual_10/10_appearance.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: Forms Chapter 9: Working with Existing PDFs
Search AspPDF.com

  This site is owned and maintained by Persits Software, Inc. Copyright © 2003. All Rights Reserved.