Drawing Graphics in PDF

Concept

PdfDocument provides a vector graphics API. The user uses a series of a drawing methods (such as moveTo, lineTo, rect) to construct a graphics path that can be filled, stroked or clipped by using the stroke, fill, fillAndStroke or clip methods.

Each of the drawing areas (such as header, body and footer) has the paths property represented by PdfPaths class which provides methods for creating graphics paths and drawing them or using them for clipping. All drawing methods are chainable.

For example, the following code draws a line and a rectangle:

import * as wjPdf from '@mescius/wijmo.pdf';

doc.paths
    .moveTo(0, 0)
    .lineTo(30, 30)
    .rect(30, 30, 50, 50)
    .stroke();

Brushes and Pens

A pen is used to draw lines and outlined paths. A brush is used to fill closed paths, such as circle or rectangle.

A pen is an instance of the PdfPen class, while a brush is an instance of any class that derives from the abstract PdfBrush class. PdfDocument provides several brush classes: PdfSolidBrush, PdfLinearGradientBrush, PdfRadialGradientBrush.

Filling and Stroking a Path

To stroke a path, the stroke method with a pen passed in should be called after the path construction is done. To fill a path, the fill method with a brush passed in should be called after the path construction is done. To fill and stroke a closed path simultaneously, the fillAndStroke method should be used.

For example, the following code fills a 10x10 rectangle with a red brush:

doc.paths.rect(0, 0, 10, 10).fill(new wjPdf.PdfSolidBrush("#ff0000"));

If the pen/brush argument is omitted, the default document pen/brush will be used. Those can be changed by the document's setPen and setBrush methods:

doc.setBrush(new wjPdf.PdfSolidBrush("#ff0000"));
doc.paths.rect(0, 0, 10, 10).fill();

All of these methods also accept wijmo.Color or any string accepted by the wijmo.Color.fromString method as a shortcut equivalent of the PdfPen and PdfSolidBrush class instances. The following lines are equivalent:

doc.paths.stroke(new wjPdf.PdfPen("#ff0000");
doc.paths.stroke(wijmo.Color.fromRgba(255, 0, 0));
doc.paths.stroke("#ff0000");

doc.paths.fill(new wjPdf.PdfSolidBrush("#ff0000");
doc.paths.fill(wijmo.Color.fromRgba(255, 0, 0));
doc.paths.fill("#ff0000");

Clipping a Path

To clip a path, the path construction should be finished with the clip method. Any subsequent drawing that falls outside the clipping path will be hidden.

doc.paths.circle(100, 100, 50).clip();

Transformations

Also, drawing area provides a number of transformation methods used to change the size or orientation of the path or transfer it from one coordinate space to another, such as rotate, translate, scale.

The following code scales a rectangle by a factor of 2:

doc.scale(2);
doc.paths.rect(0, 0, 50, 50).stroke();

Saving and Restoring the Graphics State

The graphics state is a snapshot of the default document pen, brush and transformations that have been currently applied.

The saveState method creates a copy of the graphics state and pushes it onto stack. The restoreState method restores the graphics state to its original value by popping it from the stack.

For example, you can call saveState, change the document pen, stroke some paths using it, then call restoreState to restore the document pen to its former value. Also, this approach is very useful if a series of drawing methods with transformations or clipping applied should be isolated from the other drawings.

Here, the scaling transformation has been placed between the saveState and restoreState methods so, it will not affect any drawings below the restoreState method call:

doc.saveState();

doc.scale(2);
doc.paths.rect(0, 0, 50, 50).stroke();

doc.restoreState();