Aspose.Words for .NET 23.1 Release Notes

Major Features

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

  • Significantly improved performance and quality of emulation of raster operations with metafiles.
  • Implemented an ability to work with shading theme colors.
  • Added the ability to generate TOC (table of contents) for AZW3 documents.
  • Provided the way to control how the list items are exported to the Markdown format.
  • Added support of R-squared coefficient in DML charts trendline labels when rendering.

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

Added Font property to ChartDataLabel and ChartDataLabelCollection classes

Related issue: WORDSNET-24652

The Font property has been added to the ChartDataLabel and ChartDataLabelCollection classes:

public class ChartDataLabel
{
    /// <summary>
    /// Provides access to the font formatting of this data label.
    /// </summary>
    public Font Font {get; }
    ...
}

public class ChartDataLabelCollection
{
    /// <summary>
    /// Provides access to the font formatting of the data labels of the entire series.
    /// </summary>
    /// <remarks>
    /// Value defined for this property can be overridden for an individual data label with using the
    /// <see cref="ChartDataLabel.Font"/> property.
    /// </remarks>
    public Font Font {get; }
    ...
}
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Create a column chart.
Shape shape = builder.InsertChart(ChartType.Column, 432, 252);
ChartSeriesCollection seriesCollection = shape.Chart.Series;
seriesCollection.Clear();

// Add a chart series.
ChartSeries series = seriesCollection.Add(
    "Series 1",
    new string[] { "Category 1", "Category 2", "Category 3", "Category 4", "Category 5" },
    new double[] { 5.5, 2, 3.5, 6, 9 });

// Display data labels.
series.HasDataLabels = true;
ChartDataLabelCollection labels = series.DataLabels;
labels.ShowValue = true;

// Set font size for all labels of the series.
labels.Font.Size = 12;

const int minValueIndex = 1; // Let's use a constant for simplicity.
const int maxValueIndex = 4; // Let's use a constant for simplicity.

// Mark the labels for the max and min values.
labels[minValueIndex].Font.Size = 14;
labels[minValueIndex].Font.Color = Color.Red;
labels[maxValueIndex].Font.Size = 14;
labels[maxValueIndex].Font.Color = Color.Green;

// Save the document.
doc.Save("LabelFont.docx");

Added IgnoreOleData option into LoadOptions class

Related issue: WORDSNET-24477

The IgnoreOleData property has been added to the LoadOptions class. May be usefull when destination format does not support OLE.

public class LoadOptions
{
    ...
        /// <summary>
        /// Specifies whether to ignore the OLE data.
        /// </summary>
        /// <remarks>
        /// <para>Ignoring OLE data may reduce memory consumption and increase performance without data lost in a case when destination format does not support OLE objects.</para>
        /// <para>The default value is <c>false</c>.</para>
        /// </remarks>
        /// <dev>
        /// OLE without data is converted to images on document post-loading stage.
        /// <see cref="DocumentPostLoader.ConvertOleObjectWithoutDataIntoImage"/>.
        /// </dev>
        public bool IgnoreOleData
    ...
}
LoadOptions lo = new LoadOptions() { IgnoreOleData = true };
Document doc = new Document("Test.docx", lo);

doc.Save("Test.pdf")

Added MetafileRenderingOptions.UseGdiRasterOperationsEmulation and overall improvements in metafile raster operations emulation

Related issue: #WORDSNET-24003

Metafile raster operations emulations have been improved.

Also added an option to use GDI+ in raster operations emulation process.

/// <summary>
/// Gets or sets a value determining whether or not to use the GDI+ for raster operations emulation.
/// </summary>
/// <remarks>
/// <para>Windows GDI+ library could be used to emulate raster operations. It provides support for all raster operation
/// comparing to Aspose.Words own emulation but performance may be slower in some cases.</para>
///
/// <p>When this value is set to <c>true</c>, Aspose.Words uses GDI+ for raster operations emulation.</p>
///
/// <p>When this value is set to <c>false</c>, Aspose.Words uses its own implementation of raster operations emulation.</p>
///
/// <p>This option is used only when metafile is rendered as vector graphics.</p>
///
/// <p>The default value is <c>false</c>.</p>
/// </remarks>
public bool UseGdiRasterOperationsEmulation { get; set }

Added new public properties for working with shading theme colors

Related issue: WORDSNET-24456

A new public properties ForegroundPatternThemeColor and BackgroundPatternThemeColor has been added to the Shading class.

/// <summary>
/// Gets or sets the foreground pattern theme color in the applied color scheme that is associated with this <see cref="Shading"/> object.
/// </summary>
public ThemeColor ForegroundPatternThemeColor { get; set; }

/// <summary>
/// Gets or sets the background pattern theme color in the applied color scheme that is associated with this <see cref="Shading"/> object.
/// </summary>
public ThemeColor BackgroundPatternThemeColor { get; set; }

A new public properties ForegroundTintAndShade and BackgroundTintAndShade has been added to the Shading class.

/// <summary>
/// Gets or sets a double value that lightens or darkens a foreground theme color.
/// </summary>
public double ForegroundTintAndShade { get; set; }

/// <summary>
/// Gets or sets a double value that lightens or darkens a background theme color.
/// </summary>
public double BackgroundTintAndShade { get; set; }
Document doc = new Document("c:\Documents\TestDocument.docx");

