Aspose.Words for C++ 22.1 Release Notes

Major Features

We have added the following features from Aspose.Words for .NET on this regular monthly release:

  • Implemented rendering into PDF with PDF/UA-1 compliance. This option assumes compliance with document special accessibility requirements.
  • Improved rendering of operators in MathML formulas.
  • Introduced a new option to control conflicting styles behavior upon import.
  • Added an ability to get saving progress notifications through the SaveOptions.ProgressCallback.

Limitations and API Differences

Aspose.Words for C++ has some differences as compared to its equivalent .NET version of the API. This section contains information about all such functionality that is not available in the current release. The missing features will be added in future releases.

  • The current release does not support Metered license.
  • The current release does not support LINQ and Reporting features.
  • The current release does not support OpenGL 3D Shapes rendering.
  • The current release does not support loading PDF documents.
  • The current release has limited support for database features - C++ doesn’t have common API for DB like .NET System.Data.
  • The current release supports Microsoft Visual C++ version 2017 or higher.
  • The current release supports GCC 6.3 or higher and Clang 3.9.1 or higher on Linux and only for the x86_x64 platform.
  • The current release supports macOS Big Sur or later (11.5+) for 64-bit Intel Mac platform.

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

WORDSNET-22882Provide dynamic text color setting using LINQ Reporting EngineNew Feature
WORDSNET-11575Add option to stop Document.Save method after specific timeNew Feature
WORDSNET-23246Provide list style in ApsNew Feature
WORDSNET-1506Add feature to set image as background of TextBoxNew Feature
WORDSNET-12792Add feature to set Fill.ImageBytesNew Feature
WORDSNET-6614Support of PdfCompliance PDF/UANew Feature
WORDSNET-19268Incorrect behavior of KeepSourceFormatting ImportFormatModeNew Feature
WORDSNET-18739Gather data about gradient fillsNew Feature
WORDSNET-16357Implement ability to replace shape background imageNew Feature
WORDSNET-22884Cross-reference not working in Docker after CustomXmlParts property is setEnhancement
WORDSNET-22692Compare document with content controlEnhancement
WORDSNET-22664Shape.OleFormat returns null when Excel chart is copied to Word using Option “Link & Keep Source Formatting”Enhancement
WORDSNET-23223Pass a hyperlink ScreenTip from model to ApsEnhancement
WORDSNET-20756DOCX to PDF conversion issue with accessibilityEnhancement
WORDSNET-23237RTF to DOCX - PUA characters treated as symbols instead of textBug
WORDSNET-22682After rendering a DML shape gets larger by 1 pixel than its original imageBug
WORDSNET-22853Image of a DML shape is shifted to the right after renderingBug
WORDSNET-22854Image of a DML shape is shifted to the top left after renderingBug
WORDSNET-23232NullReferenceException on cloningBug
WORDSNET-23269Remove obsolete property LayoutOptions.ShowCommentsBug
WORDSNET-22899Document compare is not working properlyBug
WORDSNET-23224Process hangs when calling UpdateFields methodBug
WORDSNET-23231Shape.Id is duplicated for watermarks inserted by Aspose.WordsBug
WORDSNET-23234NullReferenceException while re-saving documentBug
WORDSNET-17523How to determine maximum value for table borderBug
WORDSNET-22883Cross-reference not working after removing XML mappingBug
WORDSNET-23252Font is changed after open/save DOCXBug
WORDSNET-23211Setting mapping creates corrupted tableBug
WORDSNET-23213The end-of-cell marker has been removed from the new rowBug
WORDSNET-23180Section breaks are changed after inserting documentBug
WORDSNET-22845PDF Accessibility Checker (PAC 3) reports failures upon testing for PDF/UA compatibilityBug
WORDSNET-20766Structure element issues after DOCX to PDF conversionBug
WORDSNET-22919Word table formatting issue using Customer XML dataBug
WORDSNET-23220The paragraph is missing when using WordOpenXMLBug
WORDSNET-22660Compile Time error when using Aspose Words for .NET in C++/CLI projectBug
WORDSNET-23226Incorrect size and position of the minus signBug
WORDSNET-23229Fix minor rendering issueBug
WORDSNET-22526Unwanted styles appear during DOTX to DOCX conversionBug
WORDSNET-22939NullReferenceException while converting DOCX to PDFBug
WORDSNET-23212IndexOutOfRangeException at ColorSpaceDeviceRGB.ToRgbBug
WORDSNET-23194Saving RTF file hangs indefinitelyBug
WORDSNET-21205DOCX to PDF conversion issue with chart renderingBug
WORDSNET-22954Formatting of footnote is changed after re-saving documentBug
WORDSNET-23175IndexOutOfRangeException in PdfSyntaxParser.ParseArrayBug
WORDSNET-23187FileCorruptedException is thrown while loading documentBug
WORDSNET-23203NullReferenceException at PdfOperatorTj.ApplyBug
WORDSNET-23177NullReferenceException if page resources are missingBug
WORDSNET-22804Document.Compare throws System.InvalidCastExceptionBug
WORDSNET-23023FormatException at PdfTokenParser.EnterHexStringStateBug
WORDSNET-21416Strikethrough formatting in list indent is disappeared after DOCX to PDF conversionBug
WORDSNET-23171System.StackOverflowException is thrown while loading RTFBug
WORDSNET-22710Bad performance of “UpdatePageLayout”Bug
WORDSNET-23193InvalidCastException: Cannot cast PdfDictionary to PdfArrayBug
WORDSNET-23189FormatException at TimeSpanFormat.FormatCustomizedBug
WORDSNET-22981Image becomes hidden after open/save documentBug
WORDSNET-23151Wrong date format in chart after converting DOCX to PDFBug
WORDSNET-22618Percentage Values of a Vertical Axis of Chart are not PreservedBug
WORDSNET-22925Math Equation (Shape) does not render correctly in output PDFBug
WORDSNET-23041Wrong letters order for RTL text (Persian OCR)Bug
WORDSNET-23027NullReferenceException at SASLPrepAlgorithm.MapCharactersBug
WORDSNET-23192KeyNotFoundException in RomanNumber.TryParseBug
WORDSNET-23173The shape is changed while exporting from DOCX to PDF, DOC or RTFBug
WORDSNET-22127Heading style attributes are not appliedBug
WORDSNET-19692Formula converted incorrectly (DOCX to PDF)Bug
WORDSNET-23184Opening HTM file hangs indefinitelyBug
WORDSNET-23161DllNotFoundException occurs when use HarfBuzzTextShaperFactory in .NET 6.0Bug

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

