Class DrawDoc

class ooodev.draw.DrawDoc(doc, lo_inst=None)[source]

Bases: DrawingDocumentComp, OfficeDocumentPropPartial, DocPartial[DrawDoc], DrawDocPropPartial, Storable2Partial

Draw document Class

__init__(doc, lo_inst=None)[source]

Constructor.

Parameters:
  • doc (XComponent) – Writer Document component.

  • lo_inst (LoInst, optional) – Lo Instance. Use when creating multiple documents. Defaults to None.

Raises:

NotSupportedDocumentError – If not a valid Draw document.

Return type:

None

activate()

Activates document window.

Return type:

None

add_event_close_events_disposing(cb)

Adds a listener for an event.

Event is invoked when the broadcaster is about to be disposed.

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

Return type:

None

Parameters:

cb (Any) –

add_event_document_event_events_disposing(cb)

Adds a listener for an event.

Event is invoked when the broadcaster is about to be disposed.

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

Return type:

None

Parameters:

cb (Any) –

add_event_document_event_occured(cb)

Adds a listener for an event.

Event is invoked when range selection is completed.

The callback EventArgs.event_data will contain a UNO com.sun.star.document.DocumentEvent struct.

Return type:

None

Parameters:

cb (Any) –

add_event_document_event_occurred(cb)

Adds a listener for an event.

Event is invoked when range selection is completed.

The callback EventArgs.event_data will contain a UNO com.sun.star.document.DocumentEvent struct.

Return type:

None

Parameters:

cb (Any) –

add_event_listener(listener)

Adds an event listener to the component.

Parameters:

listener (XEventListener) – The event listener to be added.

Return type:

None

add_event_modified(cb)

Adds a listener for an event.

Event is invoked when something changes in the object.

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

Return type:

None

Parameters:

cb (Any) –

add_event_modify_events_disposing(cb)

Adds a listener for an event.

Event is invoked when the broadcaster is about to be disposed.

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

Return type:

None

Parameters:

cb (Any) –

add_event_notify_closing(cb)

Adds a listener for an event.

Event is invoked when the listened object is closed really.

Now the listened object is closed really. Listener has to accept that; should deregister itself and release all references to it. It’s not allowed nor possible to disagree with that by throwing any exception.

If the event com.sun.star.lang.XEventListener.disposing() occurred before it must be accepted too. There exist no chance for a disagreement any more.

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

Return type:

None

Parameters:

cb (Any) –

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_print_job_event(cb)

Adds a listener for an event.

Informs the user about the creation or the progress of a PrintJob.

The callback EventArgs.event_data will contain a UNO com.sun.star.view.PrintJobEvent struct.

Return type:

None

Parameters:

cb (Any) –

add_event_print_job_events_disposing(cb)

Adds a listener for an event.

Event is invoked when the broadcaster is about to be disposed.

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

Return type:

None

Parameters:

cb (Any) –

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_query_closing(cb)

Adds a listener for an event.

Event is invoked when somewhere tries to close listened object

Is called before XCloseListener.notifyClosing(). Listener has the chance to break that by throwing a CloseVetoException. This exception must be passed to the original caller of XCloseable.close() without any interaction.

The parameter gets_ownership regulate who has to try to close the listened object again, if this listener disagree with the request by throwing the exception. If it’s set to False the original caller of XCloseable.close() will be the owner in every case. It’s not allowed to call close() from this listener then. If it’s set to True this listener will be the new owner if he throw the exception, otherwise not! If his still running processes will be finished he must call close() on listened object again then.

If this listener doesn’t disagree with th close request it depends from his internal implementation if he deregister itself at the listened object. But normally this must be done in XCloseListener.notifyClosing().

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

Note

The callback event is an instance of KeyValArgs with the following properties: event.key=gets_ownership, event.value is a bool and event.event_data is com.sun.star.lang.EventObject.

This is because the UNO interface com.sun.star.util.XCloseListener has the following signature: void queryClosing ([in] com::sun::star::lang::EventObject Source, [in] boolean GetsOwnership).

Return type:

None

Parameters:

cb (Any) –

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_item_to_toolbar(toolbar_name, item_name, im_fnm)

Add a user-defined icon and command to the start of the specified toolbar.

Parameters:
  • toolbar_name (str) – toolbar name.

  • item_name (str) – item name.

  • im_fnm (str) – image file path.

Return type:

None

add_layer(lm, layer_name)

