Aspose.Words for Java 21.6 Release Notes

Major Features

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

  • Implemented an ability to set fill and stroke formatting for chart series, data points and markers.
  • Introduced a new API for working with textures.
  • Implemented rendering of OOXML Ink (InkML subset).
  • TxtSaveOptions.MaxCharactersPerLine property was introduced.
  • A new Document.LayoutOption is added to control page numbering in a continuous section.
  • Provided an option to always generate an object for a JSON or XML root element for LINQ Reporting Engine.

Full List of Issues Covering all Changes in this Release

KeySummaryCategory
WORDSNET-21647DOCX to PDF: Content displacement occursNew Feature
WORDSNET-12748Provide API to change Color of Category Series of ChartNew Feature
WORDSNET-13907Support rendering DrawingML InkML ContentPartNew Feature
WORDSNET-12275Add feature to change the color of ChartSeriesNew Feature
WORDSNET-21847Advanced OpenType font features not appliedNew Feature
WORDSNET-21871Add feature to create Scatter chart with linesNew Feature
WORDSNET-22070Provide an option to always generate an object for an XML root element for LINQ Reporting EngineNew Feature
WORDSNET-12529Add feature to get/set Asian Character Spacing propertiesNew Feature
WORDSNET-22082storeItemChecksum get/set methodNew Feature
WORDSNET-22002Implement Fill.PresetTextured() methodNew Feature
WORDSNET-20023Allow to change Pie chart colorsNew Feature
WORDSNET-21972Provide an option to always generate an object for a JSON root element for LINQ Reporting EngineNew Feature
WORDSNET-15201Implement MS Word 2013 behavior for continuous sections with footnotesNew Feature
WORDSJAVA-1871Regular check&update of OSGI compatibility.New Feature
WORDSJAVA-2589Roman numbering style for lists in .txt documentsNew Feature
WORDSNET-17510Aspose.Words does not mimic MS Word for document structure tagsEnhancement
WORDSNET-18186Ink annotations lost during conversion from Word to PDFEnhancement
WORDSNET-20020Transparency in converted Word Document is not shown in PDFEnhancement
WORDSNET-12640Add feature to set/get Chart series colorsEnhancement
WORDSNET-20462Handwritten contents are lost after DOCX to PDFEnhancement
WORDSNET-21156Incorrect value returned by LayoutCollectorEnhancement
WORDSNET-19199DOCX to PDF with free hand drawing imagesEnhancement
WORDSNET-22090Each Line in TXT File should have a Fix Length of Characters | Maximum Allowed Characters in LineEnhancement
WORDSNET-21795DOCX to PDF/A conversion and validation fails: Problem with word/spaces separation inside headerEnhancement
WORDSJAVA-2548TXT file is autodetected as Markdown and throws FileCorruptedException while loadingBug
WORDSJAVA-2579GetText() returns text plus list markerBug
WORDSJAVA-2584java.lang.ExceptionInInitializerError is thrown when aspose-words.jar is bundled inside the application JAR fileBug
WORDSJAVA-2590Markdown loader processes removed nodes incorrectlyBug
WORDSJAVA-2599Some JSON and XML tests are failingBug
WORDSNET-15771Table overflows to next page while converting to PDFBug
WORDSNET-22155DOCX to PDF/A conversion: significant tagging overheadBug
WORDSNET-18780Table is rendered on the next page in output PDFBug
WORDSNET-22158MailMerge CleanupOptions does not remove the empty table rowsBug
WORDSNET-14523After conversion to PDF, content is missingBug
WORDSNET-22171Missing SVG Shape in PDFBug
WORDSNET-16700PrinterMetrics does not work on Xamarin/NetStandardBug
WORDSNET-18091UpdateFields method throws System.InvalidOperationExceptionBug
WORDSNET-22186Text of Frame is overlapped after DOCX to PDF conversionBug
WORDSNET-21845DOCX to PDF > Incorrect rendering of footnotesBug
WORDSNET-21848Text in images gets cut off after DOCX to PDF converisonBug
WORDSNET-22189Incorrect list numbering when converting from DOCX to HTMLBug
WORDSNET-18945System.InvalidOperationException is thrown while saving DOCX to PDFBug
WORDSNET-18275Document.UpdatePageLayout throws System.InvalidCastExceptionBug
WORDSNET-22193Hidden text is rendered after DOCX to PDF conversionBug
WORDSNET-18618Document.UpdatePageLayout throws System.InvalidOperationExceptionBug
WORDSNET-20733Incorrect rendering of Footnotes ContentBug
WORDSNET-17613Content pushed down to subsequent pages in PDF causing overlapping in FootnotesBug
WORDSNET-22201System.InvalidOperationException is thrown after removing stylesBug
WORDSNET-22166Footnotes break continuous section break rendering (rendered as page break)Bug
WORDSNET-21332Overlapping - Embedded Table contents from 2nd & 3rd pages move to 1st page in TIFFBug
WORDSNET-21557Text is overlapped after DOCX to PDF conversionBug
WORDSNET-22207Bullet points order issue during Word to PDF conversionBug
WORDSNET-22209NullReferenceException occurs upon DOC to PDF conversionBug
WORDSNET-22208NullReferenceException occurs upon DOCX to PDF conversionBug
WORDSNET-22213Document.PageCount throws System.IndexOutOfRangeExceptionBug
WORDSNET-20769.NET Core Parallel.ForEach, Aspose.Words.Document() load not thread safeBug
WORDSNET-22219Incorrect Image resolution and dimension units while importing MarkdownBug
WORDSNET-20315A Legend Entry in Chart is missing when Converting Chart to JPEGBug
WORDSNET-19458DOCX to PDF conversion issue with document structureBug
WORDSNET-22224Hidden footnotes throws asserts during reflowBug
WORDSNET-22185Mail Merge field is lost after re-saving DOCXBug
WORDSNET-18562DOCX to PDF conversion issue with Chart’s Data LabelBug
WORDSNET-21707Font name of Hebrew text is changed to ‘Times New Roman’ after re-saving DOCXBug
WORDSNET-20920StructuredDocumentTag content is changed on page extraction.Bug
WORDSNET-15553Aspose.Words generated PDFA size issueBug
WORDSNET-20943Incorrect table positionBug
WORDSNET-21730DOCX to PDF conversion issue with ExportDocumentStructure (incorrect tags)Bug
WORDSNET-22232Aspose.Words does not mimic MS Word for document structure tagsBug
WORDSNET-22177Wrong Page Number when word converted to pdfBug
WORDSNET-22235Image is rendered as cross after inserting HTML into document at LinuxBug
WORDSNET-21993DOCX to PDF conversion issue - PDF is not editableBug
WORDSNET-21609DOCX->HTML->DOCX conversion: table size changes in the outputBug
WORDSNET-22241Checked symbol of content control is changed after first clickBug
WORDSNET-22244Process hangs when calling UpdateFields methodBug
WORDSNET-21701NullReferenceException is thrown when call UpdatePageLayoutBug
WORDSNET-16663Problem with saving DOC with footnote to PDFBug
WORDSNET-21896FileCorruptedException occurs when loading a MHTML documentBug
WORDSNET-22195Aspose.Words UpdateLayout method throws exception “Infinite loop”Bug
WORDSNET-22253Hyperlink is lost after re-saving DOCXBug
WORDSNET-21352ExportDocumentStructure creates incorrect tags in output PDFBug
WORDSNET-21937System.NullReferenceException is thrown when DOCX is saved to PDFBug
WORDSNET-22257AppendContent throws exceptionBug
WORDSNET-20631ExportDocumentStructure and NVDA applicationBug
WORDSNET-14495Alignment of OfficeMath is incorrect when it is inserted by InsertHtmlBug
WORDSNET-22103Merging two documents and list numbering doesn’t continueBug
WORDSNET-22276Incorrect rendering “Rectangle:Rounded Corners” shapeBug
WORDSNET-22174DOCX to ODT conversion throws System.InvalidOperationExceptionBug
WORDSNET-22259“Value was either too large or too small for an Int32.” exception when open DOCX fileBug
WORDSNET-21968System.IndexOutOfRangeException occurs upon Word XML Document to PDF conversionBug
WORDSNET-21969DOCX to PDF conversion | Even numbers are skipped from x-axis of chartBug
WORDSNET-21975Heading is not properly rendered when exported to PDFBug
WORDSNET-22109System.NullReferenceException occurs upon DOCX to PDF conversionBug
WORDSNET-22113Text font is changed after DOCX to PDF conversionBug
WORDSNET-22129DocumentBuilder.InsertFootnote causes System.IndexOutOfRangeException when saving to PDFBug
WORDSNET-21731DOCX to PDF conversion issue with ExportDocumentStructure (incorrect list)Bug
WORDSNET-22094Document.ExtractPages method removes BookmarksBug
WORDSNET-22149Paragraph become list item after inserting one document into anotherBug
WORDSNET-22286InvalidOperationException: Unexpected ST_TrueFalse value occurs upon loading a DOCXBug
WORDSNET-21622System.InvalidOperationException occurs upon DOCX to HTML conversionBug
WORDSNET-22292Update storeItemChecksum after XmlMapping updateBug
WORDSNET-5293REF field should show hyperlink tooltipBug
WORDSNET-16691Printer metrics is rendered improperlyBug
WORDSNET-17724DOCX to PDF conversion issue with table renderingBug
WORDSNET-17769Converting DOCX to PDF overlaps the tablesBug
WORDSNET-21482LayoutCollector fails on .NET StandardBug

