Class WriteDoc

class ooodev.write.WriteDoc(doc, lo_inst=None)[source]

Bases: LoInstPropsPartial, WriteDocPropPartial, TextDocumentComp, ReplaceablePartial, DocumentEventEvents, ModifyEvents, PrintJobEvents, RefreshEvents, PropertyChangeImplement, VetoableChangeImplement, QiPartial, PropPartial, GuiPartial, ServicePartial, EventsPartial, StylePartial, DocIoPartial[WriteDoc], CreateDialogPartial, DispatchPartial, LibrariesPartial, DocCommonPartial, CustomPropertiesPartial

A class to represent a Write document.

class ContainerListener(form_name, cp, lo_inst, subscriber=None)

Bases: Base, XContainerListener

Parameters:
  • args (Any) –

  • kwargs (Any) –

Return type:

Any

__init__(form_name, cp, lo_inst, subscriber=None)
Parameters:
Return type:

None

disposing(event)

Gets called when the broadcaster is about to be disposed.

All listeners and all other objects, which reference the broadcaster should release the reference to the source. No method should be invoked anymore on this object ( including XComponent.removeEventListener() ).

This method is called for every listener registration of derived listener interfaced, not only for registrations at XComponent.

Return type:

None

Parameters:

event (com.sun.star.lang.EventObject) –

elementInserted(event)

Event is invoked when a container has inserted an element.

Return type:

None

Parameters:

event (com.sun.star.container.ContainerEvent) –

elementRemoved(event)

Event is invoked when a container has removed an element.

Return type:

None

Parameters:

event (com.sun.star.container.ContainerEvent) –

elementReplaced(event)

Event is invoked when a container has replaced an element.

Return type:

None

Parameters:

event (com.sun.star.container.ContainerEvent) –

getImplementationId()
getTypes()
is_element_monitored_form(element)
Return type:

bool

Parameters:

element (Any) –

reset()
Return type:

None

property lo_inst: LoInst
Return type:

LoInst

__init__(doc, lo_inst=None)[source]

Constructor

Parameters:
  • doc (XTextDocument) – A UNO object that supports com.sun.star.text.TextDocument service.

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

Raises:

NotSupportedDocumentError – If document is not a Writer document.

Return type:

None

activate()

Activates document window.

Return type:

None

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_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_refresh_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_refreshed(cb)

Adds a listener for an event.

Event is invoked when when the object data is refreshed.

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

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

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) –

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=True)[source]

Closes text document

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.

Returns:

False if DOC_CLOSING event is canceled, Otherwise True.

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.

compare_cursor_ends(c1, c2)[source]

Compares two cursors ranges end positions

Parameters:
  • c1 (XTextRange) – first cursor range

  • c2 (XTextRange) – second cursor range

Raises:

Exception – if comparison fails

Returns:

Compare result. CompareEnum.BEFORE if c1 end position is before c2 end position. CompareEnum.EQUAL if c1 end position is equal to c2 end position. CompareEnum.AFTER if c1 end position is after c2 end position.

Return type:

CompareEnum

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.

create_replace_descriptor()[source]

Creates a Search Descriptor which contains properties that specify a search in this container.

The WriteSearchReplace also contains methods to perform search and replace.

Returns:

The search replace instance.

Return type:

WriteSearchReplace

New in version 0.30.0.

create_search_descriptor()[source]

Creates a Search Descriptor which contains properties that specify a search in this container.

The WriteSearchReplace also contains methods to perform the search.

Returns:

The search replace instance.

Return type:

WriteSearchReplace

Example

>>> search = doc.create_search_descriptor()
>>> search.set_search_string("important")
>>> first = search_desc.find_first()
>>> print(first.get_string())
important

New in version 0.30.0.

create_style_char(style_name, styles=None)[source]

Creates a character style and adds it to document character styles.

Parameters:
  • text_doc (XTextDocument) – Text Document

  • style_name (str) – The name of the character style.

  • styles (Sequence[StyleT], optional) – One or more styles to apply.

Returns:

Newly created style

Return type:

WriteCharacterStyle

create_style_para(style_name, styles=None)[source]

Creates a paragraph style and adds it to document paragraph styles.

Parameters:
  • style_name (str) – The name of the paragraph style.

  • styles (Sequence[StyleT], optional) – One or more styles to apply.

Returns:

Newly created style

Return type:

WriteParagraphStyle

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

find_all(desc)[source]

Searches the contained texts for all occurrences of whatever is specified.

Parameters:

desc (XSearchDescriptor | WriteSearch | WriteReplace) – The search descriptor.

Returns:

The found occurrences.

Return type:

WriteTextRange | None

Note

It is recommended to use the WriteSearch class to perform searches. The create_search_descriptor() method creates an instance of WriteSearch.

