Package org.eclipse.swt.printing

# Class PDFDocument

java.lang.Object
org.eclipse.swt.graphics.Device
org.eclipse.swt.printing.PDFDocument

All Implemented Interfaces:
  `Drawable`

public final class PDFDocument extends Device
Instances of this class are used to create PDF documents. Applications create a GC on a PDFDocument using `new GC(pdfDocument)` and then draw on the GC using the usual graphics calls.

A `PDFDocument` object may be constructed by providing a filename and the page dimensions. After drawing is complete, the document must be disposed to finalize the PDF file.

Application code must explicitly invoke the `PDFDocument.dispose()` method to release the operating system resources managed by each instance when those instances are no longer required.

Note: On Windows, this class uses the built-in "Microsoft Print to PDF" printer which is available on Windows 10 and later.

The following example demonstrates how to use PDFDocument:

        PDFDocument pdf = new PDFDocument("output.pdf", 612, 792); // Letter size in points
        GC gc = new GC(pdf);
        gc.drawText("Hello, PDF!", 100, 100);
        gc.dispose();
        pdf.dispose();

Since:
  3.133
See Also:
  - `GC`
Restriction:
  This class is provisional API and subject to change. It is being made available to gather early feedback. The API or behavior may change in future releases as the implementation evolves based on user feedback.

## Field Summary

### Fields inherited from class org.eclipse.swt.graphics.Device

`CurrentDevice, DEBUG, DeviceFinder`

## Constructor Summary

Constructors
Constructor
Description
`PDFDocument(String filename, double widthInPoints, double heightInPoints)`
Constructs a new PDFDocument with the specified filename and preferred page dimensions.
`PDFDocument(String filename, PageSize pageSize)`
Constructs a new PDFDocument with the specified filename and page size.

## Method Summary

Modifier and Type
Method
Description
`protected void`
`create(DeviceData data)`
Creates the PDF device in the operating system.
`protected void`
`destroy()`
Destroys the PDF document handle.
`Rectangle`
`getBounds()`
Returns a rectangle describing the receiver's size and location.
`Rectangle`
`getClientArea()`
Returns a rectangle which describes the area of the receiver which is capable of displaying data.
`Point`
`getDPI()`
Returns the DPI (dots per inch) of the PDF document.
`double`
`getHeight()`
Returns the actual height of the current page in points.
`double`
`getWidth()`
Returns the actual width of the current page in points.
`void`
`internal_dispose_GC(long hDC, GCData data)`
Invokes platform specific functionality to dispose a GC handle.
`long`
`internal_new_GC(GCData data)`
Invokes platform specific functionality to allocate a new GC handle.
`boolean`
`isAutoScalable()`
Returns `true` iff coordinates can be auto-scaled on this drawable and `false` if not.
`void`
`newPage()`
Starts a new page in the PDF document.
`void`
`newPage(double widthInPoints, double heightInPoints)`
Starts a new page in the PDF document with the specified dimensions.

### Methods inherited from class org.eclipse.swt.graphics.Device

`checkDevice, dispose, getDepth, getDeviceData, getDeviceZoom, getFontList, getSystemColor, getSystemFont, getWarnings, init, isDisposed, isTracking, loadFont, release, setTracking, setWarnings, win32_destroyUnusedHandles`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

## Constructor Details

### PDFDocument

public PDFDocument(String filename, PageSize pageSize)
Constructs a new PDFDocument with the specified filename and page size.

The page size specifies the preferred dimensions in points (1/72 inch). On Windows, the Microsoft Print to PDF driver only supports standard paper sizes, so the actual page size may be larger than requested. Use `getBounds()` to query the actual page dimensions after construction.

You must dispose the PDFDocument when it is no longer required.

Parameters:
  `filename` - the path to the PDF file to create
  `pageSize` - the page size specifying width and height in points (1/72 inch)
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if filename or pageSize is null
  - ERROR_INVALID_ARGUMENT - if width or height is not positive
  `SWTError` -
  - ERROR_NO_HANDLES - if the PDF printer is not available
See Also:
  - `PageSize`
  - `Device.dispose()`
  - `getBounds()`

### PDFDocument

public PDFDocument(String filename, double widthInPoints, double heightInPoints)
Constructs a new PDFDocument with the specified filename and preferred page dimensions.

The dimensions specify the preferred page size in points (1/72 inch). On Windows, the Microsoft Print to PDF driver only supports standard paper sizes, so the actual page size may be larger than requested. Use `getBounds()` to query the actual page dimensions after construction.

You must dispose the PDFDocument when it is no longer required.

Parameters:
  `filename` - the path to the PDF file to create
  `widthInPoints` - the preferred width of each page in points (1/72 inch)
  `heightInPoints` - the preferred height of each page in points (1/72 inch)