Public API and Backward Incompatible Changes

This section lists public API changes that were introduced in Aspose.Words 21.6. 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 a new LayoutEntityType and new values for the Kind property within the LayoutEnumerator class

A new value Note has been added to the public enum LayoutEntityType:

public enum LayoutEntityType
{
...
  /// <summary>
  /// Represents placeholder for note content.
  ///
  /// Note may have <see cref="Line"/> and <see cref="Row"/> child entities.
  /// </summary>
  Note
...
}

This will help users iterate over notes inside footnotes/endnotes containers.

Use Case:

Document doc = new Document("SomeDocument.docx")
LayoutEnumerator en = new LayoutEnumerator(doc);

// We start from the first page.
Debug.Assert(en.Type == LayoutEntityType.Page);

// Move to the first column on the page.
en.MoveFirstChild();
Debug.Assert(en.Type == LayoutEntityType.Column);

// Move to the first child in the column.
en.MoveFirstChild();

do
{
  // Iterate to a footnote container.
  if (en.Type == LayoutEntityType.Footnote)
   break;
}
while(en.MoveNext());

// If the footnote container exists in the column, we will process notes.
if (en.Type == LayoutEntityType.Footnote)
{
  // Move to the first note in the footnote container.
  if (en.MoveFirstChild())
  {
    do
    {
     // Move over notes inside the footnote container.
     Debug.Assert(en.Type == LayoutEntityType.Note);
     // Do something.
    }
    while (en.MoveNext());
   }
 }
}

