CanvasPrinter (yFiles-for-JavaFX-Complete-3.0 API)

java.lang.Object
- com.yworks.yfiles.view.CanvasPrinter

```
public class CanvasPrinter
extends Object
```
This class provides printing capabilities for a CanvasControl.
This instance controls the printing output. Clients can set the setCanvas(CanvasControl) canvas}, the rectangle in the world coordinate system to print, and a scale factor amongst others.

Clients can also register event handlers to the printing process:
- addPrintingListener(IEventHandler) is the event that is raised just before a page is printed.
- addPrintedListener(IEventHandler) is the event that is raised just after a page was printed.
These events give clients the ability to customize the node that is being printed, e.g. to decorate the page. Important in this context are the content margins, which enable the client to place nodes in a space between the printable borders of a page and the content that is being printed.

More information on the printing mechanism can be found in the section Printing a Canvas's Content.
See Also:

print(javafx.print.PrinterJob, boolean)

Property Summary

All Methods Instance Methods Concrete Methods
Type	Property and Description
`ObjectProperty<CanvasControl>`	`canvas` Returns the property that holds the canvas to print.
`BooleanProperty`	`centeringContentEnabled` Returns the property that holds the value for whether the contents should be centered on the page.
`ObjectProperty<InsetsD>`	`contentMargins` Returns the property that holds the content margins.
`BooleanProperty`	`pageMarkPrintingEnabled` Returns the property that holds the value for whether the `createPageMarks(PageLayout, int)` method should be called for every page that is printed.
`ObjectProperty<RectD>`	`printRectangle` Returns the property that holds the rectangle that will be printed.
`DoubleProperty`	`scale` Returns the property that holds the scale.
`BooleanProperty`	`scalingDownToFitPageEnabled` Returns the property that holds the value for whether to scale down the content so that it always fits on one page.
`BooleanProperty`	`scalingUpToFitPageEnabled` Returns the property that holds the value for whether to scale up the content so that it always fills one page as large as possible.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`CanvasPrinter.PrintInfo` Encapsulates information for printing with a specific `PageLayout`, i.e. the scale dependent on the screen DPI as well as the number of rows and columns for poster printing.

Constructor Summary

