Class LoInst

For general documation of this class see Class Lo as it mirrors this class for properties and methods.

class ooodev.loader.inst.LoInst(opt=None, events=None, **kwargs)[source]

Lo instance class. This is the main class for interacting with LO.

This class is of advanced usage and is not intended for general use.

In most cases, you should use the Lo static class instead.

This class mirrors the properties and methods of the Lo class so for documentation see ooodev.utils.lo.Lo,

Parameters:
__init__(opt=None, events=None, **kwargs)[source]

Constructor

Parameters:
  • opt (LoOptions, optional) – Options

  • events (EventObserver, optional) – Event observer

Return type:

None

Hint

  • LoOptions can be imported from ooodev.loader.inst.options

addon_initialize(addon_xcc)[source]
Return type:

XComponent

Parameters:

addon_xcc (com.sun.star.uno.XComponentContext) –

static capitalize(s)[source]
Return type:

str

Parameters:

s (str) –

close(closeable: com.sun.star.util.XCloseable)[source]
close(closeable: com.sun.star.util.XCloseable, deliver_ownership: bool)
close(closeable, deliver_ownership=False)
Return type:

bool

Parameters:

closeable (com.sun.star.util.XCloseable) –

close_doc(doc: Any)[source]
close_doc(doc: Any, deliver_ownership: bool)
close_doc(doc, deliver_ownership=False)
Return type:

None

Parameters:

doc (Any) –

close_office()[source]
Return type:

bool

create_doc(doc_type: ooodev.loader.inst.doc_type.DocTypeStr)[source]
create_doc(doc_type: ooodev.loader.inst.doc_type.DocTypeStr, loader: com.sun.star.frame.XComponentLoader)
create_doc(doc_type: ooodev.loader.inst.doc_type.DocTypeStr, *, props: Iterable[ooo.lo.beans.property_value.PropertyValue])
create_doc(doc_type: ooodev.loader.inst.doc_type.DocTypeStr, loader: com.sun.star.frame.XComponentLoader, props: Iterable[ooo.lo.beans.property_value.PropertyValue])
create_doc(doc_type, loader=None, props=None)
Return type:

XComponent

Parameters:
  • doc_type (DocTypeStr) –

  • loader (com.sun.star.frame.XComponentLoader | None) –

  • props (Iterable[PropertyValue] | None) –

create_doc_from_template(template_path: Any)[source]
create_doc_from_template(template_path: Any, loader: com.sun.star.frame.XComponentLoader)
create_doc_from_template(template_path, loader=None)
Return type:

XComponent

Parameters:
  • template_path (PathOrStr) –

  • loader (com.sun.star.frame.XComponentLoader | None) –

create_instance_mcf(atype: Type[ooodev.utils.type_var.T], service_name: str) T | None[source]
create_instance_mcf(atype: Type[ooodev.utils.type_var.T], service_name: str, args: Tuple[Any, ...] | None) T | None
create_instance_mcf(atype: Type[ooodev.utils.type_var.T], service_name: str, *, raise_err: Literal[True]) ooodev.utils.type_var.T
create_instance_mcf(atype: Type[ooodev.utils.type_var.T], service_name: str, *, raise_err: Literal[False]) T | None
create_instance_mcf(atype: Type[ooodev.utils.type_var.T], service_name: str, args: Tuple[Any, ...] | None, raise_err: Literal[True]) ooodev.utils.type_var.T
create_instance_mcf(atype: Type[ooodev.utils.type_var.T], service_name: str, args: Tuple[Any, ...] | None, raise_err: Literal[False]) T | None
create_instance_mcf(atype, service_name, args=None, raise_err=False)
Return type:

T | None

Parameters:
  • atype (Type[T]) –

  • service_name (str) –

  • args (Tuple[Any, ...] | None) –

  • raise_err (bool) –