New Kind enum values for the LayoutEnumerator class

8 new Kind enum values have been added for the LayoutEnumerator class:

"FOOTNOTES"
"ENDNOTES"
"FOOTNOTESEPARATOR"
"ENDNOTESEPARATOR"
"FOOTNOTECONTINUATIONSEPARATOR"
"ENDNOTECONTINUATIONSEPARATOR"
"FOOTNOTECONTINUATIONNOTICE"
"ENDNOTECONTINUATIONNOTICE"

The most useful values are the kinds that allow to unambiguously determine what type of separator you are working with. This is true because for all kinds of separators the LayoutEntityType is LayoutEntityType.NoteSeparator.

Use Case:

Document doc = new Document("SomeDocument.docx")
LayoutEnumerator en = new LayoutEnumerator(doc);

// We start from the first page.
Debug.Assert(en.Type == LayoutEntityType.Page);

// Move to the first column on the page.
en.MoveFirstChild();
Debug.Assert(en.Type == LayoutEntityType.Column);

// Move to the first child in the column.
en.MoveFirstChild();

do
{
   if (en.Type == LayoutEntityType.NoteSeparator && en.Kind == "FOOTNOTESEPARATOR")
   {
      // Do something.
   }

   if (en.Type == LayoutEntityType.NoteSeparator && en.Kind == "FOOTNOTECONTINUATIONSEPARATOR")
   {
      // Do something.
   }

   if (en.Type == LayoutEntityType.NoteSeparator && en.Kind == "FOOTNOTECONTINUATIONNOTICE")
   {
      // Do something.
   }
}
while(en.MoveNext());
}