Adds a layer

Parameters:
  • lm (XLayerManager) – Layer Manager

  • layer_name (str) – Layer Name

Raises:

DrawError – If error occurs.

Returns:

Newly added layer.

Return type:

XLayer

add_slide()

Add a slide to the end of the document.

Raises:
Returns:

The slide that was inserted at the end of the document.

Return type:

DrawPage

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

attach_resource(url, *args)

Informs a model about its resource description.

Return type:

bool

Parameters:
  • url (str) –

  • args (PropertyValue) –

build_play_list(custom_name, *slide_idxs)

Build a named play list container of slides from doc. The name of the play list is custom_name.

Parameters:
  • custom_name (str) – Name for play list

  • slide_idxs (int) – One or more index’s of existing slides to add to play list.

Raises:

DrawError – If error occurs.

Returns:

Name Container.

Return type:

NameContainerComp

close(deliver_ownership=True)

Try to close the Document.

Nobody can guarantee real closing of called object - because it can disagree with that if any still running processes can’t be canceled yet. It’s not allowed to block this call till internal operations will be finished here.

Parameters:

deliver_ownership (bool, optional) – If True ownership is delivered to caller. Default True. True delegates the ownership of this closing object to anyone which throw the CloseVetoException. This new owner has to close the closing object again if his still running processes will be finished. False let the ownership at the original one which called the close() method. They must react for possible CloseVetoExceptions such as when document needs saving and try it again at a later time. This can be useful for a generic UI handling.

Raises:

CancelEventError – If Saving event is canceled.

Returns:

True if document was closed; Otherwise, False.

Return type:

bool

See also

See LibreOffice API: XCloseable.close()

close_doc(deliver_ownership=False)

Closes text document.

Parameters:

deliver_ownership (bool) – True delegates the ownership of this closing object to anyone which throw the CloseVetoException. Default False.

Returns:

False if DOC_CLOSING event is canceled, Other

Return type:

bool

Events:

Note

Event args event_data is a dictionary containing text_doc.

Attention

Lo.close method is called along with any of its events.

combine_shape(shapes, combine_op)

Combines one or more shapes using a dispatch command.

If the owner of this instance is an instance of EventsPartial then the owner will be added as an observer to the dispatch events, for the duration of this method.

Parameters:
  • doc (XComponent) – Document

  • shapes (XShapes) – Shapes to combine

  • combine_op (ShapeCompKind) – Combine Operation.

Raises:

ShapeError – If error occurs.

Returns:

New combined shape.

Return type:

DrawShape

connect_controller(controller)

Is called whenever a new controller is created for this model.

The com.sun.star.lang.XComponent interface of the controller must be used to recognize when it is deleted.

Return type:

None

Parameters:

controller (com.sun.star.frame.XController) –

create_dialog(x, y, width, height, title)

Creates a dialog.

Parameters:
  • x (int) – X coordinate. If -1, the dialog Position is not set.

  • y (int) – Y coordinate. If -1, the dialog Position is not set.

  • width (int) – Width. If -1, the dialog Size is not set.

  • height (int) – Height. If -1, the dialog Size is not set.

  • title (str) – Dialog title.

Returns:

An empty dialog. The dialog contains methods for adding controls.

Return type:

Dialog

classmethod create_doc(loader=None, lo_inst=None, **kwargs)

Creates a new document.

Parameters:
  • loader (XComponentLoader, optional) – Component Loader. Usually generated with Lo

  • lo_inst (LoInst) – Lo Instance. Use when creating multiple documents. Defaults to None.

  • visible (bool) – If True document is visible; Otherwise, document is invisible. Default False.

  • kwargs (Any) –

Returns:

Class instance representing document.

Return type:

_T

classmethod create_doc_from_template(template_path, loader=None, lo_inst=None)

Create a document from a template.

Parameters:
  • template_path (PathOrStr) – path to template file.

  • loader (XComponentLoader, optional) – Component Loader.

  • lo_inst (LoInst, optional) – Lo instance. Used when created multiple documents.

Raises:

Exception – If unable to create document.

Returns:

Class instance representing document.

Return type:

_T

classmethod create_macro_doc(loader=None, lo_inst=None)

Create a document that allows executing of macros.

Parameters:
  • loader (XComponentLoader) – Component Loader.

  • lo_inst (LoInst, optional) – Lo Instance. Use when creating multiple documents. Defaults to None.

Returns:

Class instance representing document.

