Browse our Products

Aspose.Words for Java 23.6 Release Notes

Major Features

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

  • Implemented an ability to save documents as XLSX.
  • Added support of Advanced Typography in WMF, EMF and EMF+ rendering.
  • Added public property (PageInfo.Colored) indicating whether the page is in color or not.
  • Added a new way of dynamic HTML insertion for LINQ Reporting Engine.
  • Implemented ability to set fill, stroke and callout formatting for chart data labels.
  • Added a new LowCode methods intended to merge a variety of different types of documents into a single output document.

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 23.6. 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 ability to remove digital signatures from OTT

Related issue: WORDSNET-25411

Implemented removing digital signatures from OTT using Aspose.Words.DigitalSignatures.DigitalSignatureUtil.RemoveAllSignatures method.

DigitalSignatureUtil.RemoveAllSignatures("in.ott", "out.ott");

Added a new warning during reading FB2 format

Related issue:WORDSNET-25072

The corresponding warning will be added during reading a FB2 book.

The original file load format is FB2, which is not supported by Aspose.Words. The file is loaded as an XML document.

Added a new way of dynamic HTML insertion for LINQ Reporting Engine

Related issue: WORDSNET-25117

Starting from Aspose.Words 23.6, you can use the HTML tag to insert HTML dynamically to your documents using LINQ Reporting Engine. This new way of HTML insertion provides more options to control formatting of an HTML block being inserted.

By default, HTML content is formatted by deriving styles of a template document. Template syntax for this is as follows.

<<html [html_text_expression]>>
However, you can keep source HTML formatting for content being inserted (to make it look like in a browser) by using the sourceStyles switch as follows.
<<html [html_text_expression] -sourceStyles>>

Added a property indicating whether the page is in color or not

Related issue: WORDSNET-25272

Implemented a new PageInfo.Colored property indicating whether the page is in color or not.

/// <summary>
/// Returns <c>true</c> if the page contains colored content.
/// </summary>
public bool Colored
Document doc = new Document("in.docx");

// Check that the first page of the document is not colored.
Assert.IsFalse(doc.GetPageInfo(0).Colored);

Evaluating this property causes internal rendering of the document, which can affect performance. Although, if further rendering of the document is supposed, then the necessary values are most likely already in the cache.

Added new public property LayoutOptions.KeepOriginalFontMetrics

Related issue: WORDSNET-24945

We have changed the default behavior of Aspose.Words during font substitution to copy the behavior introduced in Microsoft Word 2019. Previously, the metrics of the original font were used in some cases. Now the metrics of the substitution font is used in all cases by default.

The KeepOriginalFontMetrics property has been added to the LayoutOptions class:

/// <summary>
/// Gets or sets an indication of whether the original font metrics should be used after font substitution.
/// Default is <c>true</c>.
/// </summary>
public bool KeepOriginalFontMetrics { get; set; }
Document doc = new Document("in.docx");
doc.LayoutOptions.KeepOriginalFontMetrics = true;
doc.Save("out.pdf");

Implemented ability to save documents as XLSX

Related issue: WORDSNET-25353

The following changes have been made to the API:

A new class XlsxSaveOptions has been implemented. A new item Xlsx has been added to the SaveFormat enum type. A new item Xlsx has been added to the WarningSource enum type.

namespace Aspose.Words.Saving
{
    /// <summary>
    /// Can be used to specify additional options when saving a document into the <see cref="Words.SaveFormat.Xlsx"/>
    /// format.
    /// To learn more, visit the <a href="https://docs.aspose.com/words/net/specify-save-options/">Specify
    /// Save Options</a> documentation article.
    /// </summary>
    public class XlsxSaveOptions : SaveOptions
    {
        /// <summary>
        /// Specifies the format in which the document will be saved if this save options object is used.
        /// Can only be <see cref="Words.SaveFormat.Xlsx"/>.
        /// </summary>
        public override SaveFormat SaveFormat { get; set; }

        /// <summary>
        /// Specifies the compression level used to save document.
        /// The default value is <see cref="Saving.CompressionLevel.Normal"/>.
        /// </summary>
        public CompressionLevel CompressionLevel { get; set; }
    }
}

namespace Aspose.Words
{
    public enum SaveFormat
    {
        ...
        /// <summary>
        /// Saves the document as an Office Open XML SpreadsheetML Document (macro-free).
        /// </summary>
        Xlsx = 80,
        ...
    }

    public enum WarningSource
    {
        ...
        /// <summary>
        /// Module that writes XLSX files.
        /// </summary>
        Xlsx
    }
}

Document doc = new Document("input.docx");
doc.Save("output.xlsx");

Implemented ability to set fill, stroke and callout formatting for chart data labels

Related issue: WORDSNET-23584

The Format properties of the ChartFormat type have been added to the ChartDataLabel and ChartDataLabelCollection classes.

public class ChartDataLabel
{
    ...
    /// <summary>
    /// Provides access to fill and line formatting of the data label.
    /// </summary>
    public ChartFormat Format { get; }
}

