Class DrawShape

class ooodev.draw.shapes.DrawShape(owner, component, lo_inst=None)

Bases: ShapeBase, Generic[_T], ShapeComp, ShapePartialProps, PropertyChangeImplement, VetoableChangeImplement, DrawShapePartial, QiPartial, PropPartial, StylePartial, StyledShapePartial

__init__(owner, component, lo_inst=None)

Constructor.

Parameters:

• lo_inst (LoInst, optional) – Lo instance.

• owner (_T) –

• component (XShape) –

Return type:

None

add_event_observers(*args)

Adds observers that gets their trigger method called when this class trigger method is called.

Parameters:

args (EventObserver) – One or more observers to add.

Return type:

None

Note

Observers are removed automatically when they are out of scope.

add_event_property_change(name, cb)

Adds a listener for an event.

Event is invoked when property is changed.

The callback EventArgs.event_data will contain a com.sun.star.beans.PropertyChangeEvent struct.

Parameters:

• name (str) – Property Name

• cb (EventArgsCallbackT) – Callback

Return type:

None

add_event_property_change_events_disposing(name, cb)

Adds a listener for an event.

Event is invoked when the property listener is about to be disposed.

The callback EventArgs.event_data will contain a UNO com.sun.star.lang.EventObject struct.

Parameters:

• name (str) – Property Name

• cb (EventArgsCallbackT) – Callback

Return type:

None

add_event_vetoable_change(name, cb)

Adds a listener for an event.

Event is invoked when property is changed.

The callback EventArgs.event_data will contain a com.sun.star.beans.PropertyChangeEvent struct.

Parameters:

• name (str) – Property Name

• cb (EventArgsCallbackT) – Callback

Return type:

None

add_event_vetoable_change_events_disposing(name, cb)

Adds a listener for an event.

Event is invoked when the property listener is about to be disposed.

The callback EventArgs.event_data will contain a UNO com.sun.star.lang.EventObject struct.

Parameters:

• name (str) – Property Name

• cb (EventArgsCallbackT) – Callback

Return type:

None

add_text(msg, font_size=0, **props)

Add text to a shape

Parameters:

• msg (str) – Text to add

• font_size (int, optional) – Font size.

• props (Any, optional) – Any extra properties that will be applied to cursor (font) such as CharUnderline=1

Raises:

ShapeError – If error occurs.

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

export_shape_jpg(fnm, resolution=96)

Exports shape as jpg image.

Parameters:

• fnm (PathOrStr, optional) – Image file name.

• resolution (int, optional) – Resolution in dpi. Defaults to 96.

Events:

• EXPORTING_SHAPE_JPG Standard Export Cancel Event

• EXPORTED_SHAPE_JPG Export Event Args

Return type:

None

Note

On exporting event is Class CancelEventArgsExport. On exported event is Class EventArgsExport. Args event_data is a ExportJpgT dictionary.

If fnm is not specified, the image file name is created based on the document name and page number and written to the same folder as the document.

export_shape_png(fnm, resolution=96)

Exports shape as png image.

Parameters:

• fnm (PathOrStr, optional) – Image file name.

• resolution (int, optional) – Resolution in dpi. Defaults to 96.

Events:

• EXPORTING_SHAPE_PNG Standard Export Cancel Event

• EXPORTED_SHAPE_PNG Export Event Args

Return type:

None

Note

On exporting event is Class CancelEventArgsExport. On exported event is Class EventArgsExport. Args event_data is a ExportPngT dictionary.

If fnm is not specified, the image file name is created based on the document name and page number and written to the same folder as the document.

When page is exported as png, such as an impress slide, any images on the will not be exported if filter translucent=True. For this reason, the default value for translucent is False.

get_glue_points()

Gets Glue Points.

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_known_shape()

The DrawShape class is a general class for all shapes. This means it may not have all the properties of a specific shape.

This method returns the known shape if the shape is known; Otherwise, it returns itself.

Returns the known shape.

See also

is_know_shape()

Return type:

ShapeBase[TypeVar(_T, bound= ComponentT)]

get_lo_inst()

Return type:

LoInst

get_owner()

Return type:

TypeVar(_T, bound= ComponentT)

get_position()

Gets the position of the shape in 100th mm units.

Returns:

The position of the shape.

Return type:

Point

get_position_mm()

Gets position in mm units

Raises:

PointError – If error occurs.

Returns:

Position as Point in mm units

Return type:

Point

get_property(name, default=<object object>)

Get property value

Parameters:

• name (str) – Property Name.

• default (Any, optional) – Return value if property value is None.

Returns:

Property value or default.

Return type:

Any

get_rotation()

Gets the rotation of a shape

Parameters:

shape (XShape) – Shape

Raises:

ShapeError – If error occurs.

Returns:

Rotation angle.

Return type:

Angle

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_shape_text_cursor()

Gets a cursor object for this text.

Returns:

Cursor.

Return type:

ShapeTextCursor

get_shape_type()

Returns the shape type of general.

Return type:

str

get_size()

Gets the size of the shape in 100th mm units.

Returns:

The size of the shape.

Return type:

Size

get_size_mm()

Gets Size in mm units.

Raises:

SizeError – If error occurs.

Returns:

Size in mm units

Return type:

Size

get_text_properties()

Gets the properties associated with the text area inside the shape.

Raises:

PropertySetError – If error occurs.

Returns:

Property Set

Return type:

XPropertySet

get_transformation()

Gets a transformation matrix which seems to represent a clockwise rotation.

Homogeneous matrix has three homogeneous lines

Raises:

ShapeError – If error occurs.

Returns:

Matrix

Return type:

HomogenMatrix3

get_zorder()

Gets the z-order of a shape

Raises:

DrawError – If unable to get z-order.

Returns:

Z-Order

Return type:

int

is_group()

Gets if a shape is a Group Shape

Returns:

True if shape is a group; Otherwise; False.

Return type:

bool

is_image()

Gets if a shape is an image (GraphicObjectShape).

Returns:

True if shape is image; Otherwise, False.

Return type:

bool

is_know_shape()

Returns True if the shape is known.

Returns:

True if the shape is known; Otherwise, False.

Return type:

bool

See also

get_known_shape()

move_to_bottom()

Moves the shape to the bottom of the z-order

Raises:

• ShapeMissingError – If unable to find shapes for slide.

• ShapeError – If any other error occurs.

Return type:

None

move_to_top()

Moves the shape to the top of the z-order

Raises:

• ShapeMissingError – If unable to find shapes for slide.

• ShapeError – If any other error occurs.

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_event_observer(observer)

Removes an observer

Parameters:

observer (EventObserver) – One or more observers to add.

Returns:

True if observer has been removed; Otherwise, False.

Return type:

bool

remove_event_property_change(name)

Removes a listener for an event

Parameters:

name (str) – Property Name

Return type:

None

remove_event_property_change_events_disposing(name)

Removes a listener for an event

Parameters:

name (str) – Property Name

Return type:

None

remove_event_vetoable_change(name)

Removes a listener for an event

Parameters:

name (str) – Property Name

Return type:

None

remove_event_vetoable_change_events_disposing(name)

Removes a listener for an event

Parameters:

name (str) – Property Name

Return type:

None

set_angle(angle)

Set the line style for a shape

Parameters:

angle (Angle | int) – Angle to set.

Raises:

ShapeError – If error occurs.

Return type:

None

set_bitmap_color(name)

Set bitmap color of a shape.

Parameters:

name (DrawingBitmapKind, str) – Bitmap Name

Raises:

• NameError – If name is not recognized.

• ShapeError – If any other error occurs.

Return type:

None

Note

Getting the bitmap color name can be a bit challenging. DrawingBitmapKind contains name displayed in the Bitmap color menu of Draw.

The Easiest way to get the colors is to open Draw and see what bitmap color names are available on your system.

set_bitmap_file_color(fnm)

Set bitmap color from file.

Parameters:

fnm (PathOrStr) – path to file.

Raises:

ShapeError – If error occurs.

Return type:

None

set_dashed_line(is_dashed)

Set a dashed line

Parameters:

is_dashed (bool) – Determines if line is to be dashed or solid.

Raises:

ShapeError – If error occurs.

Return type:

None

set_gradient_color(*args, **kwargs)

Set the gradient color of the shape.

Parameters:

• name (DrawingGradientKind | str) – Gradient color name.

• start_color (Color) – Start Color.

• end_color (Color) – End Color.

• angle (Angle, int) – Gradient angle.

Raises:

• NameError – If name is not recognized.

• ShapeError – If any other error occurs.

Returns:

Gradient instance that just had properties set.

Return type:

Gradient

Note

When using Gradient Name.

Getting the gradient color name can be a bit challenging. DrawingGradientKind contains name displayed in the Gradient color menu of Draw.

The Easiest way to get the colors is to open Draw and see what gradient color names are available on your system.

