Aspose.Words for Java 17.3.0 Release Notes

Major Features

There are 72 improvements and fixes in this regular monthly release. The most notable are:

• Added public API to insert online video via DocumentBuilder.InsertOnlineVideo
• Added functionality to set thread-local (and Aspose.Words application only) Locale and TimeZone. CurrentThreadSettings public API class added for this.
• New public OfficeMath properties: MathObjectType, Justification, DisplayType
• Full support for Word 2013 documents (roundtrip to/from DOCX)
• Variables support and more new features are introduced in LINQ Reporting Engine.
• Font substitution mechanism improved. Now Aspose.Words evaluates all related fields in FontInfo (Panose, Sig etc) and finds the closest match among the available font sources.
• Asian font rendering improved (more precise metrics calculation).
• Stroke weight is now taken into account while rendering auto-sized Textboxes.
• Implemented next round of improvements in table grid algorithm.
• Improved table breaking logic in compatibility mode for tables with header rows.
• Improved table breaking logic for tables with nested tables in a cell with bottom margin set.
• Improved tables breaking logic for tables with vertically merged cells having horizontal borders.
• Implemented fitText option for table cells.

Full List of Issues Covering all Changes in this Release

Public API and Backward Incompatible Changes

This section lists public API changes that were introduced in Aspose.Words 17.3.0. It includes not only new and obsoleted public methods, but also a description of any changes in the behavior behind the scenes in Aspose.Words which may affect existing code. Any behavior introduced that could be seen as a regression and modifies existing behavior is especially important and is documented here.

WORDSNET-4316: Font Substitution Mechanism Improved

Previously Aspose.Words performed font substitution only in cases when FontInfo in the document for the missing font doesn’t contains the PANOSE. Now Aspose.Words evaluates all related fields in FontInfo (Panose, Sig etc) and finds the closest match among the available font sources. In case of font substitution the warning is issued with text:

“Font ‘<font_name>’ has not been found. Using ‘<substitution_name>’ font instead. Reason: closest match according to font info from the document.”

Please note that now font substitution mechanism will override the FontSettings.DefaultFontName in cases when FontInfo for the missing font is available in the document. FontSettings.DefaultFontName will be used only in cases when there are no FontInfo for the missing font.

Also please note that font substitution algorithm in MS Word is not documented. And the result of Aspose.Words font substitution may not match MS Word choice.

WORDSNET-14602 - New Public OfficeMath.MathObjectType Property Added

To improve customer experience with Office Math objects in Aspose.Words model we’ve exposed the following simple read-only addition to the public API:

• New readon-only property OfficeMath.MathObjectType
• New public enum MathObjectType

// How to use:
OfficeMath officeMath = GetOfficeMath();
if (officeMath.getMathObjectType() == MathObjectType.MATRIX)
{
   // Do something useful with the Matrix object.
}

Support of Variables, Dynamic Text Background Setting, and a New Image Size Fit mode Added to LINQ Reporting Engine

These issues have been resolved: WORDSNET-14489, WORDSNET-14600 and WORDSNET-14627

The following sections of the engine’s documentation were added/updated to describe the changes:

• Working with DataRow and DataRowView Objects
• Inserting Images Dynamically
• Setting Text Background Color Dynamically
• Using Variables
• In-Table List Template with Running (Progressive) Total (see In-Table List Template with Running (Progressive) Total).

WORDSNET-12412 - Added a MailMergeCleanupOptions Option to Remove Empty Row

As per customer’s request, we have added a MailMergeCleanupOptions option allowing to remove empty rows during mail merge:

/// <summary>
/// Specifies whether empty rows that contain mail merge regions should be removed from the document.
/// </summary>
/// <remarks>
/// This option applies only to mail merge with regions.
/// </remarks>
RemoveEmptyTableRows = 0x20

Sample usage:

document.getMailMerge().setCleanupOptions(MailMergeCleanupOptions.REMOVE_EMPTY_TABLE_ROW | MailMergeCleanupOptions.REMOVE_CONTAINING_FIELDS);
document.getMailMerge().setMergeDuplicateRegions(true);
document.getMailMerge().executeWithRegions(dataTable);

WORDSNET-14602 - New Public Properties were Added to the OfficeMath Object.

New public properties Justification and DisplayType were added into the OfficeMath class.

/**
 Gets/sets Office Math justification.
 <p>Justification cannot be set to the Office Math with display format type <see cref="OfficeMathDisplayType.Inline"/>.</p>
 <p>Inline justification cannot be set to the Office Math with display format type <see cref="OfficeMathDisplayType.Display"/>.</p>
 <p>Corresponding <see cref="DisplayType"/> has to be set before setting Office Math justification.</p>
*/
public OfficeMathJustification Justification
/**
 Gets/sets Office Math display format type which represents whether an equation is displayed inline with the text&nbsp;
 or displayed on its own line.
 <p>Display format type has effect for top level Office Math only.</p>
 <p>Returned display format type is always <see cref="OfficeMathDisplayType.Inline"/> for nested Office Math.</p>
*/
public OfficeMathDisplayType DisplayType

Use Case:

OfficeMath officeMath = (OfficeMath)doc.getChild(NodeType.OFFICE_MATH, 0, true);

// Gets/sets Office Math display format type which represents whether an equation is displayed inline with the text

// or displayed on its own line.
officeMath.setDisplayType(OfficeMathDisplayType.DISPLAY);
 // or OfficeMathDisplayType.Inline

// Gets/sets Office Math justification.
officeMath.setJustification(OfficeMathJustification.LEFT);
 // Left justification of Math Paragraph.

Mimic MS Word VBA behavior:

•  DisplayType cannot be changed for nested Office Math. The exception will be thrown.
•   Inline justification cannot be set to the Office Math displayed on its own line (DisplayType=OfficeMathDisplayType.Display). The exception will be thrown. OfficeMath.DisplayType property has to be used to change OfficeMathDisplayType first.
•   Justification cannot be set to the Office Math displayed inline with text. The exception will be thrown. OfficeMath.DisplayType property has to be used to change OfficeMathDisplayType first.

WORDSNET-14745 - Provided Ability to Specify Locale at Field Level

As per customer’s request, we have added a property that allows to get/set field’s locale:

/**
Gets or sets LCID of the field.
<seealso cref="FieldUpdateCultureSource.FieldCode"/>
*/
public int LocaleId

Sample usage:

DocumentBuilder builder = new DocumentBuilder();
Field field = builder.insertField("=1", null);
field.setLocaleId(1027);