Aspose.Words for C++ 21.11 Release Notes

Major Features

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

  • 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.

We have added the following features for Aspose.Words for C++:

  • vcpkg registry with vcpkg package for Aspose.Words for C++

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 C++ Users)

KeySummaryCategory
WORDSCPP-1133vcpkg package for Aspose.Words for C++New Feature
WORDSCPP-1140lld linker reports ld.lld: warning: found local symbolBug

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 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

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
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

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:

auto doc = System::MakeObject<Document>(u"input.docx");
 
// Specify the new page mode for PDF.
auto options = System::MakeObject<PdfSaveOptions>();
options->set_PageMode(PdfPageMode::UseAttachments);
 
doc->Save(u"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 = u"myfile.chm";
 
// Create an input stream of the input document.
auto inputStream = System::MakeObject<MemoryStream>(System::IO::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"
auto loadOptions = System::MakeObject<ChmLoadOptions>();
loadOptions->set_OriginalFileName(fileName);
 
// Load the document.
auto doc = System::MakeObject<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.
auto doc = System::MakeObject<Document>();
auto builder = System::MakeObject<DocumentBuilder>(doc);
 
// Insert field.
builder->InsertField(u"INCLUDETEXT", u"Text in field");
 
auto regex = System::MakeObject<Regex>(u"T");
auto options = System::MakeObject<FindReplaceOptions>();
 
// Replace 'T' in document ignoring text inside field code.
options->set_IgnoreFieldCodes(true);
doc->get_Range()->Replace(regex, u"*", options);
std::cout << doc->GetText().ToUtf8String() << '\n';
 
// Replace 'T' in document NOT ignoring text inside field code.
options->set_IgnoreFieldCodes(false);
doc->get_Range()->Replace(regex, u"*", options);
std::cout << doc->GetText().ToUtf8String() << '\n';
 
// 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>
class LoadingProgressCallback : public IDocumentLoadingCallback
{
    using ThisType = LoadingProgressCallback;
    using BaseType = IDocumentLoadingCallback;
    using ThisTypeBaseTypesInfo = ::System::BaseTypesInfo<BaseType>;
    RTTI_INFO();
public:
    /// <summary>
    /// Ctr.
    /// </summary>
    public LoadingProgressCallback()
    {
        mLoadingStartedAt = System::DateTime::get_Now();
    }
 
    /// <summary>
    /// Callback method which called during document loading.
    /// </summary>
    /// <param name="args">Loading arguments.</param>
    void Notify(System::SharedPtr<DocumentLoadingArgs> args) override
    {
        auto canceledAt = System::DateTime::get_Now();
        double ellapsedSeconds = (canceledAt - mLoadingStartedAt)->get_TotalSeconds();
 
        if (ellapsedSeconds > MaxDuration)
            throw OperationCanceledException();
    }
 
private:
    /// <summary>
    /// Date and time when document loading is started.
    /// </summary>
    DateTime mLoadingStartedAt;
 
    /// <summary>
    /// Maximum allowed duration in sec.
    /// </summary>
    static constexpr double MaxDuration = 100.0;
}

Loading document code:

auto cb = System::MakeObject<LoadingProgressCallback>();
 
auto lo = System::MakeObject<LoadOptions>();
lo->set_ProgressCallback(cb);
 
try
{
    auto doc = System::MakeObject<Document>(u"bigDoc.docx", lo);
    // Do work.
}
catch (const OperationCanceledException& ex)
{
    // 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.

auto doc = System::MakeObject<Document>(u"DocumentWithShape.docx");
 
auto mso = System::MakeObject<MarkdownSaveOptions>();
mso->set_ExportImagesAsBase64(true);
 
doc->Save(u"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.