com.itextpdf.layout

Class Canvas

java.lang.Object

com.itextpdf.layout.ElementPropertyContainer

com.itextpdf.layout.RootElement<Canvas>

com.itextpdf.layout.Canvas

All Implemented Interfaces:

IPropertyContainer, Closeable, AutoCloseable

public class Canvas
extends RootElement<Canvas>

This class is used for adding content directly onto a specified PdfCanvas. Canvas does not know the concept of a page, so it can't reflow to a 'next' Canvas. This class effectively acts as a bridge between the high-level layout API and the low-level kernel API.

Field Summary

Fields

Modifier and Type	Field and Description
protected PdfPage	page Is initialized and used only when Canvas element autotagging is enabled, see enableAutoTagging(PdfPage).
protected PdfCanvas	pdfCanvas
protected Rectangle	rootArea

Fields inherited from class com.itextpdf.layout.RootElement

childElements, defaultFont, defaultFontProvider, defaultSplitCharacters, immediateFlush, pdfDocument, rootRenderer

Fields inherited from class com.itextpdf.layout.ElementPropertyContainer

properties

Constructor Summary

Constructors

Constructor and Description
Canvas(PdfCanvas pdfCanvas, PdfDocument pdfDocument, Rectangle rootArea) Deprecated. use Canvas(PdfCanvas, Rectangle) instead.
Canvas(PdfCanvas pdfCanvas, PdfDocument pdfDocument, Rectangle rootArea, boolean immediateFlush) Deprecated. use Canvas(PdfCanvas, Rectangle, boolean) instead.
Canvas(PdfCanvas pdfCanvas, Rectangle rootArea) Creates a new Canvas to manipulate a specific content stream, which might be for example a page or PdfFormXObject stream.
Canvas(PdfCanvas pdfCanvas, Rectangle rootArea, boolean immediateFlush) Creates a new Canvas to manipulate a specific document and page.
Canvas(PdfFormXObject formXObject, PdfDocument pdfDocument) Creates a new Canvas to manipulate a specific PdfFormXObject.
Canvas(PdfPage page, Rectangle rootArea) Creates a new Canvas to manipulate a specific page content stream.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the Canvas.
void	enableAutoTagging(PdfPage page) Enables canvas content autotagging.
protected RootRenderer	ensureRootRendererNotNull()
void	flush() Forces all registered renderers (including child element renderers) to flush their contents to the content stream.
PdfPage	getPage() The page on which this canvas will be rendered.
PdfCanvas	getPdfCanvas() Gets the PdfCanvas.
PdfDocument	getPdfDocument() Gets the PdfDocument for this canvas.
Rectangle	getRootArea() Gets the root area rectangle.
boolean	isAutoTaggingEnabled()
boolean	isCanvasOfPage() Defines if the canvas is exactly the direct content of the page.
void	relayout() Performs an entire recalculation of the element flow on the canvas, taking into account all its current child elements.
void	setRenderer(CanvasRenderer canvasRenderer) Sets the IRenderer for this Canvas.

Methods inherited from class com.itextpdf.layout.RootElement

add, add, createAndAddRendererSubTree, deleteOwnProperty, getDefaultProperty, getFontProvider, getOwnProperty, getProperty, getRenderer, hasOwnProperty, hasProperty, setFontProvider, setProperty, showTextAligned, showTextAligned, showTextAligned, showTextAligned, showTextAligned, showTextAligned, showTextAlignedKerned

Methods inherited from class com.itextpdf.layout.ElementPropertyContainer

getSplitCharacters, getStrokeColor, getStrokeWidth, getTextRenderingMode, setBackgroundColor, setBackgroundColor, setBackgroundColor, setBackgroundColor, setBackgroundImage, setBackgroundImage, setBaseDirection, setBold, setBorder, setBorderBottom, setBorderBottomLeftRadius, setBorderBottomRightRadius, setBorderLeft, setBorderRadius, setBorderRight, setBorderTop, setBorderTopLeftRadius, setBorderTopRightRadius, setCharacterSpacing, setDestination, setFixedPosition, setFixedPosition, setFixedPosition, setFixedPosition, setFont, setFont, setFontColor, setFontColor, setFontFamily, setFontFamily, setFontKerning, setFontScript, setFontSize, setHorizontalAlignment, setHyphenation, setItalic, setLineThrough, setOpacity, setRelativePosition, setSplitCharacters, setStrokeColor, setStrokeWidth, setTextAlignment, setTextRenderingMode, setUnderline, setUnderline, setUnderline, setUnderline, setWordSpacing

Methods inherited from class java.lang.Object

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

Field Detail

pdfCanvas

protected PdfCanvas pdfCanvas

rootArea

protected Rectangle rootArea

page

protected PdfPage page

Is initialized and used only when Canvas element autotagging is enabled, see enableAutoTagging(PdfPage). It is also used to determine if autotagging is enabled.

Constructor Detail

Canvas

public Canvas(PdfPage page,
              Rectangle rootArea)

