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 seeooodev.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 fromooodev.loader.inst.options
- addon_initialize(addon_xcc)[source]
- Return type:
XComponent
- Parameters:
addon_xcc (com.sun.star.uno.XComponentContext) –
- 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) –
- 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 viaprops
.DISPATCHED
Event args data contains any results from the dispatch commands.Changed in version 0.40.0: Now supports
in_thread
parameter.
- 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:
See also
- 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) –
- 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_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_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, …]
Note
The current supported prefixes are:
.uno:
vnd.sun.star.
service:
New in version 0.40.0.
- 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) –
- 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 itdynamic
property set toFalse
.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 toLo.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.
- on_component_loading(event_args)[source]
- Return type:
None
- Parameters:
event_args (CancelEventArgs) –
- on_controllers_locking(event_args)[source]
- Return type:
None
- Parameters:
event_args (CancelEventArgs) –
- 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_closing(event_args)[source]
- Return type:
None
- Parameters:
event_args (CancelEventArgs) –
- on_doc_creating(event_args)[source]
- Return type:
None
- Parameters:
event_args (CancelEventArgs) –
- on_doc_opening(event_args)[source]
- Return type:
None
- Parameters:
event_args (CancelEventArgs) –
- on_doc_saving(event_args)[source]
- Return type:
None
- Parameters:
event_args (CancelEventArgs) –
- 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_closing(event_args)[source]
- Return type:
None
- Parameters:
event_args (CancelEventArgs) –
- on_printing(event_args)[source]
- Return type:
None
- Parameters:
event_args (CancelEventArgs) –
- 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) –
- 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 beNone
.
- 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) –
- wait(ms)
Delay execution for a given number of milliseconds.
- Parameters:
ms (int) – Number of milliseconds to delay
- 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 componentlo_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:
- 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:
- property current_doc: OfficeDocumentT | None
Get/Sets 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.It is almost never necessary to set this property directly. When there are changes to the environment, such as when a new document gets focus, this class will automatically pick up the changes and update the current document. However, there may be exceptions this this such as when extension has a OnFocus job. In cases such as that the OnFocus may need to set the current document.
Changed in version 0.47.4: It is now possible to set the current document.
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:
- property events: EventObserver
- Return type:
- property global_event_broadcaster: TheGlobalEventBroadcaster
- Return type:
- 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 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 componentlo_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 componentlo_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