Chapter 2: Object Model Overview


2.1 Major AspPDF Objects

AspPDF is comprised of over 20 objects representing various components of a PDF document. The main top-level object is PdfManager which serves as an "object factory" for other objects, most noticeably, PdfDocument. The latter encapsulates various properties of an actual PDF document, either a new or existing one.

The PdfDocument object provides the Doc.Pages property which returns a collection of PdfPage objects, each representing an individual page in the PDF document. Other important PdfDocument collections include Doc.Fonts and Doc.Form which contain the document's fonts and form items, respectively. PdfDocument also offers methods for creating PdfTable, PdfAction, PdfDest, and PdfGraphics objects representing tables, actions, destinations and Form XObjects, respectively (all described in detail later in the manual).

Each PdfPage object has at least one PdfCanvas object associated with it, which encapsulates various drawing methods such as DrawRect, DrawText, etc.

Another important object creatable via PdfManager is PdfParam which is described in detail later in this chapter.

Click here for the complete object model diagram.

2.2 Creating an Instance of PdfManager Object

Any application using AspPDF must start by creating an instance of the PdfManager object, as follows:

Set Pdf = Server.CreateObject("Persits.Pdf")
IPdfManager objPDF = new PdfManager();

To use AspPDF in a VB project, select the entry "Persits Software AspPDF" under Project/References.

To use AspPDF in ASP.NET, you must place the wrapper assembly ASPPDFLib.dll (included with the installation) in the /Bin directory of your .NET application, and use the following directive in your source files:

<%@ Import Namespace="ASPPDFLib" %>

2.3 PdfParam Object

Due to the complexity of tasks performed by AspPDF, many of its methods take a very large number of arguments. For example, the method Canvas.DrawText, in addition to the Text and Font arguments, also takes 2 required and 10 optional numeric and Boolean parameters.

In order to facilitate better code readability and maintainability, a special object, PdfParam, was added to AspPDF's object model which encapsulates a series of named numeric and Boolean arguments. Instead of passing multiple parameters to a method, we just pass a single initialized PdfParam object.

An instance of the PdfParam object can be initialized with a single parameter string, which is a comma- or semicolon-separated list of individual parameter names and their respective values in the form Name=Value.

For example, without PdfParam we would have to call the method DrawText as follows:

' This is not a real AspPDF method call
Page.Canvas.DrawText "Hello", Font, 10, 20, 100, 500, , , , 8, , , 2, &HFF0000

With PdfParam, the code looks much more readable:

Set Param = Pdf.CreateParam("x=10; y=20; width=100, height=500; Size=8; Alignment=right; color=red")
Page.Canvas.DrawText "Hello", Param, Font

2.3.1 Creation and Reuse of PdfParam Objects

An instance of the PdfParam object is created via PdfManager's CreateParam method. This method expects an optional parameter string argument. Once a PdfParam object has been created, it can be reused. Some or all of its items can be removed or replaced by other values.

The method Clear removes all items from the param object. The Add method adds new items from a parameter string. If some of the items specified in the parameter string are already present in the object, their values are overwritten. For example, the following code sets the x value to 10, y to 20 and z to 30:

Set Param = Pdf.CreateParam("x=5")
Param.Add("x=10; y=20")

The method Set clears the object before initializing it to the new values. Therefore, the code

Param.Set("x=10; y=20")

is equivalent to

Param.Add("x=10; y=20")

2.3.2 Syntax and Numeric Values

Either the comma or semicolon character can be used as an item separator. You can use both in the same string. Spaces are ignored so you can use them to make your string more readable. Numeric values can be represented in hexadecimal format. A Hex number must be prepended with &H or #, e.g.

"x=&HFF; y=#FF0000"

In a parameter string, pre-defined constants can be used instead of numbers. PdfParam recognizes 140 constants designating various colors, such as white (&HFFFFFF), black (&H000000), red (&HFF0000), maroon (&H800000), etc. For a complete table of colors and their names, see Appendix A: Pre-defined Color Names.

In addition to the color names, PdfParam also recognizes several commonly used constants such as true (1), false (0), left (0), right (1), center (2), and others.

Parameter names and pre-defined constants are case-insensitive. Their order in the parameter string is immaterial. Therefore, the following two parameter strings are equivalent:

"Type=Widget; ReadOnly=true"
"readonly=True; type=widget"

2.3.3 Individual Value Assignment

A parameter string is not the only way to assign values to a PdfParam object. An individual value can be assigned via the object's default parameterized Item property, as follows:

Param.Item("x") = x

or simply

Param("x") = x

The Item property of the PdfParam object returns an instance of the PdfParamItem object which has two properties, Name and Value, the latter being the default property. In C#, the code above would have to look as follows:

Param["x"].Value = x;

When a parameter is a constant value, it is more convenient to assign it to a PdfParam object via a parameter string. However, if a parameter is a variable, using the Item method is more convenient.

2.3.4 Direct Use of Parameter Strings

To simplify coding even further, all AspPDF methods accepting the PdfParam object as an argument also accept a parameter string directly, i.e. instead of

Set Param = Pdf.CreateParam("x=10, y=20; color=red")
Page.Canvas.DrawText "Hello", Param, Font

you can simply write

Page.Canvas.DrawText "Hello", "x=10, y=20; color=red", Font