com.qoppa.office

Class OfficeConvertOptions

java.lang.Object

com.qoppa.office.OfficeConvertOptions

Direct Known Subclasses:

ExcelConvertOptions, PowerPointConvertOptions, WordConvertOptions

public abstract class OfficeConvertOptions
extends Object

General options common to converting both Word and Excel documents to PDF

Author:

Qoppa Software

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	OfficeConvertOptions.SubstituteFontRecord Defines a font substitution record.

Constructor Summary

Constructors

Constructor and Description
OfficeConvertOptions() Constructor - sets defaults

Method Summary

Modifier and Type	Method and Description
boolean	getEmbedFonts() Get embed fonts flag
String	getFallbackFontPath() Get embed fallback font path
int	getMaxUndefinedGlyphCountAllowed() Get the maximum number of unsupported characters allowed when falling back to the fallback font.
Map<String,OfficeConvertOptions.SubstituteFontRecord>	getSubstituteFontsMap()
void	setEmbedFonts(boolean embedFonts) Set embed fonts flag Default = true
void	setFallbackFontPath(String fallbackFontPath) Set path to TrueType fallback font that will be used when a local font cannot be found to embed for a Word document font.
void	setFontSubstitute(String origFontFamily, String substituteFontFamily, boolean preferSubstitute) Creates a SubstituteFontRecord instance and maps it to the origFontFamily see setSubstituteFontsMap(Map).
void	setMaxUndefinedGlyphCountAllowed(int max) Set the maximum number of unsupported characters allowed when falling back to the fallback font. If no Fallback Font Path has been set then this value is not used. When getEmbedFonts() == true, for each font used in the Office Document we will attempt to match a font from the local system to embed in the PDF.
void	setSubstituteFontsMap(Map<String,OfficeConvertOptions.SubstituteFontRecord> fontNameSubstitutions) Sets a map of font family names to substitute font family names.

Methods inherited from class java.lang.Object

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

Constructor Detail

OfficeConvertOptions

public OfficeConvertOptions()

Constructor - sets defaults

Method Detail

getEmbedFonts

public boolean getEmbedFonts()

Get embed fonts flag

Returns:

boolean - embed fonts flag

setEmbedFonts

public void setEmbedFonts(boolean embedFonts)

Set embed fonts flag Default = true

Parameters:

embedFonts - - true to embed fonts

getFallbackFontPath

public String getFallbackFontPath()

Get embed fallback font path

Returns:

String - embed fallback font path

setFallbackFontPath

public void setFallbackFontPath(String fallbackFontPath)

Set path to TrueType fallback font that will be used when a local font cannot be found to embed for a Word document font. If this is not set then jOfficeConvert will throw an exception when a local font for embedding cannot be found.

Default = null (no fallback font)

Parameters:

fallbackFontPath - - path to fallback font .TTF file

setMaxUndefinedGlyphCountAllowed

public void setMaxUndefinedGlyphCountAllowed(int max)

Set the maximum number of unsupported characters allowed when falling back to the fallback font.

If no Fallback Font Path has been set then this value is not used.

When getEmbedFonts() == true, for each font used in the Office Document we will attempt to match a font from the local system to embed in the PDF. If we fail to find a suitable font we will use the Fallback Font if it has been set. Setting this option allows some control over whether conversion should succeed or not when the Fallback Font does not provide complete glyph support for characters it will be used to render.

If you want conversion to ALWAYS FAIL when there are undefined glyphs for any number of characters used in the document set this value to 0.

If you want conversion to NEVER FAIL due to undefined glyphs in the resulting PDF then set this to any negative value, e.g. -1.

Setting this value to a positive value > 0 allows some heuristic control over the results. For example, sometimes a bullet point character or a single symbolic character may not be supported in the fallback font but you consider it preferable for the resulting PDF to contain Undefined Glyphs (typically rendered as rectangles, sometimes with question marks inside) in these few instances rather than for conversion to competely fail.

Parameters:

max - - the maximum number of unsupported characters to allow in the resulting PDF when getEmbedFonts() == true and the fallback font has been set.

Default = 5

getMaxUndefinedGlyphCountAllowed

public int getMaxUndefinedGlyphCountAllowed()

Get the maximum number of unsupported characters allowed when falling back to the fallback font. See setMaxUndefinedGlyphCountAllowed(int).

Default = 5

setSubstituteFontsMap

public void setSubstituteFontsMap(Map<String,OfficeConvertOptions.SubstituteFontRecord> fontNameSubstitutions)

Sets a map of font family names to substitute font family names. The mapped font families are mapped to SubstituteFontRecord instances which specify both the substitute family name and whether the substitute should be preferred when both the original and the substitute fonts happen to be available on the local system. If the substitute font family is available on the local system and the original font family is not then the substitute will be used regardless of the isPreferred flag. If both fonts are available the substitute will only be used if the SubstituteFontRecord.isPreferred() returns true.
Among other cases, mapping substitute fonts can be especially useful on Linux or other non-Microsoft systems when converting Microsoft Office documents creating with proprietary Microsoft fonts by mapping Microsoft fonts to metric-compatible alternatives. For, the free open source font "Carlito" is a metric compatible alternative to the proprietary Microsoft font called "Calibri".

The String instances used in the Map should represent font family names, rather than full face names.

Parameters:

fontNameSubstitutions - - a Map where the key values are the fonts used in an Office document and the values are the respective fonts to be used in PDF conversion.

getSubstituteFontsMap

public Map<String,OfficeConvertOptions.SubstituteFontRecord> getSubstituteFontsMap()

Returns:

an unmodifiable view of the font substitution map

see setSubstituteFontsMap(Map).

setFontSubstitute

public void setFontSubstitute(String origFontFamily,
                              String substituteFontFamily,
                              boolean preferSubstitute)

Creates a SubstituteFontRecord instance and maps it to the origFontFamily
see setSubstituteFontsMap(Map).

Parameters:

origFontFamily - - should be the font family name of a font to set a SubstituteFontRecord for

substituteFontFamily - - should be the name of the substitute font family to use for origFontFamily

preferSubstitute - - whether the substitute should be used even if the origFontFamily is available