See also

set_gradient_properties()

set_gradient_properties(grad)

Sets shapes gradient properties.

Parameters:

grad (Gradient) – Gradient properties to set.

Return type:

None

See also

set_gradient_color()

set_hatch_color(name)

Set hatching color of a shape.

Parameters:

name (DrawingHatchingKind, str) – Hatching Name.

Raises:

• NameError – If name is not recognized.

• ShapeError – If any other error occurs.

Return type:

None

Note

Getting the hatching color name can be a bit challenging. DrawingHatchingKind contains name displayed in the Hatching color menu of Draw.

The Easiest way to get the colors is to open Draw and see what gradient color names are available on your system.

set_image(fnm)

Sets the image of a shape.

Parameters:

fnm (PathOrStr) – Path to image.

Raises:

ShapeError – If error occurs.

Return type:

None

set_image_graphic(graphic)

Sets the image of a shape.

Parameters:

graphic (XGraphic) – Graphic.

Raises:

ShapeError – If error occurs.

Return type:

None

set_line_style(style)

Set the line style for a shape.

Parameters:

style (LineStyle) – Line Style.

Raises:

ShapeError – If error occurs.

Return type:

None

set_position(*args, **kwargs)

Sets Position of shape.

Parameters:

• pt (point) – Point that contains x and y positions in mm units.

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

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

Raises:

ShapeError – If error occurs.

Return type:

None

set_property(**kwargs)

Set property value

Parameters:

**kwargs (Any) – Variable length Key value pairs used to set properties.

Return type:

None

set_props(**props)

Sets properties on a shape.

Parameters:

props (Any) – Key value pairs of property name and property value

Raises:

• MissingInterfaceError – if obj does not implement XPropertySet interface

• MultiError – If unable to set a property

Return type:

None

Example

set_props(Loop=True, MediaURL=FileIO.fnm_to_url(fnm))

set_rotation(angle)

Set the rotation of a shape.

Parameters:

angle (Angle | int) – Angle or int. An angle value from 0 to 359.

Raises:

ShapeError – If error occurs.

Return type:

None

set_size(*args, **kwargs)

Sets set_size of shape.

Parameters:

• sz (Size) – Size that contains width and height positions in mm units.

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

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

Raises:

ShapeError – If error occurs.

Return type:

None

set_style(graphic_styles, style_name)

Set the graphic style for a shape.

Parameters:

• graphic_styles (XNameContainer) – Graphic styles.

• style_name (GraphicStyleKind | str) – Graphic Style Name.

Raises:

DrawError – If error occurs.

Return type:

None

set_transparency(level)

Sets the transparency level for the shape. Higher level means more transparent.

Parameters:

level (Intensity, int) – Transparency value. Represents a intensity value from 0 to 100.

Raises:

ShapeError – If error occurs.

Return type:

None

set_visible(is_visible)

Set the line style for a shape.

Parameters:

is_visible (bool) – Set is shape is visible or not.

Raises:

ShapeError – If error occurs.

Return type:

None

set_zorder(order)

Sets the z-order of a shape.

Parameters:

order (int) – Z-Order.

Raises:

DrawError – If unable to set z-order.

Return type:

None

style_position(x, y, base_point=ShapeBasePointKind.TOP_LEFT)

Style Area Color.

Parameters:

• x (float, UnitT) – Specifies the x-coordinate of the position of the shape (in mm units) or Class UnitT.

• y (float, UnitT) – Specifies the y-coordinate of the position of the shape (in mm units) or Class UnitT.

• base_point (ShapeBasePointKind, optional) – Specifies the base point of the shape used to calculate the X and Y coordinates. Default is TOP_LEFT.

Raises:

CancelEventError – If the event before_style_position is cancelled and not handled.

Returns:

Position instance or None if cancelled.

Return type:

PositionT | None

Hint

• ShapeBasePointKind can be imported from ooodev.utils.kind.shape_base_point_kind

style_position_get()

Gets the Position Style.

Raises:

CancelEventError – If the event before_style_position_get is cancelled and not handled.

Returns:

Position style or None if cancelled.

Return type:

PositionT | None

style_protect(position=None, size=None)

Style Area Color.

Parameters:

• position (bool, optional) – Specifies position protection.

• size (bool, optional) – Specifies size protection.

Raises:

CancelEventError – If the event before_style_protect is cancelled and not handled.

Returns:

Position instance or None if cancelled.

Return type:

ProtectT | None

style_protect_get()

Gets the Protect Style.

