Class SpreadsheetDrawPage

Introduction

The SpreadsheetDrawPage class is for accessing the draw page of a spreadsheet document.

This class has a forms property that gives access to Class CalcForm which in turn gives access to Class CalcForms that represents a form in the spreadsheet document.

Adding a shape to a sheet

The SpreadsheetDrawPage class has many methods for adding shapes to a sheet.

Here is an example of adding a rectangle to a sheet.

>>> doc = CalcDoc(Calc.create_doc(loader))
>>> sheet = doc.sheets[0]
>>> rect = sheet.draw_page.draw_rectangle(x=100, y=10, width=50, height=20)
>>> rect
<ooodev.draw.shapes.rectangle_shape.RectangleShape object at 0x000001B636EA3490>

Class Declaration

class ooodev.calc.SpreadsheetDrawPage(owner, component, lo_inst=None)[source]

Bases: LoInstPropsPartial, DrawPagePartial[SpreadsheetDrawPage[_T]], Generic[_T], SpreadsheetDrawPageComp, IndexAccessPartial, Shapes2Partial, Shapes3Partial, ServicePartial, QiPartial, TheDictionaryPartial, StylePartial, CalcDocPropPartial, ShapeFactoryPartial[SpreadsheetDrawPage[_T]]

Represents a draw page.

__init__(owner, component, lo_inst=None)[source]

Constructor.

Parameters:
  • lo_inst (LoInst, optional) – Lo instance.

  • owner (_T) –

  • component (XDrawPage) –

Return type:

None

add(shape)

Adds a shape to the collection.

Parameters:

shape (XShape) – The shape to add.

Return type:

None

add_bottom(shape)

Adds a shape to the bottom of the stack.

Parameters:

shape (XShape) – The shape to add.

Return type:

None

add_bullet(bulls_txt, level, text)

Add bullet text to the end of the bullets text area, specifying the nesting of the bullet using a numbering level value (numbering starts at 0).

Parameters:
  • bulls_txt (XText) – Text object

  • level (int) – Bullet Level

  • text (str) – Bullet Text

Raises:

DrawError – If error adding bullet.

Return type:

None

add_connector(shape1, shape2, start_conn=None, end_conn=None)

Add connector

Parameters:
  • shape1 (XShape) – First Shape to add connector to.

  • shape2 (XShape) – Second Shape to add connector to.

  • start_conn (GluePointsKind | None, optional) – Start connector kind. Defaults to right.

  • end_conn (GluePointsKind | None, optional) – End connector kind. Defaults to left.

Raises:

ShapeError – If error occurs.

Returns:

Connector Shape.

Return type:

XShape

Note

Properties for shape can be added or changed by using set_shape_props().

For instance the default value is EndShape=ConnectorType.STANDARD. This could be changed.

Draw.set_shape_props(shape, EndShape=ConnectorType.CURVE)
add_dispatch_shape(shape_dispatch, x, y, width, height, fn)

Adds a shape to a Draw slide via a dispatch command

Parameters:
  • shape_dispatch (ShapeDispatchKind | str) – Dispatch Command

  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, UnitT) – Shape Y position in mm units or UnitT

  • width (int, UnitT) – Shape width in mm units or UnitT

  • height (int, UnitT) – Shape height in mm units or UnitT

  • fn (DispatchShape) – Function that is responsible for running the dispatch command and returning the shape.

Raises:
Returns:

Shape

Return type:

XShape

See also

DispatchShape

add_pres_shape(shape_type, x, y, width, height)

Creates a shape from the “com.sun.star.presentation” package:

Parameters:
  • shape_type (PresentationKind) – Kind of presentation package to create.

  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, UnitT) – Shape Y position in mm units or UnitT.

  • width (int, UnitT) – Shape width in mm units or UnitT.

  • height (int, UnitT) – Shape height in mm units or UnitT.

Raises:

ShapeError – If error occurs.

Returns:

Presentation Shape.

Return type:

XShape

add_shape(shape_type, x, y, width, height)

Adds a shape to a slide.

Parameters:
  • shape_type (DrawingShapeKind | str) – Shape type.

  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, UnitT) – Shape Y position in mm units or UnitT.

  • width (int, UnitT) – Shape width in mm units or UnitT.

  • height (int, UnitT) – Shape height in mm units or UnitT.

Raises:

ShapeError – If error occurs.

Returns:

Newly added Shape.

Return type:

XShape

Note

If x or y is negative or 0 then the shape position will not be set. If width or height is negative or 0 then the shape size will not be set.

Changed in version 0.17.14: Now does not set size and/or position unless the values are greater than 0.

add_slide_number()

