Aspose.Words for Java 21.10 Release Notes

Major Features

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

  • Added an ability to get ParentRegion through the MailMergeRegionInfo.
  • Added new public methods and properties to work with gradient fills and gradient stops.
  • Introduced an intuitive capability to change the appearance of a structured document tag.
  • Added new option to ignore footnotes during find-replace operation.

Full List of Issues Covering all Changes in this Release (Reported by Java Users)

KeySummaryCategory
WORDSNET-18317The gradient fill support for WordArt shapesNew Feature
WORDSJAVA-2507CultureInfoGenerator should read .NET CultureInfo.TextInfo.ANSICodePage.New Feature
WORDSJAVA-2647Share License fixes with other Aspose teams.New Feature
WORDSJAVA-2506No content is loaded from a CHM file with ANSICodePage LanguageId.Bug
WORDSJAVA-2568Shape.getShapeRenderer is executed indefinitelyBug
WORDSJAVA-2578ShapeRenderer hangs while rendering very close and long linesBug
WORDSJAVA-2581Document.getPageCount() throws java.lang.NullPointerExceptionBug
WORDSJAVA-2605DigitalSignature.SignTime returns 8 hours later timeBug
WORDSJAVA-2607java.lang.ExceptionInInitializerError is thrown when Aspose.Words is used in OSGI with JavaSE-15Bug
WORDSJAVA-2608java.lang.ExceptionInInitializerError is thrown when Aspose.Words is used in OSGI with Java 8 and 11Bug
WORDSJAVA-2611Unable to load documents into Aspose.Words’ DOM using Java 6Bug
WORDSJAVA-2614Post-upgrade: java.lang.IllegalStateException: Invalid license signature. (Java)Bug
WORDSJAVA-2615Unable to set license when deploying application’s WAR file on serverBug
WORDSJAVA-2653Invalid license signature exception is thrown by new DocumentBug
WORDSNET-22543LINQ Reporting Engine does not allow JSON or XML data source with same element name of parent and childBug
WORDSNET-22775System.IndexOutOfRangeException occurs upon DOCX to PDF conversionBug
WORDSNET-21291Table header rows are repeated in PDF where they shouldn’t beBug
WORDSNET-18910Colors of SVG not preserved in generated DOCXBug
WORDSNET-22741DOCX to PDF: Image loses alternative textBug
WORDSNET-21277Outlined Fonts SVG output is wrong in Word DocumentBug
WORDSNET-22640Russian text is lost after DOCX to PDF ConversionBug
WORDSNET-22704Period characters move to next lines causing additional vertical space between Numbered listsBug
WORDSNET-22637Non Chinese Words render below the baseline in HTML FixedBug
WORDSNET-22667Aspose.Words.FileCorruptedException occurs upon loading a DOTBug
WORDSNET-22556Text position is changed after DOCX to PDF ConversionBug
WORDSNET-22510The List Numbers are not aligned to paragraphs in output PDFBug
WORDSNET-22154Subscript is appeared as superscript in output PDFBug
WORDSNET-20939DOCX to PDF conversion issue with list item renderingBug
WORDSNET-22118Content are lost after HTML to PDF conversionBug

Full List of Issues Covering all Changes in this Release (Reported by .NET Users)

