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 PdfCanvas.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:
| C# |
|---|
PdfParam objParam = objPDF.CreateParam("x=10; y=20; width=100, height=500; Size=8; Alignment=right; color=red");
objPage.Canvas.DrawText( "Hello", objParam, objFont );
|
| VB.NET |
|---|
Dim objParam As PdfParam =objPDF.CreateParam("x=10; y=20; width=100, height=500; Size=8; Alignment=right; color=red")
objPage.Canvas.DrawText( "Hello", objParam, objFont )
|
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:
PdfParam objParam = objPDF.CreateParam("x=5");
objParam.Add("x=10; y=20");
objParam.Add("z=30");
The method Set clears the object before
initializing it to the new values. Therefore, the code
objParam.Set("x=10; y=20");
is equivalent to
objParam.Clear();
objParam.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 indexer, as follows:
| VB.NET |
|---|
|
objParam("x") = 100
|
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 indexer method is more convenient.
2.3.4 Direct Use of Parameter Strings
To simplify coding even further, all AspPDF.NET methods accepting the PdfParam object as an argument also accept
a parameter string directly, i.e. instead of
PdfParam objParam = objPDF.CreateParam("x=10, y=20; color=red");
objPage.Canvas.DrawText( "Hello", objParam, objFont );
you can simply write
objPage.Canvas.DrawText( "Hello", "x=10, y=20; color=red", objFont );