Added a new public property CustomXmlPart.DataChecksum

Related issue: WORDSNET-22082

Added a new public property CustomXmlPart.DataChecksum:

/// <summary>
/// Specifies a cyclic redundancy check (CRC) checksum of the <see cref="Data"/> content.
/// </summary>
public long DataChecksum

It’s readonly. It is numeric representation of the storeItemChecksum element. The checksum is computed using the data of the corresponding custom XML data part.

Use Case:

Document doc = new Document("Document.docx");
StructuredDocumentTag sdt = (StructuredDocumentTag)doc.GetChild(NodeType.StructuredDocumentTag, 0, true);
Console.WriteLine(sdt.XmlMapping.CustomXmlPart.DataChecksum);
Document doc = new Document();

StructuredDocumentTag sdt = new StructuredDocumentTag(doc, SdtType.RichText, MarkupLevel.Block);
doc.FirstSection.Body.Insert(sdt, null, false);
             
sdt.XmlMapping.SetMapping(doc.CustomXmlParts.Add("C8FFD3B6-7EF8-4963-895B-3565F68A03E7",
    "<root><text>test</text></root>"), "/root/text", "");
Console.WriteLine(sdt.XmlMapping.CustomXmlPart.DataChecksum);

A new Document.LayoutOption is added to control page numbering in a continuous section

Related issues: WORDSNET-22177, WORDSNET-17760.

A new layout option is added to control Aspose.Words behavior when computing page numbers in a continuous section that restarts page numbering:

namespace Aspose.Words.Layout
{
...
    public class LayoutOptions
    {
...
        /// <summary>
        /// Gets or sets the mode of behavior for computing page numbers when a continuous section
        /// restarts the page numbering.
        /// </summary>
        /// <remarks>
        /// The default behavior matches the latest MS Word version.
        /// Older page numbering logic demonstrated by MS Word 2016 is available via this option.
        /// </remarks>
        public ContinuosSectionRestart ContinuousSectionPageNumberingRestart
}
...
    /// <summary>
    /// Represents different behaviors when computing page numbers in a continuous section that restarts page numbering.
    /// </summary>
    public enum ContinuosSectionRestart
    {
        /// <summary>
        /// Page numbering always restarts regardless of content flow.
        /// </summary>
        /// <remarks>
        /// This behavior is demonstrated by all MS Word versions, except Word 2016.
        /// </remarks>
        Always = 0,
        /// <summary>
        /// Page numbering restarts only if there is no other content before the section on the page where the section starts.
        /// </summary>
        /// <remarks>
        /// The behavior is demonstrated by MS Word 2016.
        /// </remarks>
        FromNewPageOnly,
    }
}

After the changes, the default Aspose.Words behavior matches the current MS Word version (2019). The older behavior implemented per WORDSNET-17760 is still avaialable via the introduced option:

Document doc = new Document("input.docx");
doc.LayoutOptions.ContinuousSectionPageNumberingRestart = ContinuosSectionRestart.FromNewPageOnly;
doc.Save("out.pdf");

Note: It is required to rebuild the document page layout (via Document.UpdatePageLayout() method) after changing the Document.LayoutOptions values.

Implemented ability to set fill and stroke formatting for chart series, data points and markers

Related issue: WORDSNET-12275

Properties of the new ChartFormat type have been added to the ChartSeries, ChartDataPoint and ChartMarker classes.

public class ChartSeries
{
    /// <summary>
    /// Provides access to fill and line formatting of the series.
    /// </summary>
    public ChartFormat Format { get; }
}

public class ChartDataPoint
{
    /// <summary>
    /// Provides access to fill and line formatting of this data point.
    /// </summary>
    public ChartFormat Format { get; }
}

public class ChartMarker
{
    /// <summary>
    /// Provides access to fill and line formatting of this marker.
    /// </summary>
    public ChartFormat Format { get; }
}

