2. PDF File Writer Library General Notes

2.1. Coordinate system and Unit of Measure

The PDF coordinate system origin is at the bottom left corner of the page. The X-axis is pointing to the right. The Y-axis is pointing in upward direction.

The PDF unit of measure is point. There are 72 points in one inch. The PDF File writer allows you to select your own unit of measure. All methods arguments representing position, width or height must be in your unit of measure. There are two exceptions: font size and resolution. Font size is always in points. Resolution is always in pixels per inch. The PDF File Writer converts all input arguments to points. All internal measurement values and calculations are done with double precision. At the final step when the PDF file is created, the values are converted to text strings. The conversion precision is six digits. The conversion formula used is:

// Value is Double
if(Math.Abs(Value) < 0.0001) Value = 0.0;
String Result = ((Single) Value).ToString();

2.2. Decimal Separator

PDF readers such as Adobe Acrobat expect real numbers with a fraction to use period as the decimal separator. Some of the world regions use other decimal separators such as comma. Since Version 1.1 of the PDF File Writer library will use period as decimal separator regardless of regional setting of your computer.

2.3. Language support, fonts and character sets

The PDF File Writer library supports most of the fonts installed on your computer. The only exception is device fonts. The supported fonts follow the OpenType font specifications. More information is available at Microsoft Typography - OpenType Specification. The text to be drawn is stored in a String made of Unicode characters. The library will accept any character (0 to 65536) except control codes 0 to 31 and 128 to 159. Every character is translated into a glyph. The glyphs are drawn on the page left to right in the same order as they are stored in the string. Most font files support only a subset of all possible Unicode characters. In other words, you must select a font that supports the language of your project or the symbols you are trying to display. If the input String contains unsupported glyphs, the PDF reader will display the "undefined glyph". Normally it is a small rectangle. The test program attached to this article has a "Font Families" button. If you click it you can see all available fonts on your computer and within each font all available characters. If the language of your project is a left to right language and each character is translated into one glyph and the glyph is defined in the font, the result should be what you expect. If the result is not what you expect, here are some additional notes:

Unicode control characters. Unicode control characters are used to control the interpretation or display of text, but these characters themselves have no visual or spatial representation. The PDF File writer does not identify these characters. The library assumes that every character is a display character. They will be displayed as undefined character.

Right to left language. Normally the order of characters in a text string is the order a person would read them. Since the library draws left to right the text will be written backwards. The ReverseString method reverses the character order. This will solve the problem if the text is made only of right to left characters. If the text is a mix of right to left, left to right, numbers and some characters such as brackets ()[]<>{} it will not produce the desired results. Another limitation is TextBox class cannot break long right to left text into lines.

Ligature. In some languages a sequence of two or more characters are grouped together to display one glyph. Your software can identify these sequences and replaced them with the proper glyph.

Dotted circle. If you look at the Glyph column of Glyph Metrics screen you can see that some glyphs have a small dotted circle (i.e. character codes 2364 and 2367). These characters are part of a sequence of characters. The dotted circle is not displayed. If the advance width is zero and the bounding box is on the left side of the Y axis, this glyph will be drawen ok. It will be displayed on top of the previous character. If The advance width is not zero, this glyph should be displayed before the previous character. Your software can achieve it by reversing the two characters.

2.4. Image Support

Displaying images in the PDF document is handled by the PdfImage class. This class is a PDF resource. Image sources can be:

• Image file
• .NET Image derived class such as Bitmap
• A Boolean array of black and white pixels
• QRCode barcode represented by QREncoder class
• PDF 417 barcode represented by Pdf417Encoder class
• PdfChart is a derived class of PdfImage
• PdfPrintDocument is using internally PdfImage to capture print pages

Images are saved to the PDF file in one of the following formats:

• Jpeg format (lossy compression)
• Indexed bitmap (Lossless compression)
• Gray bitmap (Lossless compression)
• Black and white bitmap (Lossless compression)

Color pictures should be saved in Jpeg format. To control the size of your image, you can reduce the resolution or change the image quality. Color pictures can be saved in shades of gray. Data size is cut by three, but you lose the color. If the image was created programmatically as in charts, and the number of colors is less than 256 the image can be saved as an indexed bitmap. Each color is represented by one byte (or less) compare to 3 bytes. This can result in a very significant file size reduction. For example, the ChartExample.pdf file is reduced from 642KB to 72KB. If the image is black and white as in PdfPrintDocument images of text, the image can be saved as BWImage. In the case of PrintExample.pdf the Jpeg file is 1795KB and the black and white version is 66KB.

Adding an image to your PDF File

Create a PdfImage class.

// create PdfImage object
PdfImage MyImage = new PdfImage(Document);

Set optional parameters if required. All the parameters have a default value.

// saved image format (default SaveImageAs.Jpeg)
// other choices are: IndexedImage, GrayImage, BWImage
MyImage.SaveAs = SaveImageAs.Jpeg;

// Crop rectangle is the image area to be cropped.
// The default is no crop (empty rectangle).
// The origin is at top left and Y axis is pointing down.
// The dimensions are in pixels.
// The crop rectangle must be contained within the image.
MyImage.CropRec = new Rectangle(x, y, width, height);

// Crop percent rectangle is the image area to be cropped.
// The default is no crop (empty rectangle).
// The origin is at top left and Y axis is pointing down.
// The dimensions are in percent of image.
// The crop rectangle must be contained within the image.
MyImage.CropPercent = new RectangleF(x, y, width, height);

// Image Quality is an integer in the range of 0 to 100.
// representing poor to best quality image.
// The default (-1) is save image with Bitmap default quality.
// For your information Bitmap class default image quality is 75.
// Lower image quality means smaller PDF file.
MyImage.ImageQuality = PdfImage.DefaultQuality;

// Image resolution sets the image resolution provided
// that it is smaller than the resolution of source image.
// Default of 0, is keeping the original image resolution.
// Resolution is specified in pixels per inch.
// Reduced resolution means smaller PDF file.
MyImage.Resolution = 0;

// Cutoff value for gray conversion to black and white.
// The range is 1 to 99. The default is 50.
// If shade of gray is below cutoff, the result is black.
// If shade of gray is above cutoff, the result is white.
MyImage.GrayToBWCutoff = 50;

// Reverse black and white
// Default is false
// In Gray or BW images the color is reversed
MyImage.ReverseBW = false;

// Attach to layer control
// Image visibility will be controlled by viewer application.
MyImage.LayerControl = PdfLayer;