Class PdfSaveOptions

java.lang.Object

com.grapecity.documents.excel.SaveOptionsBase

com.grapecity.documents.excel.PdfSaveOptions

public class PdfSaveOptions extends SaveOptionsBase

Represents options for saving a workbook to PDF.

Use this class to configure PDF-specific export behavior, such as shrink-to-fit handling for wrapped text, document properties, security settings, form field export, background image printing, transparent cell rendering, open-action JavaScript, and whether automatically merged cells are included.

This class extends SaveOptionsBase and is typically passed to a workbook save operation that targets the PDF file format.


 worksheet.getRange("A1").setValue("Quarterly Report");

 PdfSaveOptions options = new PdfSaveOptions();
 options.setPrintBackgroundPicture(true);
 options.setIncludeAutoMergedCells(true);
 options.getShrinkToFitSettings().setMinimumFont(10);
 workbook.save("path/to/output.pdf", options);

Constructor Summary

Constructors

Constructor

Description

PdfSaveOptions()

Creates a new set of options for saving a workbook as a PDF file.
Method Summary

Modifier and Type

Method

Description

final HashMap<BorderLineStyle,CustomBorderStyle>

getBorderOptions()

Gets the border options used when exporting to PDF.

DocumentProperties

getDocumentProperties()

Gets the document properties of the PDF.

boolean

getFormFields()

Gets whether Excel form controls are replaced with PDF form fields.

boolean

getIncludeAutoMergedCells()

Gets whether automatically merged cells are included when exporting to PDF.

String

getOpenActionScript()

Gets the JavaScript that is executed when the saved PDF file is opened.

Event<EventHandler<PagePrintedEventArgs>>

getPagePrintedEvent()

Occurs when a page was printed.

Event<EventHandler<PagePrintingEventArgs>>

getPagePrintingEvent()

Occurs before printing a page.

IPDFRenderEngine

getPDFRenderEngin()

Gets the PDF render engine used during PDF export.

boolean

getPrintBackgroundPicture()

Gets whether the worksheet background image is printed on the page when exporting to PDF.

boolean

getPrintTransparentCell()

Gets whether the transparency of the cell's background color is printed on the page.

PdfSecurityOptions

getSecurityOptions()

Gets the security settings of the PDF.

IShrinkToFitSettings

getShrinkToFitSettings()

Gets the settings used to perform shrink-to-fit on wrapped text during PDF export.

void

setDocumentProperties(DocumentProperties value)

Sets the document properties of the PDF.

void

setFormFields(boolean value)

Sets whether Excel form controls are replaced with PDF form fields.

void

setIncludeAutoMergedCells(boolean value)

Sets whether automatically merged cells are included when exporting to PDF.

void

setOpenActionScript(String openActionScript)

Sets the JavaScript that is executed when the saved PDF file is opened.

void

setPDFRenderEngin(IPDFRenderEngine pdfPrinter)

Sets the PDF render engine used during PDF export.

void

setPrintBackgroundPicture(boolean value)

Sets whether the worksheet background image is printed on the page when exporting to PDF.

void

setPrintTransparentCell(boolean value)

Sets whether the transparency of the cell's background color is printed on the page.

void

setSecurityOptions(PdfSecurityOptions value)

Sets the security settings of the PDF.

String

toString()

Returns a string representation of these PDF save options.

Methods inherited from class com.grapecity.documents.excel.SaveOptionsBase
getFileFormat, setFileFormat

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

Constructor Details
- PdfSaveOptions
  
  public PdfSaveOptions()
  Creates a new set of options for saving a workbook as a PDF file.
  This constructor initializes the options to use SaveFileFormat.Pdf and creates the shrink-to-fit settings that can be accessed through getShrinkToFitSettings().
  
  PdfSaveOptions options = new PdfSaveOptions(); options.setFormFields(true); options.setPrintBackgroundPicture(true); workbook.save("path/to/output.pdf", options);
Method Details
- getPDFRenderEngin
  
  public IPDFRenderEngine getPDFRenderEngin()
  Gets the PDF render engine used during PDF export.
  Use this option to set a custom PDF render engine for PDF export. Usually, you do not need to set it.
  
  Workbook workbook = new Workbook(); workbook.getActiveSheet().getRange("A1").setValue("Quarterly Report"); CustomPdfRenderEngine renderEngine = new CustomPdfRenderEngine(); renderEngine.addFontMapping("Calibri", "Arial"); PdfSaveOptions options = new PdfSaveOptions(); options.setPDFRenderEngin(renderEngine); IPDFRenderEngine currentEngine = options.getPDFRenderEngin(); workbook.save(new ByteArrayOutputStream(), options);
  Returns:
  
  The PDF render engine, or null if no custom engine is set.