Adds slide number to a slide

Parameters:

slide (XDrawPage) – Slide

Raises:

ShapeError – If error occurs.

Returns:

Slide number shape.

Return type:

DrawShape

add_top(shape)

Adds a shape to the top of the stack.

Parameters:

shape (XShape) – The shape to add.

Return type:

None

apply_styles(*styles, **kwargs)

Applies style to component.

Parameters:
  • obj. (styles expandable list of styles object such as Font to apply to) –

  • kwargs (Any, optional) – Expandable list of key value pairs.

  • styles (StyleT) –

Return type:

None

blank_slide()

Inserts a blank slide

Parameters:

slide (XDrawPage) – Slide

Raises:

DrawError – If error occurs

Return type:

None

bullets_slide(title)

Add text to the slide page by treating it as a bullet page, which has two text shapes: one for the title, the other for a sequence of bullet points; add the title text but return a reference to the bullet text area

Parameters:
  • slide (XDrawPage) – Slide

  • title (str) – Title

Raises:

DrawError – If error setting slide.

Returns:

Text Object

Return type:

DrawText

copy_shape(old_shape)

Copies a shape

Parameters:

old_shape (XShape) – Old Shape

Raises:

ShapeError – If unable to copy shape.

Returns:

Newly Copied shape.

Return type:

DrawShape

copy_shape_contents(old_shape)

Copies a shapes contents from old shape into new shape.

Parameters:

old_shape (XShape) – Old shape

Raises:

ShapeError – If unable to copy shape contents.

Returns:

New shape with contents of old shape copied.

Return type:

DrawShape

draw_bezier_closed(pts, flags)

Draws a bezier curve.

Parameters:
  • pts (Sequence[Point]) – Points

  • flags (Sequence[PolygonFlags]) – Flags

Raises:
  • IndexError – If pts and flags do not have the same number of elements.

  • ShapeError – If unable to create Bezier Shape.

Returns:

Bezier Shape.

Return type:

ClosedBezierShape

draw_bezier_open(pts, flags)

Draws a bezier curve.

Parameters:
  • pts (Sequence[Point]) – Points

  • flags (Sequence[PolygonFlags]) – Flags

Raises:
  • IndexError – If pts and flags do not have the same number of elements.

  • ShapeError – If unable to create Bezier Shape.

Returns:

Bezier Shape.

Return type:

OpenBezierShape

draw_circle(x, y, radius)

Gets a circle

Parameters:
  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, UnitT) – Shape Y position in mm units or UnitT.

  • radius (int, UnitT) – Shape radius in mm units or UnitT.

Raises:

ShapeError – If error occurs.

Returns:

Circle Shape.

Return type:

EllipseShape

draw_ellipse(x, y, width, height)

Gets an ellipse

Parameters:
  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, UnitT) – Shape Y position in mm units or UnitT.

  • width (int, UnitT) – Shape width in mm units or UnitT.

  • height (int, UnitT) – Shape height in mm units or UnitT.

Raises:

ShapeError – If error occurs.

Returns:

Ellipse Shape.

Return type:

EllipseShape

draw_formula(formula, x, y, width, height)

Draws a formula

Parameters:
  • slide (XDrawPage) – Slide

  • formula (str) – Formula as string to draw/

  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, , UnitT) – Shape Y position in mm units or UnitT

  • width (int, , UnitT) – Shape width in mm units or UnitT

  • height (int, , UnitT) – Shape height in mm units or UnitT

Raises:

ShapeError – If error occurs.

Returns:

Formula Shape.

Return type:

XShape

Note

If x or y is negative or 0 then the shape position will not be set. If width or height is negative or 0 then the shape size will not be set.

Changed in version 0.17.14: Now does not set size and/or position unless the values are greater than 0.

draw_image(*args, **kwargs)

Draws an image.

Parameters:
  • fnm (PathOrStr) – Path to image

  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, UnitT) – Shape Y position in mm units or UnitT.

  • width (int, UnitT) – Shape width in mm units or UnitT.

  • height (int, UnitT) – Shape height in mm units or UnitT.

Raises:

ShapeError – If error occurs.

Returns:

Shape

Return type:

GraphicObjectShape

draw_image_offset(fnm, xoffset, yoffset)

Insert the specified picture onto the slide page in the doc presentation document. Use the supplied (x, y) offsets to locate the top-left of the image.

Parameters:
  • slide (XDrawPage) – Slide

  • fnm (PathOrStr) – Path to image.

  • xoffset (ImageOffset, float) – X Offset with value between 0.0 and 1.0

  • yoffset (ImageOffset, float) – Y Offset with value between 0.0 and 1.0

