Shapes, Pictures, Charts
- 4 minutes to read
A worksheet may contain embedded drawing objects - pictures or charts, which implement the base Shape interface. An image in a worksheet is an instance of the Picture class, an embedded chart is an instance of the Chart class. Other shape types are currently not supported.
Note
Not all methods and properties of the base Shape interface are in effect for pictures and charts.
Accessing Shapes
Shapes are contained in the ShapeCollection collection. The collection is accessible using the Worksheet.Shapes property and contains all the shapes (pictures and charts) in a worksheet. The Worksheet.Pictures property gets a collection of all pictures, and the Worksheet.Charts property gets a collection of all charts in a worksheet.
Shape Type
Picture or chart - the shape’s type can be determined by its Shape.ShapeType property. If the type is ShapeType.Picture, you can cast the object to the Picture type and use the Picture.Image property to obtain the shape’s image. If the type is ShapeType.Chart, you can cast the object to the Chart type.
Location
A shape position in a worksheet is determined by the following properties.
| Property | Description |
|---|---|
| FloatingObject.Left | Gets or sets the distance from the left edge of the worksheet to the top left corner of the floating object. |
| FloatingObject.OffsetX | Gets a distance from the top left corner of the floating to the left edge of the cell where the top left corner of the floating object is located. |
| FloatingObject.Top | Gets or sets the distance from the top edge of the worksheet to the top left corner of the floating object. |
| FloatingObject.OffsetY | Gets a distance from the top left corner of the floating object to the top edge of the cell where the top left corner of the floating object is located. |
| FloatingObject.TopLeftCell | Gets or sets a cell where the top left corner of a floating object is located. |
| FloatingObject.BottomRightCell | Gets or sets a cell where the bottom right corner of a floating object is located. |
| Shape.ZOrderPosition | Gets the position of the current shape in the z-order. |
The picture below displays an image which has B3 as its top left cell, C6 as its bottom right cell. Left, Top, X- and Y-Offsets are indicated in the picture.
Use the FloatingObject.Move method to change the location.
Size and Rotation
A shape can be freely resized and rotated.
Utilize the FloatingObject.Height and FloatingObject.Width to specify the shape size. If the Shape.LockAspectRatio option is set to true, the modification of one property results in another property being changed to retain the aspect ratio.
Use the Shape.Rotation property to set the angle to which a shape is rotated, and use the Shape.IncrementRotation method to rotate the shape by a specified number of degrees.
An end-user can resize or rotate a shape with special handles, which are visible for a selected shape.
Placement
A shape may respond when cells underneath it are moved or resized. Shape behavior is determined by the FloatingObject.Placement property. A shape can be moved and resized with cells, or it can float freely.
When a shape is added to a worksheet, the initial placement depends on the specific overload of the PictureCollection.AddPicture method. If a Cell is passed to the method, the shape will move with cells. If a Range is passed to the method, the shape will move and size with cells. If coordinates are specified when an image is inserted in a worksheet, a shape will float freely.
To move a shape in front of or behind other shapes in a worksheet, specify its Shape.ZOrderPosition property relative to other shapes. When shapes are added to the Worksheet.Shapes collection, the ZOrderPosition gets its value incremented by one starting from 1. You can increase the ZOrderPosition property value to move the shape in front of all shapes with lower ZOrderPosition. The ShapeCollection.NormalizeZOrder method modifies ZOrderPosition values for all shapes in a collection, so that they become a series of consecutive integers starting from 1.
Hyperlink
A hyperlink can be associated with a shape. When the end-user clicks the picture, the link navigates to a certain location on the Internet, to a file, to a place in a workbook, or it sends an email. Use the Shape.InsertHyperlink method to create a hyperlink for the picture. Use the Shape.RemoveHyperlink method to delete a hyperlink.