Aspose.Words for Java 21.11 Release Notes

Major Features

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

  • Implemented a ProgressCallback to be able to show the document loading progress.
  • New UseAttachments option has been implemented to display the attachments panel in the output PDF documents.
  • Added a new ChmLoadOptions to get more control over CHM loading.
  • Added new option to ignore field codes during find-replace operation.
  • Added ability to save images as Base64 string to Markdown format.

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

KeySummaryCategory
WORDSNET-16733Add feature to get the gradient fill properties of a shapeNew Feature
WORDSNET-22707Add an ability to use type members of DataRow etc. classes at LINQ Reporting Engine templatesNew Feature
WORDSNET-20073Block level SDT not converting to Editable AcroForm field in PDFNew Feature
WORDSJAVA-2601DOCX->HTML->DOCX roundtrip: table padding changes in the outputBug
WORDSJAVA-2616java.lang.UnsatisfiedLinkError is thrown while saving DOCX to PDF at MAC.Bug
WORDSJAVA-2591Aspose.Words used as shared library in WebSphere throws exceptionBug
WORDSNET-19183Chart’s starting ending points are not correct in PDFBug
WORDSNET-22829getPageCount() returns incorrect page numbersBug
WORDSNET-22783Content converge and cause overlapping in PDFBug
WORDSNET-22573Shape’s contents are lost after DOCX to PDF ConversionBug
WORDSNET-22848Text bold formatting is lost after DOCX to PDFBug
WORDSNET-19181X-Axis numbering in Chart missing in PDFBug
WORDSNET-22050Allow row to break across pages is checked after DOC>HTML>DOCBug
WORDSNET-22044HTML to Word DOCX visibility of Hidden Numbered and Bullet ListsBug

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

