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")
Param.Add("z=30")
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.Clear
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