Constructors
Constructor and Description
`CanvasPrinter()` Initializes a new instance with no initial `CanvasControl`.
`CanvasPrinter(CanvasControl control)` Initializes a new instance using the provided `CanvasControl` for printing.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addPrintedListener(IEventHandler<PrintingEvent> printedEventHandler)` Adds a listener for the printed event.
`void`	`addPrintingListener(IEventHandler<PrintingEvent> printingEventHandler)` Adds a listener for the printing event.
`ObjectProperty<CanvasControl>`	`canvasProperty()` Returns the property that holds the canvas to print.
`BooleanProperty`	`centeringContentEnabledProperty()` Returns the property that holds the value for whether the contents should be centered on the page.
`ObjectProperty<InsetsD>`	`contentMarginsProperty()` Returns the property that holds the content margins.
`protected ContextConfigurator`	`createContextConfigurator(RectD printRectangle)` Creates a new `ContextConfigurator` instance that is used to `ContextConfigurator.createRenderContext(CanvasControl)` create the render context} that is needed to paint the visuals for the printing.
`protected Node`	`createPageMarks(javafx.print.PageLayout pageLayout, int pageIndex)` Creates page marks.
`CanvasPrinter.PrintInfo`	`createPrintInfo(javafx.print.PageLayout pageLayout)` Determines the scale and the number of rows and columns needed to print the determined contents of the component dependent on the `isScalingDownToFitPageEnabled()` and `isScalingUpToFitPageEnabled()` properties amongst others.
`protected Node`	`createPrintingNode(IRenderContext renderContext)` Constructs the node instance that is used for printing.
`CanvasControl`	`getCanvas()` Gets the canvas to print.
`InsetsD`	`getContentMargins()` Returns the margins that are defined on this printable.
`RectD`	`getPrintRectangle()` Returns the rectangle that will be printed.
`double`	`getScale()` Returns a scale factor to apply for printing.
`boolean`	`isCenteringContentEnabled()` Returns whether the contents should be centered on the page.
`boolean`	`isPageMarkPrintingEnabled()` Returns whether the `createPageMarks(PageLayout, int)` method should be called for every page that is printed.
`boolean`	`isScalingDownToFitPageEnabled()` Return whether to scale down the content so that it always fits on one page.
`boolean`	`isScalingUpToFitPageEnabled()` Returns whether to scale up the content so that it always fills one page as large as possible.
`protected void`	`onPrintedPage(PrintingEvent args)` Called whenever a page was printed.
`protected void`	`onPrintingPage(PrintingEvent args)` Called whenever a page is about to be printed.
`BooleanProperty`	`pageMarkPrintingEnabledProperty()` Returns the property that holds the value for whether the `createPageMarks(PageLayout, int)` method should be called for every page that is printed.
`boolean`	`print(javafx.print.PrinterJob job, boolean showPrintDialog)` Prints the pages using the specified `PrinterJob` which will provide the `PageLayout` for one page to print.
`ObjectProperty<RectD>`	`printRectangleProperty()` Returns the property that holds the rectangle that will be printed.
`void`	`removePrintedListener(IEventHandler<PrintingEvent> printedEventHandler)` Removes the given listener for the printed event.
`void`	`removePrintingListener(IEventHandler<PrintingEvent> printingEventHandler)` Removes the given listener for the printing event.
`DoubleProperty`	`scaleProperty()` Returns the property that holds the scale.
`BooleanProperty`	`scalingDownToFitPageEnabledProperty()` Returns the property that holds the value for whether to scale down the content so that it always fits on one page.
`BooleanProperty`	`scalingUpToFitPageEnabledProperty()` Returns the property that holds the value for whether to scale up the content so that it always fills one page as large as possible.
`void`	`setCanvas(CanvasControl canvas)` Sets the canvas to print.
`void`	`setCenteringContentEnabled(boolean centerContent)` Sets whether the contents should be centered on the page.
`void`	`setContentMargins(InsetsD contentMargins)` Sets the margins that are defined on this printable.
`void`	`setPageMarkPrintingEnabled(boolean enabled)` Sets whether the `createPageMarks(PageLayout, int)` method should be called for every page that is printed.
`void`	`setPrintRectangle(RectD printRectangle)` Sets the rectangle that will be printed.
`void`	`setScale(double scale)` Sets a scale factor to apply for printing.
`void`	`setScalingDownToFitPageEnabled(boolean scaleDownToFitPage)` Sets whether to scale down the content so that it always fits on one page.
`void`	`setScalingUpToFitPageEnabled(boolean scaleUpToFitPage)` Sets whether to scale up the content so that it always fills one page as large as possible.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Property Detail
  - canvas
```
public ObjectProperty<CanvasControl> canvasProperty
```
    Returns the property that holds the canvas to print.
  - centeringContentEnabled
```
public BooleanProperty centeringContentEnabledProperty
```
    Returns the property that holds the value for whether the contents should be centered on the page. The default value is true.
  - contentMargins
```
public ObjectProperty<InsetsD> contentMarginsProperty
```
    Returns the property that holds the content margins.
    Keep in mind that those are different to the margins that are defined by the printableWidth and -Height of the PageLayout during the printing process. The area in which the actual content is printed is defined by adding the content margins and the PageLayout margins.
    
    For example, if the page margins are defined as [20, 20, 20, 20] and the content margins are defined as [20, 50, 10, 30], the real insets will be [40, 70, 30, 50].
    
    The reason to have two distinct sets of insets is to be able to print decorations between the content (of the CanvasControl) and the page border (defined by the PageLayout).
    
    See Also:
    
    getContentMargins(), setContentMargins(com.yworks.yfiles.geometry.InsetsD)
  - pageMarkPrintingEnabled
```
public BooleanProperty pageMarkPrintingEnabledProperty
```
    Returns the property that holds the value for whether the createPageMarks(PageLayout, int) method should be called for every page that is printed. Default value is false.
  - printRectangle
```
public ObjectProperty<RectD> printRectangleProperty
```
    Returns the property that holds the rectangle that will be printed. This rectangle determines the portion of the canvas component to print in the world coordinate system. The default value is the content rectangle of the canvas to print.
    
    See Also:
    
    getPrintRectangle(), setPrintRectangle(com.yworks.yfiles.geometry.RectD)
  - scale
```
public DoubleProperty scaleProperty
```
    Returns the property that holds the scale. A value of 0.72 makes 96 units in the world coordinate system appear exactly one inch long. The default value is 1.0.
  - scalingDownToFitPageEnabled
```
public BooleanProperty scalingDownToFitPageEnabledProperty
```
    Returns the property that holds the value for whether to scale down the content so that it always fits on one page. If this is set to true, the values returned by createPrintInfo(javafx.print.PageLayout) are ignored. Default value is true.
  - scalingUpToFitPageEnabled
```
public BooleanProperty scalingUpToFitPageEnabledProperty
```
    Returns the property that holds the value for whether to scale up the content so that it always fills one page as large as possible. If the content to print is already larger than one page, this will do nothing. Default value is false.
- Constructor Detail
  - CanvasPrinter
```
public CanvasPrinter()
```
    Initializes a new instance with no initial CanvasControl. The corresponding property needs to be set before printing can be performed. The print rectangle is set to a fallback value of [0, 0, 300, 300] in this case and should be set, too.
  - CanvasPrinter
```
public CanvasPrinter(CanvasControl control)
```
    Initializes a new instance using the provided CanvasControl for printing. This method sets the print rectangle to the content rectangle of the component.
    
    Parameters:
    
    control - The CanvasControl to print.
- Method Detail
  - addPrintedListener
```
public final void addPrintedListener(IEventHandler<PrintingEvent> printedEventHandler)
```
    Adds a listener for the printed event. This event is triggered when a page was printed.
    Clients can register to this event, for example, clean up customizations performed in the addPrintingListener(IEventHandler) printing event}.
    
    Parameters:
    
    printedEventHandler - The listener to add.
    
    See Also:
    
    removePrintedListener(IEventHandler)
  - addPrintingListener
```
public final void addPrintingListener(IEventHandler<PrintingEvent> printingEventHandler)
```
    Adds a listener for the printing event. This event is triggered when a page is about to be printed.
    Clients can register to this event, for example, to add decorations to the printed page by customizing the node to be printed.
    
    Parameters:
    
    printingEventHandler - The listener to add.
    
    See Also:
    
    removePrintingListener(IEventHandler)
  - canvasProperty
```
public ObjectProperty<CanvasControl> canvasProperty()
```
    Returns the property that holds the canvas to print.
  - centeringContentEnabledProperty
```
public BooleanProperty centeringContentEnabledProperty()
```
    Returns the property that holds the value for whether the contents should be centered on the page. The default value is true.
  - contentMarginsProperty
```
public ObjectProperty<InsetsD> contentMarginsProperty()
```
    Returns the property that holds the content margins.
    Keep in mind that those are different to the margins that are defined by the printableWidth and -Height of the PageLayout during the printing process. The area in which the actual content is printed is defined by adding the content margins and the PageLayout margins.
    
    For example, if the page margins are defined as [20, 20, 20, 20] and the content margins are defined as [20, 50, 10, 30], the real insets will be [40, 70, 30, 50].
    
    The reason to have two distinct sets of insets is to be able to print decorations between the content (of the CanvasControl) and the page border (defined by the PageLayout).
    
    See Also:
    
    getContentMargins(), setContentMargins(com.yworks.yfiles.geometry.InsetsD)
  - createContextConfigurator
```
protected ContextConfigurator createContextConfigurator(RectD printRectangle)
```
    Creates a new ContextConfigurator instance that is used to ContextConfigurator.createRenderContext(CanvasControl) create the render context} that is needed to paint the visuals for the printing.
    
    Parameters:
    
    printRectangle - The world bounds to print.
    
    Returns:
    
    A new ContextConfigurator instance.
  - createPageMarks
```
protected Node createPageMarks(javafx.print.PageLayout pageLayout,
                               int pageIndex)