KeySummaryCategory
WORDSNET-22787Introduce ExportImagesAsBase64 option for MD formatNew Feature
WORDSNET-22897Check Aspose.Words for .NET Standard works with .NET 6.0New Feature
WORDSNET-14472Consider adding a Callback event that notifies the progress of loading documentNew Feature
WORDSNET-8696Add new property of PdfSaveOptions to export SDT controls as editable PDF form fieldsNew Feature
WORDSNET-22513Support “ms-its” and other local URLs during import CHM from a streamNew Feature
WORDSNET-22794Implement MS Word scaling algorithm for non-native Ink objects when renderingNew Feature
WORDSNET-22803Provide full support of ReportingEngine.UseReflectionOptimization for .NET StandardNew Feature
WORDSNET-11453Add feature to view/hide navigation panes of PDFNew Feature
WORDSNET-9945Support native gradients with transparency in PDFNew Feature
WORDSNET-14850Export drop-down list content controls as ‘select’ HTML elementsNew Feature
WORDSNET-17181Block level SDT not converting to Editable AcroFrom fieldNew Feature
WORDSNET-14510SDT controls are not editable in the produced PDFNew Feature
WORDSNET-18648Text gradient supportNew Feature
WORDSNET-1697Add possibility to use complex Fill Effects for shapes (gradient, texture etc)New Feature
WORDSNET-21698Convert Word Content Controls to Editable Controls in PDFEnhancement
WORDSNET-14318Provide option to export SDT checkboxes as input in HTMLEnhancement
WORDSNET-8920SDT controls placed outside paragraph level are not preserved when converting to PDFEnhancement
WORDSNET-11542Provide ExportDropDownFormFieldAsText property for StructuredDocumentTagEnhancement
WORDSNET-16057PDF with gradient fill print Issue with ChromeEnhancement
WORDSNET-22457Arabic words not rendering as expectedBug
WORDSNET-22133Incorrect version of harfbuzz.dll is selected when running app with .NET CLIBug
WORDSNET-19158OfficeMath renders incorrectly in output EMFBug
WORDSNET-22750System.ArgumentException Illegal characters in path MHTML to HTML conversionBug
WORDSNET-22777Import of mhtml differs from what is in browserBug
WORDSNET-22821Space around the barcode is increased after conversion DOC to PDFBug
WORDSNET-22742System.OverflowException occurs upon loading a XMLBug
WORDSNET-22683‘Culture not supported’ exception is thrown while saving document to PDFBug
WORDSNET-22540Data labels in the chart messed up when converting to PDFBug
WORDSNET-19157Arrows in OfficeMath equation are rendered incorrectly in output EMFBug
WORDSNET-22757Shapes do not render correctly after DOCX to PDF conversionBug
WORDSNET-22844Incorrect font substitution for East Asian characters in MathTextElementBug
WORDSNET-22348Extra text is exported after DOCX to HTML conversionBug
WORDSNET-22367Latent Style Information Lost during re-SavingBug
WORDSNET-22828Extracting Html of a paragraph throws errorsBug
WORDSNET-22765Doc to Pdf Conversion with HarfBuzz causes ArithmeticOverflowExceptionBug
WORDSNET-22759Content misplacement issue upon converting DOCX to PDFBug
WORDSNET-19731Incorrect calculation of the X-axis maximum when converting chart to PDFBug
WORDSNET-18805Incorrect scaling of the secondary vertical axis after converting to PDFBug
WORDSNET-22834Page break at bookmark position does not workBug
WORDSNET-22686In Range.Replace how to ignore cross referencesBug
WORDSNET-22772Extra vertical spacing added in PDFBug
WORDSNET-20917Page numbering incorrect when Cover page present in documentBug
WORDSNET-22847Fix SonarQube issuesBug
WORDSNET-21782Bottom and Right border is lost after converting Shape to ImageBug
WORDSNET-22633HTML is loaded as plain textBug
WORDSNET-22814Range.Replace does not replace the numbers when Number ends with line, section and page breakBug
WORDSNET-22517NullReferenceException when exporting to HTMLBug
WORDSNET-22817Convert the SvgReader output APS geometry into EMUs for further rendering in DML codeBug
WORDSNET-17043PDF generated by Aspose.Words is blank when it is printed by Acrobat Reader DCBug
WORDSNET-17045PDF with gradient fill print Issue with ChromeBug
WORDSNET-9273Conversion of DOCX to DOC and PDF file format change the NUMPAGES valueBug
WORDSNET-22840Missing the image which size is huge in PDF after convert word to PDFBug
WORDSNET-22837Loading encrypted word File Corrupted ExceptionBug

Public API and Backward Incompatible Changes

This section lists public API changes that were introduced in Aspose.Words 21.11. 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 “UseAttachments” Mode for PDF Rendering

Related issue: WORDSNET-11453

An option has been implemented that allows to display the attachments panel in rendered PDF documents when opened in supporting readers.

The option is specified by setting PdfSaveOptions.PageMode to newly created PdfPageMode.UseAttachments value.

public enum PdfPageMode
{
    /// <summary>
    /// Attachments panel is visible.
    /// </summary>
    /// <remarks>
    /// Not supported in the following PDF versions: <see cref="PdfCompliance.Pdf15"/>,
    /// <see cref="PdfCompliance.PdfA1a"/>, <see cref="PdfCompliance.PdfA1b"/>.
    /// </remarks>
    UseAttachments
}

Use Case:

Document doc = new Document("input.docx");
 
// Specify the new page mode for PDF.
PdfSaveOptions options = new PdfSaveOptions();
options.PageMode = PdfPageMode.UseAttachments;
 
doc.Save("output.pdf", options);

Added a new ChmLoadOptions class

Related issue: WORDSNET-22513

Currently, this public class contains a single public property OriginalFileName. This property allows to specify the name of the CHM file. It is useful if a document is loaded from a stream and it contains links that reference the same document by the file name.