Return type:

_T

Attention

create_doc() method is called along with any of its events.

delete_slide(idx)[source]

Deletes a slide

Parameters:

idx (int) – Index. Can be a negative value to delete from the end of the document. For example, -1 will delete the last slide.

Returns:

True on success; Otherwise, False

Return type:

bool

disconnect_controller(controller)

is called whenever an existing controller should be deregistered at this model.

The com.sun.star.lang.XComponent interface of the controller must be used to recognize when it is deleted.

Return type:

None

Parameters:

controller (com.sun.star.frame.XController) –

dispatch_cmd(cmd, props=None, frame=None)

Dispatches a LibreOffice command.

Parameters:
  • cmd (str) – Command to dispatch such as GoToCell. Note: cmd does not contain .uno: prefix.

  • props (PropertyValue, optional) – properties for dispatch.

  • frame (XFrame, optional) – Frame to dispatch to.

Raises:
Returns:

A possible result of the executed internal dispatch. The information behind this any depends on the dispatch!

Return type:

Any

Events:

Note

There are many dispatch command constants that can be found in dispatch Namespace

DISPATCHING Event args data contains any properties passed in via props.
DISPATCHED Event args data contains any results from the dispatch commands.
dispose()

Disposes the component.

Return type:

None

duplicate(idx)

Duplicates a slide

Parameters:

idx (int) – Index of slide to duplicate.

Raises:

DrawError If unable to create duplicate.

Returns:

Duplicated slide.

Return type:

DrawPage

find_master_page(style)

Finds master page

Parameters:

style (str) – Style of master page

Raises:
Returns:

Master page as Draw Page if found.

Return type:

DrawPage

find_slide_idx_by_name(name)

Gets a slides index by its name

Parameters:

name (str) – Slide Name

Returns:

Zero based index if found; Otherwise -1

Return type:

int

classmethod from_current_doc()

Get a document from the current component.

This method is useful in macros where the access to current document is needed. This method does not require the use of the MacroLoader in macros.

Parameters:

lo_inst (LoInst, optional) – Lo Instance. Use when creating multiple documents. Defaults to None.

Returns:

Class instance representing document.

Return type:

_T

Example

from ooodev.calc import CalcDoc
doc = CalcDoc.from_current_doc()
doc.sheets[0]["A1"].Value = "Hello World"

See also

ooodev.utils.lo.Lo.current_doc

get_args()

Provides read access on currently representation of the com.sun.star.document.MediaDescriptor of this model which describes the model and its state

Return type:

Tuple[PropertyValue, ...]

get_control_access()

Get control access from office document.

Returns:

control access.

Return type:

XControlAccess

get_controller()

Gets controller from document.

Returns:

Controller.

Return type:

XController

get_current_controller()

Provides access to the controller which currently controls this model

Return type:

XController

get_current_selection()

Provides read access on current selection on controller

Return type:

XInterface

get_custom_properties()

Gets custom properties.

Returns:

custom properties.

Return type:

DotDict

Hint

DotDict is a class that allows you to access dictionary keys as attributes or keys. DotDict can be imported from ooodev.utils.helper.dot_dict.DotDict.

get_custom_property(name, default=<object object>)

Gets a custom property.

Parameters:
  • name (str) – The name of the property.

  • default (Any, optional) – The default value to return if the property does not exist.

Raises:

AttributeError – If the property is not found.

Returns:

The value of the property.

Return type:

Any

classmethod get_doc_from_component(doc, lo_inst=None)

Gets a document.

Parameters:
  • doc (XComponent) – Component to build document from.

  • lo_inst (LoInst, optional) – Lo Instance. Use when creating multiple documents. Defaults to None.

Raises:

Exception – If not a valid document.

Returns:

Document.

Return type:

_T

get_dpi()

Gets Dispatch provider interception.

Returns:

Dispatch provider interception.

Return type:

XDispatchProviderInterception

get_frame()

Gets frame from doc.

Returns:

document frame.

Return type:

XFrame

get_frame_comp()

Gets frame from doc as a FrameComp.

Returns:

document frame.

Return type:

FrameComp

get_handout_master_page()

Gets handout master page

Raises:
Returns:

Draw Page

Return type:

DrawPage

get_layer(layer_name)

Gets layer from layer name

Parameters:

layer_name (str) – Layer Name

Raises:
  • NameError – If layer_name does not exist.

  • DrawError – If unable to get layer

