Module org.freedesktop.cairo

Package org.freedesktop.cairo

Class PDFSurface

java.lang.Object

io.github.jwharm.cairobindings.Proxy

org.freedesktop.cairo.Surface

org.freedesktop.cairo.PDFSurface

All Implemented Interfaces:

AutoCloseable

public final class PDFSurface
extends Surface

The PDF surface is used to render cairo graphics to Adobe PDF files and is a multi-page vector surface backend.

The following mime types are supported on source patterns: MimeType.JPEG, MimeType.JP2, MimeType.UNIQUE_ID, MimeType.JBIG2, MimeType.JBIG2_GLOBAL, MimeType.JBIG2_GLOBAL_ID, MimeType.CCITT_FAX, MimeType.CCITT_FAX_PARAMS.

JBIG2 Images

JBIG2 data in PDF must be in the embedded format as described in ISO/IEC 11544. Image specific JBIG2 data must be in MimeType.JBIG2. Any global segments in the JBIG2 data (segments with page association field set to 0) must be in MimeType.JBIG2_GLOBAL. The global data may be shared by multiple images. All images sharing the same global data must set MimeType.JBIG2_GLOBAL_ID to a unique identifier. At least one of the images must provide the global data using MimeType.JBIG2_GLOBAL. The global data will only be embedded once and shared by all JBIG2 images with the same MimeType.JBIG2_GLOBAL_ID.

CCITT Fax Images

The MimeType.CCITT_FAX mime data requires a number of decoding parameters These parameters are specified using MimeType.CCITT_FAX_PARAMS.

MimeType.CCITT_FAX_PARAMS mime data must contain a string of the form "param1=value1 param2=value2 ...".

Columns: [required] An integer specifying the width of the image in pixels.

Rows: [required] An integer specifying the height of the image in scan lines.

K: [optional] An integer identifying the encoding scheme used. < 0 is 2 dimensional Group 4, = 0 is Group3 1 dimensional, > 0 is mixed 1 and 2 dimensional encoding. Default is 0.

EndOfLine: [optional] If true end-of-line bit patterns are present. Default is false.

EncodedByteAlign: [optional] If true the end of line is padded with 0 bits so the next line begins on a byte boundary. Default is false.

EndOfBlock: [optional] If true the data contains an end-of-block pattern. Default is true.

BlackIs1: [optional] If true 1 bits are black pixels. Default is false.

DamagedRowsBeforeError: [optional] An integer specifying the number of damages rows tolerated before an error occurs. Default is 0.

Boolean values may be "true" or "false", or 1 or 0.

These parameters are the same as the CCITTFaxDecode parameters in the PostScript Language Reference and Portable Document Format (PDF). Refer to these documents for further details.

An example MimeType.CCITT_FAX_PARAMS string is:

 "Columns=10230 Rows=40000 K=1 EndOfLine=true EncodedByteAlign=1 BlackIs1=false"
 

Since:

1.2

See Also:

• Surface

Field Summary

Fields

Modifier and Type	Field	Description
static final int	CAIRO_PDF_OUTLINE_ROOT	The root outline item in cairo_pdf_surface_add_outline().

Constructor Summary

Constructors

Constructor	Description
PDFSurface(MemorySegment address)	Constructor used internally to instantiate a java PDFSurface object for a native cairo_surface_t instance

Method Summary

Modifier and Type	Method	Description
int	addOutline(int parentId, String string, String linkAttribs, Set<PDFOutlineFlags> flags)	Add an item to the document outline hierarchy with the name utf8 that links to the location specified by linkAttribs.
static PDFSurface	create(OutputStream stream, double widthInPoints, double heightInPoints)	Creates a PDF surface of the specified size in points to be written incrementally to the stream.
static PDFSurface	create(String filename, double widthInPoints, double heightInPoints)	Creates a PDF surface of the specified size in points to be written to filename.
PDFSurface	restrictToVersion(PDFVersion version)	Restricts the generated PDF file to version .
PDFSurface	setCustomMetadata(String name, String value)	Set custom document metadata.
PDFSurface	setMetadata(PDFMetadata metadata, String string)	Set document metadata.
PDFSurface	setPageLabel(String string)	Set page label for the current page.
PDFSurface	setSize(double widthInPoints, double heightInPoints)	Changes the size of a PDF surface for the current (and subsequent) pages.
PDFSurface	setThumbnailSize(int width, int height)	Set the thumbnail image size for the current and all subsequent pages.

Methods inherited from class org.freedesktop.cairo.Surface

close, copyPage, createForRectangle, createSimilar, createSimilarImage, destroy, finish, flush, getContent, getDevice, getDeviceOffset, getDeviceScale, getFallbackResolution, getFontOptions, getMimeData, getSurfaceType, getType, getUserData, hasShowTextGlyphs, mapToImage, markDirty, markDirtyRectangle, setDeviceOffset, setDeviceScale, setFallbackResolution, setMimeData, setUserData, showPage, status, supportsMimeType, unmapImage

