Browse our Products

Aspose.Words for Java 23.4 Release Notes

Major Features

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

  • Added an ability to set distance between table and surrounding text.
  • Provided an ability to determine whether a Run is a phonetic guide run.
  • Implemented the simple way to work with series and axes of a combo charts.
  • Provided the new public properties connected to the shape relative positioning and sizing.
  • Improved accuracy and performance of color brightness calculation for automatic text color resolution in accordance with the latest versions of MS Word.

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.4. 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 ability to set distance between table and surrounding text

Related issue: WORDSNET-25164

Now you can set the following properties of the Table class:

/// <summary>
/// Gets or sets distance between table left and the surrounding text, in points.
/// </summary>
public double DistanceLeft { get; set; }

/// <summary>
/// Gets or sets distance between table right and the surrounding text, in points.
/// </summary>
public double DistanceRight { get; set; }

/// <summary>
/// Gets or sets distance between table top and the surrounding text, in points.
/// </summary>
public double DistanceTop { get; set; }

/// <summary>
/// Gets or sets distance between table bottom and the surrounding text, in points.
/// </summary>
public double DistanceBottom { get; set; }

Please note: setting these properties makes the table floating.

Document doc = new Document("input.docx");
Table table = doc.FirstSection.Body.Tables[0];

// Set distance between table and surrounding text.
table.DistanceLeft = 24;
table.DistanceRight = 24;
table.DistanceTop = 3;
table.DistanceBottom = 3;

doc.Save("output.docx");

Added public property GradientStop.BaseColor

Related issue: WORDSNET-24937

The following public property was added to the Aspose.Words.Drawing.GradientStop class:

/// <summary>
/// Gets a value representing the color of the gradient stop without any modifiers.
/// </summary>
public Color BaseColor { get; }
DocumentBuilder builder = new DocumentBuilder();
Shape shape = builder.InsertShape(ShapeType.Balloon, 300, 300);

// Set stroke thickness to 7pt.
shape.Stroke.Weight = 7;

// Fill the stroke with one-color gradient.
shape.Stroke.Fill.OneColorGradient(Color.Red, GradientStyle.Horizontal, GradientVariant.Variant1, 0.1);

// In OneColorGradient the second color is set automatically by adding to the first color either tint or shade.
// So, we can check unmodified color is actually those we set to the first color.
GradientStop gradientStop = shape.Stroke.Fill.GradientStops[1];
Console.WriteLine("The color is: {0}", gradientStop.Color);
Console.WriteLine("The base (unmodified) color is: {0}", gradientStop.BaseColor);

/* This code produces the following output:
The color is: Color [A=255, R=51, G=0, B=0]
The base (unmodified) color is: Color [A=255, R=255, G=0, B=0]
*/

Added public property Run.IsPhoneticGuide

Related issue: WORDSNET-24973

The following public property was added to the Aspose.Words.Run class:

/// <summary>
/// Gets a boolean value indicating either the run is a phonetic guide.
/// </summary>
public bool IsPhoneticGuide { get; }
DocumentBuilder builder = new DocumentBuilder();

builder.Write("text");

Run run = builder.Document.FirstSection.Body.FirstParagraph.Runs[0];
Console.WriteLine("The phonetic guide value of the run is '{0}'", run.IsPhoneticGuide);

/* This code produces the following output:
The phonetic guide value of the run is 'False'
*/

Added public property Stroke.Fill

Related issue: WORDSNET-24937

The following public property was added to the Aspose.Words.Drawing.Stroke class:

/// <summary>
/// Gets fill formatting for the <see cref="Stroke"/>.
/// </summary>
public Fill Fill { get; }
DocumentBuilder builder = new DocumentBuilder();
Shape shape =  builder.InsertShape(ShapeType.Balloon, 300, 300);

// Set stroke thickness to 7pt.
shape.Stroke.Weight = 7;

// Fill the stroke with two-color gradient.
shape.Stroke.Fill.TwoColorGradient(Color.Red, Color.Blue, GradientStyle.Vertical, GradientVariant.Variant1);

builder.Document.Save("GradientStroke.docx");

Improvements in Chart class for Combo charts

Related issue: WORDSNET-24908

The following changes have been implemented:

  • A ChartSeriesCollection instance returned by the Chart.Series property includes all series of a combo chart, not just those of a main chart type.
  • Implemented the ChartAxisCollection class. Added the Chart.Axes property of this type, which allows access to all axes of a combo chart.
/// <summary>
/// Gets a collection of all axes of this chart.
/// </summary>
public ChartAxisCollection Axes { get; }
/// <summary>
/// Represents a collection of chart axes.
/// </summary>
public class ChartAxisCollection : IEnumerable<ChartAxis>
{
    /// <summary>
    /// Gets the axis at the specified index.
    /// </summary>
    public ChartAxis this[int index] { get; }

    /// <summary>
    /// Gets the number of axes in this collection.
    /// </summary>
    public int Count { get; }
}
Document doc = new Document("ComboChart.docx");
NodeCollection shapes = doc.GetChildNodes(NodeType.Shape, true);
Chart chart = ((Shape)shapes[0]).Chart;

// Show markers in the line series named 'Series 3'.
foreach (ChartSeries series in chart.Series)
{
    if (series.Name == "Series 3")
    {
        series.Marker.Symbol = MarkerSymbol.Circle;
        series.Marker.Size = 18;
        break;
    }
}

