[]
DsExcel allows you to insert various types of shapes into worksheet cells, including standard shapes, connector shapes, picture shapes, and group shapes. You can manage and manipulate these shapes consistently using the properties and methods of the IShape interface and the IShapes interface.
DsExcel provides the AddShape method of the IShapes interface, which supports multiple overloads. This allows you to add various types of shapes at specified positions or within specified cell ranges in a worksheet, as well as set their sizes. You can assign a custom name to each newly created shape, making it easy to directly access and modify the shape’s properties by name, without the need to iterate through the entire shapes collection.
The following example demonstrates how to add a Rectangle shape at a specified position and assign it a name. You can also refer to the AutoShapeType enumeration to add other types of shapes.
// Create a workbook.
Workbook workbook = new Workbook();
IWorksheet worksheet = workbook.Worksheets[0];
// Add a shape with a custom name at a specific position.
IShape shape = worksheet.Shapes.AddShape("Rectangle", AutoShapeType.Rectangle, 50, 50, 100, 150);
// Alternatively, add the shape to a specified range.
// IShape rangeShape = worksheet.Shapes.AddShape(AutoShapeType.Rectangle, worksheet.Range["F5:I10"]);
// Assign a new name and retrieve the shape by its name.
shape.Name = "NewRectangleName";
IShape balloon = worksheet.Shapes["NewRectangleName"];
balloon.TextFrame.TextRange.Text = "Rectangle Shape";
balloon.TextFrame.TextRange.TextAlignment=TextAlignmentAnchor.Center;
// Save the Excel file.
workbook.Save("RectangleShape.xlsx");
The output is shown in the figure below:
Each shape object contains a Type property that indicates the specific type of the shape. This property corresponds to the ShapeType enumeration. By reading the Type property, you can quickly retrieve and identify the type of a shape. (e.g. Callout, Textbox, Line etc.)
The following example demonstrates how to iterate through all shapes in a worksheet and display a type label to the right of each shape. Click here to download the worksheet. ShapeType.xlsx
// Create a new workbook.
var workbook = new GrapeCity.Documents.Excel.Workbook();
// Import the workbook.
var fileStream = this.GetResourceStream("xlsx\\ShapeType.xlsx");
workbook.Open(fileStream);
var sheet = workbook.Worksheets[0];
int row = 2;
int column = 4;
for (int i = 0; i < sheet.Shapes.Count; i++)
{
var shape = sheet.Shapes[i];
// Add a text on the right side of the shape to display the type of the shape.
sheet.Range[row, column].Value = "This is a " + shape.Type.ToString() + ".";
sheet.Range[row, column].Font.Bold = true;
sheet.Range[row, column].Font.Size = 13;
if ((i + 1) % 4 == 0)
{
row = 2;
column += 6;
}
else
{
row += 10;
}
}
// Save to an excel file.
workbook.Save("GetShapeType.xlsx");
The output is shown in the figure below:
The following example demonstrates how to iterate through all the shapes in a worksheet, filter out rectangles from the AutoShapes, and output the pixel-level position information (including top, left, height, and width) for each rectangle. Click here to download the worksheet.AutoShapeType.xlsx
// Create a new workbook.
var workbook = new GrapeCity.Documents.Excel.Workbook();
// Import the workbook.
var fileStream = this.GetResourceStream("xlsx\\AutoShapeType.xlsx");
workbook.Open(fileStream);
var sheet = workbook.Worksheets[0];
// Iterate through all shape objects in the worksheet.
for (int i = 0; i < sheet.Shapes.Count; i++)
{
var shape = sheet.Shapes[i];
if (shape.Type == ShapeType.AutoShape && shape.AutoShapeType == AutoShapeType.Rectangle)
{
// Output the position and size of the rectangle.
Console.WriteLine("Top: " + shape.Top + " , Left: " + shape.Left + " , Height: " + shape.Height + ", Width: " + shape.Width);
}
}
Apart from changing the size of a shape in DsExcel, you can also change the geometry of a shape and modify its appearance. This can be achieved by setting the adjustment values of shapes, such as AutoShapes or Connectors. It allows you to have more control over the shapes in order to create efficient flowcharts, dashboards and reports.
DsExcel provides the Adjustments property in the IShape interface to get a collection of adjustment values for the specified AutoShape or Connector.
The valid ranges of adjustent values for different adjustement types are described below:
Adjustment type | Valid values |
---|---|
Linear (horizontal or vertical) | Value 0.0 represents the left or top edge of the shape. Value 1.0 represents the right or bottom edge of the shape. For shapes such as connectors and callouts, the values 0.0 and 1.0 correspond to the rectangle defined by the starting and ending points of the connector or callout line. Values lesser than 0.0 and greater than 1.0 are also valid. The valid values for the adjustment correspond to the valid adjustments that can be made to shapes in Excel by extending the adjustment points. For example, if you can only pull an adjustment point half way across the shape in Excel, the maximum value for the corresponding adjustment will be 0.5. |
Radial | Value 1.0 represents the shape width. Hence, the maximum value for radial adjustment is 0.5, which is half way across the shape. |
Angle | Value is expressed in degrees. If you specify the value outside the range of 180 degree, it will be normalized to be within that range. |
In most cases, if a value exceeds the valid range, it is normalized to the closest valid value.
Refer to the following example code to adjust the dimensions of a shape in Excel:
public void AdjustmentPointForShape()
{
// Initialize workbook
Workbook workbook = new Workbook();
// Fetch default worksheet
IWorksheet worksheet = workbook.Worksheets[0];
// Add a right arrow callout
IShape shape = worksheet.Shapes.AddShape(AutoShapeType.RightArrowCallout, 20, 20, 200, 100);
IAdjustments adjustments = shape.Adjustments;
// Get the count of adjustment values for shape
int c = adjustments.Count;
Console.WriteLine("Count of Adjustment Values: " + c.ToString());
// Set adjustment values for shapes
adjustments[0] = 0.5;// arrow neck width
adjustments[1] = 0.4;// arrow head width
adjustments[2] = 0.5;// arrow head height
adjustments[3] = 0.6;// text box width
// Saving workbook to Xlsx
workbook.Save(@"AdjustmentPointForShape.xlsx", SaveFileFormat.Xlsx);
}
The order of overlapping shapes in a worksheet is decided by their z-order positions. DsExcel allows its users to set the z-order of shapes so that their positions can be controlled while creating flow charts or business diagrams etc.
The ZOrder method in DsExcel API can be used to move the specified shape in front of or behind the other shapes. It takes ZOrderType enum as a parameter to specify the position of a shape relative to the other shapes.
The ZOrderPosition property of the IShape interface can be used to retrieve the position of a specified shape in the z-order.
!type=note
Note: If the z-order of a shape is changed, the index of the shape in Worksheet.Shapes collection is also changed.
Refer to the below example code to add various shapes, change their z-order and get their positions in z-order in a worksheet.
// Initialize workbook
Workbook workbook = new Workbook();
// Fetch default worksheet
IWorksheet worksheet = workbook.Worksheets[0];
IShapes shapes = worksheet.Shapes;
//add shapes
IShape rectangle = shapes.AddShape(AutoShapeType.Rectangle, 20, 20, 100, 100);
rectangle.Fill.Color.RGB = System.Drawing.Color.Blue;
IShape oval = shapes.AddShape(AutoShapeType.Oval, 50, 50, 100, 100);
oval.Fill.Color.RGB = System.Drawing.Color.Green;
IShape pentagon = shapes.AddShape(AutoShapeType.Pentagon, 80, 80, 100, 100);
pentagon.Fill.Color.RGB = System.Drawing.Color.Red;
IShape triangle = shapes.AddShape(AutoShapeType.IsoscelesTriangle, 100, 100, 100, 100);
triangle.Fill.Color.RGB = System.Drawing.Color.Orange;
//set rectangle above oval
rectangle.ZOrder(ZOrderType.BringForward);
//get position of rectangle in z-order
Console.WriteLine("Z-Order rectangle: " + rectangle.ZOrderPosition);
//set triangle to bottom
triangle.ZOrder(ZOrderType.SendToBack);
//get position of triangle in z-order
Console.WriteLine("Z-Order triangle: " + triangle.ZOrderPosition);
//save to an excel file
workbook.Save("setshapezorder.xlsx");
Note:
DsExcel.NET also provides support for loading and saving SpreadJS JSON files with shapes. For more information, refer to Import and Export SpreadJS Files.
The targetRange and the shape to be added must exist in the same worksheet. Otherwise, it results into an InvalidOperationException.