Returns:

Found Layer

Return type:

XLayer

get_layer_manager()

Gets Layer manager for document.

Parameters:

doc (XComponent) – Document

Raises:

DrawError – If error occurs.

Returns:

Layer Manager

Return type:

XLayerManager

get_location()

After XStorable.storeAsURL() it returns the URL the object was stored to.

Return type:

str

get_master_page(idx)

Gets master page by index

Parameters:

idx (int) – Index of master page

Raises:
Returns:

Master page as Draw Page.

Return type:

MasterDrawPage

get_master_page_count()

Gets master page count

Raises:

DrawError – If error occurs.

Returns:

Master Page Count.

Return type:

int

get_notes_page_by_index(idx)

Gets notes page by index.

Each draw page has a notes page.

Parameters:

idx (int) – Index

Raises:

DrawPageError – If error occurs.

Returns:

Notes Page.

Return type:

DrawPage

See also

get_notes_page()

get_ordered_shapes()

Gets ordered shapes

Returns:

List of Ordered Shapes.

Return type:

List[ShapeBase[_T]]

See also

get_shapes()

Note

The Shapes returned from this method will have various properties and methods injected into them based on the UNO services they support.

get_play_list()

Gets Play list

Raises:

DrawError – If error occurs.

Returns:

Name Container

Return type:

NameContainerComp

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

Get selected shapes.

Returns:

List of selected shapes.

Return type:

List[ShapeBase]

Note

See: Rotate Shape Macro for an example.

get_selection()

Gets selection.

Returns:

Returns current selection or None.

Return type:

Any

get_selection_supplier()

Gets selection supplier

Returns:

Selection supplier

Return type:

XSelectionSupplier

get_services()

Gets service names for the instance.

Returns:

service names

Return type:

List[str]

get_shape_factory()

Gets a shape factory that can be used to convert XShape to ShapeBase objects.

Returns:

Shape Factory

Return type:

ShapeFactory

get_shapes()

Gets shapes

Parameters:

doc (XComponent) – Document

Raises:

DrawError – If error occurs.

Returns:

List of Shapes.

Return type:

List[ShapeBase[_T]]

Note

The Shapes returned from this method will have various properties and methods injected into them based on the UNO services they support.

get_shapes_text()

Gets the text from inside all the document shapes

Returns:

Shapes text.

Return type:

str

get_slide(**kwargs)

Gets slide

Parameters:
  • slides (XDrawPages) – Draw Pages

  • idx (int) – Index of slide. Default 0

Raises:
  • IndexError – If idx is out of bounds

  • DrawError – If any other error occurs.

Returns:

Slide as Draw Page.

Return type:

DrawPage

get_slide_number(xdraw_view)

Gets slide number.

Parameters:

xdraw_view (XDrawView) – Draw View.

Raises:

DrawError – If error occurs.

Returns:

Slide Number.

Return type:

int

get_slide_size()

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

Raises:

SizeError – If unable to get size.

Returns:

Size struct.

Return type:

Size

get_slides()[source]

Gets the draw pages of a document.

Parameters:

doc (XComponent) – Document.

Raises:
Returns:

Draw Pages.

Return type:

DrawPages

get_slides_count()

Gets the slides count.

Returns:

Number of slides.

Return type:

int

get_slides_list()

Gets all the slides as a list of XDrawPage

Returns:

List of pages

Return type:

List[DrawPage[_T]]

get_top_window()

Gets top window.

Returns:

Top window or None if there is no Active Top Window.

Return type:

XTopWindow | None

get_url()

Provides information about the location of this model

Return type:

str

get_viewed_page()

Gets viewed page

Raises:

DrawPageError – If error occurs.

Returns:

Draw Page

Return type:

DrawPage

goto_page(page)

Go to page.

Parameters:

page (XDrawPage) – Page.

Raises:

DrawError – If error occurs.

Return type:

None

has_controllers_locked()

determines if there is at least one lock remaining.

While there is at least one lock remaining, some notifications for display updates are not broadcasted to the controllers.

Return type:

bool

has_custom_property(name)

Gets if a custom property exists.

Parameters:

name (str) – The name of the property to check.

Returns:

True if the property exists, otherwise False.

Return type:

bool

has_location()

The object may know the location because it was loaded from there, or because it is stored there.

Return type:

bool

hide_all_menu_bars()

Make all the toolbars invisible.

Return type:

None

hide_menu_bar()

