Shape

Shape — Aspose.Cells FOSS for Python API Reference

aspose-cells-foss supports adding geometric shapes and text boxes to worksheets through the ShapeCollection (ws.shapes). Each shape is represented by a Shape object with configurable fill, line, and text properties.

Package: aspose.cells_foss

from aspose.cells_foss import (
    MsoDrawingType, FillType, MsoLineDashStyle,
    TextAlignmentType, TextAnchorType,
    MsoFillFormat, MsoLineFormat, ShapeFont, Shape,
)

MsoDrawingType

MsoDrawingType is an IntEnum identifying the geometric shape type.

Member	Value	Member	Value
`UNKNOWN`	0	`TEXT_BOX`	21
`RECTANGLE`	1	`CALLOUT`	22
`ROUNDED_RECTANGLE`	2	`PENTAGON`	23
`OVAL`	3	`CLOUD`	24
`DIAMOND`	4	`HEART`	25
`TRIANGLE`	5	`LIGHTNING_BOLT`	26
`RIGHT_TRIANGLE`	6	`SMILEY_FACE`	27
`PARALLELOGRAM`	7	`LEFT_RIGHT_ARROW`	28
`TRAPEZOID`	8	`UP_DOWN_ARROW`	29
`HEXAGON`	9	`CUBE`	30
`OCTAGON`	10	`BEVEL`	31
`CROSS`	11	`STAR_4`	12
`RIGHT_ARROW`	17	`STAR_5`	13
`LEFT_ARROW`	18	`STAR_6`	14
`UP_ARROW`	19	`STAR_7`	15
`DOWN_ARROW`	20	`STAR_8`	16

FillType

FillType is an IntEnum identifying the type of fill applied to a shape.

Member	Value
`NONE`	0
`SOLID`	1
`GRADIENT`	2
`PATTERN`	3
`AUTOMATIC`	4

MsoLineDashStyle

MsoLineDashStyle is an IntEnum for the border/outline line dash pattern.

Member	Value
`SOLID`	0
`DASH`	1
`DOT`	2
`DASH_DOT`	3
`DASH_DOT_DOT`	4
`LONG_DASH`	5
`LONG_DASH_DOT`	6

TextAlignmentType

TextAlignmentType is an IntEnum for horizontal text alignment within a shape.

Member	Value
`LEFT`	0
`CENTER`	1
`RIGHT`	2
`JUSTIFY`	3
`DISTRIBUTED`	4

TextAnchorType

TextAnchorType is an IntEnum for vertical text anchoring within a shape.

Member	Value
`TOP`	0
`MIDDLE`	1
`BOTTOM`	2
`JUSTIFIED`	3

MsoFillFormat

Controls the fill appearance of a shape. Accessed via shape.fill.

Properties

Property	Type	Description
`fill_type`	`FillType`	The active fill type.
`fore_color`	`str`	Foreground (primary) fill color as RRGGBB hex.
`transparency`	`float`	Fill opacity as a value from `0.0` (fully opaque) to `1.0` (fully transparent).

Methods

copy

fill.copy() -> MsoFillFormat

Returns a deep copy of these fill settings.

MsoLineFormat

Controls the outline/border appearance of a shape. Accessed via shape.line.

Properties

Property	Type	Description
`is_visible`	`bool`	`True` to draw the shape outline.
`color`	`str`	Outline color as RRGGBB hex.
`weight`	`int`	Outline weight (thickness) in points.
`dash_style`	`MsoLineDashStyle`	Dash pattern for the outline.
`transparency`	`float`	Outline opacity from `0.0` (opaque) to `1.0` (transparent).

Methods

copy

line.copy() -> MsoLineFormat

Returns a deep copy of these line settings.

ShapeFont

Controls the text font within a shape. Accessed via shape.font.

Properties

Property	Type	Description
`name`	`str`	Font family name (e.g., `"Calibri"`).
`size`	`float`	Font size in points.
`bold`	`bool`	`True` for bold weight.
`italic`	`bool`	`True` for italic style.
`underline`	`bool`	`True` for single underline.
`color`	`str`	Font color as RRGGBB hex.

Methods

copy

font.copy() -> ShapeFont

Returns a deep copy of these font settings.

Shape

Shape objects are not constructed directly. Use ws.shapes.add(...) or ws.shapes.add_text_box(...).

Properties