public class ChartDataLabelCollection : IEnumerable<ChartDataLabel>
{
    ...
    /// <summary>
    /// Provides access to fill and line formatting of the data labels.
    /// </summary>
    public ChartFormat Format { get; }
}

The new enum type ChartShapeType has been implemented and the ShapeType property of this type has been added to the ChartFormat class.

/// <summary>
/// Specifies the shape type of chart elements.
/// </summary>
public enum ChartShapeType
{
    /// <summary>
    /// Indicates that a shape is not defined for the chart element.
    /// </summary>
    Default,

    /// <summary>
    /// Rectangle.
    /// </summary>
    Rectangle,
    ...
}

public class ChartFormat
{
    ...
    /// <summary>
    /// Gets or sets the shape type of the parent chart element.
    /// </summary>
    /// <remarks>
    /// Currently, the property can only be used for data labels.
    /// </remarks>
    public ChartShapeType ShapeType { get; set; }
}
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Shape shape = builder.InsertChart(ChartType.Column, 432, 252);
Chart chart = shape.Chart;

// Delete default generated series.
chart.Series.Clear();

// Add new series.
ChartSeries series = chart.Series.Add("AW Series 1",
    new string[] { "AW Category 1", "AW Category 2", "AW Category 3", "AW Category 4" },
    new double[] { 100, 200, 300, 400 });

// Show data labels.
series.HasDataLabels = true;
series.DataLabels.ShowValue = true;

// Format data labels as callouts.
ChartFormat format = series.DataLabels.Format;
format.Stroke.Color = Color.Gray;
format.ShapeType = ChartShapeType.WedgeRectCallout;

doc.Save(dir + "Callouts.docx");
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Shape shape = builder.InsertChart(ChartType.Column, 432, 252);
Chart chart = shape.Chart;

// Delete default generated series.
chart.Series.Clear();

// Add new series.
ChartSeries series = chart.Series.Add("AW Series 1",
    new string[] { "AW Category 1", "AW Category 2", "AW Category 3", "AW Category 4" },
    new double[] { 100, 200, 300, 400 });

// Show data labels.
series.HasDataLabels = true;
series.DataLabels.ShowValue = true;

// Set fill and stroke for all data labels.
ChartFormat format = series.DataLabels.Format;
format.Stroke.Color = Color.DarkGreen;
format.Fill.Solid(Color.Green);
series.DataLabels.Font.Color = Color.Yellow;

// Change fill and stroke of an individual data label.
ChartFormat labelFormat = series.DataLabels[0].Format;
labelFormat.Stroke.Color = Color.DarkBlue;
labelFormat.Fill.Solid(Color.Blue);

doc.Save("FillAndStroke.docx");

Supported table-column data bands and conditional blocks for LINQ Reporting Engine

Related issue: WORDSNET-18034

The following sections of the engine’s documentation were added or updated to describe the change (see attachments):

Starting from this version, LINQ Reporting Engine supports table-column data bands and conditional blocks making it possible to affect table columns in addition to table rows while filling a table template with data. This enables you to build tables growing horizontally or even in the both directions - vertically and horizontally - depending on bound data. Also, showing or hiding a table column depending on a condition becomes available in this release as well.

Removed obsolete property Fill.On

Related issue: WORDSNET-21898

The following obsolete public property is removed from Aspose.Words.Drawing.Fill class:

/// <summary>
/// Gets or sets value that is <c>true</c> if the formatting applied to this instance, is visible.
/// </summary>
[Obsolete("This property is obsolete. Please, use Visible property instead.")]
public bool On {get; set;}

We also decided to leave obsolete property Fill.Color along with a new Fill.ForeColor, as these two methods have slightly different behavior in regarding transparency:

/// <summary>
/// Gets or sets a Color object that represents the foreground color for the fill.
/// </summary>
/// <remarks> This property preserves the alpha component of the <see cref="System.Drawing.Color"/>,
/// unlike the <see cref="ForeColor"/> property, which resets it to fully opaque color.</remarks>
public Color Color {get; set;}
/// <summary>
/// Gets or sets a Color object that represents the foreground color for the fill.
/// </summary>
/// <remarks> This property resets the alpha component of the <see cref="System.Drawing.Color"/> to fully
/// opaque color unlike the <see cref="Color"/> property, which preserves it.</remarks>
public Color ForeColor {get; set;}

DocumentBuilder builder = new DocumentBuilder();

Shape shape = builder.InsertShape(ShapeType.Balloon, 300, 300);
// Set Color with transparency.
shape.Fill.Color = Color.FromArgb(128, Color.Red);

// Fill.Color preserves alpha component of the Color.
Console.WriteLine("Fill.Color: {0}", shape.Fill.Color);

// Fill.ForeColor ignores alpha component of the Color.
Console.WriteLine("Fill.ForeColor: {0}", shape.Fill.ForeColor);

// Use Fill.Visible instead of obfuscated Fill.On property to determine fill visibility.
Console.WriteLine("Fill.Visible: {0}", shape.Fill.Visible);

// Make fill invisible.
shape.Fill.Visible = false;
Console.WriteLine("Fill.Visible: {0}", shape.Fill.Visible);