Raises:

CancelEventError – If the event before_style_protect_get is cancelled and not handled.

Returns:

Protect style or None if cancelled.

Return type:

ProtectT | None

style_size(width, height, base_point=ShapeBasePointKind.TOP_LEFT)

Style Area Color.

Parameters:

• width (float | UnitT) – Specifies the width of the shape (in mm units) or Class UnitT.

• height (float | UnitT) – Specifies the height of the shape (in mm units) or Class UnitT.

• base_point (ShapeBasePointKind, optional) – Specifies the base point of the shape used to calculate the X and Y coordinates. Default is TOP_LEFT.

Raises:

CancelEventError – If the event before_style_size is cancelled and not handled.

Returns:

Position instance or None if cancelled.

Return type:

SizeT | None

Hint

• ShapeBasePointKind can be imported from ooodev.utils.kind.shape_base_point_kind

style_size_get()

Gets the Size Style.

Raises:

CancelEventError – If the event before_style_size_get is cancelled and not handled.

Returns:

Size style or None if cancelled.

Return type:

SizeT | None

subscribe_event(event_name, callback)

Add an event listener to current instance.

Parameters:

• event_name (str) – Event Name.

• callback (EventCallback) – Callback of the event listener.

Return type:

None

subscribe_event_shape_jpg_exported(callback)

Add an event listener to current instance that is triggered on export complete.

Parameters:

callback (Callable[[Any, EventArgsExport[ExportJpgT]], None]) – Callback of the event listener.

Return type:

None

subscribe_event_shape_jpg_exporting(callback)

Add an event listener to current instance that is triggered on exporting.

Parameters:

callback (Callable[[Any, CancelEventArgsExport[ExportJpgT]], None]) – Callback of the event listener.

Return type:

None

subscribe_event_shape_png_exported(callback)

Add an event listener to current instance that is triggered on export complete.

Parameters:

callback (Callable[[Any, EventArgsExport[ExportPngT]], None]) – Callback of the event listener.

Return type:

None

subscribe_event_shape_png_exporting(callback)

Add an event listener to current instance that is triggered on exporting.

Parameters:

callback (Callable[[Any, CancelEventArgsExport[ExportPngT]], None]) – Callback of the event listener.

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

trigger_event(event_name, event_args)

Trigger an event on current instance.

Parameters:

• event_name (str) – Event Name.

• event_args (EventArgsT) – Event Args.

Return type:

None

unsubscribe_event(event_name, callback)

Remove an event listener from current instance.

Parameters:

• event_name (str) – Event Name.

• callback (EventCallback) – Callback of the event listener.

Return type:

None

unsubscribe_event_shape_jpg_exported(callback)

Remove an event listener from current instance.

Parameters:

callback (Callable[[Any, EventArgsExport[ExportJpgT]], None]) – Callback of the event listener.

Return type:

None

unsubscribe_event_shape_jpg_exporting(callback)

Remove an event listener from current instance.

Parameters:

callback (Callable[[Any, CancelEventArgsExport[ExportJpgT]], None]) – Callback of the event listener.

Return type:

None

unsubscribe_event_shape_png_exported(callback)

Remove an event listener from current instance.

Parameters:

callback (Callable[[Any, EventArgsExport[ExportPngT]], None]) – Callback of the event listener.

Return type:

None

unsubscribe_event_shape_png_exporting(callback)

Remove an event listener from current instance.

Parameters:

callback (Callable[[Any, CancelEventArgsExport[ExportPngT]], None]) – Callback of the event listener.

Return type:

None

property component: XShape

Gets the component.

Return type:

XShape

property event_observer: EventObserver

Gets/Sets The Event Observer for this instance.

Return type:

EventObserver

property hyperlink: str | None

Gets/Sets property lets you get and set a hyperlink for this shape.

optional

Return type:

str | None

property interop_grab_bag: Tuple[PropertyValue, ...] | None

Grab bag of shape properties, used as a string-any map for interim interop purposes.

This property is intentionally not handled by the ODF filter. Any member that should be handled there should be first moved out from this grab bag to a separate property.

optional

Return type:

Tuple[PropertyValue, …] | None

property layer_id: int | None

Gets/Sets the ID of the Layer to which this Shape is attached.

optional

Return type:

int | None

property layer_name: str | None

Gets/Sets the name of the Layer to which this Shape is attached.

optional

Return type:

str | None

property lo_inst: LoInst

Lo Instance

Return type:

LoInst

property move_protect: bool | None

