Work with Shapes — Presentation API for Java

• Sep 01, 2026
• 11 minutes to read

Shapes are the primary visual elements in a presentation. The DevExpress Presentation API allows you to create, customize, arrange, connect, group, and remove shapes programmatically.

Shape API Basics

Slide masters, slide layouts, and slides store shapes in their IShapeCollection. Use the getShapes() method to access the shape collection.

Each item in the collection can be one of the following types:

• Shape — A preset or custom geometric shape (rectangle, star, arrow, etc.).
• PictureShape — A shape that displays an embedded image.
• GroupShape — A container that groups multiple shapes. Grouped shapes can be transformed as a single unit.
• ConnectorShape — A line or curve that links two shapes at defined connection points.
• Table — A shape for tabular data presentation.

The following code snippet retrieves shapes from a slide’s getShapes() collection and casts them to their corresponding types:

Java

// Retrieve the first shape and cast it to a Shape object.
Shape shape = (Shape)slide.getShapes().getFirst();

// Retrieve the third shape and cast it to a ConnectorShape object.
ConnectorShape connector = (ConnectorShape)slide.getShapes().get(2);

// Retrieve the fourth shape and cast it to a PictureShape object.
PictureShape picture = (PictureShape)slide.getShapes().get(3);

Add a Shape

To add a shape to a slide, create a Shape object and add it to Slide.getShapes(). Pass the shape type to the constructor. The ShapeType enumeration lists available preset shapes.

Use the following methods to customize a shape:

Method	Description
setX(float value)	Specifies the horizontal position of the shape’s bounding box.
setY(float value)	Specifies the vertical position of the shape’s bounding box.
setWidth(float value)	Specifies the shape width.
setHeight(float value)	Specifies the shape height.
setOutline(LineStyle value)	Specifies outline settings.
setFill(Fill value)	Specifies fill settings.

Note

Position and size values are measured in document units (1/300 inch). The point (0, 0) corresponds to the slide’s upper-left corner.

The following code snippet adds a star shape to a slide:

Java

// Get the first slide.
Slide slide = presentation.getSlides().getFirst();

// Create a new shape (5-point star).
Shape shape = new Shape(ShapeType.getStar5());

// Create and configure the shape outline (stroke).
LineStyle lineStyle = new LineStyle();
// Set outline color to dark red.
lineStyle.setFill(new SolidFill(Color.getDarkRed()));
// Set outline thickness (in document units).
lineStyle.setWidth(4);

// Apply outline settings to the shape.
shape.setOutline(lineStyle);

// Set the fill color of the shape to coral.
shape.setFill(new SolidFill(Color.getCoral()));

// Set the shape's position and size.
shape.setX(30);
shape.setY(30);
shape.setWidth(800);
shape.setHeight(800);

// Add the configured shape to the slide.
slide.getShapes().add(shape);

Picture Shapes

To insert a picture, do the following:

1. Create a PictureShape.
2. Assign the picture using the PictureShape.setImage() method.
3. Add the shape to the slide.

The following code snippet loads an image from a file, creates a PictureShape, configures its size and position, and adds it to a slide.

Java

import com.devexpress.docs.*;
import com.devexpress.docs.presentation.*;
import java.io.*;

// Create a presentation.
try(Presentation presentation = new Presentation()) {
    // Get the first slide.
    Slide slide = presentation.getSlides().getFirst();

    // Create a new PictureShape.
    PictureShape pictureShape = new PictureShape();

    // Load image data from a file.
    try(
            FileInputStream stream = new FileInputStream("images/devexpress-logo.png");
            DXImage image = DXImage.fromStream(stream);
    ) {

        pictureShape.setImage(new OfficeImage(image));
    }

    // Set the width, height, and X-Y-coordinates of the picture (in document units).
    pictureShape.setWidth(250);
    pictureShape.setHeight(250);
    pictureShape.setX(40);
    pictureShape.setY(40);

    // Add the picture shape to the slide's shape collection.
    slide.getShapes().add(pictureShape);

    // Your additional implementation goes here.
}

Custom Shapes

Custom shapes are defined using geometry paths composed of primitive drawing commands.

To create a custom shape, do the following:

1. Create a ShapeGeometry object and pass it to the Shape constructor.
2. Create ShapePath objects and add them to ShapeGeometry.getPaths().

Supported path segments:

• PathArc
• PathClose
• PathCubicBezier
• PathLine
• PathMove
• PathQuadraticBezier