/* This code produces the following output:
Fill.Color: Color [A=128, R=255, G=0, B=0]
Fill.ForeColor: Color [A=255, R=255, G=0, B=0]
Fill.Visible: True
Fill.Visible: False
 */

Added a new LowCode methods intended to merge a variety of different types of documents into a single output document

Added a new LowCode.Merger class, which represents a group of methods intended to merge a variety of different types of documents into a single output document.

The following overloads were provided:

/// <summary>
/// Merges the given input documents into a single output document using specified input and output file names.
/// </summary>
/// <param name="outputFile">The output file name.</param>
/// <param name="inputFiles">The input file names.</param>
/// <remarks>
/// <p>By default <see cref="MergeFormatMode.KeepSourceFormatting"/> is used.</p>
/// </remarks>
public static void Merge(string outputFile, string[] inputFiles)

/// <summary>
/// Merges the given input documents into a single output document using specified input output file names and the final document format.
/// </summary>
/// <param name="outputFile">The output file name.</param>
/// <param name="inputFiles">The input file names.</param>
/// <param name="saveFormat">The save format.</param>
/// <param name="mergeFormatMode">Specifies how to merge formatting that clashes.</param>
public static void Merge(string outputFile, string[] inputFiles, SaveFormat saveFormat, MergeFormatMode mergeFormatMode)

/// <summary>
/// Merges the given input documents into a single output document using specified input output file names and save options.
/// </summary>
/// <param name="outputFile">The output file name.</param>
/// <param name="inputFiles">The input file names.</param>
/// <param name="saveOptions">The save options.</param>
/// <param name="mergeFormatMode">Specifies how to merge formatting that clashes.</param>
public static void Merge(string outputFile, string[] inputFiles, SaveOptions saveOptions, MergeFormatMode mergeFormatMode)

/// <summary>
/// Merges the given input documents into a single document and returns <see cref="Document"/> instance of the final document.
/// </summary>
/// <param name="inputFiles">The input file names.</param>
/// <param name="mergeFormatMode">Specifies how to merge formatting that clashes.</param>
public static Document Merge(string[] inputFiles, MergeFormatMode mergeFormatMode)

/// <summary>
/// Merges the given input documents into a single output document using specified input output streams and the final document format.
/// </summary>
/// <param name="outputStream">The output stream.</param>
/// <param name="inputStreams">The input streams.</param>
/// <param name="saveFormat">The save format.</param>
public static void Merge(Stream outputStream, Stream[] inputStreams, SaveFormat saveFormat)

/// <summary>
/// Merges the given input documents into a single output document using specified input output streams and save options.
/// </summary>
/// <param name="outputStream">The output stream.</param>
/// <param name="inputStreams">The input streams.</param>
/// <param name="saveOptions">The save options.</param>
/// <param name="mergeFormatMode">Specifies how to merge formatting that clashes.</param>
public static void Merge(Stream outputStream, Stream[] inputStreams, SaveOptions saveOptions, MergeFormatMode mergeFormatMode)

/// <summary>
/// Merges the given input documents into a single document and returns <see cref="Document"/> instance of the final document.
/// </summary>
/// <param name="inputStreams">The input streams.</param>
/// <param name="mergeFormatMode">Specifies how to merge formatting that clashes.</param>
public static Document Merge(Stream[] inputStreams, MergeFormatMode mergeFormatMode)

Added a new MergeFormatMode enum, which specifies how formatting is merged when combining multiple documents.

 /// <summary>
/// Specifies how formatting is merged when combining multiple documents.
/// </summary>
public enum MergeFormatMode
{
    /// <summary>
    /// Combine the formatting of the merged documents.
    /// </summary>
    /// <remarks>
    /// <p>By using this option, Aspose.Words adapts the formatting of the first document to match the structure and
    /// appearance of the second document, but keeps some of the original formatting intact.
    /// This option is useful when you want to maintain the overall look and feel of the destination document
    /// but still retain certain formatting aspects from the original document.</p>
    ///
    /// <p>This option does not have any affect when the input and the output formats are PDF.</p>
    /// </remarks>
    MergeFormatting,

    /// <summary>
    /// Means that the source document will retain its original formatting,
    /// such as font styles, sizes, colors, indents, and any other formatting elements applied to its content.
    /// </summary>
    /// <remarks>
    /// <p>By using this option, you ensure that the copied content appears as it did in the original source,
    /// regardless of the formatting settings of the first document in merge queue.</p>
    ///
    /// <p>This option does not have any affect when the input and the output formats are PDF.</p>
    /// </remarks>
    KeepSourceFormatting,

    /// <summary>
    /// Preserve the layout of the original documents in the final document.
    /// </summary>
    /// <remarks>
    /// <p>In general, it looks like you print out the original documents and manually adhere them together using glue.</p>
    /// </remarks>
    KeepSourceLayout
}
// Merges multiple documents (DOCX, PDF, DOC, RTF) into a single PDF document.
Merger.Merge("out.pdf", new string[] { "in.docx", "in.pdf", "in.doc", "in.rtf" });