Hides the main menu bar.

Return type:

None

input_box(title, msg, input_value='', ok_lbl='OK', cancel_lbl='Cancel', is_password=False)

Displays an input box and returns the results.

Parameters:
  • title (str) – Title for the dialog

  • msg (str) – Message to display such as “Input your Name”

  • input_value (str, optional) – Value of input box when first displayed.

  • ok_lbl (str, optional) – OK button Label. Defaults to “OK”.

  • cancel_lbl (str, optional) – Cancel Button Label. Defaults to “Cancel”.

  • is_password (bool, optional) – Determines if the input box is masked for password input. Defaults to False.

Returns:

The value of input or empty string.

Return type:

str

Note

Raises a global event GblNamedEvent.INPUT_BOX_CREATING before creating the dialog. The event args are of type CancelEventArgs. The event_data is a dictionary that contains the following key:

  • msg: The message to display.

  • title: The title of the dialog.

  • input_value: The value of the input box when first displayed.

  • ok_lbl: The label for the OK button.

  • cancel_lbl: The label for the Cancel button.

  • is_password: Determines if the input box is masked for password input.

  • frame: The frame of the dialog. If not set, the frame of the current document is used.

The default frame is None. If set value must be a XFrame object.

If the event is cancelled, the result value of event_data` if set will be returned. Otherwise if the event is not handled, a ``CancelEventError is raised.

insert_master_page(idx)

Inserts a master page

Parameters:

idx (int) – Index used to insert page

Raises:

DrawPageError – If unable to insert master page.

Returns:

The newly inserted draw page.

Return type:

MasterDrawPage

insert_slide(idx)

Inserts a slide at the given position in the document

Parameters:

idx (int) – Index, can be a negative value to insert from the end of the document. For example, -1 will insert at the end of the document.

Raises:
Returns:

New slide that was inserted.

Return type:

DrawPage

is_readonly()

It is not possible to call XStorable.store() successfully when the data store is read-only.

Return type:

bool

lock_controllers()

suspends some notifications to the controllers which are used for display updates.

The calls to XModel.lockControllers() and XModel.unlockControllers() may be nested and even overlapping, but they must be in pairs. While there is at least one lock remaining, some notifications for display updates are not broadcasted.

Return type:

None

maximize()

Maximizes document window.

Return type:

None

minimize()

Minimizes document window.

Return type:

None

msgbox(msg, title='Message', boxtype=MessageBoxType.MESSAGEBOX, buttons=MessageBoxButtonsEnum.BUTTONS_OK)

Simple message box.

Parameters:
  • msg (str) – the message for display.

  • title (str, optional) – the title of the message box. Defaults to “Message”.

  • boxtype (MessageBoxType, optional) – determines the type of message box to display. Defaults to Type.MESSAGEBOX.

  • buttons (MessageBoxButtonsEnum, int, optional) – determines what buttons to display. Defaults to Buttons.BUTTONS_OK.

Returns:

MessageBoxResultsEnum

Return type:

Results

Note

If BoxType is an integer, the following values are valid:

  • 0: MESSAGEBOX

  • 1: INFOBOX

  • 2: WARNINGBOX

  • 3: ERRORBOX

  • 4: QUERYBOX

Note

  • Button press Abort return MessageBoxResultsEnum.CANCEL

  • Button press Cancel return MessageBoxResultsEnum.CANCEL

  • Button press Ignore returns MessageBoxResultsEnum.IGNORE

  • Button press No returns MessageBoxResultsEnum.NO

  • Button press OK returns MessageBoxResultsEnum.OK

  • Button press Retry returns MessageBoxResultsEnum.RETRY

  • Button press Yes returns MessageBoxResultsEnum.YES

Note

Raises a global event GblNamedEvent.MSG_BOX_CREATING before creating the dialog. The event args are of type CancelEventArgs. The event_data is a dictionary that contains the following key:

  • msg: The message to display.

  • title: The title of the dialog.

  • boxtype: The type of message box to display.

  • buttons: The buttons to display.

If the event is cancelled, the result value of event_data` if set will be returned. Otherwise if the event is not handled, a ``CancelEventError is raised.

classmethod open_doc(fnm, loader=None, lo_inst=None, **kwargs)

Open a office document.

Parameters:
  • fnm (PathOrStr) – path of document to open.

  • loader (XComponentLoader, optional) – Component Loader.

  • lo_inst (LoInst, optional) – Lo Instance. Use when creating multiple documents. Defaults to None.

  • visible (bool) – If True document is visible; Otherwise, document is invisible. Default False.

  • kwargs (Any) –