/// <summary>
/// Represents the formatting of a chart element.
/// </summary>
public class ChartFormat
{
    /// <summary>
    /// Gets fill formatting for the parent chart element.
    /// </summary>
    public Fill Fill { get; }

    /// <summary>
    /// Gets line formatting for the parent chart element.
    /// </summary>
    public Stroke Stroke { get; }
}

Also aliases to some existing properties have been added to the Stroke class: ForeColor, BackColor, Visible and Transparency. The original Color, Color2, On and Opacity properties will be made obsolete in a future version of Aspose.Words.

public class Stroke
{
    /// <summary>
    /// Gets or sets the foreground color of the stroke.
    /// </summary>
    public Color ForeColor { get; set; }

    /// <summary>
    /// Gets or sets the background color of the stroke.
    /// </summary>
    public Color BackColor { get; set; }
     
    /// <summary>
    /// Gets or sets a flag indicating whether the stroke is visible.
    /// </summary>
    public bool Visible { get; set; }
     
    /// <summary>
    /// Gets or sets a value between 0.0 (opaque) and 1.0 (clear) representing the degree of transparency of the stroke.
    /// </summary>
    /// <remarks>
    /// The default value is 0.
    /// </remarks>
    public double Transparency { get; set; }
}

Use Case: Explains how to set series color

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Shape shape = builder.InsertChart(ChartType.Column, 432, 252);

Chart chart = shape.Chart;
ChartSeriesCollection seriesColl = chart.Series;

// Delete default generated series.
seriesColl.Clear();

// Create category names array.
string[] categories = new string[] { "AW Category 1", "AW Category 2" };

// Adding new series. Value and category arrays must be the same size.
ChartSeries series1 = seriesColl.Add("AW Series 1", categories, new double[] { 1, 2 });
ChartSeries series2 = seriesColl.Add("AW Series 2", categories, new double[] { 3, 4 });
ChartSeries series3 = seriesColl.Add("AW Series 3", categories, new double[] { 5, 6 });

// Set series color.
series1.Format.Fill.ForeColor = Color.Red;
series2.Format.Fill.ForeColor = Color.Yellow;
series3.Format.Fill.ForeColor = Color.Blue;

doc.Save("ColumnColor.docx");

Use Case: Explains how to set individual formatting for categories of a column chart

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Shape shape = builder.InsertChart(ChartType.Column, 432, 252);
Chart chart = shape.Chart;

// Delete default generated series.
chart.Series.Clear();

// Adding new series.
ChartSeries series = chart.Series.Add("AW Series 1", new string[] { "AW Category 1", "AW Category 2", "AW Category 3", "AW Category 4" }, new double[] { 1, 2, 3, 4 });

// Set column formatting.
ChartDataPointCollection dataPoints = series.DataPoints;
dataPoints[0].Format.Fill.PresetTextured(PresetTexture.Denim);
dataPoints[1].Format.Fill.ForeColor = Color.Red;
dataPoints[2].Format.Fill.ForeColor = Color.Yellow;
dataPoints[3].Format.Fill.ForeColor = Color.Blue;

doc.Save("IndividualColumnFormatting.docx");

Use Case: Explains how to set line color and weight

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Shape shape = builder.InsertChart(ChartType.Line, 432, 252);

Chart chart = shape.Chart;
ChartSeriesCollection seriesColl = chart.Series;

// Delete default generated series.
seriesColl.Clear();

// Adding new series.
ChartSeries series1 = seriesColl.Add("AW Series 1", new double[] { 0.7, 1.8, 2.6 }, new double[] { 2.7, 3.2, 0.8 });
ChartSeries series2 = seriesColl.Add("AW Series 2", new double[] { 0.5, 1.5, 2.5 }, new double[] { 3, 1, 2 });

// Set series color.
series1.Format.Stroke.ForeColor = Color.Red;
series1.Format.Stroke.Weight = 5;
series2.Format.Stroke.ForeColor = Color.LightGreen;
series2.Format.Stroke.Weight = 5;

doc.Save("LineColorAndWeight.docx");

Use Case: Explains how to set line segment colors

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Shape shape = builder.InsertChart(ChartType.Line, 432, 252);
Chart chart = shape.Chart;

