Chapter 2: Object Model Overview

AspPDF.NET 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.

The PdfManager object (and all other AspPDF.NET objects for that matter) are part of the Persits.PDF namespace residing in the assembly Persits.PDF.dll. Place this assembly in the /Bin subfolder of your application. To import the namespace Persits.PDF into your application, use the statement

If you are using AspPDF.NET directly in an aspx file, use the directive

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

PdfManager acts as the "object factory" for all other AspPDF.NET objects.

Due to the complexity of tasks performed by AspPDF.NET, 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.

For better code readability, AspPDF.NET provides a special object, PdfParam, 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:

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:

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