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:

opt (LoOptions | None) –
events (EventObserver | None) –

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

CancelEventError – If Dispatching is canceled via event.
DispatchError – If any other error occurs.

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.

See also

2.5 Saving a Document

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:

connector (connectors.ConnectPipe, connectors.ConnectSocket, ConnectBase, None) – Connection information. Ignore for macros.
cache_obj (Cache, optional) – Cache instance that determines of LibreOffice profile is to be copied and cached Ignore for macros. Defaults to None.
opt (Options, optional) – Extra Load options.

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)

See also

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:

src (Any) –
event (EventArgs) –

on_lo_del_cache_attrs(source, event)[source]

Return type:

None

Parameters:

source (object) –
event (EventArgs) –

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:

source (Any) –
event (CancelEventArgs) –

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.

It will autoload if called in a macro.
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

Get the current document.

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

Return type:: OfficeDocumentT

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.

It will autoload if called in a macro.
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.

It will autoload if called in a macro.
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 xscript_context: com.sun.star.script.provider.XScriptContext

Return type:: XScriptContext