// Delete default generated series.
chart.Series.Clear();

// Adding new series.
ChartSeries series = chart.Series.Add("AW Series 1", new double[] { 0.7, 1.8, 2.6, 3.5 }, new double[] { 2.7, 3.2, 0.8, 0.1 });
series.Format.Stroke.Weight = 4;

// Set line colors.
ChartDataPointCollection dataPoints = series.DataPoints;
dataPoints[1].Format.Stroke.ForeColor = Color.Red;
dataPoints[2].Format.Stroke.ForeColor = Color.Yellow;
dataPoints[3].Format.Stroke.ForeColor = Color.Blue;

doc.Save("LineSegmentColor.docx");

Use Case: Explains how to set Pie chart colors

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Shape shape = builder.InsertChart(ChartType.Pie, 432, 252);
Chart chart = shape.Chart;

// Delete default generated series.
chart.Series.Clear();

// Adding new series.
ChartSeries series = chart.Series.Add("Series 1", new string[] { "Category1", "Category2", "Category3" }, new double[] { 2.7, 3.2, 0.8 });

// Set data point color.
ChartDataPointCollection dataPoints = series.DataPoints;
dataPoints[0].Format.Fill.ForeColor = Color.Red;
dataPoints[1].Format.Fill.ForeColor = Color.Yellow;
dataPoints[2].Format.Fill.ForeColor = Color.Green;

doc.Save("PieColor.docx");

Use Case: Explains how to set marker formatting

Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

Shape shape = builder.InsertChart(ChartType.Scatter, 432, 252);
Chart chart = shape.Chart;

// Delete default generated series.
chart.Series.Clear();

// Adding new series.
ChartSeries series = chart.Series.Add("AW Series 1", new double[] { 0.7, 1.8, 2.6, 3.9 }, new double[] { 2.7, 3.2, 0.8, 1.7 });

// Set marker formatting.
series.Marker.Size = 40;
series.Marker.Symbol = MarkerSymbol.Square;
ChartDataPointCollection dataPoints = series.DataPoints;
dataPoints[0].Marker.Format.Fill.PresetTextured(PresetTexture.Denim);
dataPoints[0].Marker.Format.Stroke.ForeColor = Color.Yellow;
dataPoints[1].Marker.Format.Fill.PresetTextured(PresetTexture.WaterDroplets);
dataPoints[1].Marker.Format.Stroke.ForeColor = Color.Yellow;
dataPoints[2].Marker.Format.Fill.PresetTextured(PresetTexture.GreenMarble);
dataPoints[2].Marker.Format.Stroke.ForeColor = Color.Yellow;
dataPoints[3].Marker.Format.Fill.PresetTextured(PresetTexture.Oak);
dataPoints[3].Marker.Format.Stroke.ForeColor = Color.Yellow;

doc.Save("MarkerFormatting.docx");

Implemented Rendering of OOXML Ink (InkML subset)

OOXML Ink content is specified by a subset of syntax and semantics for the Ink Markup Language (see “InkML specification”). The details of the subset are described in “2.1.4 Ink Content Part” of OOXML specification.

Prior to this version Aspose.Words could render only fallback shapes for OOXML Ink objects, i.e. InkML was not actually processed and a simple prerendered image was used instead. And now OOXML ink content part can be rendered directly (“cold” rendering).

To control the mode of Ink rendering a new public property SaveOptions.ImlRenderingMode was introduced and the corresponding enum was added:

/// <summary>
/// Gets or sets a value determining how ink (InkML) objects are rendered.
/// </summary>
/// <remarks>
/// The default value is <see cref="Aspose.Words.Saving.ImlRenderingMode.InkML"/>.
/// <para>This property is used when the document is exported to fixed page formats.</para>
/// </remarks>
public ImlRenderingMode ImlRenderingMode
/// <summary>
/// Specifies how ink (InkML) objects are rendered to fixed page formats.
/// </summary>
public enum ImlRenderingMode
{
    /// <summary>
    /// If fall-back shape is available for ink (InkML) object, Aspose.Words renders fall-back shape instead of the InkML.
    /// </summary>
    /// <remarks>
    /// Please note that after saving a document to a fixed page format with fall-back rendering mode,
    /// InkML objects in the Aspose.Words document model are permanently replaced with their fall-back counterparts.
    /// As a result, saving the same document again will always use fall-back shapes, even if ImlRenderingMode is set to InkML.
    /// </remarks>
    Fallback,
    /// <summary>
    /// Aspose.Words ignores fall-back shape of ink (InkML) object and renders InkML itself.
    /// This is the default mode.
    /// </summary>
    InkML
}