// Hide the major grid lines on the primary and secondary Y axes.
foreach (ChartAxis axis in chart.Axes)
{
    if (axis.Type == ChartAxisType.Value)
        axis.HasMajorGridlines = false;
}

doc.Save("output.docx");

New public properties for working with the shape relative positioning and sizing have been added

Related issue: WORDSNET-24502

New public properties RelativeHorizontalSize and RelativeVerticalSize for specifying the relative size binding of the shape have been added to the Shape class:

/// <summary>
/// Gets or sets the value of shape's relative size in horizontal direction.
/// </summary>
public RelativeHorizontalSize RelativeHorizontalSize { get; set; }

/// <summary>
/// Gets or sets the value of shape's relative size in vertical direction.
/// </summary>
public RelativeVerticalSize RelativeVerticalSize { get; set; }

New public properties HeightRelative and WidthRelative for specifying the shape relative size in percent have been added to the Shape class:

/// <summary>
/// Gets or sets the value that represents the percentage of shape's relative height.
/// </summary>
public float HeightRelative { get; set; }

/// <summary>
/// Gets or sets the value that represents the percentage of shape's relative width.
/// </summary>
public float WidthRelative { get; set; }

New public properties LeftRelative and TopRelative for specifying the shape relative position in percent have been added to the Shape class:

/// <summary>
/// Gets or sets the value that represents shape's relative left position in percent.
/// </summary>
public float LeftRelative { get; set; }

/// <summary>
/// Gets or sets the value that represents shape's relative top position in percent.
/// </summary>
public float TopRelative { get; set; }

New public enums RelativeHorizontalSize and RelativeVerticalSize have been introduced:

/// <summary>
/// Specifies relatively to what the width of a shape or a text frame is calculated horizontally.
/// </summary>
public enum RelativeHorizontalSize

/// <summary>
/// Specifies relatively to what the height of a shape or a text frame is calculated vertically.
/// </summary>
public enum RelativeVerticalSize
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);

// Adding a simple shape with absolute size and position.
Shape shape = builder.InsertShape(ShapeType.Rectangle, 100, 40);
// Set WrapType to WrapType.None since Inline shapes are automatically converted to absolute units.
shape.WrapType = WrapType.None;

// Checking and setting the relative horizontal size.
if (shape.RelativeHorizontalSize == RelativeHorizontalSize.Default)
{
    // Setting the horizontal size binding to Margin.
    shape.RelativeHorizontalSize = RelativeHorizontalSize.Margin;
    // Setting the width to 50% of Margin width.
    shape.WidthRelative = 50;
}

// Checking and setting the relative vertical size.
if (shape.RelativeVerticalSize == RelativeVerticalSize.Default)
{
    // Setting the vertical size binding to Margin.
    shape.RelativeVerticalSize = RelativeVerticalSize.Margin;
    // Setting the height to 30% of Margin height.
    shape.HeightRelative = 30;
}

// Checking and setting the relative vertical position.
if (shape.RelativeVerticalPosition == RelativeVerticalPosition.Paragraph)
{
    // Setting the position binding to TopMargin.
    shape.RelativeVerticalPosition = RelativeVerticalPosition.TopMargin;
    // Setting relative Top to 30% of TopMargin position.
    shape.TopRelative = 30;
}

// Checking and setting the relative horizontal position.
if (shape.RelativeHorizontalPosition == RelativeHorizontalPosition.Default)
{
    // Setting the position binding to RightMargin.
    shape.RelativeHorizontalPosition = RelativeHorizontalPosition.RightMargin;
    // The position relative value can be negative.
    shape.LeftRelative = -260;
}

doc.Save("output.docx");

Removed obsolete property JsonDataLoadOptions.ExactDateTimeParseFormat

The obsolete property JsonDataLoadOptions.ExactDateTimeParseFormat has been removed. Please use the JsonDataLoadOptions.ExactDateTimeParseFormats property instead.

/// <summary>
/// Gets or sets exact formats for parsing JSON date-time values while loading JSON. The default is <c>null</c>.
/// </summary>
/// <remarks>
/// <para>
/// Strings encoded using Microsoft® JSON date-time format (for example, "/Date(1224043200000)/") are always 
/// recognized as date-time values regardless of a value of this property. The property defines additional 
/// formats to be used while parsing date-time values from strings in the following way:
/// </para>
/// <list type="bullet">
/// <item>
/// When <see cref="ExactDateTimeParseFormats"/> is <c>null</c>, the ISO-8601 format and all date-time formats 
/// supported for the current, English USA, and English New Zealand cultures are used additionally in 
/// the mentioned order.
/// </item>
/// <item>
/// When <see cref="ExactDateTimeParseFormats"/> contains strings, they are used as additional date-time
/// formats utilizing the current culture.
/// </item>
/// <item>
/// When <see cref="ExactDateTimeParseFormats"/> is empty, no additional date-time formats are used.
/// </item>
/// </list>
/// </remarks>
public IEnumerable<string> ExactDateTimeParseFormats
{
    get { return mExactDateTimeParseFormats; }
    set { mExactDateTimeParseFormats = value; }
}
const string dateTimeParseFormat = "dd.MM.yy";
JsonDataLoadOptions options = new JsonDataLoadOptions();

//options.ExactDateTimeParseFormat = dateTimeParseFormat;
List<string> formats = new List<string> { dateTimeParseFormat };
options.ExactDateTimeParseFormats = formats;

JsonDataSource dataSource = new JsonDataSource(stream, options);