create_instance_msf(atype: Type[ooodev.utils.type_var.T], service_name: str) T | None[source]
create_instance_msf(atype: Type[ooodev.utils.type_var.T], service_name: str, msf: Any | None) T | None
create_instance_msf(atype: Type[ooodev.utils.type_var.T], service_name: str, *, raise_err: Literal[True]) ooodev.utils.type_var.T
create_instance_msf(atype: Type[ooodev.utils.type_var.T], service_name: str, *, raise_err: Literal[False]) T | None
create_instance_msf(atype: Type[ooodev.utils.type_var.T], service_name: str, msf: Any | None, raise_err: Literal[True]) ooodev.utils.type_var.T
create_instance_msf(atype: Type[ooodev.utils.type_var.T], service_name: str, msf: Any | None, raise_err: Literal[True], *args: Any) ooodev.utils.type_var.T
create_instance_msf(atype: Type[ooodev.utils.type_var.T], service_name: str, msf: Any | None, raise_err: Literal[False]) T | None
create_instance_msf(atype: Type[ooodev.utils.type_var.T], service_name: str, msf: Any | None, raise_err: Literal[False], *args: Any) T | None
create_instance_msf(atype, service_name, msf=None, raise_err=False, *args)
Return type:

T | None

Parameters:
  • atype (Type[T]) –

  • service_name (str) –

  • msf (XMultiServiceFactory | None) –

  • raise_err (bool) –

  • args (Any) –

create_macro_doc(doc_type: ooodev.loader.inst.doc_type.DocTypeStr)[source]
create_macro_doc(doc_type: ooodev.loader.inst.doc_type.DocTypeStr, loader: com.sun.star.frame.XComponentLoader)
create_macro_doc(doc_type, loader=None)
Return type:

XComponent

Parameters:
  • doc_type (DocTypeStr) –

  • loader (com.sun.star.frame.XComponentLoader | None) –

delay(ms)[source]

Delay execution for a given number of milliseconds.

Parameters:

ms (int) – Number of milliseconds to delay

Return type:

None

dispatch_cmd(cmd, props=None, frame=None, in_thread=False)[source]

Dispatches a LibreOffice command.

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

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

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

  • in_thread (bool, optional) – If True then dispatch is done in a separate thread.

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.

Changed in version 0.40.0: Now supports in_thread parameter.

doc_type_str(doc_type_val)[source]
Return type:

DocTypeStr

Parameters:

doc_type_val (DocType) –

ext_to_doc_type(ext)[source]

Gets document type from extension

Parameters:

ext (str) – extension used for lookup

Returns:

DocTypeStr enum. If not match if found defaults to DocTypeStr.WRITER

Return type:

DocTypeStr

ext_to_format(ext: str)[source]
ext_to_format(ext: str, doc_type: ooodev.loader.inst.doc_type.DocType)
ext_to_format(ext, doc_type=DocType.UNKNOWN)
Return type:

str

Parameters:
  • ext (str) –

  • doc_type (DocType) –

extract_item_name(uno_cmd)[source]
Return type:

str

Parameters:

uno_cmd (str) –

find_container_props(con, nm)[source]
Return type:

XPropertySet | None

Parameters:
  • con (XIndexAccess) –

  • nm (str) –

get_component_factory()[source]

Gets current multi component factory.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Return type:

XMultiComponentFactory

get_container_names(con)[source]
Return type:

List[str] | None

Parameters:

con (XIndexAccess) –

get_context()[source]

Gets current LO Component Context.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Return type:

XComponentContext

get_desktop()[source]

Gets current LO Desktop.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Return type:

XDesktop

get_flat_filter_name(doc_type)[source]

Gets the Flat XML filter name for the doc type.

Parameters:

doc_type (DocTypeStr) – Document type.

Returns:

Flat XML filter name.

Return type:

str

New in version 0.12.0.

get_frame()[source]
Return type:

XFrame

get_model()[source]
Return type:

XModel

get_parent(a_component)[source]
Return type:

XInterface

Parameters:

a_component (com.sun.star.container.XChild) –

get_relative_doc()[source]

Gets current document.