In addition to limitations described in “2.1.4 Ink Content Part” of OOXML specification, the first version of InkML cold rendering has the following limitations:

InkML Structural Element:

  • channel
    • The name attribute can be any string, but strings other than the following strings are ignored: X, Y, F.
    • The units attribute can be any string, but any value other than the following value is ignored: dev, in, cm
  • traceGroup
    • Any content other than trace and traceGroup is ignored and not persisted.
  • brushProperty
    • rasterOp - A value that defines how the colors of the pen and background interact. Is ignored.
    • antiAliased - A value that indicates if the drawn ink is anti-aliased. Is ignored.
    • fitToCurve - A value that indicates if the ink is rendered as a series of curves versus as lines between pen sample points. Is ignored.
  • annotationXML
    • Is ignored and not persisted.

Due to the limitations described above the Aspose.Words output may not exactly match the MS Word output in some cases. If the rendering result is unsatisfactory, please use the fallback mode to get a result similar to previous versions of Aspose.Words.

ImportFormatOptions.MergePastedLists property was introduced

Related issue: WORDSNET-22103

The following new public property was added into the ImportFormatOptions class:

/// <summary>
/// Gets or sets a boolean value that specifies whether pasted lists will be merged with surrounding lists.
/// The default value is <c>false</c>.
/// </summary>
public bool MergePastedLists

Use Case: Explains how to merge pasted lists with surrounding lists when adding one document to another

Document srcDoc = new Document("src.docx");
Document dstDoc = new Document("dst.docx");

ImportFormatOptions importFormatOptions = new ImportFormatOptions();
importFormatOptions.MergePastedLists = true;
dstDoc.AppendDocument(srcDoc, ImportFormatMode.UseDestinationStyles, importFormatOptions);

dstDoc.Save("out.docx");

Public API for working with textures has been introduced

Related issue: WORDSNET-22002

A new Fill.PresetTextured() public method has been added:

/// <summary>
/// Sets the fill to a preset texture.
/// <param name="presetTexture"><see cref="Drawing.PresetTexture"/></param>
/// </summary>
public void PresetTextured(PresetTexture presetTexture)

A new Fill.PresetTexture public property has been added:

/// <summary>
/// Gets a <see cref="Drawing.PresetTexture"/> for the fill.
/// </summary>
public PresetTexture PresetTexture{ get; }

A new public enum has been introduced:

/// <summary>
/// Specifies texture to be used to fill a shape.
/// </summary>
public enum PresetTexture

Use Case: Explains how to get and apply a texture to a fill

// Open some document with a shape.
Document doc = new Document("DocWithShape.docx");

// Get Fill object for the first shape.
Fill fill = doc.FirstSection.Body.Shapes[0].Fill;

// Check Fill PresetTexture value.
Console.WriteLine("PresetTexture value is: {0}", fill.PresetTexture);

// Apply BrownMarble texture to the shape fill.
fill.PresetTextured(PresetTexture.BrownMarble);

doc.Save("BrownMarble.docx");

TxtSaveOptions.MaxCharactersPerLine property was introduced

Related issue: WORDSNET-22090

The following new public property was added into the TxtSaveOptions class:

/// <summary>
/// Gets or sets an integer value that specifies the maximum number of characters per one line.
/// The default value is 0, that means no limit.
/// </summary>
public int MaxCharactersPerLine { get; set; }

Use Case: Explains how to limit maximum characters per line in output document of TXT format:

Document doc = new Document("input.docx");

TxtSaveOptions saveOptions = new TxtSaveOptions();
// Set 60 characters as maximum allowed per one line.
saveOptions.MaxCharactersPerLine = 60;

doc.Save("out.txt", saveOptions);