KeySummaryCategory
WORDSNET-22808Allow to work with gradient stops of gradient fillsNew Feature
WORDSNET-19658Provide API to Set Opacity of Image ShapeNew Feature
WORDSNET-22651StructuredDocumentTag - control AppearanceNew Feature
WORDSNET-21594Provide API to Add Remove Gradient Color Fill for TextNew Feature
WORDSNET-16032Support of Gradient Fill for ShapesNew Feature
WORDSNET-22371Add ability to ignore Footnotes in Range.ReplaceNew Feature
WORDSNET-22003Implement Fill.OneColorGradient() methodNew Feature
WORDSNET-22302Provide API to Set Shading Fill & Patterns for TableNew Feature
WORDSNET-22445Implement Fill.TextureAlignment propertyNew Feature
WORDSNET-22650FieldToc.UpdatePageNumbers takes much time to executeEnhancement
WORDSNET-22565Shape is lost after DOCX to PDF ConversionBug
WORDSNET-22261SVG is stretched in output DOCX and PDFBug
WORDSNET-21228DOCX to PDF conversion issue table positionBug
WORDSNET-22617storeItemChecksum attribute not calculatedBug
WORDSNET-22108Text and tables do not convert correctly in output DOCXBug
WORDSNET-22691String format firstCap does not work in combination with html switchBug
WORDSNET-22690String format firstCap not working in combination with html switch for LINQ Reporting EngineBug
WORDSNET-22616StructuredDocumentTagRangeStart\End pair removed from document modelBug
WORDSNET-22773Content overlaps in PDFBug
WORDSNET-22790Document comparison does not show deletion of shapeBug
WORDSNET-22767System.IndexOutOfRangeException is thrown when DOC is saved to PDFBug
WORDSNET-14562Paragraph background color trasparencyBug
WORDSNET-22764Extra vertical spacing added in PDFBug
WORDSNET-22140Run.Font.Border changes the text of column as single vertical lineBug
WORDSNET-22608Data merge issueBug
WORDSNET-21936Text is truncated in table cell after DOCX to PDF conversionBug
WORDSNET-22728DOCX to PDF: Banded rows style is not displayed correctlyBug
WORDSNET-19767Paragraph formatting is lost after removing bookmarkBug
WORDSNET-19660Incorret scaling of the vertical axisBug
WORDSNET-20808Aspose.Words does not import content controls containing TableBug
WORDSNET-22717MailMergeRegionInfo.EndField returns null for mail merge regionBug
WORDSNET-22709Incorrect formatting of appended document with UseDestinationStyles modeBug
WORDSNET-22596DOCX to PDF: Column missing in the output fileBug
WORDSNET-19172Chart to PNG conversion issue with Y-axisBug
WORDSNET-22699Incorrect order of the series data labels and incorrect rendering of the leader lines after converting to PDFBug
WORDSNET-22693PieChart. Rounding of the series data labels valuesBug
WORDSNET-22708Incorrect font selection when rendering MathML objectsBug
WORDSNET-22400Table graphics is not taggedBug
WORDSNET-22680Image text is changed after DOCX to PDF ConversionBug
WORDSNET-22653Image is lost after RTF to DOCX/PDF conversionBug
WORDSNET-22701The invoked member is not supported in a dynamic assembly exception when setting a licenseBug
WORDSNET-22624Text position is changed after DOCX to PDF conversionBug
WORDSNET-22222UpdatePageLayout does not update SDT contentBug
WORDSNET-18053Add support for the “preserveAspectRatio” SVG attribute on importBug
WORDSNET-20967DOCX to PDF conversion issue with Bullet item left indentBug
WORDSNET-22346Table alignment is missing in the output PDF/DOCBug
WORDSNET-21732Lines between Data Points Disappear when updating a Scatter Chart with Smooth LinesBug
WORDSNET-14609Dml text shadow disappears after renderingBug

Public API and Backward Incompatible Changes

This section lists public API changes that were introduced in Aspose.Words 21.10. 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 regression and modifies the existing behavior is especially important and is documented here.

Added a new public property MailMergeRegionInfo.ParentRegion

A new public property ParentRegion has been added to the MailMergeRegionInfo class.

/// <summary>
/// Returns parent region info (null for top-level region).
/// </summary>
public MailMergeRegionInfo ParentRegion { get; }

Use Case: Explains how to use the ParentRegion property.

Document document = new Document("template.docx");
foreach (MailMergeRegionInfo detailsRegion in document.MailMerge.GetRegionsByName("Details"))
{
    MailMergeRegionInfo masterRegion = detailsRegion.ParentRegion;
    Console.WriteLine(masterRegion.Name);
}

Added new public methods and properties to work with gradient fills

Related issue: WORDSNET-22003

Added the following methods to Fill class:

/// <summary>
/// Sets the specified fill to a one-color gradient.
/// </summary>
/// <param name="style">The gradient style <see cref="Drawing.GradientStyle"/></param>
/// <param name="variant">The gradient variant <see cref="Drawing.GradientVariant"/></param>
/// <param name="degree">The gradient degree. Can be a value from 0.0 (dark) to 1.0 (light).</param>
public void OneColorGradient(GradientStyle style, GradientVariant variant, double degree)
 