The following code snippet creates a custom Pythagorean triangle shape and adds it to a slide:

Java

// Define a path with a 1000×1000 coordinate system.
ShapePath path = new ShapePath(1000, 1000, true);

// Move to the top-left vertex (right angle corner).
path.getSegments().add(
        new PathMove(
                new AdjustCoordinate(0),
                new AdjustCoordinate(0)));

// Draw line to bottom-left vertex (vertical leg).
path.getSegments().add(
        new PathLine(
                new AdjustCoordinate(0),
                new AdjustCoordinate(1000)));

// Draw line to bottom-right vertex (hypotenuse endpoint).
path.getSegments().add(
        new PathLine(
                new AdjustCoordinate(1000),
                new AdjustCoordinate(1000)));

// Close the triangle back to the starting point.
path.getSegments().add(new PathClose());

// Set fill mode for the triangle interior.
path.setFillMode(FillMode.NORMAL);

// Add path to geometry.
ShapeGeometry geometry = new ShapeGeometry();
geometry.getPaths().add(path);

// Create a shape based on custom geometry.
Shape rightTriangle = new Shape(
        new ShapeType(geometry),
        100,    // X position
        100,    // Y position
        1000,   // Width
        1000);  // Height

// Apply fill color.
rightTriangle.setFill(new SolidFill(Color.getLightSkyBlue()));

// Add shape to slide.
slide.getShapes().add(rightTriangle);

Group Shapes

Grouping allows you to apply transformations and effects to multiple shapes as a single unit.

Create a Group

To create a shape group, create a GroupShape and add shapes to its IShapeCollection. Use the group.getShapes() method to access the collection.

The following code snippet creates two shapes and groups them:

Java

// Create the first shape (12-point star).
Shape shape1 = new Shape(ShapeType.getStar12());

// Configure outline settings.
LineStyle lineStyle = new LineStyle();
lineStyle.setFill(new SolidFill(Color.getDarkGreen()));
lineStyle.setWidth(4);

// Apply outline to the shape.
shape1.setOutline(lineStyle);
shape1.setFill(new SolidFill(Color.getYellow()));

// Position and size of the first shape on the slide.
shape1.setX(200);
shape1.setY(200);
shape1.setWidth(800);
shape1.setHeight(800);

// Create the second shape (10-point star).
Shape shape2 = new Shape(ShapeType.getStar10());
LineStyle lineStyle2 = new LineStyle();
lineStyle2.setFill(new SolidFill(Color.getBlack()));
lineStyle2.setWidth(4);
shape2.setOutline(lineStyle2);

// Use group fill so the shape inherits fill from its parent group.
shape2.setFill(new GroupFill());

// Position and size of the second shape.
shape2.setX(900);
shape2.setY(900);
shape2.setWidth(800);
shape2.setHeight(800);

// Create a group shape to combine shapes.
GroupShape group = new GroupShape();
group.setName("stars");

// Set group-level fill (applies to child shapes using GroupFill).
group.setFill(new SolidFill(Color.getDarkMagenta()));

// Position and size of the group container.
group.setX(200);
group.setY(200);
group.setWidth(1800);
group.setHeight(1800);

// Add shapes to the group.
group.getShapes().add(shape1);
group.getShapes().add(shape2);

// Add the group to the slide.
slide.getShapes().add(group);

Tip

A shape can inherit its fill from the parent group. Assign a GroupFill instance to the shape using the setFill method.

Ungroup Shapes

To ungroup shapes, move them back to the slide and remove the group:

Java

// Find the group shape named "stars" and ungroup its contents.
GroupShape targetGroup = null;

for (ShapeBase shapeBase : slide1.getShapes()) {
    if (shapeBase instanceof GroupShape groupShape
            && "stars".equals(groupShape.getName())) {
        targetGroup = groupShape;
        break;
    }
}

// If the group was found, move its children to the slide and remove the group.
if (targetGroup != null) {
    for (ShapeBase child : targetGroup.getShapes()) {
        slide.getShapes().add(child);
    }

    slide.getShapes().remove(targetGroup);
}

Connect Shapes

Connectors link two shapes using defined connection points.

To add a connector between shapes:

1. Create a ConnectorShape object.
2. Add it to the slide’s shape collection.

The following table lists the connector configuration API:

Method	Description
setStartShape(FilledShape value)	Specifies the start shape.
setEndShape(FilledShape value)	Specifies the end shape.
setStartShapeSiteIndex(int value)	Specifies the start connection point index.
setEndShapeSiteIndex(int value)	Specifies the end connection point index.
setType(ConnectorShapeType value)	Specifies connector type.
setOutline(LineStyle value)	Specifies the connector’s outline settings.

Tip

Connection site indexes start at the top (0) and increase counterclockwise. Use the ShapeGeometry.getConnectionSites() method to determine available points.

The following code snippet creates two shapes (rectangle and diamond), adds them to a slide, and connects them with a curved connector. The connector is attached to specific connection points on each shape and configured with a red outline.

Java

// Create a presentation.
try(Presentation presentation = new Presentation()) {
    // Create the first shape
    Shape shape1 = new Shape(ShapeType.getRectangle()) {{
        setX(30);
        setY(30);
        setWidth(800);
        setHeight(800);
    }};

    // Create the second shape
    Shape shape2 = new Shape(ShapeType.getDiamond()) {{
        setX(1200);
        setY(1200);
        setWidth(800);
        setHeight(800);
    }};

    Slide slide = new Slide(SlideLayoutType.BLANK);

    // Add shapes to the slide
    slide.getShapes().add(shape1);
    slide.getShapes().add(shape2);

    // Configure connector outline
    LineStyle style = new LineStyle();
    style.setFill(new SolidFill(Color.getRed()));
    style.setWidth(6);

    // Create a curved connector between the shapes
    ConnectorShape connector = new ConnectorShape() {{
        setStartShape(shape1);
        setEndShape(shape2);
        setStartShapeSiteIndex(2);
        setEndShapeSiteIndex(0);
        setType(ConnectorShapeType.CURVED);
        setOutline(style);
    }};

    // Add connector to the slide
    slide.getShapes().add(connector);

    presentation.getSlides().add(slide);

    // Your additional implementation goes here.
}

Iterate Through Shapes in a Slide

Iterate through all shapes on a slide to access and process individual slide elements (such as text boxes, images, and graphic objects).

The following code snippet iterates through all shapes on the first slide, outputs each shape’s name, and prints its placeholder type if the shape is a placeholder:

import com.devexpress.docs.presentation.*;
import java.nio.file.*;

public class Main {
    public static void main(String[] args) throws Exception {
        Path path = Path.of("presentation.pptx");
        try (Presentation presentation =
                     new Presentation(Files.readAllBytes(path))) {

            // Get the first slide in the presentation.
            Slide slide1 = presentation.getSlides().getFirst();

            // Iterate through all shapes on the slide.
            for(ShapeBase shapeBase : slide1.getShapes()) {
                System.out.println("Shape Name: " + shapeBase.getName());

                // ShapeBase may represent different shape types.
                // Cast is required only when accessing type-specific properties.
                if(shapeBase instanceof Shape shape && shape.getPlaceholderSettings() != null) {
                    System.out.println("Shape Placeholder Type: " +
                            shape.getPlaceholderSettings().getType());
                }
            }
        }
    }
}

Process Shapes of a Specific Type

The following code snippet iterates through shapes on a slide and processes only text-based shapes:

import com.devexpress.docs.presentation.*;
import java.nio.file.*;

public class Main {
    public static void main(String[] args) throws Exception {
        Path path = Path.of("presentation.pptx");

        try (Presentation presentation =
                     new Presentation(Files.readAllBytes(path))) {

            // Get the first slide in the presentation
            Slide slide = presentation.getSlides().getFirst();

            // Process only the title shape
            for (ShapeBase shapeBase : slide.getShapes()) {

                if (shapeBase instanceof Shape shape &&
                        shape.getPlaceholderSettings() != null &&
                        shape.getPlaceholderSettings().getType() == PlaceholderType.CENTERED_TITLE) {

                    // Read and output the slide title text.
                    String title = shape.getTextArea().getText();
                    System.out.println("Slide Title: " + title);
                }
            }
        }
    }
}

Reorder Shapes

Shape order in the collection determines stacking (z-order).

Use the following methods to rearrange shapes within the collection.

Method	Description
sendToBack()	Moves a shape behind all other shapes on the slide.
sendBackward()	Moves a shape one level backward in the stacking order.
bringToFront()	Moves a shape in front of all other shapes on the slide.
bringForward()	Moves a shape one level forward in the stacking order.
move()	Moves a shape to the specified position within the collection.

The following code snippet reorders shapes on a slide:

Java