WORDSNET-23142Support HTML color codes as color values for LINQ Reporting Engine tagsNew Feature
WORDSNET-22953Comparing documents with changes around a table cause the table to be marked as deleted and re-addedBug
WORDSNET-22436Font-size incorrectly added to paragraph tag, it should be added to span insteadBug
WORDSNET-22562Document.Compare does not ignore commentBug
WORDSNET-23215InvalidCastException is thrown upon loading documentBug
WORDSNET-22824Chart issues when converting DOCX to PDFBug
WORDSNET-22956Revision.Accept throws System.InvalidOperationExceptionBug
WORDSNET-22983Blank page is produced in output PDF where hidden content was in the original documentBug
WORDSNET-23253Exported PDF contains image with lower resolutionBug

Public API and Backward Incompatible Changes

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

The new implementation of System::Xml namespace

The new implementation for System::Xml namespace was provided. Previously, we had custom implementation which was based on the libxml2 and libxslt libraries. The new version is based on the ported CoreFX code. Some APIs may have become unavailable. Some APIs may have changed. The new API is much closer to such of .NET. Please use the API Reference for more information.

Added new Chart.SourceFullName property

Related issue: WORDSNET-22664

The following public property has been added to the Chart class. If a chart is linked to an external xls/xlsx document, the property returns its file name.

/// <summary>
/// Gets the path and name of an xls/xlsx file this chart is linked to.
/// </summary>
public string SourceFullName { get; }

Use Case:

auto doc = System::MakeObject<Document>(filename);
auto shape = System::StaticCast<Shape>(doc->GetChild(NodeType::Shape, 0, true));
std::cout << shape->get_Chart()->get_SourceFullName() << '\n';

Added new ImportFormatOptions.ForceCopyStyles property

Related issue: WORDSNET-19268.

The following public property is added to ImportFormatOptions class:

/// <summary>
/// Gets or sets a boolean value indicating either to copy conflicting styles
/// in <see cref="ImportFormatMode.KeepSourceFormatting"/> mode.
/// The default value is <c>false</c>.
/// </summary>
/// <remarks>
/// <para>By default, if a matching style already exists in a destination document, the source style formatting
/// is expanded into direct node attributes and the style of this node is reset to a default.</para>
/// <para> When this option is set to <c>true</c>, the source style will be forcibly copied
/// into destination document with unique name and applied to the imported node.</para>
/// <para> Note, in this case it is not guaranteed that formatting of the imported node in destination document
/// will be preserved. </para>
/// </remarks>
public bool ForceCopyStyles { get; set; }

