Alternative Text

To assist visually impaired individuals in understanding the content of shapes, users can add alternative text (alt text) to shapes. When content is accessed using a screen reader, this associated alternative text is identified and read aloud, enabling users to better understand the shape’s purpose or meaning.

DsExcel Java provides the setTitle, setAlternativeText, and setDecorative methods of the IShape interface, which are used to set the title and content of a shape’s alternative text, or to indicate whether the shape is decorative.

Method	Description
setTitle	Sets the title for the alternative text of a shape.
setAlternativeText	Sets the main content for the shape's alternative text.
setDecorative	Indicates whether the shape is decorative. When set to true, the shape is marked as decorative and will generally be ignored by screen readers. Setting the setAlternativeText method to a non-empty string automatically sets Decorative to false. Setting the setDecorative method to true clears the alternative text. Default value: false.

Method

Description

setTitle

Sets the title for the alternative text of a shape.

setAlternativeText

Sets the main content for the shape's alternative text.

setDecorative

Indicates whether the shape is decorative. When set to true, the shape is marked as decorative and will generally be ignored by screen readers.

Setting the setAlternativeText method to a non-empty string automatically sets Decorative to false.
Setting the setDecorative method to true clears the alternative text.

Default value: false.

Shapes, as well as pictures, charts, slicers, group shapes, linked pictures, and controls support alternative text.
SpreadJS does not support the setDecorative method. If a file has the setDecorative method set and is exported to SJS or SSJSON format, the Decorative setting will not be retained.

Add Alternative Text

Refer to the following sample code to add alternative text to a shape.

// Create a new workbook.
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getActiveSheet();

// Add a rounded rectangle shape.
IShape shape = worksheet.getShapes().addShape(AutoShapeType.RoundedRectangle, 10, 10, 200, 100);

// Set alternative text.
shape.setTitle("Test Shape");
shape.setAlternativeText("This is a rounded rectangle.");

// Save to an excel file.
workbook.save("SetShapeAltText.xlsx");

The output is shown in the figure below:

image-20250430-020659

Mark as Decorative

Refer to the following sample code to mark the shape as decorative.

// Create a new workbook.
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.getActiveSheet();

// Add a rounded rectangle shape.
IShape shape = worksheet.getShapes().addShape(AutoShapeType.RoundedRectangle, 10, 10, 200, 100);

// Set alternative text.
shape.setTitle("Test Shape");
shape.setAlternativeText("This is a rounded rectangle.");

// When a shape is marked as decorative, the alternative text will be cleared.
shape.setDecorative(true); 

// Save to an excel file.
workbook.save("SetShapeAltText.xlsx");

The output is shown in the figure below:

image-20250430-013735