- setPDFRenderEngin
  
  public void setPDFRenderEngin(IPDFRenderEngine pdfPrinter)
  Sets the PDF render engine used during PDF export.
  Use this option to set a custom PDF render engine for PDF export. Usually, you do not need to set it.
  
  Workbook workbook = new Workbook(); workbook.getActiveSheet().getRange("A1").setValue("Quarterly Report"); CustomPdfRenderEngine renderEngine = new CustomPdfRenderEngine(); renderEngine.addFontMapping("Calibri", "Arial"); PdfSaveOptions options = new PdfSaveOptions(); options.setPDFRenderEngin(renderEngine); workbook.save(new ByteArrayOutputStream(), options);
  Parameters:
  
  pdfPrinter - The PDF render engine to use, or null to clear the custom engine.
- getPrintBackgroundPicture
  
  public boolean getPrintBackgroundPicture()
  Gets whether the worksheet background image is printed on the page when exporting to PDF.
  When this option is enabled, the sheet background image is rendered in the center of the exported PDF page.
  
  PdfSaveOptions options = new PdfSaveOptions(); options.setPrintBackgroundPicture(true); boolean printBackgroundPicture = options.getPrintBackgroundPicture(); workbook.save("path/to/output.pdf", options);
  Returns:
  
  true if the worksheet background image is printed on the page during PDF export; otherwise, false.
- setPrintBackgroundPicture
  
  public void setPrintBackgroundPicture(boolean value)
  Sets whether the worksheet background image is printed on the page when exporting to PDF.
  When this option is enabled, the sheet background image is rendered in the center of the exported PDF page.
  
  PdfSaveOptions options = new PdfSaveOptions(); options.setPrintBackgroundPicture(true); workbook.save("path/to/output.pdf", options);
  Parameters:
  
  value - true if the worksheet background image is printed on the page during PDF export; otherwise, false.
- getPrintTransparentCell
  
  public boolean getPrintTransparentCell()
  Gets whether the transparency of the cell's background color is printed on the page.
  The default value is false. When this property is true, transparent cell background colors are preserved during PDF export so content such as background images can remain visible through the cell fill.
  
  PdfSaveOptions options = new PdfSaveOptions(); options.setPrintTransparentCell(true); boolean printTransparentCell = options.getPrintTransparentCell(); workbook.save("path/to/output.pdf", options);
  Returns:
  
  true if the transparency of the cell's background color is printed on the page; otherwise, false.
- setPrintTransparentCell
  
  public void setPrintTransparentCell(boolean value)
  Sets whether the transparency of the cell's background color is printed on the page.
  The default value is false. When this property is true, transparent cell background colors are preserved during PDF export so content such as background images can remain visible through the cell fill.
  
  PdfSaveOptions options = new PdfSaveOptions(); options.setPrintTransparentCell(true); workbook.save("path/to/output.pdf", options);
  Parameters:
  
  value - true if the transparency of the cell's background color is printed on the page; otherwise, false.
- getShrinkToFitSettings
  
  public IShrinkToFitSettings getShrinkToFitSettings()
  Gets the settings used to perform shrink-to-fit on wrapped text during PDF export.
  The returned IShrinkToFitSettings object lets you control how wrapped text is reduced to fit within its cell when a workbook is saved as PDF, including whether wrapped text can shrink, the minimum font size, and the ellipsis string.
  
  PdfSaveOptions options = new PdfSaveOptions(); IShrinkToFitSettings settings = options.getShrinkToFitSettings(); settings.setCanShrinkToFitWrappedText(true); settings.setMinimumFont(10); workbook.save("path/to/output.pdf", options);
  Returns:
  
  The shrink-to-fit settings for wrapped text used during PDF export.
- getDocumentProperties
  
  public DocumentProperties getDocumentProperties()
  Gets the document properties of the PDF.
  Use setDocumentProperties(DocumentProperties) to assign PDF metadata such as title, author, subject, keywords, creator, producer, creation date, modify date, and PDF version before retrieving it.
  
  PdfSaveOptions options = new PdfSaveOptions(); DocumentProperties documentProperties = new DocumentProperties(); documentProperties.setTitle("Quarterly Sales Summary"); options.setDocumentProperties(documentProperties); DocumentProperties properties = options.getDocumentProperties(); workbook.save("path/to/output.pdf", options);
  Returns:
  
  The document properties used for PDF export.