Gets/Sets - With this set to True, this Shape cannot be moved interactively in the user interface.

Return type:

bool | None

property name: str | None

Gets/Sets the name of this Shape.

optional

Return type:

str | None

property navigation_order: int | None

Gets/Sets the navigation order of this shape.

If this value is negative, the navigation order for this shapes page is equal to the z-order.

optional

Return type:

int | None

property office_doc: OfficeDocumentT

Office Document.

Return type:

OfficeDocumentT

property owner: _T

Component Owner

Return type:

TypeVar(_T, bound= ComponentT)

property position: PointStructGenericComp[UnitMM]

Gets/Sets the position of the shape in UnitMM Values.

When setting this value, it can be set with a com.sun.star.awt.Position instance or a PointStructGenericComp instance.

The Position can be set by just setting a Position property.

Returns:

Position in UnitMM Values.

Return type:

PointStructGenericComp[UnitMM]

Note

This is the position as reported by the shape. This is not the same as the position of the shape on the page. The position of the shape on the page includes is from the page margins.

For instance if the page has a margin of 10mm and the shape is at position (15, 15) then the position of the shape in the Draw Dialog box is (5, 5) where as this position property will report (15, 15).

Example

Can be set by just setting a Position property using int or UnitMM.

shape.position.x = 1000 # 10 mm
shape.position.y = UnitMM(20) # 20 mm

Can also be set using any UnitT object.

shape.position.x = UnitCM(1.2)
shape.position.y = UnitMM(40)

Can also be set using a com.sun.star.awt.Position struct.

shape.position = Position(1000, 2000) # in 1/100mm

property printable: bool | None

Gets/Sets - If this is False, the Shape is not visible on printer outputs.

optional

Return type:

bool | None

property relative_height: int | None

Gets/Sets the relative height of the object.

It is only valid if it is greater than zero.

optional

Return type:

int | None

property relative_height_relation: int | None

Gets/Sets the relation of the relative height of the object.

It is only valid if RelativeHeight is greater than zero.

optional

Return type:

int | None

property relative_width: int | None

Gets/Sets the relative width of the object.

It is only valid if it is greater than zero.

optional

Return type:

int | None

property relative_width_relation: int | None

Gets/Sets the relation of the relative width of the object.

It is only valid if relative_width is greater than zero.

optional

Return type:

int | None

property shape_type: str

Gets the shape type.

Return type:

str

property shape_user_defined_attributes: NameContainerComp | None

Gets/Sets xml attributes.

They will be saved to and restored from automatic styles inside xml files.

When setting the value can be either a NameContainerComp or XNameContainer.

optional

Returns:

The name container component. Or None if the property is not available.

Return type:

NameContainerComp | None

property size: SizeStructGenericComp[UnitMM]

Gets/Sets the size of the shape in UnitMM Values.

When setting this value, it can be set with a com.sun.star.awt.Size instance or a SizeStructGenericComp instance.

The Size can be set by just setting a Size property.

Returns:

Size in UnitMM Values.

Return type:

SizeStructGenericComp[UnitMM]

Example

Can be set by just setting a Size property using int or UnitMM.

shape.size.width = 1000 # 10 mm
shape.size.height = UnitMM(20) # 20 mm

Can also be set using any UnitT object.

shape.size.width = UnitCM(1.2)
shape.size.height = UnitMM(40)

Can also be set using a com.sun.star.awt.Size struct.

shape.size = Size(1000, 2000) # in 1/100mm

property size_protect: bool | None

Gets/Sets With this set to True, this Shape may not be sized interactively in the user interface.

optional

Return type:

bool | None

property style: StyleComp | None

Gets/Sets - this property lets you get and set a style for this shape.

optional

Returns:

The style component. Or None if the property is not available.

Return type:

StyleComp | None

property transformation: HomogenMatrix3StructComp | None

this property lets you get and set the transformation matrix for this shape.

The transformation is a 3x3 homogeneous matrix and can contain translation, rotation, shearing and scaling.

optional

Returns:

The homogen matrix 3 struct component. Or None if the property is not available.

Return type:

HomogenMatrix3StructComp | None

Hint

HomogenMatrix3 can be imported from ooo.dyn.drawing.homogen_matrix_line3

property visible: bool | None

If this is False, the Shape is not visible on screen outputs.

Please note that the Shape may still be visible when printed, see Printable.

optional

Return type:

bool | None

property z_order: int | None

Gets/Sets the z-order of this Shape.

optional

Return type:

int | None