Aspose.Words for Java 22.11 Release Notes

Major Features

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

  • Update API references for Java
  • Implemented custom colored/grayscale printing mode.
  • Added an ability to create the new structured document tags of Citation type.
  • Implemented field updating progress tracking.
  • Introduced the new property which allows to embed OLE attachments from the source document to the output PDF document.
  • Changed default behavior when opening document of unknown format.

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

WORDSJAVA-1768Create JavaDoc for Ref classNew Feature
WORDSJAVA-2787Update Bouncy Castle libraryNew Feature
WORDSJAVA-2759Update API references for Java (markdown Hugo based)New Feature
WORDSNET-23141Support Nullable values at LINQ Reporting Engine tags where not Nullable values are expectedNew Feature
WORDSNET-20906Document Compare method incorrectly Deletes and then Inserts same ParagraphBug
WORDSNET-18031Document.Compare generates incorrect revisionsBug
WORDSNET-17310Incorrect Revision for a List Paragraph when ComparingBug
WORDSNET-18036Document.Compare generates incorrect revisionsBug
WORDSNET-24516NullReferenceException is thrown when check watermark type in the document without header/footerBug
WORDSNET-24514FileCorruptedException is thrown upon loading DOCX documentBug
WORDSNET-24423DOCX to PDF: Placeholders in formula not rendered correctlyBug
WORDSNET-22563Document.Compare issue with document commentsBug
WORDSNET-24396Font size is incorrect after rendering the documentBug
WORDSNET-24483InvalidCastException is thrown upon comparing documentBug
WORDSNET-24444List list labels are incorrect after rendering documentBug
WORDSNET-24372IF field is updated improperly when REF field is usedBug
WORDSNET-24370Aspose.Words hangs upon rendering documentBug
WORDSNET-24429Span tags created for the blank lines when ExportLanguageToSpanTag is setBug
WORDSNET-17087Make embedded objects in PDF clickableBug
WORDSNET-23263Custom style does not apply after HTML to DOCX conversionBug

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

WORDSNET-24261Consider providing a way to get number of pages printed in colorNew Feature
WORDSNET-23333Provide an ability to track field updating progressNew Feature
WORDSNET-23496Import the borders and the margins of block-level HTML elements during loading alt chunksNew Feature
WORDSNET-23491Consider providing an ability to specify condition name in LINQ reporting syntaxNew Feature
WORDSNET-23489Support tag headers to match opening and closing tags for LINQ Reporting EngineNew Feature
WORDSNET-24350Add a switch to trim the last paragraph break when inserting a document using LINQ Reporting EngineNew Feature
WORDSNET-24421Use information from the OpenType OS/2 table for precise subscript and superscript font sizesNew Feature
WORDSNET-14001Add feature to export OLE as attachment in PDFNew Feature
WORDSNET-24395Incorrect horizontal offsets if display units are set after converting to PDFNew Feature
WORDSNET-24520Date format of SDTs is lost after renderingBug
WORDSNET-17324Document.Compare does not mimic MS Word behaviorBug
WORDSNET-17298It creates a new bullet and same change appears as both an insert and delete after CompareBug
WORDSNET-14770Document.Compare generates incorrect revision in output DOCXBug
WORDSNET-18187Comparing documents with AW gives different revisions from Word compareBug
WORDSNET-21077Wrong detections of revisions - deletion of runs in the next paragraphBug
WORDSNET-23713Cell preferred width does not match MS Word for RTF inputBug
WORDSNET-24375PDF to PDF with signing: Formatting issuesBug
WORDSNET-24266Axis title is rendered while it is invisible in MS WordBug
WORDSNET-24490DocumentBuilder.InsertField methods do not support cursor position at the end of a structured document tagBug
WORDSNET-24113TOC is not the same during DOCX->HTML->DOCX roundtripBug
WORDSNET-24399Circled digits should be rotated like ideographic characters when TextBox has vertical directionBug
WORDSNET-24311System.Exception is thrown when HarfBuzz is used with Fody packageBug
WORDSNET-24470Part of content is lost after open/save DOCX documentBug
WORDSNET-24484Calculate of the position for the below barBug
WORDSNET-24467Exception when loading docxBug
WORDSNET-24491DOCX to HTML: Link inside shapes refers to a non-existing external pageBug
WORDSNET-21894DOCX to PDF conversion issue with chart axis and labelsBug
WORDSNET-24408UnsupportedFileFormatException upon loading documentsBug
WORDSNET-24341Implement caching of background shape for PDFBug
WORDSNET-24507DrHatchBrush shifted for cached shapesBug
WORDSNET-24479Chart is not added to the OTT documentBug
WORDSNET-24176Text reflection position is incorrect after rendering to FixedHtmlBug
WORDSNET-24029FileCorruptedException is thrown upon loading HTML when BlockImportMode.Preserve is usedBug
WORDSNET-21348Document comparison issue with numberingBug
WORDSNET-20025Position of bookmark is incorrect after moving cursor to paragraph and inserting bookmarkBug
WORDSNET-17074Tab stop are exported incorrectly when converting from DOCX to HTMLBug
WORDSNET-24473Document compare throws System.InvalidOperationException: Unexpected node type exceptionBug
WORDSNET-24407Font is changed from “Calibri” to “Times New Roman” after comparing documentsBug
WORDSNET-24035Content is pushed to the next page, that lead to incorrect page countBug
WORDSNET-24471Paragraph first line indent is incorrect after renderingBug
WORDSNET-24366Date format in chart’s axis is incorrectBug
WORDSNET-24036“w14:checked” is not Sdt.CheckBox direct valueBug
WORDSNET-24418PDF to DOCX: Footer overlap on the next pageBug
WORDSNET-24367Axis labels are rendered improperlyBug
WORDSNET-22096Error in low-level  comparison algorithmBug
WORDSNET-24437Formatting of heading is broken when use ImportFormatMode.UseDestinationStyles while appending documentBug
WORDSNET-23228Imitate MS Word behavior for handling invalid table preferred width valuesBug
WORDSNET-24274Embedded PDF document is not renderedBug
WORDSNET-24353Aspose.Words hangs upon rendering documentBug
WORDSNET-20220Table’s column width is changed after conversion from HTML to DOCXBug

