Chapter 2: Object Model Overview

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.

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

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:

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:

With PdfParam, the code looks much more readable:

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:

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

is equivalent to

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:

or simply

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:

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

you can simply write