Creates a new Canvas to manipulate a specific page content stream. The given page shall not be flushed: drawing on flushed pages is impossible because their content is already written to the output stream. Use this constructor to be able to add Link elements on it (using any other constructor would result in inability to add PDF annotations, based on which, for example, links work).

If the PdfDocument.isTagged() is true, using this constructor would automatically enable the tagging for the content. Regarding tagging the effect is the same as using enableAutoTagging(PdfPage).

Parameters:

page - the page on which this canvas will be rendered, shall not be flushed (see PdfObjectWrapper.isFlushed()).

rootArea - the maximum area that the Canvas may write upon

Canvas

public Canvas(PdfCanvas pdfCanvas,
              Rectangle rootArea)

Creates a new Canvas to manipulate a specific content stream, which might be for example a page or PdfFormXObject stream.

Parameters:

pdfCanvas - the low-level content stream writer

rootArea - the maximum area that the Canvas may write upon

Canvas

@Deprecated
public Canvas(PdfCanvas pdfCanvas,
                          PdfDocument pdfDocument,
                          Rectangle rootArea)

Deprecated. use Canvas(PdfCanvas, Rectangle) instead.

Creates a new Canvas to manipulate a specific document and content stream, which might be for example a page or PdfFormXObject stream.

Parameters:

pdfCanvas - the low-level content stream writer

pdfDocument - the document that the resulting content stream will be written to

rootArea - the maximum area that the Canvas may write upon To be removed in 7.2

Canvas

public Canvas(PdfCanvas pdfCanvas,
              Rectangle rootArea,
              boolean immediateFlush)

Creates a new Canvas to manipulate a specific document and page.

Parameters:

pdfCanvas - The low-level content stream writer

rootArea - The maximum area that the Canvas may write upon

immediateFlush - Whether to flush the canvas immediately after operations, false otherwise

Canvas

@Deprecated
public Canvas(PdfCanvas pdfCanvas,
                          PdfDocument pdfDocument,
                          Rectangle rootArea,
                          boolean immediateFlush)

Deprecated. use Canvas(PdfCanvas, Rectangle, boolean) instead.

Creates a new Canvas to manipulate a specific document and page.

Parameters:

pdfCanvas - The low-level content stream writer

pdfDocument - The document that the resulting content stream will be written to

rootArea - The maximum area that the Canvas may write upon

immediateFlush - Whether to flush the canvas immediately after operations, false otherwise To be removed in 7.2

Canvas

public Canvas(PdfFormXObject formXObject,
              PdfDocument pdfDocument)

Creates a new Canvas to manipulate a specific PdfFormXObject.

Parameters:

formXObject - the form

pdfDocument - the document that the resulting content stream will be written to

Method Detail

getPdfDocument

public PdfDocument getPdfDocument()

Gets the PdfDocument for this canvas.

Returns:

the document that the resulting content stream will be written to

getRootArea

public Rectangle getRootArea()

Gets the root area rectangle.

Returns:

the maximum area that the Canvas may write upon

getPdfCanvas

public PdfCanvas getPdfCanvas()

Gets the PdfCanvas.

Returns:

the low-level content stream writer

setRenderer

public void setRenderer(CanvasRenderer canvasRenderer)

Sets the IRenderer for this Canvas.

Parameters:

canvasRenderer - a renderer specific for canvas operations

getPage

public PdfPage getPage()

The page on which this canvas will be rendered.

Returns:

the specified PdfPage instance, might be null if this the page was not set.

enableAutoTagging

public void enableAutoTagging(PdfPage page)

Enables canvas content autotagging. By default it is disabled.

Parameters:

page - the page, on which this canvas will be rendered.

isAutoTaggingEnabled

public boolean isAutoTaggingEnabled()

Returns:

true if autotagging of canvas content is enabled. Default value - false.

isCanvasOfPage

public boolean isCanvasOfPage()

Defines if the canvas is exactly the direct content of the page. This is known definitely only if this instance was created by Canvas(PdfPage, Rectangle) constructor overload, otherwise this method returns false.

Returns:

true if the canvas on which this instance performs drawing is directly the canvas of the page; false if the instance of this class was created not with Canvas(PdfPage, Rectangle) constructor overload.

relayout

public void relayout()

Performs an entire recalculation of the element flow on the canvas, taking into account all its current child elements. May become very resource-intensive for large documents. Do not use when you have set RootElement.immediateFlush to true.

flush

public void flush()

Forces all registered renderers (including child element renderers) to flush their contents to the content stream.

close

public void close()

Closes the Canvas. Although not completely necessary in all cases, it is still recommended to call this method when you are done working with Canvas object, as due to some properties set there might be some 'hanging' elements, which are waiting other elements to be added and processed. close() tells the Canvas that no more elements will be added and it is time to finish processing all the elements.

ensureRootRendererNotNull

protected RootRenderer ensureRootRendererNotNull()

Specified by:

ensureRootRendererNotNull in class RootElement<Canvas>