```
    Creates page marks.
    The default implementation places page marks inside the content margin. I.e. page marks are outside the actual content area but inside the printable area of the given page layout.
    
    This method is only called if the page mark printing is enabled.
    
    Parameters:
    
    pageLayout - the page layout for the current print job.
    
    pageIndex - the index of the page for which page marks should be printed.
    
    See Also:
    
    getContentMargins()
  - createPrintInfo
```
public CanvasPrinter.PrintInfo createPrintInfo(javafx.print.PageLayout pageLayout)
```
    Determines the scale and the number of rows and columns needed to print the determined contents of the component dependent on the isScalingDownToFitPageEnabled() and isScalingUpToFitPageEnabled() properties amongst others.
    
    Parameters:
    
    pageLayout - the PageLayout that defines the printable area of a page.
    
    Returns:
    
    a PrintInfo instance that encapsulates the computed values for scale, number of rows and columns.
  - createPrintingNode
```
protected Node createPrintingNode(IRenderContext renderContext)
```
    Constructs the node instance that is used for printing. The default implementation simply delegates to CanvasControl.exportContent(IRenderContext)
    
    Parameters:
    
    renderContext - the context for the rendering of the node to be printed. The instance is created by the ContextConfigurator returned by createContextConfigurator(com.yworks.yfiles.geometry.RectD).
  - getCanvas
```
public CanvasControl getCanvas()
```
    Gets the canvas to print.
  - getContentMargins
```
public InsetsD getContentMargins()
```
    Returns the margins that are defined on this printable.
    Keep in mind that those are different to the margins that are defined by the printableWidth and -Height of the PageLayout during the printing process. The area in which the actual content is printed is defined by adding the content margins and the PageLayout margins.
    
    For example, if the page margins are defined as [20, 20, 20, 20] and the content margins are defined as [20, 50, 10, 30], the real insets will be [40, 70, 30, 50].
    
    The reason to have two distinct sets of insets is to be able to print decorations between the content (of the CanvasControl) and the page border (defined by the PageLayout).
  - getPrintRectangle
```
public RectD getPrintRectangle()
```
    Returns the rectangle that will be printed. This rectangle determines the portion of the canvas component to print in the world coordinate system. The default value is the content rectangle of the canvas to print.
    
    Returns:
    
    a rectangle in the world coordinate system that defines the area of the contents of the canvas component to print.
  - getScale
```
public double getScale()
```
    Returns a scale factor to apply for printing. A value of 0.72 makes 96 units in the world coordinate system appear exactly one inch long. The default value is 1.0.
  - isCenteringContentEnabled
```
public boolean isCenteringContentEnabled()
```
    Returns whether the contents should be centered on the page. The default value is true.
  - isPageMarkPrintingEnabled
```
public boolean isPageMarkPrintingEnabled()
```
    Returns whether the createPageMarks(PageLayout, int) method should be called for every page that is printed. The default value is false.
  - isScalingDownToFitPageEnabled
```
public boolean isScalingDownToFitPageEnabled()
```
    Return whether to scale down the content so that it always fits on one page. If this is set to true, the values returned by createPrintInfo(javafx.print.PageLayout) are ignored. Default value is true.
  - isScalingUpToFitPageEnabled
```
public boolean isScalingUpToFitPageEnabled()
```
    Returns whether to scale up the content so that it always fills one page as large as possible. If the content to print is already larger than one page, this will do nothing. Default value is false.
  - onPrintedPage
```
protected void onPrintedPage(PrintingEvent args)
```
    Called whenever a page was printed.
    
    Parameters:
    
    args - contains the information of what is about to be printed (column and row of the page in the raster, render context and the printed node itself).
  - onPrintingPage
```
protected void onPrintingPage(PrintingEvent args)
```
    Called whenever a page is about to be printed.
    
    Parameters:
    
    args - contains the information of what is about to be printed (column and row of the page in the raster, render context and the node to be printed itself).
  - pageMarkPrintingEnabledProperty
```
public BooleanProperty pageMarkPrintingEnabledProperty()
```
    Returns the property that holds the value for whether the createPageMarks(PageLayout, int) method should be called for every page that is printed. Default value is false.
  - print
```
public boolean print(javafx.print.PrinterJob job,
                     boolean showPrintDialog)