Returns:

Shape on success, None otherwise.

Return type:

GraphicObjectShape | None

draw_line(x1, y1, x2, y2)

Draws a line.

Parameters:
  • x1 (int, UnitT) – Line start X position in mm units or UnitT.

  • y1 (int, UnitT) – Line start Y position mm units or UnitT.

  • x2 (int, UnitT) – Line end X position mm units or UnitT.

  • y2 (int, UnitT) – Line end Y position mm units or UnitT.

Raises:
  • ValueError – If x values and y values are a point and not a line.

  • ShapeError – If unable to create Line.

Returns:

Line Shape.

Return type:

LineShape

draw_lines(xs, ys)

Draw lines

Parameters:
  • xs (Sequence[Union[int, UnitT]) – Sequence of X positions in mm units or UnitT.

  • ys (Sequence[Union[int, UnitT]) – Sequence of Y positions in mm units or UnitT.

Raises:
  • IndexError – If xs and xy do not have the same number of elements.

  • ShapeError – If any other error occurs.

Returns:

Lines Shape.

Return type:

PolyLineShape

Note

The number of points must be the same for both xs and ys.

draw_media(fnm, x, y, width, height)

Draws media.

Parameters:
  • fnm (PathOrStr) – Path to Media file.

  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, UnitT) – Shape Y position in mm units or UnitT.

  • width (int, UnitT) – Shape width in mm units or UnitT.

  • height (int, UnitT) – Shape height in mm units or UnitT.

Raises:

ShapeError – If error occurs.

Returns:

Media shape.

Return type:

XShape

Note

If x or y is negative or 0 then the shape position will not be set. If width or height is negative or 0 then the shape size will not be set.

Changed in version 0.17.14: Now does not set size and/or position unless the values are greater than 0.

draw_polar_line(x, y, degrees, distance)

Draw a line from x, y in the direction of degrees, for the specified distance degrees is measured clockwise from x-axis

Parameters:
  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, UnitT) – Shape Y position in mm units or UnitT.

  • degrees (int) – Direction of degrees

  • distance (int, UnitT) – Distance of line in mm units or UnitT..

Raises:

ShapeError – If unable to create Polar Line Shape.

Returns:

Polar Line Shape.

Return type:

LineShape

draw_polygon(x, y, sides, radius=20)

Gets a polygon.

Parameters:
  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, UnitT) – Shape Y position in mm units or UnitT.

  • sides (PolySides | int) – Polygon Sides value from 3 to 30.

  • radius (int, optional) – Shape radius in mm units. Defaults to the value of draw.Draw.POLY_RADIUS.

Raises:

ShapeError – If error occurs.

Returns:

Polygon Shape.

Return type:

PolyPolygonShape

draw_rectangle(x, y, width, height)

Gets a rectangle.

Parameters:
  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, UnitT) – Shape Y position in mm units or UnitT.

  • width (int, UnitT) – Shape width in mm units or UnitT.

  • height (int, UnitT) – Shape height in mm units or UnitT.

Raises:

ShapeError – If error occurs.

Returns:

Rectangle Shape.

Return type:

RectangleShape

Note

If x or y is negative or 0 then the shape position will not be set. If width or height is negative or 0 then the shape size will not be set.

Changed in version 0.17.14: Now does not set size and/or position unless the values are greater than 0.

draw_text(msg, x, y, width, height, font_size=0)

Draws Text.

Parameters:
  • slide (XDrawPage) – Slide.

  • msg (str) – Text to draw.

  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, UnitT) – Shape Y position in mm units or UnitT.

  • width (int, UnitT) – Shape width in mm units or UnitT.

  • height (int, UnitT) – Shape height in mm units or UnitT.

  • font_size (float, UnitT, optional) – Font size of text in Points or UnitT.

Raises:

ShapeError – If error occurs.

Returns:

Shape

Return type:

TextShape

Note

If x or y is negative or 0 then the shape position will not be set. If width or height is negative or 0 then the shape size will not be set.

Changed in version 0.17.14: Now does not set size and/or position unless the values are greater than 0.

find_biggest_zorder()

Finds the shape with the largest z-order.

Raises:

DrawError – If unable to find biggest z-order.

Returns:

Z-Order

Return type:

int

find_cell_with_control(ctl)[source]

Find the cell that contains the control.

Parameters:

ctl (FormCtlBase | XControlModel) – Control to find cell for.

Returns:

Cell that contains the control or None if not found.

Return type:

CalcCell | None

New in version 0.38.0.

find_shape_at_position(x, y)

Finds a shape at a given position.

Parameters:
  • x (int) – X position.

  • y (int) – Y position.