Shading shading = doc.FirstSection.Body.FirstParagraph.ParagraphFormat.Shading;
// Gets and sets the values of theme colors.
if (shading.ForegroundPatternThemeColor == ThemeColor.Accent1)
    shading.ForegroundPatternThemeColor = ThemeColor.Dark1;

if (shading.BackgroundPatternThemeColor == ThemeColor.Accent2)
    shading.BackgroundPatternThemeColor = ThemeColor.Dark2;

// Gets and sets the lightens values.
if (shading.ForegroundTintAndShade == 0)
    shading.ForegroundTintAndShade = 0.5;

if (shading.BackgroundTintAndShade == 0)
    shading.BackgroundTintAndShade = -0.2;

doc.Save("output.docx");

Added public property Range.Revisions

Related issue: WORDSNET-24257

A new public property Revisions has been added to the Range class:

/// <summary>
/// Gets a collection of revisions (tracked changes) that exist in this range.
/// </summary>
/// <remarks>
/// <para>The returned collection is a "live" collection, which means if you remove parts of a document that contain
/// revisions, the deleted revisions will automatically disappear from this collection.</para>
/// </remarks>
public RevisionCollection Revisions { get; }
Document doc = new Document("c:\Documents\TestDocument.docx");
// Getting the first paragraph revisions.
Paragraph paragraph = doc.FirstSection.Body.FirstParagraph;
foreach (Revision revision in paragraph.Range.Revisions)
{
    if (revision.RevisionType == RevisionType.Deletion)
        revision.Accept();
}
// Getting the first section revisions.
doc.FirstSection.Range.Revisions.RejectAll();

Added the ability to generate TOC (table of contents) for AZW3 documents

Related issue: WORDSNET-24389

Now Aspose.Words can generate TOC (table of contents) for AZW3 documents.

Desired depth of TOC can be specified same way as it’s done for EPUB documents using the HtmlSaveOptions.EpubNavigationMapLevel property.

Document doc = new Document();

HtmlSaveOptions options = new HtmlSaveOptions(SaveFormat.Azw3);
options.EpubNavigationMapLevel = 2;

doc.Save(MyDir + "DocumentWithTwoLevelTOC.azw3", options);

Added the ability to specify how list items will be written to the Markdown

Related issue: WORDSNET-24544

The following public enumeration is added to Aspose.Words.Saving namespace:

/// <summary>
/// Specifies how lists are exported into Markdown.
/// </summary>
public enum MarkdownListExportMode
{
    /// <summary>
    /// Export list items compatible with Markdown syntax.
    /// </summary>
    MarkdownSyntax,

    /// <summary>
    /// Export list items as plain text.
    /// </summary>
    PlainText
}

The following public property is added to the MarkdownSaveOptions class:

/// <summary>
/// Specifies how list items will be written to the output file.
/// Default value is <see cref="MarkdownListExportMode.MarkdownSyntax"/>.
/// </summary>
/// <remarks>
/// <para>When this property is set to <see cref="MarkdownListExportMode.PlainText"/> all list labels are
/// updated using <see cref="Document.UpdateListLabels"/> and exported with their actual values. Such lists
/// can be non-compatible with Markdown format and will be recognized as plain text upon importing in this case.</para>
/// <para>When this property is set to <see cref="MarkdownListExportMode.MarkdownSyntax"/>, writer tries to export
/// list items in manner that allows to numerate list items in automatic mode by Markdown.</para>
/// </remarks>
public MarkdownListExportMode ListExportMode { get; set; }
Document doc = new Document("input.docx");

// Set option to export list items as plain text.
MarkdownSaveOptions options = new MarkdownSaveOptions { ListExportMode = MarkdownListExportMode.PlainText };
doc.Save("output.md", options);

HtmlSaveOptions.ScaleImageToShapeSize now also affects grouped raster images

Related issue: WORDSNET-24065

Behavior of the HtmlSaveOptions.ScaleImageToShapeSize property was changed to affect groups of raster images.

Previously, HtmlSaveOptions.ScaleImageToShapeSize didn’t affect grouped raster images and they were always scaled to shape size and were rendered using the resolution value specified in HtmlSaveOptions.ImageResolution. If grouped images were high resolution, their quality would reduce considerably because of scaling.

Now Aspose.Words tries to preserve quality of grouped high resolution images. If a group of raster images is saved to HTML and the HtmlSaveOptions.ScaleImageToShapeSize property is set to false, Aspose.Words computes max intrinsic resolution among all images in the group and if it is greater than the value specified in HtmlSaveOptions.ImageResolution, the group is rendered using the computed increased resolution. This doesn’t eliminate scaling completely but reduces its impact on grouped high resolution raster images.

OfficeMath.EquationXmlEncoding property was marked as obsolete

Related issue: WORDSNET-24770

The OfficeMath.EquationXmlEncoding property has been marked as obsolete because it is not intended to be used in the API.

/// <summary>
/// Gets/sets an encoding that was used to encode equation XML, if this office math object is read from equation XML.
/// </summary>
[Obsolete("Not intended for use in the API")]
public Encoding EquationXmlEncoding
{
    get;
    set;
}