```
    Prints the pages using the specified PrinterJob which will provide the PageLayout for one page to print.
    This method will print the contents of the CanvasControl of the set print rectangle in world coordinates either on one page (if it fits on one page or if the isScalingDownToFitPageEnabled() property is set to true) or on as many pages as it needs to print the content.
    
    Note that calling this method will show the print dialog of the PrinterJob with the window of the CanvasControl as owner.
    
    Throws:
    
    IllegalArgumentException - if the specified PrinterJob is null.
    
    Parameters:
    
    job - the PrinterJob with the settings for printing. Cannot be null.
    
    showPrintDialog - If the PrinterJob.showPrintDialog(javafx.stage.Window) method should be called before printing. Clients that set this parameter to false should call this or a similar method by themselves before calling this method. If this option is set to true and the user cancels the print dialog, this method exits immediately and returns false.
    
    Returns:
    
    true if all pages were printed, false if something went wrong and not all pages were printed.
  - printRectangleProperty
```
public ObjectProperty<RectD> printRectangleProperty()
```
    Returns the property that holds the rectangle that will be printed. This rectangle determines the portion of the canvas component to print in the world coordinate system. The default value is the content rectangle of the canvas to print.
    
    See Also:
    
    getPrintRectangle(), setPrintRectangle(com.yworks.yfiles.geometry.RectD)
  - removePrintedListener
```
public final void removePrintedListener(IEventHandler<PrintingEvent> printedEventHandler)
```
    Removes the given listener for the printed event. This event is triggered when a page was printed.
    
    Parameters:
    
    printedEventHandler - The listener to remove.
    
    See Also:
    
    addPrintedListener(IEventHandler)
  - removePrintingListener
```
public final void removePrintingListener(IEventHandler<PrintingEvent> printingEventHandler)
```
    Removes the given listener for the printing event. This event is triggered when a page is about to be printed.
    
    Parameters:
    
    printingEventHandler - The listener to remove.
    
    See Also:
    
    addPrintingListener(IEventHandler)
  - scaleProperty
```
public DoubleProperty scaleProperty()
```
    Returns the property that holds the scale. A value of 0.72 makes 96 units in the world coordinate system appear exactly one inch long. The default value is 1.0.
  - scalingDownToFitPageEnabledProperty
```
public BooleanProperty scalingDownToFitPageEnabledProperty()
```
    Returns the property that holds the value for whether to scale down the content so that it always fits on one page. If this is set to true, the values returned by createPrintInfo(javafx.print.PageLayout) are ignored. Default value is true.
  - scalingUpToFitPageEnabledProperty
```
public BooleanProperty scalingUpToFitPageEnabledProperty()
```
    Returns the property that holds the value for whether to scale up the content so that it always fills one page as large as possible. If the content to print is already larger than one page, this will do nothing. Default value is false.
  - setCanvas
```
public void setCanvas(CanvasControl canvas)
```
    Sets the canvas to print.
  - setCenteringContentEnabled
```
public void setCenteringContentEnabled(boolean centerContent)
```
    Sets whether the contents should be centered on the page. The default value is true.
  - setContentMargins
```
public void setContentMargins(InsetsD contentMargins)
```
    Sets the margins that are defined on this printable.
    Keep in mind that those are different to the margins that are defined by the printableWidth and -Height of the PageLayout during the printing process. The area in which the actual content is printed is defined by adding the content margins and the PageLayout margins.
    
    For example, if the page margins are defined as [20, 20, 20, 20] and the content margins are defined as [20, 50, 10, 30], the real insets will be [40, 70, 30, 50].
    
    The reason to have two distinct sets of insets is to be able to print decorations between the content (of the CanvasControl) and the page border (defined by the PageLayout).
  - setPageMarkPrintingEnabled
```
public void setPageMarkPrintingEnabled(boolean enabled)
```
    Sets whether the createPageMarks(PageLayout, int) method should be called for every page that is printed. The default value is false.
  - setPrintRectangle
```
public void setPrintRectangle(RectD printRectangle)
```
    Sets the rectangle that will be printed. This rectangle determines the portion of the canvas component to print in the world coordinate system. The default value is the content rectangle of the canvas to print.
    
    Parameters:
    
    printRectangle - a rectangle in the world coordinate system that defines the area of the contents of the canvas component to print.
  - setScale
```
public void setScale(double scale)
```
    Sets a scale factor to apply for printing. A value of 0.72 makes 96 units in the world coordinate system appear exactly one inch long. The default value is 1.0.
  - setScalingDownToFitPageEnabled
```
public void setScalingDownToFitPageEnabled(boolean scaleDownToFitPage)
```
    Sets whether to scale down the content so that it always fits on one page. If this is set to true, the values returned by createPrintInfo(javafx.print.PageLayout) are ignored. Default value is true.
  - setScalingUpToFitPageEnabled
```
public void setScalingUpToFitPageEnabled(boolean scaleUpToFitPage)
```
    Sets whether to scale up the content so that it always fills one page as large as possible. If the content to print is already larger than one page, this will do nothing. Default value is false.

Class CanvasPrinter

Property Summary

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Property Detail

canvas

centeringContentEnabled

contentMargins

pageMarkPrintingEnabled

printRectangle

scale

scalingDownToFitPageEnabled

scalingUpToFitPageEnabled

Constructor Detail

CanvasPrinter

CanvasPrinter

Method Detail

addPrintedListener

addPrintingListener

canvasProperty

centeringContentEnabledProperty

contentMarginsProperty

createContextConfigurator

createPageMarks

createPrintInfo

createPrintingNode

getCanvas

getContentMargins

getPrintRectangle

getScale

isCenteringContentEnabled

isPageMarkPrintingEnabled

isScalingDownToFitPageEnabled

isScalingUpToFitPageEnabled

onPrintedPage

onPrintingPage

pageMarkPrintingEnabledProperty

print

printRectangleProperty

removePrintedListener

removePrintingListener

scaleProperty

scalingDownToFitPageEnabledProperty

scalingUpToFitPageEnabledProperty

setCanvas

setCenteringContentEnabled

setContentMargins

setPageMarkPrintingEnabled

setPrintRectangle

setScale

setScalingDownToFitPageEnabled

setScalingUpToFitPageEnabled