Use Case: Explains how to force import styles in KeepSourceFormatting mode.

// There are MyStyle1 and MyStyle2 in both source and destination document.
// Also there is style MyStyle3 that exists only in source document.
auto srcDoc = System::MakeObject<Document>(u"Src.docx");
auto dstDoc = System::MakeObject<Document>(u"Dst.docx");

auto options = System::MakeObject<ImportFormatOptions>();

auto nodeImporter = System::MakeObject<NodeImporter>(srcDoc, dstDoc, ImportFormatMode::KeepSourceFormatting, options);

std::cout << "Imported styles:\n";
auto paras = srcDoc->get_FirstSection()->get_Body()->get_Paragraphs();
for (int i = 0; i < paras->get_Count(); i++)
    auto importedPara = System::StaticCast<Paragraph>(nodeImporter->ImportNode(paras->idx_get(i), true));
    std::cout << importedPara->get_ParagraphStyle()->get_Name();

// The code produces the following output:
// Imported styles:
// MyStyle1_0
// MyStyle2_0
// MyStyle3

Added SaveOptions.ProgressCallback property

Related issue: WORDSNET-11575

The following public property is added to SaveOptions class:

/// <summary>
/// Called during saving a document and accepts data about saving progress.
/// </summary>
/// <remarks>
/// <para><see cref="SaveFormat.Docx"/>, <see cref="SaveFormat.FlatOpc"/>, <see cref="SaveFormat.Docm"/>, <see cref="SaveFormat.Dotm"/>, <see cref="SaveFormat.Dotx"/> formats supported.</para>
/// </remarks>
public IDocumentSavingCallback ProgressCallback

Supported formats are:

  • Docx
  • FlatOpc
  • Docm
  • Dotm
  • Dotx

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

/// <summary>
/// Implement this interface if you want to have your own custom method called during saving a document.
/// </summary>
public interface IDocumentSavingCallback
     /// <summary>
     /// This is called to notify of document saving 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 saving process.<para/>
     /// An exception should be threw from the progress callback for abortion and it should be caught in the consumer code.<para/>
     /// </remarks>
     void Notify(DocumentSavingArgs args);

Structure of the accepted arguments is:

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

Use case:

/// <summary>
/// Saving progress callback. Cancel a document saving after the "MaxDuration" seconds.
/// </summary>
class SavingProgressCallback : public IDocumentSavingCallback
     /// <summary>
     /// Callback method which called during document saving.
     /// </summary>
     /// <param name="args">Saving arguments.</param>
     void Notify(System::SharedPtr<DocumentSavingArgs> args) override
         auto canceledAt = System::DateTime::get_Now();
         double ellapsedSeconds = (canceledAt - mSavingStartedAt).get_TotalSeconds();
         if (ellapsedSeconds > MaxDuration)
             throw OperationCanceledException(System::String::Format("EstimatedProgress = {}; CanceledAt = {}", args->get_EstimatedProgress(), canceledAt);

     /// <summary>
     /// Date and time when document saving is started.
     /// </summary>
     System::DateTime mSavingStartedAt = System::DateTime::get_Now();

     /// <summary>
     /// Maximum allowed duration in sec.
     /// </summary>
     static constexpr double MaxDuration = 100d;

Loading document code:

aoto cb = System::MakeObject<SavingProgressCallback>();
auto so = System::MakeObject<OoxmlSaveOptions>(SaveFormat::Docx);

   auto doc = System::MakeObject<Document>(u"bigDoc.rtf");

   // Do work.
   doc->Save(u"bigDoc.docx", so);
catch (const OperationCanceledException& ex)
    std::cout << ex.get_Message();
   // Handle saving duration issue.

Added saving to PDFUA-1

Related issue: WORDSNET-6614

New value added to PdfCompliance enum

public enum PdfCompliance
    /// <summary>
    /// The output file will comply with the PDF/UA-1 (ISO 14289-1) standard.
    /// The primary purpose of PDF/UA is to define how to represent electronic documents in the PDF format in a
    /// manner that allows the file to be accessible.
    /// </summary>

Several PdfSaveOptions are prohibited when saving to PDF/UA and they are automatically fixed. Also options which are prohibited for PDF/A formats are now automatically fixed instead of throwing exception. Also warning is issued when option is automatically fixed.

public class PdfSaveOptions
    /// <summary>
    /// Specifies whether to preserve Microsoft Word form fields as form fields in PDF or convert them to text.
    /// Default is <c>false</c>.
    /// </summary>
    /// <remarks>
    /// <para>Editable forms are prohibited by PDF/A compliance. <c>false</c> value will be used automatically
    /// when saving to PDF/A.</para>
    /// <para>Form fields are not supported when saving to PDF/UA. <c>false</c> value will be used automatically.</para>
    /// </remarks>
    public bool PreserveFormFields;

    /// <summary>
    /// Gets or sets the details for encrypting the output PDF document.
    /// </summary>
    /// <remarks>
    /// <para>Encryption is prohibited by PDF/A compliance. This option will be ignored when saving to PDF/A.</para>
    /// <para><see cref="PdfPermissions.ContentCopyForAccessibility"/> permission is required by PDF/UA compliance
    /// if the output document is encrypted. This permission will automatically used when saving to PDF/UA.</para>
    /// </remarks>
    public PdfEncryptionDetails EncryptionDetails;
    /// <summary>
    /// Specifies the font embedding mode.
    /// </summary>
    /// <remarks>
    /// <para>PDF/A and PDF/UA compliance requires all fonts to be embedded.
    /// <see cref="PdfFontEmbeddingMode.EmbedAll"/> value will be used automatically when saving to
    /// PDF/A and PDF/UA.</para>
    /// </remarks>
    public PdfFontEmbeddingMode FontEmbeddingMode
    /// <summary>
    /// Gets or sets a value determining whether or not to substitute TrueType fonts Arial, Times New Roman,
    /// Courier New and Symbol with core PDF Type 1 fonts.
    /// </summary>
    /// <remarks>
    /// <para>PDF/A and PDF/UA compliance requires all fonts to be embedded. <c>false</c> value will be used
    /// automatically when saving to PDF/A and PDF/UA.</para>
    /// </remarks>
    public bool UseCoreFonts
    /// <summary>
    /// Gets or sets a value determining the way <see cref="Document.CustomDocumentProperties"/> are exported to PDF file.
    /// </summary>
    /// <remarks>
    /// <para><see cref="PdfCustomPropertiesExport.Metadata"/> value is not supported when saving to PDF/A.
    /// <see cref="PdfCustomPropertiesExport.Standard"/> will be used instead.
    /// </para>
    /// </remarks>
    public PdfCustomPropertiesExport CustomPropertiesExport
    /// <summary>
    /// Gets or sets a value determining whether hyperlinks in the output Pdf document
    /// are forced to be opened in a new window (or tab) of a browser.
    /// </summary>
    /// <remarks>
    /// <para>JavaScript actions are prohibited by PDF/A compliance. <c>false</c> will be used automatically when
    /// saving to PDF/A.</para>
    /// </remarks>
    public bool OpenHyperlinksInNewWindow
    /// <summary>
    /// Gets or sets a value determining whether or not to export document structure.
    /// </summary>
    /// <remarks>
    /// <para>
    /// This value is ignored when saving to PDF/A-1a, PDF/A-2a and PDF/UA-1 because document structure is required for this compliance.
    /// </para>
    /// </remarks>
    public bool ExportDocumentStructure
    /// <summary>
    /// Specifies how the color space will be selected for the images in PDF document.
    /// </summary>
    /// <remarks>
    /// <para><see cref="PdfImageColorSpaceExportMode.SimpleCmyk"/> value is not supported when saving to PDF/A.
    /// <see cref="PdfImageColorSpaceExportMode.Auto"/> value will be used instead.</para>
    /// </remarks>
    public PdfImageColorSpaceExportMode ImageColorSpaceExportMode
    /// <summary>
    /// A flag specifying whether the window’s title bar should display the document title taken from
    /// the Title entry of the document information dictionary.
    /// </summary>
    /// <remarks>
    /// <para>This flag is required by PDF/UA compliance. <c>true</c> value will be used automatically when saving
    /// to PDF/UA.</para>
    /// </remarks>
    public bool DisplayDocTitle
    /// <summary>
    /// A flag indicating whether image interpolation shall be performed by a conforming reader.
    /// When <c>false</c> is specified, the flag is not written to the output document and
    /// the default behaviour of reader is used instead.
    /// </summary>
    /// <remarks>
    /// <para>Interpolation flag is prohibited by PDF/A compliance. <c>false</c> value will be used automatically
    /// when saving to PDF/A.</para>
    /// </remarks>
    public bool InterpolateImages

Removed obsolete property LayoutOptions.ShowComments

Removes obsolete property LayoutOptions.ShowComments.

public bool ShowComments { get; set; }

Use LayoutOptions.CommentDisplayMode property instead:

auto doc = System::MakeObject<Document>(u"in.docx");