If the current options are set to dynamic, then the current document is returned from the script context. Otherwise, the current internal document is returned. The internal document is set when a new document is created via the Write, Calc, etc.

In most instances the internal document is the same as the xscript context document.

By Default the dynamic option is set to False.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Raises:

NoneError – If the document is None.

Returns:

Current Document

Return type:

XComponent

get_service_factory()[source]

Gets current multi service factory.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Return type:

XMultiServiceFactory

get_singleton(name)[source]

Gets a singleton object from the office default context.

Parameters:

name (str) – Singleton name such as /singletons/com.sun.star.frame.theDesktop

Returns:

Singleton object or None if not found

Return type:

Any

get_supported_dispatch_prefixes()[source]

Gets the prefixes are are supported by the local dispatch_cmd() method.

Returns:

Tuple of supported dispatch prefixes.

Return type:

Tuple[str, …]

New in version 0.40.0.

has_controllers_locked()[source]
Return type:

bool

inspect(obj)[source]
Return type:

None

Parameters:

obj (object) –

static is_none_or_empty(s)[source]
Return type:

bool

Parameters:

s (str) –

static is_null_or_empty(s)
Return type:

bool

Parameters:

s (str) –

is_uno_interfaces(component, *args)[source]
Return type:

bool

Parameters:
  • component (Any) –

  • args (str | UnoInterface) –

static is_url(fnm)[source]
Return type:

bool

Parameters:

fnm (PathOrStr) –

kill_office()[source]
Return type:

None

load_component(component)[source]

Loads a component, can be a document or a sub-component such as a database sub-form

Parameters:

component (XComponent) – Component to load

Return type:

None

Events:

Note

When and instance of this class is created for the purpose of loading a component then the options should have it dynamic property set to False.

New in version 0.9.8.

load_from_lo_loader(loader)[source]

Loads Office from a LoLoader instance.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:

loader (LoLoader) – LoLoader instance.

Returns:

component loader.

Return type:

XComponentLoader

New in version 0.40.0.

load_office(connector=None, cache_obj=None, opt=None)[source]

Loads Office

Not available in a macro.

If running outside of office then a bridge is created that connects to office.

If running from inside of office e.g. in a macro, then Lo.XSCRIPTCONTEXT is used. using_pipes is ignored with running inside office.

Method NOT is Lo Instance Safe. Use Class LoContext when using with multiple document instances.

Parameters:
Returns:

component loader

Return type:

XComponentLoader

Events:

Note

Event args event_data is a dictionary containing all method parameters.

Note

When using this class to connect to a running office instance, the connector parameter should be set to Lo.bridge_connector, the existing bridge connection.

The following example creates a new instance, connects to a running office instance and creates a new calc document.

lo = LoInst()
lo.load_office(Lo.bridge_connector)
lo_doc = lo.create_doc(DocTypeStr.CALC)

Changed in version 0.6.10: Added opt parameter.

Changed in version 0.9.8: connector can now also be ConnectBase to allow for existing connections.

lock_controllers()[source]
Return type:

bool

make_uno_cmd(item_name)[source]
Return type:

str

Parameters:

item_name (str) –

mri_inspect(obj)[source]
Return type:

None

Parameters:

obj (object) –

on_component_loaded(event_args)[source]
Return type:

None

Parameters:

event_args (EventArgs) –

on_component_loading(event_args)[source]
Return type:

None

Parameters:

event_args (CancelEventArgs) –

on_controllers_locked(event_args)[source]
Return type:

None

Parameters:

event_args (EventArgs) –

on_controllers_locking(event_args)[source]
Return type:

None

Parameters:

event_args (CancelEventArgs) –

on_controllers_unlocked(event_args)[source]
Return type:

None

Parameters:

event_args (EventArgs) –

on_controllers_unlocking(event_args)[source]
Return type:

None

Parameters:

event_args (CancelEventArgs) –

on_dispatched(event_args)[source]
Return type:

None

Parameters:

event_args (DispatchArgs) –