Raises:
Returns:

Shape if Found; Otherwise, None.

Return type:

ShapeBase[Any] | None

find_shape_at_position_size(x, y, width, height)

Finds a shape at a given position with a given size.

Parameters:
  • x (int) – X position.

  • y (int) – Y position.

  • width (int) – width of the shape.

  • height (int) – height of the shape.

Raises:
Returns:

Shape if Found; Otherwise, None.

Return type:

ShapeBase[Any] | None

find_shape_by_name(shape_name)

Finds a shape by its name.

Parameters:

shape_name (str) – Shape Name.

Raises:
Returns:

Shape.

Return type:

DrawShape

find_shape_by_type(shape_type)

Finds a shape by its type

Parameters:

shape_type (DrawingNameSpaceKind | str) – Shape Type

Raises:
Returns:

Shape

Return type:

DrawShape

find_top_shape()

Gets the top most shape of a slide.

Raises:
Returns:

Top most shape.

Return type:

DrawShape

get_animation_node()

Gets Animation Node

Parameters:

slide (XDrawPage) – Slide

Raises:

DrawPageError – If error occurs.

Returns:

Animation Node

Return type:

XAnimationNode

get_by_index(idx)

Gets the element at the specified index.

Parameters:

idx (int) – The Zero-based index of the element.

Returns:

The element at the specified index.

Return type:

Any

get_chart_shape(x, y, width, height)

Gets a chart shape.

Parameters:
  • x (int, UnitT) – Shape X position in mm units or UnitT.

  • y (int, UnitT) – Shape Y position in mm units or UnitT.

  • width (int, UnitT) – Shape width in mm units or UnitT.

  • height (int, UnitT) – Shape height in mm units or UnitT.

Raises:

ShapeError – If Error occurs.

Returns:

Chart Shape.

Return type:

OLE2Shape

get_count()

Gets the number of elements contained in the container.

Returns:

The number of elements.

Return type:

int

get_element_type()

Gets the type of the elements contained in the container.

Returns:

The type of the elements. None means that it is a multi-type container and you cannot determine the exact types with this interface.

Return type:

Any

get_fill_color()

Gets the fill color of a shape.

Parameters:

shape (XShape) – Shape

Raises:

ColorError – If error occurs.

Returns:

Color

Return type:

Color

get_form_container()

Gets form container. The first form in slide is returned if found.

Raises:

DrawError – If error occurs.

Returns:

Form Container on success, None otherwise.

Return type:

IndexContainerComp | None

get_glue_points()

Gets Glue Points

Parameters:

shape (XShape) – Shape

Raises:

DrawError – If error occurs

Returns:

Glue Points.

Return type:

Tuple[GluePoint2, …]

Note

If a glue point can not be accessed then it is ignored.

get_line_color()

Gets the line color of a shape.

Raises:

ColorError – If error occurs.

Returns:

Color

Return type:

Color

get_line_thickness()

Gets line thickness of a shape.

Returns:

Line Thickness on success; Otherwise, 0.

Return type:

int

get_name()

Gets the name of the slide.

Raises:

DrawError – If error occurs setting name.

Returns:

Slide name.

Return type:

str

New in version 0.17.13.

get_ordered_shapes()

Gets ordered shapes

Returns:

List of Ordered Shapes.

Return type:

List[DrawShape[_T]]

See also

get_shapes()

get_services()

Gets service names for the instance.

Returns:

service names

Return type:

List[str]

get_shape_text()

Gets the text from inside a shape.

Raises:

DrawError – If error occurs getting shape text.

Returns:

Shape text

Return type:

str

get_shapes()

Gets shapes

Returns:

List of Shapes.

Return type:

List[ShapeBase[_T]]

get_size_mm()

Gets size of the given slide page (in mm units)

Raises:

SizeError – If unable to get size.

Returns:

Size struct.

Return type:

Size

get_slide_number()

Gets slide number.

Raises:

DrawError – If error occurs.

Returns:

Slide Number.

Return type:

int

get_slide_title()

Gets slide title if it exist.

Raises:

DrawError – If error occurs.

Returns:

Slide Title on success; Otherwise, None.

Return type:

str | None

goto_page()

Go to page represented by this object.

Raises:

DrawError – If error occurs.

Return type:

None

group(shapes)

Groups the given shapes.

Parameters:

shapes (XShapes) – The shapes to group.

Returns:

The group shape.

Return type:

XShapeGroup

has_elements()

Determines whether the container has elements.

Return type:

bool

is_know_shape(shape)

Checks if a shape is known by this factory.

Parameters:

shape (XShape) – UNO object of a shape.