/// <summary>
/// Sets the specified fill to a one-color gradient and applies a specified color to the <see cref="ForeColor"/>.
/// </summary>
/// <param name="color">The color to apply to <see cref="ForeColor"/> after the fill is set.</param>
/// <param name="style">The gradient style <see cref="Drawing.GradientStyle"/></param>
/// <param name="variant">The gradient variant <see cref="Drawing.GradientVariant"/></param>
/// <param name="degree">The gradient degree. Can be a value from 0.0 (dark) to 1.0 (light).</param>
public void OneColorGradient(Color color, GradientStyle style, GradientVariant variant, double degree)
 
/// <summary>
/// Sets the specified fill to a two-color gradient.
/// </summary>
/// <param name="style">The gradient style <see cref="Drawing.GradientStyle"/>.</param>
/// <param name="variant">The gradient variant <see cref="Drawing.GradientVariant"/></param>
public void TwoColorGradient(GradientStyle style, GradientVariant variant)
 
/// <summary>
/// Sets the specified fill to a two-color gradient.
/// </summary>
/// <param name="color1">The first gradient color,
/// which will be set to <see cref="ForeColor"/> after the fill is applied.</param>
/// <param name="color2">The second gradient color,
/// which will be set to <see cref="BackColor"/> after the fill is applied.</param>
/// <param name="style">The gradient style <see cref="Drawing.GradientStyle"/>.</param>
/// <param name="variant">The gradient variant <see cref="Drawing.GradientVariant"/></param>
public void TwoColorGradient(Color color1, Color color2, GradientStyle style, GradientVariant variant)

Added the following properties to Fill class:

/// <summary>
/// Gets or sets the angle of the gradient fill.
/// </summary>
public double GradientAngle
 
/// <summary>
/// Gets the gradient variant <see cref="Drawing.GradientVariant"/> for the fill.
/// </summary>
public GradientVariant GradientVariant
 
/// <summary>
/// Gets the gradient style <see cref="Drawing.GradientStyle"/> for the fill.
/// </summary>
public GradientStyle GradientStyle

Also the following public enums are introduced:

/// <summary>
/// Specifies the style for a gradient fill.
/// </summary>
public enum GradientStyle
 
/// <summary>
/// Specifies the variant for a gradient fill.
/// </summary>
/// <remarks>
/// Corresponds to the four variants on the Gradient tab in the Fill Effects dialog box in Word.
/// </remarks>
public enum GradientVariant

Use Case: Explains how to work with gradient fills.

DocumentBuilder builder = new DocumentBuilder();
 
// Add new rectangle shape.
Shape shape = builder.InsertShape(ShapeType.Rectangle, 80, 80);
// Apply One-color gradient fill to the shape.
shape.Fill.OneColorGradient(GradientStyle.Horizontal, GradientVariant.Variant2, 0.1);
// Change ForeColor of gradient fill.
shape.Fill.ForeColor = Color.Red;
 
// Print gradient style, variant and angle of the fill.
Console.WriteLine(
    "Gradient style:{0}, variant:{1}, angle: {2}",
    shape.Fill.GradientStyle,
    shape.Fill.GradientVariant,
    shape.Fill.GradientAngle);
 
// Add another one rectangle shape.
shape = builder.InsertShape(ShapeType.Rectangle, 80, 80);
// Apply Two-color gradient fill to the shape.
shape.Fill.TwoColorGradient(GradientStyle.FromCorner, GradientVariant.Variant4);
// Change BackColor of gradient fill.
shape.Fill.BackColor = Color.Yellow;
 
// Print gradient style, variant and angle of the fill.
Console.WriteLine(
    "Gradient style:{0}, variant:{1}, angle: {2}",
    shape.Fill.GradientStyle,
    shape.Fill.GradientVariant,
    shape.Fill.GradientAngle);
 
builder.Document.Save("Gradients.docx");
 
// The code produces the following output:
//
// Gradient style:Horizontal, variant:Variant2, angle: 270
// Gradient style:FromCorner, variant:Variant4, angle: 0

Added new public methods and properties to work with gradient stops

Related issue: WORDSNET-22808

Added the following property to Fill class:

/// <summary>
/// Gets a collection of <see cref="GradientStop"/> objects for the fill.
/// </summary>
public GradientStopCollection GradientStops

Implemented the following new class GradientStopCollection:

/// <summary>
/// Contains a collection of <see cref="GradientStop"/> objects.
/// </summary>
/// <remarks>
/// You do not create instances of this class directly.
/// Use the <see cref="Fill.GradientStops"/> property to access gradient stops of fill objects.
/// </remarks>
public class GradientStopCollection : IEnumerable<GradientStop>

with the following public methods:

/// <summary>
/// Gets or sets a <see cref="GradientStop"/> object in the collection.
/// </summary>
public GradientStop this[int index]
 
/// <summary>
/// Inserts a <see cref="GradientStop"/> to the collection at a specified index.
/// </summary>
public GradientStop Insert(int index, GradientStop gradientStop)
 
/// <summary>
/// Adds a specified <see cref="GradientStop"/> to a gradient.
/// </summary>
public GradientStop Add(GradientStop gradientStop)
 
/// <summary>
/// Removes a <see cref="GradientStop"/> from the collection at a specified index.
/// </summary>
/// <returns>Removed <see cref="GradientStop"/>.</returns>
public GradientStop RemoveAt(int index)
 
/// <summary>
/// Removes a specified <see cref="GradientStop"/> from the collection.
/// </summary>
/// <returns>True if gradient stop was successfully removed, otherwise false.</returns>
public bool Remove(GradientStop gradientStop)

and the following public property:

/// <summary>
/// Gets an integer value indicating the number of items in the collection.
/// </summary>
public int Count

Implemented the following new class GradientStop:

/// <summary>
/// Represents one gradient stop.
/// </summary>
public class GradientStop

with the following public methods:

/// <summary>
/// Initializes a new instance of the <see cref="GradientStop" /> class.
/// </summary>
/// <param name="color">Represents the color of the gradient stop.</param>
/// <param name="position">Represents the position of a stop within
/// the gradient expressed as a percent in range 0.0 to 1.0.</param>
public GradientStop(Color color, double position)
 
/// <summary>
/// Initializes a new instance of the <see cref="GradientStop" /> class.
/// </summary>
/// <param name="color">Represents the color of the gradient stop.</param>
/// <param name="position">Represents the position of a stop within
/// the gradient expressed as a percent in range 0.0 to 1.0.</param>
/// <param name="transparency">Represents the transparency of a stop within
/// the gradient expressed as a percent in range 0.0 to 1.0.</param>
public GradientStop(Color color, double position, double transparency) : this(color, position)
 
/// <summary>
/// Removes the gradient stop from the parent <see cref="GradientStopCollection"/>.
/// </summary>
public void Remove()

and the following public properties:

/// <summary>
/// Gets or sets a value representing the color of the gradient stop.
/// </summary>
public Color Color
 
/// <summary>
/// Gets or sets a value representing the position of a stop within the gradient
/// expressed as a percent in range 0.0 to 1.0.
/// </summary>
public double Position
 
/// <summary>
/// Gets or sets a value representing the transparency of the gradient fill
/// expressed as a percent in range 0.0 to 1.0.
/// </summary>
public double Transparency

Use Case: Explains how to work with gradient stops of gradient fills.

DocumentBuilder builder = new DocumentBuilder();
builder.Document.CompatibilityOptions.OptimizeFor(MsWordVersion.Word2010);
 
// Add new rectangle shape.
Shape shape = builder.InsertShape(ShapeType.Rectangle, 80, 80);
shape.Fill.TwoColorGradient(Color.Green, Color.Red, GradientStyle.Horizontal, GradientVariant.Variant2);
 
// Get gradient stops collection.
GradientStopCollection gradientStops = shape.Fill.GradientStops;
 
// Change first gradient stop.
gradientStops[0].Color = Color.Aqua;
gradientStops[0].Position = 0.1;
gradientStops[0].Transparency = 0.25;
 
// Add new gradient stop to the end of collection.
GradientStop gradientStop = new GradientStop(Color.Brown, 0.5);
gradientStops.Add(gradientStop);
 
// Remove gradient stop at index 1.
gradientStops.RemoveAt(1);
// And insert new gradient stop at the same index 1.
gradientStops.Insert(1, new GradientStop(Color.Chocolate, 0.75, 0.3));
 