/// <summary>
/// Allows to specify additional options when loading CHM document into a <see cref="Document"/> object.
/// </summary>
public class ChmLoadOptions
{
    /// <summary>
    /// The name of the CHM file.
    /// Default value is <c>null</c>.
    /// </summary>
    /// <remarks>
    /// <para>
    /// CHM documents may contain links that reference the same document by file name. Aspose.Words supports such links
    /// and normally uses <see cref="Document.OriginalFileName"/> to check whether the file referenced by a link
    /// is the file that is being loaded. If a document is loaded from a stream, its original file name should be specified
    /// explicitly via this property, since it cannot be determined automatically.
    /// </para>
    /// <para>
    /// If a CHM document is loaded from a file and a non-null value for this property is specified, the value will take
    /// priority over the actual name of the file stored in <see cref="Document.OriginalFileName"/>.
    /// </para>
    /// </remarks>
    public string OriginalFileName { get; set; }
}

Use Case:

// The input document name.
string fileName= "myfile.chm";
 
// Create an input stream of the input document.
Stream inputStream = new MemoryStream(File.ReadAllBytes(fileName));
 
// Specify the file name in CHM load options.
// This allows Aspose.Words to correctly resolve URLs like "ms-its:myfile.chm::/index.htm"
ChmLoadOptions loadOptions = new ChmLoadOptions();
loadOptions.OriginalFileName = fileName;
 
// Load the document.
Document doc = new Document(inputStream , loadOptions);

Added a new FindReplaceOptions.IgnoreFieldCodes property

Related issue: WORDSNET-22686.

The following public property is added to FindReplaceOptions class:

/// <summary>
/// Gets or sets a boolean value indicating either to ignore text inside field codes.
/// The default value is <c>false</c>.
/// </summary>
/// <remarks>
/// <para>This option affects only field codes (it does not ignore nodes between
/// <see cref="NodeType.FieldSeparator"/> and <see cref="NodeType.FieldEnd"/>).</para>
/// <para>To ignore whole field, please use corresponding option <see cref="IgnoreFields"/>.</para>
/// </remarks>
public bool IgnoreFieldCodes

Use Case: Explains how to ignore text inside field codes.

// Create document.
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
 
// Insert field.
builder.InsertField("INCLUDETEXT", "Text in field");
 
Regex regex = new Regex("T");
FindReplaceOptions options = new FindReplaceOptions();
 
// Replace 'T' in document ignoring text inside field code.
options.IgnoreFieldCodes = true;
doc.Range.Replace(regex, "*", options);
Console.WriteLine(doc.GetText());
 
// Replace 'T' in document NOT ignoring text inside field code.
options.IgnoreFieldCodes = false;
doc.Range.Replace(regex, "*", options);
Console.WriteLine(doc.GetText());
 
// The code produces the following output:
// \u0013INCLUDETEXT\u0014*ext in field\u0015\u000c
// \u0013INCLUDE * EX * \u0014 * ext in field\u0015\u000c

Added LoadOptions.ProgressCallback property

Related issue: WORDSNET-14472.

The following public property is added to the LoadOptions class:

/// <summary>
/// Called during loading a document and accepts data about loading progress.
/// </summary>
/// <remarks>
/// <para><see cref="LoadFormat.Docx"/>, <see cref="LoadFormat.FlatOpc"/>, <see cref="LoadFormat.Docm"/>, <see cref="LoadFormat.Dotm"/>, <see cref="LoadFormat.Dotx"/> formats supported.</para>
/// </remarks>
public IDocumentLoadingCallback ProgressCallback { get; set;}

Supported formats are: Docx, FlatOpc, Docm, Dotm, Dotx.

Consumer should implement the following interface and set instance of it to the ProgressCallback to get loading progress notifications.