Raises:

CancelEventError – if DOC_OPENING event is canceled.

Returns:

Class instance representing document.

Return type:

_T

Events:

Note

Event args event_data is a dictionary containing all method parameters.

See also

Note

If connection it office is a remote server then File URL must be used, such as file:///home/user/fancy.odt

classmethod open_flat_doc(fnm, loader=None, lo_inst=None)

Opens a flat document.

Parameters:
  • fnm (PathOrStr) – path of XML document.

  • loader (XComponentLoader, optional) – Component loader.

  • lo_inst (LoInst, optional) – Lo instance. Used when created multiple documents.

Raises:

Exception – if unable to open document.

Returns:

Class instance representing document.

Return type:

_T

See also

classmethod open_readonly_doc(fnm, loader=None, lo_inst=None, **kwargs)

Open a office document as read-only.

Parameters:
  • fnm (PathOrStr) – path of document to open.

  • loader (XComponentLoader) – Component Loader.

  • lo_inst (LoInst, optional) – Lo instance. Used when created multiple documents.

  • kwargs (Any) –

Returns:

Class instance representing document.

Return type:

_T

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_custom_property(name)

Removes a custom property.

Parameters:

name (str) – The name of the property to remove.

Raises:

AttributeError – If the property is a forbidden key.

Return type:

None