- setDocumentProperties
  
  public void setDocumentProperties(DocumentProperties value)
  Sets the document properties of the PDF.
  Use this method to assign a DocumentProperties instance that defines PDF metadata such as the title, author, subject, keywords, creator, producer, creation date, modification date, and PDF version.
  
  PdfSaveOptions options = new PdfSaveOptions(); DocumentProperties documentProperties = new DocumentProperties(); documentProperties.setTitle("Quarterly Sales Summary"); options.setDocumentProperties(documentProperties); workbook.save("path/to/output.pdf", options);
  Parameters:
  
  value - The DocumentProperties instance that defines the PDF document properties.
- getOpenActionScript
  
  public String getOpenActionScript()
  Gets the JavaScript that is executed when the saved PDF file is opened.
  Use this method to retrieve the open action script configured by setOpenActionScript(String) for PDF export.
  Security: PDF open action JavaScript runs when the exported PDF is opened. Use only fixed, trusted, and reviewed scripts. Do not pass external or user-controlled input to this property. Leave it unset unless the PDF explicitly requires an open action.
  
  PdfSaveOptions options = new PdfSaveOptions(); String trustedOpenActionScript = "this.dirty = false;"; options.setOpenActionScript(trustedOpenActionScript); String openActionScript = options.getOpenActionScript(); workbook.save("path/to/output.pdf", options);
  Returns:
  
  The JavaScript to be executed when the saved PDF file is opened.
- setOpenActionScript
  
  public void setOpenActionScript(String openActionScript)
  Sets the JavaScript that is executed when the saved PDF file is opened.
  Security: PDF open action JavaScript runs when the exported PDF is opened. Use only fixed, trusted, and reviewed scripts. Do not pass external or user-controlled input to this property. Leave it unset unless the PDF explicitly requires an open action.
  
  PdfSaveOptions options = new PdfSaveOptions(); String trustedOpenActionScript = "this.dirty = false;"; options.setOpenActionScript(trustedOpenActionScript); workbook.save("path/to/output.pdf", options);
  Parameters:
  
  openActionScript - The JavaScript to be executed when the saved PDF file is opened.
- getSecurityOptions
  
  public PdfSecurityOptions getSecurityOptions()
  Gets the security settings of the PDF.
  Returns the PdfSecurityOptions object that defines PDF passwords and permissions for this save operation. Use setSecurityOptions(PdfSecurityOptions) to assign the security settings.
  
  PdfSaveOptions options = new PdfSaveOptions(); PdfSecurityOptions securityOptions = new PdfSecurityOptions(); String userPassword = getPdfUserPassword(); securityOptions.setUserPassword(userPassword); options.setSecurityOptions(securityOptions); PdfSecurityOptions pdfSecurityOptions = options.getSecurityOptions(); workbook.save("path/to/output.pdf", options);
  Returns:
  
  The security settings of the PDF.
- setSecurityOptions
  
  public void setSecurityOptions(PdfSecurityOptions value)
  Sets the security settings of the PDF.
  Assign a PdfSecurityOptions object to define PDF passwords and permissions for this save operation, such as printing, modifying, or extracting content.
  
  PdfSaveOptions options = new PdfSaveOptions(); PdfSecurityOptions securityOptions = new PdfSecurityOptions(); String userPassword = getPdfUserPassword(); securityOptions.setUserPassword(userPassword); securityOptions.setPrintPermission(false); options.setSecurityOptions(securityOptions); workbook.save("path/to/output.pdf", options);
  Parameters:
  
  value - The PdfSecurityOptions object that defines the PDF security settings. null removes the current security settings.
- getIncludeAutoMergedCells
  
  public boolean getIncludeAutoMergedCells()
  Gets whether automatically merged cells are included when exporting to PDF.
  This option controls whether auto-merge information is applied during PDF export. The default value is false.
  
  PdfSaveOptions options = new PdfSaveOptions(); options.setIncludeAutoMergedCells(true); boolean includeAutoMergedCells = options.getIncludeAutoMergedCells(); workbook.save("path/to/output.pdf", options);
  Returns:
  
  true if automatically merged cells are included during PDF export; otherwise, false.