// Print properties:
Console.WriteLine("There are {0} gradient stops in the fill:", gradientStops.Count);
foreach (GradientStop stop in gradientStops)
{
    Console.WriteLine("Color: {0}, Position: {1}, Transparency: {2}", stop.Color, stop.Position, stop.Transparency);
}
 
builder.Document.Save("GradientStops.docx");
 
// The code produces the following output:
//
//There are 3 gradient stops in the fill:
//Color: Color [A=255, R=0, G=255, B=255], Position: 0.1, Transparency: 0.25
//Color: Color [A=255, R=210, G=105, B=30], Position: 0.75, Transparency: 0.3
//Color: Color [A=255, R=165, G=42, B=42], Position: 0.5, Transparency: 0

Added new public property Fill.TextureAlignment

Related issue: WORDSNET-22445

A new Fill.TextureAlignment public property has been added:

/// <summary>
/// Gets or sets the alignment for tile texture fill.
/// </summary>
public TextureAlignment TextureAlignment { get; set; }

A new public enum has been introduced:

/// <summary>
/// Specifies the alignment for the tiling of the texture fill.
/// </summary>
public enum TextureAlignment

Use Case: Explains how to get and apply a TextureAlignment for the tiling of the texture fill.

// Open some document with a textured shape.
Document doc = new Document("TexturedShape.docx");
  
// Get Fill object for the textured shape.
Fill fill = doc.FirstSection.Body.Shapes[0].Fill;
  
// Check Fill TextureAlignment value.
Console.WriteLine("TextureAlignment value is: {0}", fill.TextureAlignment);
  
// Apply TopRight texture alignment to the shape fill.
fill.TextureAlignment = TextureAlignment.TopRight;
  
doc.Save("TexturedShape_TopRight.docx");

A new public property StructuredDocumentTag.Appearance has been published

Related issue: WORDSNET-22651

A new public property StructuredDocumentTag.Appearance has been published:

/// <summary>
/// Gets/sets the appearance of a structured document tag.
/// </summary>
public SdtAppearance Appearance{ get; set; }

A new public enum has been introduced:

/// <summary>
/// Specifies the appearance of a structured document tag.
/// </summary>
public enum SdtAppearance

Use Case: Explains how to work with an Appearance of a StructuredDocumentTag.

// Get structured document tag object.
StructuredDocumentTag sdt = document.GetChild(NodeType.StructuredDocumentTag, 0, true) as StructuredDocumentTag;
 
// Check Appearance value.
Console.WriteLine("Appearance value is: {0}", sdt.Appearance);
 
// Apply SdtAppearance.Hidden appearance to the structured document tag object.
sdt.Appearance = SdtAppearance.Hidden;
 
doc.Save("output.docx");

Added new property HtmlLoadOptions.ConvertSvgToEmf

Related issue: WORDSNET-18910

The new option HtmlLoadOptions.ConvertSvgToEmf allows to turn back the legacy behavior where all SVG images loaded from a HTML document were converted to EMF. Now SVG images are loaded without conversion if the MS Word version specified in load options supports SVG images natively.

Use Case:

LoadOptions lo = new HtmlLoadOptions() {ConvertSvgToEmf = true};
Document doc = new Document("html_file_with_svg_images.html", lo);

Added new option to ignore footnotes during find-replace operation

Related issue: WORDSNET-22371

New option allows to ignore footnote during find/replace operations.

Use Case: Explains how to ignore footnote during find/replace operations.

Document doc = new Document("document with footnotes");
 
FindReplaceOptions options = new FindReplaceOptions() { IgnoreFootnotes = true };
doc.Range.Replace("Hello World", "other", options);

Added new property LoadOptions.FlatOpcXmlMappingOnly

Related issue: WORDSNET-22608

New option allows to map structured document tag to documents which have other than FlatOpc document format.

In general customer need to set both LoadOptions.FlatOpcXmlMappingOnly and SaveOptions.FlatOpcXmlMappingOnly to allow this non-standard kind of mapping.

Use Case:

LoadOptions lo = new LoadOptions() {FlatOpcXmlMappingOnly = false};
Document doc = new Document("input_file_name", lo);
 
SaveOptions so = SaveOptions.CreateSaveOptions(SaveFormat.Pdf);
so.FlatOpcXmlMappingOnly = false;
 
doc.Save("output_file_name", so);