Class

UIGraphicsPDFRenderer

A graphics renderer for creating PDFs.

Declaration

class UIGraphicsPDFRenderer : UIGraphicsRenderer

Overview

You can use PDF renderers to create PDF files, without having to manage Core Graphics contexts.

To render a PDF:

  1. Optionally create a UIGraphicsPDFRendererFormat object to specify nondefault parameters the renderer should use to create its context.

  2. Instantiate a UIGraphicsPDFRenderer object, providing the dimensions of the output image and a format object. The renderer uses sensible defaults for the current device if you don't provide format object, as demonstrated in Creating a Graphics PDF Renderer.

  3. Choose one of the rendering methods depending on your desired output: pdfData(actions:) outputs the PDF in the form of a Data object, and writePDF(to:withActions:) saves the PDF as a file directly to disk.

  4. Provide Core Graphics drawing instructions within the closure associated with your chosen method, as shown in Creating a PDF with a PDF Renderer.

  5. Optionally, you can create a multi-page PDF, using the approach shown in Adding Pages.

  6. Optionally, add links to your PDF to make navigation easy, as shown in Creating Internal Links.

Once a PDF renderer is initialized, you can use it to draw multiple PDFs with the same configuration.

Creating a Graphics PDF Renderer

Create a PDF renderer, providing the bounds of the PDF page.

Listing 1

Creating a PDF renderer

let renderer = UIGraphicsPDFRenderer(bounds: CGRect(x: 0, y: 0, width: 500, height: 300))

You can instead use one of the other UIGraphicsPDFRenderer initializers to specify a renderer format (UIGraphicsPDFRendererFormat) in addition to the bounds. This allows you to configure the underlying Core Graphics context with custom PDF document info. If you don't provide a format, the default() format is used, which creates a context best suited for the current device.

Creating a PDF with a PDF Renderer

Use the pdfData(actions:) method to create a PDF with the PDF renderer you created above. This takes a block that represents the drawing actions. Within this block, the renderer creates a Core Graphics context using the parameters provided when the renderer was initialized, and sets this to be the current context.

Before issuing PDF drawing instructions, you must create a page with a call to either the beginPage() method or beginPage(withBounds:pageInfo:) method on the supplied UIGraphicsPDFRendererContext.

Listing 2

Drawing using a PDF renderer

let pdf = renderer.pdfData { (context) in
  context.beginPage()
  let attributes = [
    NSFontAttributeName : UIFont.boldSystemFont(ofSize: 150)
  ]
  let text = "Hello!" as NSString
  text.draw(in: CGRect(x: 0, y: 0, width: 500, height: 200), withAttributes: attributes)
}

The drawing actions closure takes a single argument of type UIGraphicsPDFRendererContext. This provides access to some high-level drawing functions, such as fill(_:) via the UIGraphicsRendererContext superclass.

The above code creates the image shown in Figure 1.

Figure 1

Creating a PDF that says "Hello!"

Image of a PDF open in Preview, with the word "Hello!" rendered in large, black lettering in the top-left.

Adding Pages

Add multiple pages to your PDF through repeated calls to the beginPage() method on the UIGraphicsPDFRendererContext provided to the drawing block.

Listing 3

Adding pages to a PDF

let pdf = renderer.pdfData { (context) in
  let attributes = [
    NSFontAttributeName : UIFont.boldSystemFont(ofSize: 150)
  ]
  for page in 1...3 {
    context.beginPage()
    let text = "Page \(page)" as NSString
    text.draw(in: CGRect(x: 0, y: 0, width: 500, height: 200), withAttributes: attributes)
  }
}

Use the beginPage(withBounds:pageInfo:) method instead of the beginPage() method if you want to override the default properties for the new page.

The code in Listing 3 creates a PDF with three pages, each of which contains the current page number as large text, as shown in Figure 2.

Figure 2

Adding multiple pages to a PDF

Screenshot from Preview showing a 3-page PDF. Each page contains large black lettering which details the current page number.

Creating Internal Links

You can create internal links, known as destinations, in PDFs. A complete link is made up of two components:

The code in Listing 4 demonstrates how to use destinations with a PDF renderer by showing how to create links that jump to the next page.

Listing 4

Using destinations in a PDF renderer

let pdf = renderer.pdfData { (context) in
  let pageNumberAttributes = [
    NSFontAttributeName : UIFont.boldSystemFont(ofSize: 150)
  ]
  
  let nextPage = "Next Page ↠" as NSString
  let nextPageRect = CGRect(x: 350, y: 250, width: 150, height: 40)
  let nextPageAttributes = [
    NSFontAttributeName : UIFont.systemFont(ofSize: 25),
    NSBackgroundColorAttributeName : UIColor.red,
    NSForegroundColorAttributeName : UIColor.white
  ]
  
  for page in 1...3 {
    context.beginPage()
    let pageNumber = "Page \(page)" as NSString
    pageNumber.draw(in: CGRect(x: 0, y: 0, width: 500, height: 200), withAttributes: pageNumberAttributes)
    
    nextPage.draw(in: nextPageRect, withAttributes: nextPageAttributes)
    
    context.addDestination(withName: "page-\(page)", at: CGPoint.zero.applying(context.cgContext.userSpaceToDeviceSpaceTransform))
    context.setDestinationWithName("page-\(page + 1)", for: nextPageRect.applying(context.cgContext.userSpaceToDeviceSpaceTransform))
  }
}

The code in Listing 4 adds large red labels that when clicked will jump from the current page to the next page. Each page has a destination with names of the form page-1, positioned at the origin. The bounding box for the next-page label is used as the link to the destination on the following page.

Figure 3 shows the PDF that results from the code in Listing 4.

Figure 3

Adding internal links with a PDF renderer

Screenshot from Preview showing a 3-page PDFs with red links entitled "Next Page" at the bottom-right of each page.

Topics

Creating a PDF Renderer

init(bounds: CGRect, format: UIGraphicsPDFRendererFormat)

Creates a new graphics renderer with the given bounds and format.

Managing the PDF Data

func pdfData(actions: (UIGraphicsPDFRendererContext) -> Void) -> Data

Creates a PDF by following a set of drawing instructions and returns it as a data object.

func writePDF(to: URL, withActions: (UIGraphicsPDFRendererContext) -> Void)

Creates a PDF by following a set of drawing instructions and saves it to a specified URL.

Type Aliases

typealias UIGraphicsPDFRenderer.DrawingActions

A handler block that you use to draw PDF content.

Relationships

Inherits From

Conforms To

See Also

Drawing Contexts

class UIGraphicsRenderer

An abstract base class for creating graphics renderers.

class UIGraphicsRendererContext

The base class for the drawing environments associated with graphics renderers.

class UIGraphicsRendererFormat

A set of drawing attributes that represent the configuration of a graphics renderer context.

class UIGraphicsImageRenderer

A graphics renderer for creating Core Graphics-backed images.

class UIGraphicsImageRendererContext

The drawing environment associated with an image renderer.

class UIGraphicsImageRendererFormat

A set of drawing attributes that represent the configuration of an image renderer context.

typealias UIGraphicsPDFRenderer.DrawingActions

A handler block that you use to draw PDF content.

class UIGraphicsPDFRendererContext

A drawing environment associated with a PDF renderer.

class UIGraphicsPDFRendererFormat

A set of drawing attributes that represents the configuration of a PDF renderer context.