- setIncludeAutoMergedCells
  
  public void setIncludeAutoMergedCells(boolean value)
  Sets whether automatically merged cells are included when exporting to PDF.
  This option controls whether auto-merge information is applied during PDF export. The default value is false.
  
  PdfSaveOptions options = new PdfSaveOptions(); options.setIncludeAutoMergedCells(true); workbook.save("path/to/output.pdf", options);
  Parameters:
  
  value - true if automatically merged cells are included during PDF export; otherwise, false.
- getPagePrintingEvent
  
  public Event<EventHandler<PagePrintingEventArgs>> getPagePrintingEvent()
  Occurs before printing a page.
  final boolean[] pagePrintingInvoked = new boolean[] { false }; PdfSaveOptions options = new PdfSaveOptions(); options.getPagePrintingEvent().addListener(new EventHandler<PagePrintingEventArgs>() { public void invoke(Object sender, PagePrintingEventArgs e) { pagePrintingInvoked[0] = true; } }); ByteArrayOutputStream outputStream = new ByteArrayOutputStream(); workbook.save(outputStream, options);
  Returns:
  
  The event raised before a page is printed.
- getPagePrintedEvent
  
  public Event<EventHandler<PagePrintedEventArgs>> getPagePrintedEvent()
  Occurs when a page was printed.
  worksheet.getRange("A1:A96").setValue(1); final boolean[] hasMorePages = new boolean[] { false }; PdfSaveOptions options = new PdfSaveOptions(); options.getPagePrintedEvent().addListener(new EventHandler<PagePrintedEventArgs>() { public void invoke(Object sender, PagePrintedEventArgs e) { hasMorePages[0] |= e.getHasMorePages(); } }); ByteArrayOutputStream outputStream = new ByteArrayOutputStream(); workbook.save(outputStream, options);
  Returns:
  
  The event raised after a page is printed.
- toString
  
  public String toString()
  
  Returns a string representation of these PDF save options.
  
  Overrides:
  
  toString in class Object
  
  Returns:
  
  A string representation of these PDF save options.
- getFormFields
  
  public boolean getFormFields()
  Gets whether Excel form controls are replaced with PDF form fields.
  When this property is true, supported Excel form controls are exported as PDF form fields. Not all controls and properties are supported.
  
  PdfSaveOptions options = new PdfSaveOptions(); options.setFormFields(true); boolean formFields = options.getFormFields(); workbook.save("path/to/output.pdf", options);
  Returns:
  
  true if Excel form controls will be exported as PDF form fields; otherwise, false. The default value is false.
- setFormFields
  
  public void setFormFields(boolean value)
  Sets whether Excel form controls are replaced with PDF form fields.
  When this property is true, supported Excel form controls are exported as PDF form fields. Not all controls and properties are supported.
  
  PdfSaveOptions options = new PdfSaveOptions(); options.setFormFields(true); workbook.save("path/to/output.pdf", options);
  Parameters:
  
  value - true if Excel form controls will be exported as PDF form fields; otherwise, false. The default value is false.
- getBorderOptions
  
  public final HashMap<BorderLineStyle,CustomBorderStyle> getBorderOptions()
  Gets the border options used when exporting to PDF.
  The returned map stores custom PDF border settings for each BorderLineStyle. Add or update entries in this map to override the exported border width and dash pattern for specific border line styles.
  
  PdfSaveOptions options = new PdfSaveOptions(); CustomBorderStyle thinBorderStyle = new CustomBorderStyle(); thinBorderStyle.setBorderWidth(0.4); options.getBorderOptions().put(BorderLineStyle.Thin, thinBorderStyle); workbook.save("path/to/output.pdf", options);
  Returns:
  
  A map that stores custom border styles for PDF export, keyed by BorderLineStyle.

Class PdfSaveOptions

Constructor Summary

Method Summary

Methods inherited from class com.grapecity.documents.excel.SaveOptionsBase

Methods inherited from class java.lang.Object

Constructor Details

PdfSaveOptions

Method Details

getPDFRenderEngin

setPDFRenderEngin

getPrintBackgroundPicture

setPrintBackgroundPicture

getPrintTransparentCell

setPrintTransparentCell

getShrinkToFitSettings

getDocumentProperties

setDocumentProperties

getOpenActionScript

setOpenActionScript

getSecurityOptions

setSecurityOptions

getIncludeAutoMergedCells

setIncludeAutoMergedCells

getPagePrintingEvent

getPagePrintedEvent

toString

getFormFields

setFormFields

getBorderOptions