remove_event_close_events_disposing(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

remove_event_document_event_events_disposing(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

remove_event_document_event_occured(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

remove_event_document_event_occurred(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

remove_event_listener(listener)

Removes an event listener from the component.

Parameters:

listener (XEventListener) – The event listener to be removed.

Return type:

None

remove_event_modified(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

remove_event_modify_events_disposing(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

remove_event_notify_closing(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

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_print_job_event(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

remove_event_print_job_events_disposing(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

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_query_closing(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

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

save_doc(fnm, password=None, format=None)

Save document.

Parameters:
  • fnm (PathOrStr) – file path to save as.

  • password (str, optional) – password to save document with.

  • format (str, optional) – document format such as ‘odt’ or ‘xml’.

Raises:

CancelEventError – If Saving event is canceled.

Returns:

False if DOC_SAVING event is canceled; Otherwise, True

Return type:

bool

Events:

Note

Event args event_data is a dictionary containing all method parameters.

Attention

store_doc() method is called along with any of its events.

set_current_controller(controller)

sets a registered controller as the current controller.

Raises:

com.sun.star.container.NoSuchElementExceptionNoSuchElementException

Return type:

None

Parameters:

controller (com.sun.star.frame.XController) –

set_custom_properties(properties)

Sets custom properties.

Parameters:

properties (DotDict) – custom properties to set.

Return type:

None

Hint

DotDict is a class that allows you to access dictionary keys as attributes or keys. DotDict can be imported from ooodev.utils.helper.dot_dict.DotDict.

Return type:

None

Parameters:

properties (DotDict) –

set_custom_property(name, value)

Sets a custom property.

Parameters:
  • name (str) – The name of the property.

  • value (Any) – The value of the property.

Raises:

AttributeError – If the property is a forbidden key.

set_property(**kwargs)

Set property value

Parameters:

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

Return type:

None

set_visible(visible=True)

Set window visibility.

Parameters:

visible (bool, optional) – If True window is set visible; Otherwise, window is set invisible. Default True

Return type:

None

show_menu_bar()

Shows the main menu bar.

Return type:

None

store()

Stores the data to the URL from which it was loaded. Only objects which know their locations can be stored.

Raises:

com.sun.star.io.IOExceptionIOException

Return type:

None

store_as_url(url, *args)

Stores the object’s persistent data to a URL and makes this URL the new location of the object. This is the normal behavior for UI save-as feature. The change of the location makes it necessary to store the document in a format that the object can load. For this reason the implementation of XStorable.storeAsURL() will throw an exception if a pure export filter is used, it will accept only combined import/export filters. For such filters the method XStorable.storeToURL() must be used that does not change the location of the object.

Parameters:
  • url (str) – The URL to be stored.

  • *args (PropertyValue) – Additional parameters for storing process.

Raises:

com.sun.star.io.IOExceptionIOException

Return type:

None

store_self(*args)

Stores the data to the URL from which it was loaded. Only objects which know their locations can be stored. This is an extension of the XStorable.store(). This method allows to specify some additional parameters for storing process.

Parameters:

*args (PropertyValue) – Additional parameters for storing process.

Raises:
  • com.sun.star.lang.IllegalArgumentExceptionIllegalArgumentException

  • com.sun.star.io.IOExceptionIOException

Return type:

None

store_to_url(url, *args)

Stores the object’s persistent data to a URL and continues to be a representation of the old URL. This is the normal behavior for UI export feature. This method accepts all kinds of export filters, not only combined import/export filters because it implements an exporting capability, not a persistence capability.

Parameters:
  • url (str) – The URL to be stored.

  • *args (PropertyValue) – Additional parameters for storing process.

Raises:

com.sun.star.io.IOExceptionIOException

Return type:

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

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

toggle_menu_bar()

Toggles the main menu bar.

Return type:

None

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

unlock_controllers()

resumes the notifications which were suspended by XModel.lockControllers().

The calls to XModel.lockControllers() and XModel.unlockControllers() may be nested and even overlapping, but they must be in pairs. While there is at least one lock remaining, some notifications for display updates are not broadcasted.

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

zoom(type=ZoomKind.ENTIRE_PAGE)

Zooms document to a specific view.

Parameters:

type (ZoomKind, optional) – Type of Zoom to set. Defaults to ZoomKind.ZOOM_100_PERCENT.

Return type:

None

zoom_value(value=100)

Sets the zoom level of the Document

Parameters:

value (int, optional) – Value to set zoom. e.g. 160 set zoom to 160%. Default 100.

Return type:

None

DOC_CLSID: CLSID = '4bab8970-8a3b-45b3-991c-cbeeac6bd5e3'
DOC_TYPE: DocType = 4
property basic_libraries: DocumentScriptLibraryContainerComp

Gets the basic libraries container.

Returns:

The instance.

Return type:

DocumentScriptLibraryContainerComp

property component: com.sun.star.drawing.DrawingDocument

DrawingDocument Component

Return type:

DrawingDocument

property current_controller: DrawDocView

Gets controller from document.

Returns:

controller.

Return type:

Any

property dialog_libraries: DocumentDialogLibraryContainerComp

Gets the dialog libraries container.

Returns:

The instance.

Return type:

DocumentDialogLibraryContainerComp

property draw_doc: Any

Write Document.

Return type:

DrawDoc

property event_observer: EventObserver

Gets/Sets The Event Observer for this instance.

Return type:

EventObserver

property events_listener_close: CloseListener

Returns listener

Return type:

CloseListener

property events_listener_document_event: DocumentEventListener

Returns listener

Return type:

DocumentEventListener

property events_listener_modify: ModifyListener

Returns listener

Return type:

ModifyListener

property events_listener_print_job: PrintJobListener

Returns listener

Return type:

PrintJobListener

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 lo_inst: LoInst

Lo Instance

Return type:

LoInst

property log: NamedLogger

Gets the logger.

Returns:

The logger.

Return type:

NamedLogger

property menu: MenuApp

Gets access to Draw Menus.

Returns:

Draw Menu

Return type:

MenuApp

Example

# Example of getting the Calc Menus
file_menu = doc.menu["file"]
file_menu[3].execute()

New in version 0.40.0.

property office_doc: OfficeDocumentT

Office Document.

Return type:

OfficeDocumentT

property python_script: PythonScript

Gets the python script instance.

Returns:

The instance.

Return type:

PythonScript

property runtime_uid: str

Gets the runtime id such as 1

Returns:

The runtime id.

Return type:

str

property shortcuts: Shortcuts

Gets access to Draw Shortcuts.

Returns:

Draw Shortcuts

Return type:

Shortcuts

New in version 0.40.0.

property slides: DrawPages[DrawDoc]

Returns: Any: Draw Pages.

Return type:

DrawPages[DrawDoc]

property string_value: str

Gets the string value of the doc such as 'vnd.sun.star.tdoc:/1/'

Returns:

The string value.

Return type:

str

property theme: ThemeComp | None

Gets document theme.

Returns:

Document Theme or None if not available.

Return type:

ThemeComp | None

Note

Theme is only supported in LibreOffice 7.6 and later.

New in version 0.50.0.

property version_info: Tuple[int, ...]

Gets the running LibreOffice version.

Returns:

version as tuple such as (24, 2, 6, 2)

Return type:

tuple