on_dispatching(event_args)[source]
Return type:

None

Parameters:

event_args (DispatchCancelArgs) –

on_doc_closed(event_args)[source]
Return type:

None

Parameters:

event_args (EventArgs) –

on_doc_closing(event_args)[source]
Return type:

None

Parameters:

event_args (CancelEventArgs) –

on_doc_created(event_args)[source]
Return type:

None

Parameters:

event_args (EventArgs) –

on_doc_creating(event_args)[source]
Return type:

None

Parameters:

event_args (CancelEventArgs) –

on_doc_opened(event_args)[source]
Return type:

None

Parameters:

event_args (EventArgs) –

on_doc_opening(event_args)[source]
Return type:

None

Parameters:

event_args (CancelEventArgs) –

on_doc_saved(event_args)[source]
Return type:

None

Parameters:

event_args (EventArgs) –

on_doc_saving(event_args)[source]
Return type:

None

Parameters:

event_args (CancelEventArgs) –

on_doc_stored(event_args)[source]
Return type:

None

Parameters:

event_args (EventArgs) –

on_doc_storing(event_args)[source]
Return type:

None

Parameters:

event_args (CancelEventArgs) –

on_global_document_event(src, event, *args, **kwargs)[source]
Return type:

None

Parameters:
on_lo_del_cache_attrs(source, event)[source]
Return type:

None

Parameters:
on_lo_disposed(source, event)[source]
Return type:

None

Parameters:
  • source (Any) –

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

on_lo_disposing_bridge(src, event)[source]
Return type:

None

Parameters:
  • src (EventListener) –

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

on_lo_loaded(source, event)[source]
Return type:

None

Parameters:
  • source (Any) –

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

on_lo_loading(source, event)[source]
Return type:

None

Parameters:
on_office_closed(event_args)[source]
Return type:

None

Parameters:

event_args (EventArgs) –

on_office_closing(event_args)[source]
Return type:

None

Parameters:

event_args (CancelEventArgs) –

on_office_loaded(event_args)[source]
Return type:

None

Parameters:

event_args (EventArgs) –

on_office_loading(event_args)[source]
Return type:

None

Parameters:

event_args (EventArgs) –

on_printing(event_args)[source]
Return type:

None

Parameters:

event_args (CancelEventArgs) –

on_reset(event_args)[source]
Return type:

None

Parameters:

event_args (EventArgs) –

open_doc(fnm: Any)[source]
open_doc(fnm: Any, loader: com.sun.star.frame.XComponentLoader)
open_doc(fnm: Any, *, props: Iterable[ooo.lo.beans.property_value.PropertyValue])
open_doc(fnm: Any, loader: com.sun.star.frame.XComponentLoader, props: Iterable[ooo.lo.beans.property_value.PropertyValue])
open_doc(fnm, loader=None, props=None)
Return type:

XComponent

Parameters:
  • fnm (PathOrStr) –

  • loader (com.sun.star.frame.XComponentLoader | None) –

  • props (Iterable[PropertyValue] | None) –

open_flat_doc(fnm: Any, doc_type: ooodev.loader.inst.doc_type.DocType)[source]
open_flat_doc(fnm: Any, doc_type: ooodev.loader.inst.doc_type.DocType, loader: com.sun.star.frame.XComponentLoader)
open_flat_doc(fnm, doc_type, loader=None)
Return type:

XComponent

Parameters:
  • fnm (PathOrStr) –

  • doc_type (DocType) –

  • loader (com.sun.star.frame.XComponentLoader | None) –

open_readonly_doc(fnm: Any)[source]
open_readonly_doc(fnm: Any, loader: com.sun.star.frame.XComponentLoader)
open_readonly_doc(fnm, loader=None)
Return type:

XComponent

Parameters:
  • fnm (PathOrStr) –

  • loader (com.sun.star.frame.XComponentLoader | None) –

parse_int(s)[source]
Return type:

int

Parameters:

s (str) –

print(*args, **kwargs)[source]
Return type:

None

