Advanced use

This section covers the following topics:

• Page units
• Custom pages
• Display orientation

Page units

All graphics operations are implicitly expressed in units, called 'page units'. By default, the unit used is the Point, or 1/72^nd of an inch. You can change the unit used by graphics operation at any point by setting the PageUnit property of a Graphics instance to one of the following values:

Centimetres

All operations will be expressed in centimetres. One inch is 2.54 centimetres.

Inches

All operations will be expressed in inches. There are 72 points in an inch.

Millimetres

All operations will be expressed in millimetres. There are 25.4 millimetres in an inch.

Pixels

All operations will be expressed in pixels. This is translated into points through the resolution of the Graphics object. See below for more details.

Points

(default) All operations will be expressed in points.

Note: Some values and operations are always expressed in points, regardless of the current page unit. Font size and spacing values used in rendering text are always expressed in points.

Resolution

Although PDF Graphics.NET deals with vector graphics (expect for images) and is therefore not dependent on device resolution, it does have an intrinsic resolution that is used to convert values in pixels to values in points. This resolution is only interesting while the PageUnit property of the Graphics object is set to Pixels.

By default, the resolution is set to 72 dpi in both X and Y direction. This means that a pixel corresponds to a point, since they are both 1/72^nd of an inch. To change these values, use the DpiX and DpiY properties of the Graphics class.

Custom pages

Graphics are always rendered on a page. If you don't explicitly create a page in your PDF document, PDF Graphics .NET will implicitly create a DIN A4 page. To create a new page, use the NewPage() method. This method has three overloads:

NewPage()

Creates a new page with the same dimensions as the current page. For a Graphics instance that was constructed without an explicit page size, this defaults to DIN A4.

NewPage(float width, float height)

Creates a new page with the specified width and height. The width and height are expressed in points, regardless of the page unit of the Graphics instance.

NewPage(Rectangle bounds)

Creates a new page based on the specified rectangle. Only the width and height of the rectangle are considered; its position is not relevant. The width and height are expressed in points, regardless of the page unit of the Graphics instance.

You can also create a Graphics instance with a preset size, using one of its constructor overloads. This is functionally equivalent to creating an instance and calling NewPage() overload with a page size.

Standard pages

PDF Graphics .NET has a number of standard pages that can be used to create pages in popular formats. They standard pages are found in the StandardPages static class, and can be used in overloads of NewPage() as well as the Graphics constructors. The full list of standard pages is as follows:

A0

The DIN A0 paper format is the largest format in the list of DIN/ISO pages. It is approximately 33.1" x 46.8" in size.

A1

The DIN A1 paper format is a large paper format specified by DIN. It is approximately 23.4" x 33.1" in size.

A2

The DIN A2 paper format is a popular large paper format. It is approximately 16.5" x 23.4" in size.

A3

The DIN A3 paper format is a popular large paper format, twice the size of an A4 sheet. It is approximately 11.7" x 16.5" in size.

A4

DIN A4 is the most popular page size internationally. It is 8.26" x 11.7" in size. Because of its popularity, it is the default page size in the PDF Graphics .NET library.

A5

A DIN A5 page is half the size of an A4 page. It is 5.83" x 8.26".

A6

DIN A6 is the smallest paper size in the DIN list. It is approximately 4.14" x 5.83".

Legal

The US legal format is a long and narrow page. It is approximately 8.5" x 14".

Letter

The US Letter format is a popular page format that is approximately 8.5" x 11" in size.

Tabloid

The US tabloid page is a large sheet format of approximately 11" x 17".

Display orientation

The standard set of page sizes included in the PDF Graphics.NET library is mostly based on portrait-oriented sheets. To create a landscape-oriented page you can do either of the following:

• Use NewPage() and specify a Rectangle instance with the appropriate dimensions; the width being the long side.
• Create a regular page and rotate the coordinate space using TransformTranslate() and TransformRotate(), or Reorient();

When viewing the PDF document, any landscape-oriented pages will appear as landscape-oriented pages; with their long sides across. This is convenient for viewing the document on-screen but may cause issues when printing.

The PDF standard allows a document to specify the display direction of a page. In PDF Graphics .NET, this is controlled through an overload of NewPage() that accepts an Orientation argument.

Using the Orientation argument, you can pass a landscape page size to NewPage() and still display it with the short side across, like portrait pages.

It can also be used to orient pages upside-down, which may be a requirement for some printers.

Navigation options:

< Colour schemes