Document Solutions for Excel, .NET Edition | Document Solutions
Features / Shapes and Pictures
In This Topic
    Shapes and Pictures
    In This Topic

    DsExcel .NET allows you to embed drawing objects like shapes and pictures on cells of a worksheet. You can work with shape and picture by accessing the properties and methods of the IShape interface and the IShapes interface.

    With DsExcel library, you can create different shape types such as Connector, Shape and Picture.


    A connector is used when you need to connect or disconnect two general shapes. In DsExcel, you can add connectors at specific coordinates or a specific range of a worksheet using the AddConnector method. You can also use the BeginConnect method, EndConnect method, BeginDisconnect method and EndDisconnect method of the IConnectorFormat interface to attach and detach the ends of the connector to other shapes.

    Refer to the following code to connect general shapes using the connector format. You can add a Connector by providing the connector position in points, or add a connector directly to a range.

    Copy Code
    // To config the connector shape.
    // Add shapes using points
    IShape shapeBegin = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, 1, 1, 100, 100);
    IShape endBegin = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, 200, 200, 100, 100);
    //Add connector for shapeBegin and endShape, by providing connector position in points
    IShape connectorShape = worksheet.Shapes.AddConnector(ConnectorType.Straight, 1, 1, 101, 101);
    connectorShape.Width = 10;
    // To detach the ends of the connector to other shapes.
    connectorShape.ConnectorFormat.BeginConnect(shapeBegin, 3);
    connectorShape.ConnectorFormat.EndConnect(endBegin, 0);
    // Add shape using range
    IShape rectangle3 = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, worksheet.Range["B12"]);
    IShape rectangle4 = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, worksheet.Range["D12"]);
    //Add connector for rectangle3 and rectangle4, by adding connector directly to a range
    IShape rangeConnectorShape = worksheet.Shapes.AddConnector(ConnectorType.Curve, worksheet.Range["B12:D12"]);

    Note: One of the limitations of using connector format is that you can add a connector to connect two general shapes and export it but the connector will be shown only after you drag the shape to your spreadsheet.


    A shape is a drawing object and a member of the Shapes collection. In DsExcel, the Shapes collection represents the collection of shapes in a specified worksheet. All the drawing objects including chart, comment, picture, slicer, general shape and shape group are defined as Shape.

    A name can also be assigned to a shape, be it a chart, picture, connector or any autoshape, by using different methods provided in IShapes interface. By assigning a name to a shape, it be directly accessed and its properties can be modified rather than traversing through the list of all shapes.

    To add shapes in a DsExcel worksheet, you can use AddShape method of the IShapes interface. The method provides overloads which allow you to add variety of shapes at a specified position or to a specified range.

    Refer to the below example code to add shapes at a particular position and to a specific range:
    Copy Code
    Workbook workbook = new Workbook();
    // Fetch default worksheet
    IWorksheet worksheet = workbook.Worksheets[0];
    // Create shape with custom name at a specific position
    IShape shape = worksheet.Shapes.AddShape("Balloon", AutoShapeType.Balloon, 50, 50, 100, 200);
    // Add shape to a range
    // IShape rangeShape = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, worksheet.Range["F5:I10"]);
    // Save to an excel file

    Refer to the below example code to assign a name to a chart.

    Copy Code
     //create a new workbook
     Workbook workbook = new Workbook();
     IWorksheet worksheet = workbook.Worksheets[0];
     //set chart name
     IShape shape = worksheet.Shapes.AddChart("Area chart with custom name", ChartType.Area, 250, 20, 360, 230);
     worksheet.Range["A1:C13"].Value = new object[,] {
    { null, "Blue Series", "Orange Series" },
    { "Jan", 0, 59.1883603948205 },
    { "Feb", 44.6420211591501, 52.2280901938606 },
    { "Mar", 45.2174930051225, 49.8093056416248 },
    { "Apr", 62, 37.3065749226828 },
    { "May", 53, 34.4312192530766 },
    { "Jun", 31.8933622049831, 69.7834561753736 },
    { "Jul", 41.7930895085093, 63.9418103906982 },
    { "Aug", 73, 57.4049534494926 },
    { "Sep", 49.8773891668518, 33 },
    { "Oct", 50, 74 },
    { "Nov", 54.7658428630216, 22.9587876597096 },
    { "Dec", 32, 54 },
     //Get chart by name
     IShape areaChart = worksheet.Shapes["Area chart with custom name"];
     areaChart.Chart.SeriesCollection.Add(worksheet.Range["A1:C13"], RowCol.Columns);
     areaChart.Chart.ChartTitle.Text = "Area Chart";
     //save to an excel file


    You can insert pictures on cells of a spreadsheet by using AddPicture method of the IShapes interface. The method allows you to add a picture at a specific location or to a specific range. The IPictureFormat interface in DsExcel allows users to customize and format pictures while working in a spreadsheet.

    Refer to the following example code when working with picture in DsExcel:

    Copy Code
    // Add a picture through stream
    string path = @"Images\flower.jpg";
    FileStream stream = System.IO.File.Open(path, FileMode.Open);
    IShape picture = worksheet.Shapes.AddPicture(stream, ImageType.JPG, 480, 10, 100, 100);
    // Add a picture through file at specific location
    // IShape picture = worksheet.Shapes.AddPicture(@"Images\flower.jpg", 480, 10, 100, 100);
    // Add a picture to a specific range 
    // IShape pictureInRange = worksheet.Shapes.AddPicture("flower.jpg", worksheet.Range["D3:F5"]);
    // Fill the inserted picture
    picture.Fill.Color.RGB = Color.AliceBlue;
    //Customize the inserted picture
    picture.PictureFormat.Crop.PictureWidth = 80;

    Refer to the below example code to assign a name to a picture.

    Copy Code
    Workbook workbook = new Workbook();
    // Fetch default worksheet
    IWorksheet worksheet = workbook.Worksheets[0];
    //add picture with custom name
    IShape shape = worksheet.Shapes.AddPicture("Custom Name to Image", "image.png", 10, 10, 250, 150);
    //save to an excel file

    To view the code in action, see Add shape to range and Add picture to range demos.

    Working with shapes and pictures in the DsExcel library involves the following tasks:

    Customize Shape Format and Shape Text

    Hyperlink on Shape

    Group or Ungroup Shapes

    Shape Adjustment

    Background Image

    Size and Position of Image

    Image Transparency

    Control Position of Overlapping Shapes

    Linked Picture


    • DsExcel.NET also provides support for loading and saving SpreadJS JSON files with shapes. For more information, refer to Import and Export JSON Stream.
    • The targetRange and the shape to be added must exist in the same worksheet. Otherwise, it results into an InvalidOperationException.
    See Also