Methods inherited from class io.github.jwharm.cairobindings.Proxy

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Details

CAIRO_PDF_OUTLINE_ROOT

public static final int CAIRO_PDF_OUTLINE_ROOT

The root outline item in cairo_pdf_surface_add_outline().

Since:

1.16

See Also:

• Constant Field Values

Constructor Details

PDFSurface

public PDFSurface(MemorySegment address)

Constructor used internally to instantiate a java PDFSurface object for a native cairo_surface_t instance

Parameters:

address - the memory address of the native cairo_surface_t instance

Method Details

create

public static PDFSurface create(String filename,
 double widthInPoints,
 double heightInPoints)

Creates a PDF surface of the specified size in points to be written to filename.

Parameters:

filename - a filename for the PDF output (must be writable), and empty String may be used to specify no output. This will generate a PDF surface that may be queried and used as a source, without generating a temporary file.

widthInPoints - width of the surface, in points (1 point == 1/72.0 inch)

heightInPoints - height of the surface, in points (1 point == 1/72.0 inch)

Returns:

the newly created surface

Since:

1.2

create

public static PDFSurface create(OutputStream stream,
 double widthInPoints,
 double heightInPoints)

Creates a PDF surface of the specified size in points to be written incrementally to the stream.

Parameters:

stream - an OutputStream to accept the output data, may be null to indicate a no-op stream. With a no-op stream, the surface may be queried or used as a source without generating any temporary files.

widthInPoints - width of the surface, in points (1 point == 1/72.0 inch)

heightInPoints - height of the surface, in points (1 point == 1/72.0 inch)

Returns:

the newly created surface

Since:

1.2

restrictToVersion

public PDFSurface restrictToVersion(PDFVersion version)

Restricts the generated PDF file to version . See PDFVersion.getVersions() for a list of available version values that can be used here.

This function should only be called before any drawing operations have been performed on the given surface. The simplest way to do this is to call this function immediately after creating the surface.

Parameters:

version - PDF version

Returns:

the PDF surface

Since:

1.10

setSize

public PDFSurface setSize(double widthInPoints,
 double heightInPoints)

Changes the size of a PDF surface for the current (and subsequent) pages.

This function should only be called before any drawing operations have been performed on the current page. The simplest way to do this is to call this function immediately after creating the surface or immediately after completing a page with either Context.showPage() or Context.copyPage().

Parameters:

widthInPoints - new surface width, in points (1 point == 1/72.0 inch)

heightInPoints - new surface height, in points (1 point == 1/72.0 inch)

Returns:

the PDF surface

Since:

1.2

addOutline

public int addOutline(int parentId,
 String string,
 String linkAttribs,
 Set<PDFOutlineFlags> flags)

Add an item to the document outline hierarchy with the name utf8 that links to the location specified by linkAttribs. Link attributes have the same keys and values as the Link Tag, excluding the "rect" attribute. The item will be a child of the item with id parentId. Use CAIRO_PDF_OUTLINE_ROOT as the parent id of top level items.

Parameters:

parentId - the id of the parent item or CAIRO_PDF_OUTLINE_ROOT if this is a top level item.

string - the name of the outline

linkAttribs - the link attributes specifying where this outline links to

flags - outline item flags

Returns:

the id for the added item.

Since:

1.16

setMetadata

public PDFSurface setMetadata(PDFMetadata metadata,
 String string)

Set document metadata. The PDFMetadata.CREATE_DATE and PDFMetadata.MOD_DATE values must be in ISO-8601 format: YYYY-MM-DDThh:mm:ss. An optional timezone of the form "[+/-]hh:mm" or "Z" for UTC time can be appended. All other metadata values can be any UTF-8 string.

For example:

 surface.setMetadata(PDFMetadata.TITLE, "My Document");
 surface.setMetadata(PDFMetadata.CREATE_DATE, "2015-12-31T23:59+02:00");
 

Parameters:

metadata - The metadata item to set.

string - metadata value

Returns:

the PDF surface

Since:

1.16

setCustomMetadata

public PDFSurface setCustomMetadata(String name,
 String value)

Set custom document metadata. name may be any string except for the following names reserved by PDF: "Title", "Author", "Subject", "Keywords", "Creator", "Producer", "CreationDate", "ModDate", "Trapped".

If value is null or an empty string, the name metadata will not be set.

For example:

pdfSurface.setCustomMetadata("ISBN", "978-0123456789");

Parameters:

name - The name of the custom metadata item to set (utf8).

value - The value of the metadata (utf8).

Returns:

the PDF surface

Since:

1.18

setPageLabel

public PDFSurface setPageLabel(String string)

Set page label for the current page.

Parameters:

string - The page label.

Returns:

the PDF surface

Since:

1.16

setThumbnailSize

public PDFSurface setThumbnailSize(int width,
 int height)

Set the thumbnail image size for the current and all subsequent pages. Setting a width or height of 0 disables thumbnails for the current and subsequent pages.

Parameters:

width - Thumbnail width.

height - Thumbnail height.

Returns:

the PDF surface

Since:

1.16