Returns:

True if shape is known; Otherwise, False.

Return type:

bool

move_to_bottom(shape)

Moves a shape to the bottom of the z-order

Parameters:

shape (XShape) – Shape

Raises:
Return type:

None

move_to_top(shape)

Moves a shape to the top of the z-order

Parameters:

shape (XShape) – Shape

Raises:
Return type:

None

qi(atype, raise_err=False)

Generic method that get an interface instance from an object.

Parameters:
  • atype (T) – Interface type to query obj for. Any Uno class that starts with ‘X’ such as XInterface

  • raise_err (bool, optional) – If True then raises MissingInterfaceError if result is None. Default False

Raises:

MissingInterfaceError – If ‘raise_err’ is ‘True’ and result is None

Returns:

instance of interface if supported; Otherwise, None

Return type:

T | None

Note

When raise_err=True return value will never be None.

remove(shape)

Removes a shape from the collection.

Parameters:

shape (XShape) – The shape to remove.

Return type:

None

remove_master_page()

Removes a master page

Parameters:

slide (XDrawPage) – Draw page to remove

Raises:

DrawError – If unable to remove master page/

Return type:

None

save_page(fnm, mime_type, filter_data=None)

Saves a Draw page to file.

Parameters:
  • fnm (PathOrStr) – Path to save page as

  • mime_type (str) – Mime Type of page to save as such as image/jpeg or image/png.

  • filter_data (dict, optional) – Filter data. Defaults to None.

Raises:

DrawError – If error occurs.

Return type:

None

Changed in version 0.21.3: Added filter_data parameter.

set_name(name)

Sets the name of a slide.

Parameters:

name (str) – Name.

Raises:

DrawError – If error occurs setting name.

Return type:

None

set_transition(fade_effect, speed, change, duration)

Sets the transition for a slide.

Parameters:
  • slide (XDrawPage) – Slide

  • fade_effect (FadeEffect) – Fade Effect

  • speed (AnimationSpeed) – Animation Speed

  • change (SlideShowKind) – Slide show kind

  • duration (int) – Duration of slide. Only used when change=SlideShowKind.AUTO_CHANGE

Raises:

DrawPageError – If error occurs.

Return type:

None

shape_factory(shape)

Gets a ShapeBase object from a XShape object.

Parameters:

shape (XShape) – UNO object of a shape.

Raises:

ValueError – If shape does not have ShapeType property.

Returns:

Object the inherits from ShapeBase such as RectangleShape or EllipseShape. If ShapeType of shape is not a match then DrawShape[_T] is returned.

Return type:

ShapeBase[_T]

sort(sort_order)

Sort shapes according to given sort order, for perf reason just rearrange and don’t broadcast.

Parameters:
  • comparator (Any) – Desired order of the shapes

  • sort_order (Tuple[int, ...]) –

Return type:

None

support_service(*service)

Gets if instance supports a service.

Parameters:

*service (str) – Variable length argument list of UNO namespace strings such as com.sun.star.configuration.GroupAccess

Returns:

True if instance supports any passed in service; Otherwise, False

Return type:

bool

title_only_slide(header)

Creates a slide with only a title

Parameters:

header (str) – Header text.

Raises:

DrawError – If error occurs.

Return type:

None

ungroup(shape)

Un-groups the given shape.

Parameters:

shape (XShapeGroup) – The shape to ungroup.

Return type:

None

property calc_doc: CalcDoc

Calc Document.

Return type:

CalcDoc

property component: com.sun.star.sheet.SpreadsheetDrawPage

SpreadsheetDrawPage Component

Return type:

SpreadsheetDrawPage

property extra_data: TheDict

Extra Data Key Value Pair Dictionary.

Properties can be assigned properties and access like a dictionary and with dot notation.

Note

This is a dictionary object that can be used to store key value pairs. Generally speaking this data is not part of the object’s main data structure and is not saved with the object (document).

This property is used to store data that is not part of the object’s main data structure and can be used however the developer sees fit.

Return type:

TheDict

property forms: CalcForms

Gets the forms of the draw page.

Return type:

CalcForms

property lo_inst: LoInst

Lo Instance

Return type:

LoInst

property name: str

Gets/Sets the name of the draw page.

Note

Naming for Impress pages seems a little different then Draw pages. Attempting to name a Draw page Slide # where # is a number will fail and Draw will auto name the page. It seems that Slide followed by a space and a number is reserved for Impress.

Return type:

str

property office_doc: OfficeDocumentT

Office Document.

Return type:

OfficeDocumentT

property owner: _T

Component Owner

Return type:

TypeVar(_T, bound= ComponentT)