/// <summary>
/// Implement this interface if you want to have your own custom method called during loading a document.
/// </summary>
public interface IDocumentLoadingCallback
{
    /// <summary>
    /// This is called to notify of document loading progress.
    /// </summary>
    /// <param name="args">An argument of the event.</param>
    /// <remarks>
    /// The primary uses for this interface is to allow application code to obtain progress status and abort loading process.<para/>
    /// An exception should be threw from the progress callback for abortion and it should be caught in the consumer code.<para/>
    /// </remarks>
    /// <seealso cref="LoadOptions.ProgressCallback"/>
    void Notify(DocumentLoadingArgs args);
}

Structure of the accepted arguments is:

/// <summary>
/// An argument passed into <see cref="IDocumentLoadingCallback.Notify(DocumentLoadingArgs)"/>.
/// </summary>
public sealed class DocumentLoadingArgs
{
    /// <summary>
    /// Overall estimated percentage progress.
    /// </summary>
    public double EstimatedProgress { get; }
}

Use case:

/// <summary>
/// Loading progress callback. Cancel a document loading after the "MaxDuration" seconds.
/// </summary>
public class LoadingProgressCallback : IDocumentLoadingCallback
{
    /// <summary>
    /// Ctr.
    /// </summary>
    public LoadingProgressCallback()
    {
        mLoadingStartedAt = DateTime.Now;
    }
 
    /// <summary>
    /// Callback method which called during document loading.
    /// </summary>
    /// <param name="args">Loading arguments.</param>
    public void Notify(DocumentLoadingArgs args)
    {
        DateTime canceledAt = DateTime.Now;
        double ellapsedSeconds = (canceledAt - mLoadingStartedAt).TotalSeconds;
 
        if (ellapsedSeconds > MaxDuration)
            throw new OperationCanceledException($"EstimatedProgress = {args.EstimatedProgress}; CanceledAt = {canceledAt}");
    }
 
    /// <summary>
    /// Date and time when document loading is started.
    /// </summary>
    private readonly DateTime mLoadingStartedAt;
 
    /// <summary>
    /// Maximum allowed duration in sec.
    /// </summary>
    private const double MaxDuration = 100d;
}

Loading document code:

LoadingProgressCallback cb = new LoadingProgressCallback();
 
LoadOptions lo = new LoadOptions();
lo.ProgressCallback = cb;
 
try
{
    Document doc = new Document("bigDoc.docx", lo);
    // Do work.
}
catch (OperationCanceledException ex)
{
    Console.WriteLine(ex.Message);
    // Handle loading duration issue.
}

Added new ExportImagesAsBase64 public option

Related issue: WORDSNET-22787

A new ExportImagesAsBase64 public option has been added in MarkdownSaveOptions class:

/// <summary>
/// Specifies whether images are saved in Base64 format to the output file.
/// Default is <c>false</c>.
/// </summary>
/// <remarks>
/// <para>When this property is set to <c>true</c> images data are exported
/// directly into the <b>img</b> elements and separate files are not created.</para>
/// </remarks>
public bool ExportImagesAsBase64

Use case: Explains how to save Base64 encoded images directly inside a Markdown document.

Document doc = new Document("DocumentWithShape.docx");
 
MarkdownSaveOptions mso = new MarkdownSaveOptions();
mso.ExportImagesAsBase64 = true;
 
doc.Save("DocumentWithShape.md", mso);

Related issue: WORDSNET-22367

New style identifiers for Mention, Smart Hyperlink, Hashtag and Unresolved Mention have been added.

/// <summary>
/// The Mention style.
/// </summary>
Mention = 372,
 
/// <summary>
/// The SmartHyperlink style.
/// </summary>
SmartHyperlink = 373,
 
/// <summary>
/// The Hashtag style.
/// </summary>
Hashtag = 374,
 
/// <summary>
/// The UnresolvedMention style.
/// </summary>
UnresolvedMention = 375
The styles are undocumented, they do not have their own constants in Micosoft VBA and they are not displayed in MS Word Style Sheet. The styles are added to preserve the document structure invariability, in particular to preserve latent styles when converting Docx to Docx using Aspose.Words.