// Move the specified shape behind all other shapes.
slide.getShapes().sendToBack(shape1);
// Move the shape at index 0 behind all other shapes.
slide.getShapes().sendToBack(0);

// Move the specified shape one level backward.
slide.getShapes().sendBackward(shape2);
// Move the shape at index 1 one level backward.
slide.getShapes().sendBackward(1);

// Move the specified shape one level forward.
slide.getShapes().bringForward(shape3);
// Move the shape at index 2 one level forward.
slide.getShapes().bringForward(2);

// Move the specified shape in front of all other shapes.
slide.getShapes().bringToFront(shape4);
// Move the shape at index 3 in front of all other shapes.
slide.getShapes().bringToFront(3);

// Move the specified shape to the beginning of the collection.
slide.getShapes().move(shape5, 0);
// Move the shape at index 4 to index 0.
slide.getShapes().move(4, 0);

Warning

An exception is thrown if the specified shape does not belong to the collection or if the specified index is outside the bounds of the collection.

Remove Shapes

Java

slide.getShapes().remove(shape);
slide.getShapes().remove(0);
slide.getShapes().clear();

Visual Effects

You can apply different visual effects to shapes. Use the getEffects() method to access effect settings (EffectProperties).

Supported effects include:

• getBlur()
• getEffect3D()
• getFillOverlay()
• getGlow()
• getInnerShadow()
• getOuterShadow()
• getPresetShadow()
• getReflection()
• getSoftEdge()

The following code snippet adds a shadow to a shape:

Java

// Create a rectangle shape.
Shape shape = new Shape(ShapeType.getRectangle());

// Customize shape outline.
LineStyle lineStyle = new LineStyle();
lineStyle.setFill(new SolidFill(Color.getDarkRed()));
lineStyle.setWidth(4);
shape.setOutline(lineStyle);

// Configure shape fill.
shape.setFill(new SolidFill(Color.getLightGreen()));

// Set shape position and size.
shape.setX(300);
shape.setY(300);
shape.setWidth(800);
shape.setHeight(800);

// Configure visual effects.
ShapeEffectProperties effects = new ShapeEffectProperties();

// Create outer shadow effect.
OuterShadowEffect outerShadow = new OuterShadowEffect();
outerShadow.setColor(
    new OfficeColor(Color.getGray()));  // Shadow color
outerShadow.setBlurRadius(50);          // Blur radius of the shadow
outerShadow.setHorizontalScale(120);    // Horizontal scaling of the shadow
outerShadow.setVerticalScale(120);      // Vertical scaling of the shadow

// Attach shadow effect to shape effects.
effects.setOuterShadow(outerShadow);

// Apply effects to the shape.
shape.setEffects(effects);

// Add the shape to the slide.
slide.getShapes().add(shape);

Lock Settings

Lock settings control user interaction with shapes in presentation editors.

The DevExpress Presentation API includes additional lock settings for shapes, group shapes, picture shapes, and connectors. Each shape type exposes a corresponding lock settings class through getLockSettings():

Shape Type	Lock Settings Class
Shape	ShapeLockSettings
GroupShape	GroupLockSettings
PictureShape	PictureLockSettings
ConnectorShape	ConnectorLockSettings

The following code snippet locks specific user operations for different shape types:

Java

import com.devexpress.docs.presentation.*;

// Configure shape lock settings.
ShapeLockSettings shapeLocks = shape.getLockSettings();
shapeLocks.setDisableTextEdit(true);
shapeLocks.setDisableHandles(true);
shapeLocks.setDisableRotation(true);

// Configure group lock settings.
GroupLockSettings groupLocks = groupShape.getLockSettings();
groupLocks.setDisableGrouping(true);
groupLocks.setDisableMoving(true);

// Configure picture lock settings.
PictureLockSettings pictureLocks = pictureShape.getLockSettings();
pictureLocks.setDisableCropping(true);
pictureLocks.setDisableResize(true);

// Configure connector lock settings.
ConnectorLockSettings connectorLocks = connector.getLockSettings();
connectorLocks.setDisableResize(true);
connectorLocks.setDisableRotation(true);
connectorLocks.setDisableSelection(true);

Inherit Shapes from Master Slides and Layouts

Slides can inherit shapes from slide masters and slide layouts. Placeholder shapes can be populated with content at the slide level.

Refer to the following help topic for additional information: Configure Slide Masters and Layouts.

Format Shape Text

Refer to the following help topic for information on formatting shape text: Work with Text in Shapes.