static print_names(names)[source]
static print_names(names, num_per_line)
static print_names(names, num_per_line=4)
Return type:

None

Parameters:
  • names (Sequence[str]) –

  • num_per_line (int) –

static print_table(name: str, table: Any) None[source]
static print_table(name: str, table: Any, format_opt: ooodev.formatters.formatter_table.FormatterTable) None
static print_table(name, table, format_opt=None)
Return type:

None

Parameters:
  • name (str) –

  • table (Table) –

  • format_opt (FormatterTable | None) –

qi(atype: Type[ooodev.utils.type_var.T], obj: Any) T | None[source]
qi(atype: Type[ooodev.utils.type_var.T], obj: Any, raise_err: Literal[True]) ooodev.utils.type_var.T
qi(atype: Type[ooodev.utils.type_var.T], obj: Any, raise_err: Literal[False]) T | None
qi(atype, obj, raise_err=False)

Generic method that get an interface instance from an object.

Method is Lo Instance Safe for use with multiple documents.

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

  • obj (object) – Object that implements interface.

  • 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.

save(doc)[source]
Return type:

bool

Parameters:

doc (object) –

save_doc(doc: object, fnm: Any) bool[source]
save_doc(doc: object, fnm: Any, password: str) bool
save_doc(doc: object, fnm: Any, password: str, format: str) bool
save_doc(doc, fnm, password=None, format=None)
Return type:

bool

Parameters:
  • doc (object) –

  • fnm (PathOrStr) –

  • password (str | None) –

  • format (str | None) –

script_initialize(sc)[source]
Return type:

XComponent

Parameters:

sc (com.sun.star.script.provider.XScriptContext) –

store_doc(store: com.sun.star.frame.XStorable, doc_type: ooodev.loader.inst.doc_type.DocType, fnm: Any)[source]
store_doc(store: com.sun.star.frame.XStorable, doc_type: ooodev.loader.inst.doc_type.DocType, fnm: Any, password: str)
store_doc(store, doc_type, fnm, password=None)
Return type:

bool

Parameters:
  • store (com.sun.star.frame.XStorable) –

  • doc_type (DocType) –

  • fnm (PathOrStr) –

  • password (str | None) –

store_doc_format(store: com.sun.star.frame.XStorable, fnm: Any, format: str) bool[source]
store_doc_format(store: com.sun.star.frame.XStorable, fnm: Any, format: str, password: str) bool
store_doc_format(store, fnm, format, password=None)
Return type:

bool

Parameters:
  • store (XStorable) –

  • fnm (PathOrStr) –

  • format (str) –

  • password (str | None) –

unlock_controllers()[source]
Return type:

bool

wait(ms)

Delay execution for a given number of milliseconds.

Parameters:

ms (int) – Number of milliseconds to delay

Return type:

None

static wait_enter()[source]

Console displays Press Enter to continue…

Return type:

None

property StarDesktop: com.sun.star.frame.XDesktop

Get current desktop

Return type:

XDesktop

property ThisComponent: XComponent | None

This component is similar to the ThisComponent in Basic.

It is functionally the same as XSCRIPTCONTEXT.getDesktop().getCurrentComponent().

When running in a macro this property can be access directly to get the current document. When not in a macro then load_office() must be called first

This property differs from lo_component in the following ways.

  1. It will autoload if called in a macro.

  2. It will observe the dynamic option for this instance.

When this class options are set to dynamic then this property will always return the current document from internal XSCRIPTCONTEXT; otherwise, it will return the current internal document. In most cases this property should be used instead of lo_component. Also in most cases this property will return the same component lo_component.

Returns:

Component or None if not loaded.

Return type:

XComponent | None

property XSCRIPTCONTEXT: com.sun.star.script.provider.XScriptContext
Return type:

XScriptContext

property app_font_pixel_ratio: GenericSizePos[float]

Gets the ratio between App Font and Pixels.

This is used to convert font sizes to pixels. This value will vary on different systems.

Returns:

