Class CalcDoc

class ooodev.calc.CalcDoc(doc, lo_inst=None)[source]

Bases: LoInstPropsPartial, SpreadsheetDocumentComp, QiPartial, PropPartial, GuiPartial, ServicePartial, StylePartial, EventsPartial, DocIoPartial[CalcDoc], CreateDialogPartial, DispatchPartial, LibrariesPartial, CalcDocPropPartial

Defines a Calc Document

__init__(doc, lo_inst=None)[source]

Constructor

Parameters:

doc (XSpreadsheetDocument) – UNO object the supports com.sun.star.sheet.SpreadsheetDocument service.
lo_inst (LoInst, optional) – Lo Instance. Use when creating multiple documents. Defaults to None.

Raises:

NotSupportedDocumentError – If not a valid Calc 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_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) –

call_fun(func_name, *args)[source]

Execute a Calc function by its (English) name and based on the given arguments

Parameters:

func_name (str) – the English name of the function to execute
args (Any) – (Any): the arguments of the called function. Each argument must be either a string, a numeric value or a sequence of sequences ( tuples or list ) combining those types.

Returns:

The (string or numeric) value or the array of arrays returned by the call to the function: When the arguments contain arrays, the function is executed as an array function Wrong arguments generate an error

Return type:

Any

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

close_doc(deliver_ownership: bool)

close_doc(deliver_ownership=False)

Closes 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.
Return type:: None

Note

If deliver_ownership is True then 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.

Attention

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

compute_function(fn, cell_range)[source]

Computes a Calc Function

Parameters:

fn (GeneralFunction | str) – Function to calculate, GeneralFunction Enum value or String such as ‘SUM’ or ‘MAX’
cell_range (XCellRange) – Cell range to apply function on.

Returns:

result of function if successful. If there is an error then 0.0 is returned.

Return type:

float

See also

23.2 General Functions

Hint

GeneralFunction can be imported from ooo.dyn.sheet.general_function

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_cell_style(style_name)[source]

Creates a style

Parameters:: style_name (str) – Style name
Raises:: Exception – if unable to create style.
Returns:: Newly created style
Return type:: XStyle

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.

See also

2.4 Creating a Document

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:

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

dispose()

Disposes the component.

Return type:: None

find_function(func_nm: str) → Tuple[PropertyValue] | None[source]

find_function(idx: int) → Tuple[PropertyValue] | None

find_function(*args, **kwargs)

Finds a function.

Parameters:

func_nm (str) – function name.
idx (int) – Index of function.

Returns:

Function properties as tuple on success; Otherwise, None.

Return type:

Tuple[PropertyValue, …] | None

freeze(num_cols, num_rows)[source]

Freezes spreadsheet columns and rows

Parameters:

num_cols (int) – Number of columns to freeze
num_rows (int) – Number of rows to freeze

Return type:

None

See also

freeze_cols(num_cols)[source]

Freezes spreadsheet columns

Parameters:: num_cols (int) – Number of columns to freeze
Return type:: None

See also

freeze_rows(num_rows)[source]

Freezes spreadsheet rows

Parameters:: num_rows (int) – Number of rows to freeze
Return type:: None

See also

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

Gets the active sheet

Returns:: Active Sheet if found; Otherwise, None
Return type:: CalcSheet | None

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]

Provides access to the controller which currently controls this model

Raises:: MissingInterfaceError – If unable to access controller
Returns:: Controller for Spreadsheet Document
Return type:: XController | None

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

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_dpi()

Gets Dispatch provider interception.

Returns:: Dispatch provider interception.
Return type:: XDispatchProviderInterception

get_frame()

Gets frame from doc.

Returns:: document frame.
Return type:: XFrame

get_frame_comp()

Gets frame from doc as a FrameComp.

Returns:: document frame.
Return type:: FrameComp

get_function_names()[source]

Get a list of all function names.

Returns:: List of function names if found; Otherwise, None.
Return type:: List[str] | None

get_property(name, default=<object object>)

Get property value

Parameters:

name (str) – Property Name.
default (Any, optional) – Return value if property value is None.

Returns:

Property value or default.

Return type:

Any

get_selected_addr()[source]

Gets select cell range addresses

Raises:

Exception – if unable to get document model
MissingInterfaceError – if unable to get interface XCellRangeAddressable

Returns:

Cell range addresses.

Return type:

CellRangeAddress

See also

get_selected_cell_addr()[source]

Gets the cell address of current selected cell of the active sheet.

Raises:: CellError – if active selection is not a single cell
Returns:: Cell Address
Return type:: CellAddress

Note

CellAddress returns Zero-base values. For instance: Cell B4 has Column value of 1 and Row value of 3

See also

get_selected_range()[source]

Gets select cell range

Parameters:

doc (XSpreadsheetDocument) – Spreadsheet Document
model (XModel) – model used to access sheet

Raises:

Exception – if unable to get document model
MissingInterfaceError – if unable to get interface XCellRangeAddressable

Returns:

Cell range addresses

Return type:

RangeObj

See also

get_selection()

Gets selection.

Returns:: Returns current selection or None.
Return type:: Any

get_selection_supplier()

Gets selection supplier

Returns:: Selection supplier
Return type:: XSelectionSupplier

get_services()

Gets service names for the instance.

Returns:: service names
Return type:: List[str]

get_sheet()[source]

get_sheet(idx: int)

get_sheet(sheet_name: str)

get_sheet(*args, **kwargs)

Gets a sheet of spreadsheet document

Parameters:

idx (int, optional) – Zero based index of spreadsheet. Idx can be a negative value to index from the end of the list. For example, -1 will return the last element.
sheet_name (str, optional) – Name of spreadsheet

Raises:

MissingNameError – If spreadsheet is not found by name.
IndexError – If spreadsheet is not found by index.

Returns:

Spreadsheet at index.

Return type:

CalcSheet

get_sheet_names()[source]

Gets names of all existing spreadsheets in the spreadsheet document.

Returns:: Tuple of sheet names.
Return type:: Tuple[str, …]

get_sheets()[source]

Gets all existing spreadsheets in the spreadsheet document.

Returns:: document sheets
Return type:: XSpreadsheets

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

Is the main interface of a SpreadsheetView.

It manages the active sheet within this view.

The com.sun.star.sheet.SpreadsheetView service is the spreadsheet’s extension of the com.sun.star.frame.Controller service and represents a table editing view for a spreadsheet document.

Returns:: CalcSheetView
Return type:: mCalcSheetView

get_view_data()[source]

Gets a set of data that can be used to restore the current view status at later time by using set_view_data()

Returns:: View Data
Return type:: str

get_view_panes()[source]

represents a pane in a view of a spreadsheet document.

Parameters:: doc (XSpreadsheetDocument) – Spreadsheet Document
Raises:: MissingInterfaceError – if unable access the view pane container
Returns:: List of XViewPane on success; Otherwise, None
Return type:: List[XViewPane] | None

Note

The com.sun.star.sheet.XViewPane interface’s getFirstVisibleColumn(), getFirstVisibleRow(), setFirstVisibleColumn() and setFirstVisibleRow() methods query and set the start of the exposed area. The getVisibleRange() method returns a com.sun.star.table. CellRangeAddress struct describing which cells are shown in the pane. Columns or rows that are only partly visible at the right or lower edge of the view are not included.

get_view_states()[source]

Extract the view states for all the sheets from the view data. The states are returned as an array of ViewState objects.

The view data string has the format 100/60/0;0;tw:879;0/4998/0/1/0/218/2/0/0/4988/4998

The view state info starts after the third ;, the fourth entry. The view state for each sheet is separated by ;

Based on a post by user Hanya to: openoffice forum

Return type:: None

Hint

ViewState can be imported from ooodev.utils.view_state

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

hide_all_menu_bars()

Make all the toolbars invisible.

Return type:: None

hide_menu_bar()

Hides the main menu bar.

Return type:: None

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

Displays an input box and returns the results.

Parameters:

title (str) – Title for the dialog
msg (str) – Message to display such as “Input your Name”
input_value (str, optional) – Value of input box when first displayed.
ok_lbl (str, optional) – OK button Label. Defaults to “OK”.
cancel_lbl (str, optional) – Cancel Button Label. Defaults to “Cancel”.
is_password (bool, optional) – Determines if the input box is masked for password input. Defaults to False.

Returns:

The value of input or empty string.

Return type:

str

Note

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

msg: The message to display.
title: The title of the dialog.
input_value: The value of the input box when first displayed.
ok_lbl: The label for the OK button.
cancel_lbl: The label for the Cancel button.
is_password: Determines if the input box is masked for password input.
frame: The frame of the dialog. If not set, the frame of the current document is used.

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

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

insert_sheet(name: str)[source]

insert_sheet(name: str, idx: int)

insert_sheet(name, idx=-1)

Inserts a spreadsheet into document sheet collections.

Parameters:

name (str) – Name of sheet to insert
idx (int, optional) – zero-based index position of the sheet to insert. Can be a negative value to insert from the end of the collection. Default is -1 which inserts at the end of the collection.

Raises:

Exception – If unable to insert spreadsheet
CancelEventError – If SHEET_INSERTING event is canceled

Returns:

The newly inserted sheet

Return type:

CalcSheet

Events:

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

move_sheet(name, idx)[source]

Moves a sheet in a spreadsheet document

Parameters:

name (str) – Name of sheet to move
idx (int) – The zero based index to move sheet into.

Returns:

True on success; Otherwise, False

Return type:

bool

Events:

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

open_doc()
load_office()
2.3 Opening a Document

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

open_flat_doc()
2.3 Opening a Document

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

See also

2.3 Opening a Document

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_event_document_event_events_disposing(cb)