Property	Type	Access	Description
`name`	`str`	Read/Write	Shape name (must be unique within the worksheet).
`drawing_type`	`MsoDrawingType`	Read	The geometric type of this shape.
`upper_left_row`	`int`	Read/Write	0-based row index of the top-left anchor cell.
`upper_left_column`	`int`	Read/Write	0-based column index of the top-left anchor cell.
`lower_right_row`	`int`	Read/Write	0-based row index of the bottom-right anchor cell.
`lower_right_column`	`int`	Read/Write	0-based column index of the bottom-right anchor cell.
`upper_left_row_offset`	`int`	Read/Write	Pixel offset from the top edge of the top-left cell.
`upper_left_column_offset`	`int`	Read/Write	Pixel offset from the left edge of the top-left cell.
`lower_right_row_offset`	`int`	Read/Write	Pixel offset from the top edge of the bottom-right cell.
`lower_right_column_offset`	`int`	Read/Write	Pixel offset from the left edge of the bottom-right cell.
`fill`	`MsoFillFormat`	Read	Fill (background) settings.
`line`	`MsoLineFormat`	Read	Outline/border settings.
`text`	`str`	Read/Write	Text content displayed inside the shape.
`font`	`ShapeFont`	Read	Font settings for the shape text.
`text_horizontal_alignment`	`TextAlignmentType`	Read/Write	Horizontal text alignment inside the shape.
`text_vertical_alignment`	`TextAnchorType`	Read/Write	Vertical text anchoring inside the shape.
`is_text_wrapped`	`bool`	Read/Write	`True` to wrap text at the shape boundary.
`is_locked`	`bool`	Read/Write	`True` to lock the shape when worksheet protection is active.
`is_hidden`	`bool`	Read/Write	`True` to hide the shape.
`hyperlink`	`str \| None`	Read/Write	URL or cell reference hyperlink attached to the shape.

Methods

copy

shape.copy() -> Shape

Returns a deep copy of this shape with all formatting preserved.

ShapeCollection

ShapeCollection is accessed as ws.shapes. It contains all shapes on a worksheet.

Methods

add

ws.shapes.add(
    drawing_type: MsoDrawingType,
    upper_left_row: int,
    upper_left_column: int,
    lower_right_row: int,
    lower_right_column: int
) -> Shape

Adds a shape of the specified type. All position arguments are 0-based row/column indices.

add_text_box

ws.shapes.add_text_box(
    upper_left_row: int,
    upper_left_column: int,
    lower_right_row: int,
    lower_right_column: int
) -> Shape

Shortcut for add(MsoDrawingType.TEXT_BOX, ...).

Properties and Iteration

Member	Description
`count`	Number of shapes in the collection (read-only).
`__len__()`	Returns `count`.
`__iter__()`	Iterates over all `Shape` objects.
`__getitem__(index)`	Returns the `Shape` at zero-based `index`.

Examples

Add a Rectangle with Solid Fill

from aspose.cells_foss import Workbook, MsoDrawingType, FillType, MsoLineDashStyle, TextAlignmentType

wb = Workbook()
ws = wb.worksheets[0]

# Add a blue rectangle spanning rows 1-5, columns 1-4 (0-based)
rect = ws.shapes.add(MsoDrawingType.RECTANGLE, 1, 1, 5, 4)
rect.name = "BlueBox"

rect.fill.fill_type = FillType.SOLID
rect.fill.fore_color = "4472C4"      # blue
rect.fill.transparency = 0.0

rect.line.is_visible = True
rect.line.color = "1F3864"           # dark blue
rect.line.weight = 2
rect.line.dash_style = MsoLineDashStyle.SOLID

rect.text = "Sales Summary"
rect.font.bold = True
rect.font.color = "FFFFFF"           # white text
rect.font.size = 12
rect.text_horizontal_alignment = TextAlignmentType.CENTER

wb.save("shapes.xlsx")

Add a Text Box

from aspose.cells_foss import Workbook

wb = Workbook()
ws = wb.worksheets[0]

tb = ws.shapes.add_text_box(2, 0, 5, 3)
tb.name = "NoteBox"
tb.text = "Review this section before publishing."
tb.font.italic = True
tb.font.color = "595959"
tb.is_text_wrapped = True
tb.line.is_visible = True
tb.line.color = "BFBFBF"

wb.save("textbox.xlsx")

Shape — Aspose.Cells FOSS for Python API Reference

MsoDrawingType

FillType

MsoLineDashStyle

TextAlignmentType

TextAnchorType

MsoFillFormat

Properties

Methods

copy

MsoLineFormat

Properties

Methods

copy

ShapeFont

Properties

Methods

copy

Shape

Properties

Methods

copy

ShapeCollection

Methods

add

add_text_box

Properties and Iteration

Examples

Add a Rectangle with Solid Fill

Add a Text Box

See Also