Throws:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if filename is null
  - ERROR_INVALID_ARGUMENT - if width or height is not positive
  `SWTError` -
  - ERROR_NO_HANDLES - if the PDF printer is not available
See Also:
  - `Device.dispose()`
  - `getBounds()`

## Method Details

### create

protected void create(DeviceData data)
Creates the PDF device in the operating system. This method is called before `init`.

Overrides:
  `create` in class `Device`
Parameters:
  `data` - the DeviceData which describes the receiver
See Also:
  - `Device.init()`

### newPage

public void newPage()
Starts a new page in the PDF document.

This method should be called after completing the content of one page and before starting to draw on the next page. The new page will have the same dimensions as the initial page.

Throws:
  `SWTException` -
  - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### newPage

public void newPage(double widthInPoints, double heightInPoints)
Starts a new page in the PDF document with the specified dimensions.

This method should be called after completing the content of one page and before starting to draw on the next page.

Note: On Windows, changing page dimensions after the document has been started may not be fully supported by all printer drivers.

Parameters:
  `widthInPoints` - the preferred width of the new page in points (1/72 inch)
  `heightInPoints` - the preferred height of the new page in points (1/72 inch)
Throws:
  `IllegalArgumentException` -
  - ERROR_INVALID_ARGUMENT - if width or height is not positive
  `SWTException` -
  - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### getWidth

public double getWidth()
Returns the actual width of the current page in points.

On Windows, this may be larger than the preferred width specified in the constructor due to standard paper size constraints.

Returns:
  the actual width in points (1/72 inch)
Throws:
  `SWTException` -
  - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### getHeight

public double getHeight()
Returns the actual height of the current page in points.

On Windows, this may be larger than the preferred height specified in the constructor due to standard paper size constraints.

Returns:
  the actual height in points (1/72 inch)
Throws:
  `SWTException` -
  - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### getDPI

public Point getDPI()
Returns the DPI (dots per inch) of the PDF document. Since the coordinate system is scaled to work in points (1/72 inch), this always returns 72 DPI, consistent with GTK and Cocoa implementations.

Overrides:
  `getDPI` in class `Device`
Returns:
  a point whose x coordinate is the horizontal DPI and whose y coordinate is the vertical DPI
Throws:
  `SWTException` -
  - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### getBounds

public Rectangle getBounds()
Returns a rectangle describing the receiver's size and location. The rectangle dimensions are in points (1/72 inch).

On Windows, this returns the actual page size which may be larger than the preferred size specified in the constructor.

Overrides:
  `getBounds` in class `Device`
Returns:
  the bounding rectangle
Throws:
  `SWTException` -
  - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### getClientArea

public Rectangle getClientArea()
Returns a rectangle which describes the area of the receiver which is capable of displaying data.

On Windows, the printable area may be smaller than the page bounds due to printer margins.

Overrides:
  `getClientArea` in class `Device`
Returns:
  the client area
Throws:
  `SWTException` -
  - ERROR_DEVICE_DISPOSED - if the receiver has been disposed
See Also:
  - `Device.getBounds()`

### internal_new_GC

public long internal_new_GC(GCData data)
Invokes platform specific functionality to allocate a new GC handle.

IMPORTANT: This method is not part of the public API for `PDFDocument`. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms, and should never be called from application code.

Specified by:
  `internal_new_GC` in interface `Drawable`
Specified by:
  `internal_new_GC` in class `Device`
Parameters:
  `data` - the platform specific GC data
Returns:
  the platform specific GC handle
Restriction:
  This method is not intended to be referenced by clients.

### internal_dispose_GC

public void internal_dispose_GC(long hDC, GCData data)
Invokes platform specific functionality to dispose a GC handle.

IMPORTANT: This method is not part of the public API for `PDFDocument`. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms, and should never be called from application code.

Specified by:
  `internal_dispose_GC` in interface `Drawable`
Specified by:
  `internal_dispose_GC` in class `Device`
Parameters:
  `hDC` - the platform specific GC handle
  `data` - the platform specific GC data
Restriction:
  This method is not intended to be referenced by clients.

### isAutoScalable

public boolean isAutoScalable()
Description copied from interface: `Drawable`
Returns `true` iff coordinates can be auto-scaled on this drawable and `false` if not. E.g. a `GC` method should not auto-scale the bounds of a figure drawn on a Printer device, but it may have to auto-scale when drawing on a high-DPI Display monitor.

Returns:
  `true` if auto-scaling is enabled for this drawable
Restriction:
  This method is not intended to be referenced by clients.

### destroy

protected void destroy()
Destroys the PDF document handle. This method is called internally by the dispose mechanism of the `Device` class.

Overrides:
  `destroy` in class `Device`
See Also:
  - `Device.dispose()`
  - `Device.release()`