Public API and Backward Incompatible Changes

This section lists public API changes that were introduced in Aspose.Words 22.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 PdfSaveOptions.EmbedAttachments property

Related issue: WORDSNET-14001

The new property allows to embed OLE attachments from source document to output PDF document.

/// <summary>
/// Gets or sets a value determining whether or not to embed attachments to the PDF document.
/// </summary>
/// <remarks>
/// <para>Default value is <c>false</c> and attachments are not embedded.</para>
/// <para>When the value is <c>true</c> attachments are embedded to the PDF document.</para>
/// <para>Embedding attachments is not supported when saving to PDF/A and PDF/UA compliance.
/// <c>false</c> value will be used automatically.</para>
/// <para>Embedding attachments is not supported when encryption is enabled. <c>false</c> value
/// will be used automatically.</para>
/// </remarks>
public bool EmbedAttachments { get; set; }

Allowed creation of structured document tags of Citation type

Related issue: WORDSNET-24458

Added an ability to create the new structured document tags of SdtType.Citation type.

Use Case:

Document doc = new Document();

// Create a structured document tag of the Citation type.
StructuredDocumentTag sdt = new StructuredDocumentTag(doc, SdtType.Citation, MarkupLevel.Inline);

// Append to a paragraph.
Paragraph paragraph = doc.FirstSection.Body.FirstParagraph;

// Create a Citation field.
DocumentBuilder builder = new DocumentBuilder(doc);
builder.MoveToParagraph(0, -1);
builder.InsertField(@"CITATION Ath22 \l 1033 ", "(Author1, 2022)");

// Move the field to the structured document tag.
while (sdt.NextSibling != null)


Changed default behavior when opening document of unknown format

Related issue: WORDSNET-24408.

We changed the behavior for the case when the format of the input document cannot be identified. Previously, we always threw an exception. Now we do this only if the input document has the file name extension .docx, .odt, or .sxw. In case the format of the input document cannot be identified and has an extension other than the above-mentioned, the format will be set to .txt.

Use Case:

public static void Main(string[] args)
    string content = new string('\u0000', 20);

    File.WriteAllText("a.doc", content);

    File.WriteAllText("b.docx", content);

private static void OpenDoc(string fileName)
        Document doc = new Document(fileName);
    catch (UnsupportedFileFormatException e)
        Console.WriteLine("{0} is opened with exception", fileName);

    Console.WriteLine("{0} is opened successfully", fileName);

// The code produces the following output:
// a.doc is opened successfully
// b.docx is opened with exception

Implemented custom colored/grayscale printing mode

Related issues: WORDSNET-24285, WORDSNET-24261

A new printing property allows to control how non-colored pages are printed if the device supports color printing. This feature can be useful if you want to automatically print a non-colored pages using only grayscale printer mode.

The print mode is controlled by a new property in the AsposeWordsPrintDocument class:

/// <summary>
/// Gets or sets how non-colored pages are printed if the device supports color printing.
/// </summary>
/// <remarks>
/// Doesn't affect booklet printing.
/// </remarks>
public ColorPrintMode ColorMode { get; set; }

The print mode is specified by one of the values of the new enumeration:

/// <summary>
/// Specifies how non-colored pages are printed if the device supports color printing.
/// </summary>
public enum ColorPrintMode
    /// <summary>
    /// All pages are printed according to the printer's capabilities and settings.
    /// </summary>

    /// <summary>
    /// Non-colored pages if detected are printed in grayscale.
    /// </summary>
    /// <remarks>
    /// <see cref="PageSettings.Color"/> is automatically set false for detected non-colored pages.
    /// If the printer does not support color printing, this setting is ignored.
    /// </remarks>

The number of pages printed in color can be obtained using a new property in the AsposeWordsPrintDocument class:

/// <summary>
/// Gets the number of pages printed in color (i.e. with <see cref="PageSettings.Color"/> set to true).
/// </summary>
public int ColorPagesPrinted { get; }

Use Case:

Document document = new Document(filename);

// Select the required printer.
PrinterSettings printerSettings = new PrinterSettings();
printerSettings.PrinterName = "Microsoft Print to PDF";

// Specify the pages to print.
printerSettings.FromPage = 1;
printerSettings.ToPage = doc.PageCount;

AsposeWordsPrintDocument printDoc = new AsposeWordsPrintDocument(doc);
printDoc.PrinterSettings = printerSettings;

// Specify the new color print mode.
printDoc.ColorMode = ColorPrintMode.GrayscaleAuto;


// Return the numer of pages printed in color.
return printDoc.ColorPagesPrinted;

Implemented field updating progress tracking

Related issue: WORDSNET-23333

The following property is added to FieldOptions class:

/// <summary>
/// Gets or sets <see cref="IFieldUpdatingProgressCallback"/> implementation.
/// </summary>
public IFieldUpdatingProgressCallback FieldUpdatingProgressCallback { get; set; }

New IFieldUpdatingProgressCallback interface is introduced:

/// <summary>
/// Implement this interface if you want to track field updating progress.
/// </summary>
public interface IFieldUpdatingProgressCallback
    /// <summary>
    /// A user defined method that is called when updating progress is changed.
    /// </summary>
    void Notify(FieldUpdatingProgressArgs args);

New FieldUpdatingProgressArgs class is introduced:

/// <summary>
/// Provides data for the field updating progress event.
/// </summary>
public sealed class FieldUpdatingProgressArgs
    /// <summary>
    /// Gets the total fields count to be updated.
    /// </summary>
    /// <remarks>
    /// The value is not constant and may be increased during updating process.
    /// </remarks>
    public int TotalFieldsCount { get; }

    /// <summary>
    /// Gets the number of updated fields.
    /// </summary>
    public int UpdatedFieldsCount { get; }

    /// <summary>
    /// Gets a value indicating whether field updating is completed.
    /// </summary>
    public bool UpdateCompleted { get; }

Use Case:

Document document = new Document(filename);
document.FieldOptions.FieldUpdatingProgressCallback = new FieldUpdatingProgressCallback();;

public class FieldUpdatingProgressCallback : IFieldUpdatingProgressCallback
    void IFieldUpdatingProgressCallback.Notify(FieldUpdatingProgressArgs args)

Renamed PdfSaveOptions.CacheHeaderFooterShapes property

PdfSaveOptions.CacheHeaderFooterShapes property renamed to PdfSaveOptions.CacheBackgroundGraphics and enabled by default:

/// <summary>
/// Gets or sets a value determining whether or not to cache graphics placed in document's background.
/// </summary>
/// <remarks>
/// <para> Default value is <c>true</c> and background graphics are written to the PDF document as an xObject.</para>
/// <para> When the value is <c>false</c> background graphics are not cached.</para>
/// <para> Some shapes are not supported for caching(shapes with fields, bookmarks, HRefs).</para>
/// <para> Document background graphic is various shapes, charts, images placed in the footer or header,
/// well as background and border of a page.</para>
/// </remarks>
public bool CacheBackgroundGraphics { get; set; }

The new property allows you to cache the header/footer shapes and reduce the size of PDF output file. Use Case:

Document doc = new Document(fileName);
PdfSaveOptions saveOptions = new PdfSaveOptions();
saveOptions.CacheBackgroundGraphics = true;
doc.Save(outputFileName, saveOptions);

Supported tag headers to match opening and closing tags for LINQ Reporting Engine

Related issue: WORDSNET-23489

From now on, it is possible to use template tag headers to match opening and closing tags and make LINQ Reporting Engine indicate an error in case of a mismatch, for example, because of a wrong closing tags’ order. Template syntax for using tag headers is as follows:

<<tag_name ... #header1>><<tag_name ... #header2>>...<</tag_name #header2>><</tag_name #header1>>

Added a switch to trim the last paragraph break when inserting a document using LINQ Reporting Engine

Related issue: WORDSNET-24350

Starting from Aspose.Words 22.11, it is possible to trim the last paragraph break from a document being dynamically inserted by LINQ Reporting Engine. The template syntax for this is as follows:

<<doc [document_expression] -inline>>