New in version 0.30.0.

find_bookmark(bm_name)[source]

Finds a bookmark

Parameters:

bm_name (str) – Bookmark name

Returns:

Bookmark if found; Otherwise, None

Return type:

WriteTextContent | None

find_first(desc)[source]

Searches the contained texts for the next occurrence of whatever is specified.

Parameters:

desc (XSearchDescriptor | WriteSearch | WriteReplace) – The search descriptor.

Returns:

The found occurrence.

Return type:

WriteTextRange | None

Note

It is recommended to use the WriteSearch class to perform searches. The create_search_descriptor() method creates an instance of WriteSearch.

New in version 0.30.0.

find_next(start, desc)[source]

Searches the contained texts for the next occurrence of whatever is specified.

Parameters:
  • start (XInterface | ComponentT) – The starting point of the search. Any object that supports XInterface or an object that has a Component that supports XInterface.

  • desc (XSearchDescriptor | WriteSearch | WriteReplace) – The search descriptor.

Return type:

WriteTextRange[WriteDoc] | None

Note

It is recommended to use the WriteSearch class to perform searches. The create_search_descriptor() method creates an instance of WriteSearch.

New in version 0.30.0.

Return type:

WriteTextRange[WriteDoc] | None

Parameters:
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()[source]

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_cursor()[source]
get_cursor(*, cursor_obj: Any)
get_cursor(*, rng: com.sun.star.text.XTextRange, txt: com.sun.star.text.XText)
get_cursor(*, rng: com.sun.star.text.XTextRange)
get_cursor(**kwargs)

Returns the cursor of the document.

Return type:

WriteTextCursor[WriteDoc]

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)

Gets a document.

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

  • lo_inst (LoInst | None) –

Raises:

Exception – If not a Draw document.

Returns:

Document.

Return type:

_T

get_doc_path()[source]

Gets document path as a System path such has C:\Users\User\Documents\MyDoc.odt.

Returns:

Document path if available; Otherwise empty string.

Return type:

PathOrStr

New in version 0.20.4.

get_doc_settings()[source]

Gets Text Document Settings

Returns:

Settings

Return type:

XPropertySet

get_dpi()

Gets Dispatch provider interception.

Returns:

Dispatch provider interception.

Return type:

XDispatchProviderInterception

get_draw_page()[source]

Gets draw page.

Returns:

Draw Page

Return type:

GenericDrawPage

get_draw_pages()[source]

Gets draw pages.

Returns:

Draw Page

Return type:

GenericDrawPages

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

Gets graphic links

Parameters:

doc (XComponent) – Document

Raises:

MissingInterfaceError – if doc does not implement XTextGraphicObjectsSupplier interface

Returns:

Graphic Links on success, Otherwise, None

Return type:

NameAccessComp | None

get_left_cursor(rng)[source]

Creates a new TextCursor with position left that can travel right.

Parameters:

rng (XTextRange) – Text Range.

Returns:

a new instance of a TextCursor which is located at the specified TextRange to travel in the given text context.

Return type:

WriteTextCursor

get_num_of_pages()[source]

Gets document page count

Returns:

page count

Return type:

int

get_page_count_field(numbering_type=NumberingTypeEnum.ARABIC)[source]

Gets page count field

Returns:

Page Count Field

Return type:

PageCountComp

Parameters:

numbering_type (NumberingTypeEnum) –

get_page_number_field(numbering_type=NumberingTypeEnum.ARABIC, sub_type=PageNumberType.CURRENT)[source]

Gets Arabic style number showing current page value

Parameters:
  • numbering_type (NumberingTypeEnum, optional) – Numbering Type. Defaults to NumberingTypeEnum.ARABIC.

  • sub_type (PageNumberType, optional) – Page Number Type. Defaults to PageNumberType.CURRENT.

Returns:

Page Number Field

Return type:

PageNumberComp

get_page_size()[source]

Get page size in 1/100 mm units.

Raises:
  • PropertiesError – If unable to access properties

  • Exception – If unable to get page size

Returns:

Page Size in 1/100 mm units.

Return type:

Size

get_page_text_size()[source]

Get page text size in 1/100 mm units.

Raises:
  • PropertiesError – If unable to access properties

  • Exception – If unable to get page size

Returns:

Page text Size in 1/100 mm units.

Return type:

Size

get_page_text_width()[source]

Get the width of the page’s text area in 1/100 mm units.

Returns:

Page Width in 1/100 mm units on success; Otherwise 0

Return type:

int

get_paragraph_cursor()[source]

Gets document paragraph cursor

Raises:

ParagraphCursorError – If Unable to get cursor

Returns:

Paragraph cursor

Return type:

WriteParagraphCursor

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_right_cursor(rng)[source]

Creates a new TextCursor with position right that can travel left.

Parameters:

rng (XTextRange) – Text Range.

Returns:

a new instance of a TextCursor which is located at the specified TextRange to travel in the given text context.

Return type:

WriteTextCursor

get_selected()[source]

Gets the text range for current selection

Parameters:

text_doc (XTextDocument) – Text Document

Raises:

MissingInterfaceError – If unable to obtain required interface.

Returns:

If no selection is made then None is returned; Otherwise, Text Range.

Return type:

WriteTextRange | None

Note

Writer must be visible for this method or None is returned.

get_selected_str()[source]

Gets the first selection text for Document

Returns:

Selected text or empty string.

Return type:

str

Note

Writer must be visible for this method or empty string is returned.

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_sentence_cursor()[source]

Gets document sentence cursor.

Raises:

SentenceCursorError – If Unable to get cursor.

Returns:

Sentence Cursor.

Return type:

WriteSentenceCursor

get_services()

Gets service names for the instance.

Returns:

service names

Return type:

List[str]

get_style_cell(name='Standard')[source]

Gets a cell style by name.

Parameters:

name (str, optional) – Name of style to get. Defaults to Standard.

Raises:

StyleError – If unable to get style

Returns:

Style

Return type:

WriteCellStyle

get_style_character(name='Standard')[source]

Gets a character style by name.

Parameters:

name (str, StyleCharKind, optional) – Name of style to get. Defaults to Standard.

Raises:

StyleError – If unable to get style

Returns:

Style

Return type:

WriteCharacterStyle

get_style_families()[source]

Gets a cell style by name.

Raises:

StyleError – If unable to get style

Returns:

Style

Return type:

WriteStyleFamilies

get_style_frame(name='Frame')[source]

Gets a frame style by name.

Parameters:

name (str, StyleFrameKind, optional) – Name of style to get. Defaults to Frame.

Raises:

StyleError – If unable to get style

Returns:

Style

Return type:

WriteStyle

get_style_names(family_style_name=FamilyNamesKind.PARAGRAPH_STYLES)[source]

Gets a list of style names

Parameters:

family_style_name (str, FamilyNamesKind, optional) – name of family style. Default is FamilyNamesKind.PARAGRAPH_STYLES.

Raises:

StyleError – If unable to access Style names

Returns:

List of style names

Return type:

List[str]

get_style_numbering(name=StyleListKind.NUM_123)[source]

Gets a character style by name.

Parameters:

name (str, StyleListKind, optional) – Name of style to get. Defaults to StyleListKind.NUM_123.

Raises:

StyleError – If unable to get style

Returns:

Style

Return type:

WriteNumberingStyle

get_style_page(name='Standard')[source]

Gets a page style by name.

Parameters:

name (str, WriterStylePageKind, optional) – Name of style to get. Defaults to Standard.

Raises:

StyleError – If unable to get style

Returns:

Style

Return type:

WritePageStyle

get_style_paragraph(name='Standard')[source]

Gets a paragraph style by name.

Parameters:

name (str, StyleParaKind, optional) – Name of style to get. Defaults to Standard.

Raises:

StyleError – If unable to get style

Returns:

Style

Return type:

WriteParagraphStyle

get_style_table(name='Default Style')[source]

Gets a table style by name.

Parameters:

name (str, optional) – Name of style to get. Defaults to Default Style.

Raises:

StyleError – If unable to get style

Returns:

Style

Return type:

WriteStyle

get_text()[source]

Gets text that is enumerable.

Returns:

Text.

Return type:

WriteText

get_text_frames()[source]

Gets document Text Frames.

Parameters:

doc (XComponent) – Document.

Returns:

Document Text Frames

Return type:

WriteTextFrames

get_text_graphics()[source]

Gets text graphics.

Raises:

Exception – If unable to get text graphics

Returns:

Text Graphics

Return type:

List[XGraphic]

Note

If there is error getting a graphic link then it is ignored and not added to the return value.

get_text_paragraphs()[source]

Gets text that is enumerable.

Returns:

Text.

Return type:

WriteText

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_view_cursor()[source]

Gets document view cursor.

Describes a cursor in a text document’s view.

Raises:

ViewCursorError – If Unable to get cursor

Returns:

Text View Cursor

Return type:

WriteTextViewCursor

get_word_cursor()[source]

Gets document word cursor.

Raises:

WordCursorError – If Unable to get cursor.

Returns:

Word Cursor.

Return type:

WriteWordCursor

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

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.

is_anything_selected()[source]

Determine if anything is selected.

If Write document is not visible this method returns false.

Returns:

True if anything in the document is selected: Otherwise, False

Return type:

bool

Note

Writer must be visible for this method or False is always returned.

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_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_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_refresh_events_disposing(cb)

Removes a listener for an event

Return type:

None

Parameters:

cb (Any) –

remove_event_refreshed(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

replace_all(desc)

Searches and replace all occurrences of whatever is specified.

Returns:

The number of replacements.

Return type:

int

Parameters:

desc (com.sun.star.util.XSearchDescriptor) –

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.

select_next_word()[source]

Select the word right from the current cursor position.

Returns:

True if go to next word succeeds; Otherwise, False.

Return type:

bool

Events:

Note

The method returning True does not necessarily mean that the cursor is located at the next word, or any word at all! This may happen for example if it travels over empty paragraphs.

Note

Event args event_data is a dictionary containing text_doc.

set_a4_page_format()[source]

Set Page Format to A4

Returns:

True if page format is set; Otherwise, False

Return type:

bool

Attention

set_page_format() 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.

Modify the footer via the page style for the document. Put the text on the right hand side in the header in a general font of 10pt.

Parameters:
  • text (str) – Header Text

  • styles (Sequence[StyleT]) – Styles to apply to the text.

Raises:
  • PropertiesError – If unable to access properties

  • Exception – If unable to set header text

Return type:

None

See also

set_header()

Note

The font applied is determined by Info.get_font_general_name()

Return type:

None

Parameters:
  • text (str) –

  • styles (Sequence[StyleT] | None) –

set_header(text, styles=None)[source]

Modify the header via the page style for the document. Put the text on the right hand side in the header in a general font of 10pt.

Parameters:
  • text (str) – Header Text

  • styles (Sequence[StyleT]) – Styles to apply to the text.

Raises:
  • PropertiesError – If unable to access properties

  • Exception – If unable to set header text

Return type:

None

See also

set_footer()

Note

The font applied is determined by Info.get_font_general_name()

Return type:

None

Parameters:
  • text (str) –

  • styles (Sequence[StyleT] | None) –

set_page_format(paper_format)[source]

Set Page Format

Parameters:

paper_format (PaperFormat) – Paper Format.

Raises:

MissingInterfaceError – If text_doc does not implement XPrintable interface

Returns:

True if page format is set; Otherwise, False

Return type:

bool

Events:

Note

Event args event_data is a dictionary containing fnm.

See also

  • set_a4_page_format()

set_page_numbers()[source]

Modify the footer via the page style for the document. Put page number & count in the center of the footer in Times New Roman, 12pt

Raises:
  • PropertiesError – If unable to get properties

  • Exception – If Unable to set page numbers

Returns:

Page Number Field

Return type:

PageNumberComp

set_property(**kwargs)

Set property value

Parameters:

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

Return type:

None

set_replace_string(replace)

Sets the string to replace the found string with.

Parameters:

replace (str) – The string to replace the found string with.

Return type:

None

set_visible(visible=True)[source]

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

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)[source]

Zooms document to a specific view.

Parameters:

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

Return type:

None

Hint

  • ZoomKind can be imported from ooodev.utils.kind.zoom_kind

Return type:

None

Parameters:

type (ZoomKind) –

zoom_value(value=100)[source]

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 = '8bc6b165-b1b2-4edd-aa47-dae2ee689dd6'
DOC_TYPE: DocType = 1
property basic_libraries: DocumentScriptLibraryContainerComp

Gets the basic libraries container.

Returns:

The instance.

Return type:

DocumentScriptLibraryContainerComp

property component: com.sun.star.text.TextDocument

TextDocument Component

Return type:

TextDocument

property dialog_libraries: DocumentDialogLibraryContainerComp

Gets the dialog libraries container.

Returns:

The instance.

Return type:

DocumentDialogLibraryContainerComp

property draw_page: WriteDrawPage[WriteDoc]

Gets draw page.

Returns:

Draw Page

Return type:

GenericDrawPage

property draw_pages: WriteDrawPages

Gets draw pages.

Returns:

Draw Pages

Return type:

GenericDrawPages

property event_observer: EventObserver

Gets/Sets The Event Observer for this instance.

Return type:

EventObserver

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 events_listener_refresh: RefreshListener

Returns listener

Return type:

RefreshListener

property lo_inst: LoInst

Lo Instance

Return type:

LoInst

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: None

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 Writer Shortcuts.

Returns:

Writer Shortcuts

Return type:

Shortcuts

New in version 0.40.0.

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 tables: WriteTables

Gets tables.

Returns:

Tables

Return type:

WriteTables

property text_frames: WriteTextFrames

Gets text frames.

Returns:

Text Frames

Return type:

WriteTextFrames

property write_doc: WriteDoc

Write Document.

Return type:

WriteDoc