Ratios of how many pixels are in an app font.

Return type:

GenericSizePos[float]

property bridge: XComponent | None
Return type:

XComponent | None

property bridge_connector: ConnectBase
Return type:

ConnectBase

property cache: LRUCache

Gets access to the a cache for the current instance.

This is a Least Recently Used (LRU) Cache. This cache is also used within this framework.

Returns:

Cache instance.

Return type:

LRUCache

property current_doc: OfficeDocumentT | None

Get the current document.

If there is no current document then an attempt is made to get the current document from the last active document from the desktop components.

Note

This property does not require the use of the MacroLoader in macros.

Changed in version 0.45.5: This property will now return the latest document from the desktop components if the current document is None.

Return type:

OfficeDocumentT | None

property desktop: TheDesktop

Get the current desktop

Return type:

TheDesktop

property events: EventObserver
Return type:

EventObserver

property global_event_broadcaster: TheGlobalEventBroadcaster
Return type:

TheGlobalEventBroadcaster

property is_default: bool

Gets if the current instance is the default Lo instance.

Return type:

bool

property is_loaded: bool
Return type:

bool

property is_macro_mode: bool
Return type:

bool

property lo_component: XComponent | None

Gets the internal component.

Unlike the this_component property this property will not autoload and it will not observe the dynamic option for this instance.

This property will always return the current internal component document.

In most cases the this_component property should be used instead of this property.

Returns:

Component or None if not loaded.

Return type:

XComponent | None

property lo_loader: LoLoader

Get/Sets the loader for this instance

Return type:

LoLoader

property loader_current: com.sun.star.frame.XComponentLoader
Return type:

XComponentLoader

property null_date: datetime
Return type:

datetime

property options: Options
Return type:

Options

property star_desktop: com.sun.star.frame.XDesktop

Get current desktop

Return type:

XDesktop

property stardesktop: com.sun.star.frame.XDesktop

Get current desktop

Return type:

XDesktop

property sys_font_pixel_ratio: GenericSizePos[float]

Gets the ratio between System Font and Pixels.

This is used to convert font sizes to pixels. This value will vary on different systems.

Returns:

Ratios of how many pixels are in an system font.

Return type:

GenericSizePos[float]

property this_component: XComponent | None

This component is similar to the ThisComponent in Basic.

It is functionally the same as XSCRIPTCONTEXT.getDesktop().getCurrentComponent().

When running in a macro this property can be access directly to get the current document. When not in a macro then load_office() must be called first

This property differs from lo_component in the following ways.

  1. It will autoload if called in a macro.

  2. It will observe the dynamic option for this instance.

When this class options are set to dynamic then this property will always return the current document from internal XSCRIPTCONTEXT; otherwise, it will return the current internal document. In most cases this property should be used instead of lo_component. Also in most cases this property will return the same component lo_component.

Returns:

Component or None if not loaded.

Return type:

XComponent | None

property thiscomponent: XComponent | None

This component is similar to the ThisComponent in Basic.

It is functionally the same as XSCRIPTCONTEXT.getDesktop().getCurrentComponent().

When running in a macro this property can be access directly to get the current document. When not in a macro then load_office() must be called first

This property differs from lo_component in the following ways.

  1. It will autoload if called in a macro.

  2. It will observe the dynamic option for this instance.

When this class options are set to dynamic then this property will always return the current document from internal XSCRIPTCONTEXT; otherwise, it will return the current internal document. In most cases this property should be used instead of lo_component. Also in most cases this property will return the same component lo_component.

Returns:

Component or None if not loaded.

Return type:

XComponent | None

property tmp_dir: Path

Gets the LibreOffice temporary directory.

Returns:

Temporary directory.

Return type:

Path

New in version 0.41.0.

property version: Tuple[int, int, int]

Gets the OooDev version.

Returns:

Version tuple.

Return type:

Tuple[int, int, int]

New in version 0.45.0.

property xscript_context: com.sun.star.script.provider.XScriptContext
Return type:

XScriptContext