Class CalcForms

Introduction

The CalcForms class represents the collection of forms in a Calc document.

This class contains several python magic methods to make it behave like a collection.

Getting Number of Forms

To get the number of pages in a draw document, use the built in len() method:

>>> doc = CalcDoc(Calc.create_doc(loader))
>>> sheet = doc.sheets[0]
>>> draw_page = sheet.draw_page
>>> len(draw_page.forms)
0
>>> draw_page.forms.add_form()
>>> len(draw_page.forms)
1

Getting a form

There are several ways to get a form from a Calc sheet. The simplest is to use the [] method:

Get Form by Index.

>>> doc = CalcDoc(Calc.create_doc(loader))
>>> sheet = doc.sheets[0]
>>> if len(sheet.draw_page.forms) == 0:
...    sheet.draw_page.forms.add_form()
>>> form = sheet.draw_page.forms[0]
<ooodev.calc.CalcForm object at 0x7f8b1c0b4a90>

Get Form by Name.

>>> doc = CalcDoc(Calc.create_doc(loader))
>>> sheet = doc.sheets[0]
>>> if len(sheet.draw_page.forms) == 0:
...    sheet.draw_page.forms.add_form("MyForm")
>>> form = sheet.draw_page.forms["MyForm"]
<ooodev.calc.CalcForm object at 0x7f8b1c0b4a90>

To get the last form in a sheet, use the -1 index:

>>> doc = CalcDoc(Calc.create_doc(loader))
>>> sheet = doc.sheets[0]
>>> if len(sheet.draw_page.forms) == 0:
...    sheet.draw_page.forms.add_form()
>>> form = sheet.draw_page.forms[-1]
<ooodev.calc.CalcForm object at 0x7f8b1c0b4a90>

Deleting a form

To delete a form, use the del keyword:

Delete by form index.

>>> sheet = doc.sheets[0]
>>> del sheet.draw_page.forms[1]

Delete by form name.

>>> sheet = doc.sheets[0]
>>> del sheet.draw_page.forms["MyForm"]

Iterating over forms

To iterate over the forms in a sheet, use the for keyword:

>>> sheet = doc.sheets[0]
>>> for form in sheet.draw_page.forms:
...     print(form.name)
MyForm

Class Declaration

class ooodev.calc.CalcForms(owner, forms, lo_inst=None)[source]

Bases: LoInstPropsPartial, FormsComp, ServicePartial, TheDictionaryPartial, QiPartial, CalcDocPropPartial

Class for managing Calc Forms.

This class is Enumerable and returns CalcForm instance on iteration.

for sheet in doc.sheets:
    sheet["A1"].set_val("test")
    assert sheet["A1"].get_val() == "test"

This class also as index access and returns CalcSheet instance.

sheet = doc.sheets["Sheet1"]
# or set the value of cell A2 to TEST
doc.sheets[0]["A2"].set_val("TEST")

# get the last sheet of the document
last_sheet = doc.sheets[-1]

# get the second last sheet of the document
second_last_sheet = doc.sheets[-2]

# get the number of sheets
num_sheets = len(doc.sheets)

New in version 0.18.2.

__delitem__(_item)[source]

Removes a form from the document.

Parameters:: _item (int | str) – Index, or name, of the form.
Raises:: TypeError – If the item is not a supported type.
Return type:: None

__getitem__(index)[source]

Gets the form at the specified index or name.

This is short hand for get_by_index() or get_by_name().

Parameters:

key (key, str, int) – The index or name of the form. When getting by index can be a negative value to get from the end.
index (str | int) –

Returns:

The form with the specified index or name.

Return type:

CalcForm

See also

get_by_index()
get_by_name()

__init__(owner, forms, lo_inst=None)[source]

Constructor

Parameters:

owner (SpreadsheetDrawPage) – Owner Component
forms (XForms) – Forms instance.
lo_inst (LoInst | None) –

Return type:

None

__len__()[source]

Gets the number of forms in the document.

Returns:: Number of forms in the document.
Return type:: int

__next__()[source]

Gets the next form.

Returns:: The next form.
Return type:: CalcForm

add_container_listener(listener)

Adds the specified listener to receive events when elements are inserted or removed.

Parameters:: listener (XContainerListener) – The listener to be added.
Return type:: None

add_event_listener(listener)

Adds an event listener to the component.

Parameters:: listener (XEventListener) – The event listener to be added.
Return type:: None

add_form()[source]

add_form(idx: int)

add_form(name: str)

add_form(*args, **kwargs)

Adds a new form.

Parameters:

name (str) – Name of form.
idx (int) – Index of form.

Raises:

NameClashError – If name already exists.

Returns:

Form

Return type:

CalcForm

create_clone()

Creates a clone of the object.

Returns:: The clone.
Return type:: XCloneable

create_enumeration()

Creates an enumeration of the container’s elements.

Return type:: XEnumeration

dispose()

Disposes the component.

Return type:: None

get_by_index(idx)[source]

Gets the element at the specified index.

Parameters:: idx (int) – The Zero-based index of the element. Idx can be a negative value to index from the end of the list. For example, -1 will return the last element.
Returns:: The element at the specified index.
Return type:: CalcForm

get_by_name(name)[source]

Gets the element with the specified name.

Parameters:: name (str) – The name of the element.
Raises:: MissingNameError – If sheet is not found.
Returns:: The element with the specified name.
Return type:: CalcForm

get_count()

Gets the number of elements contained in the container.

Returns:: The number of elements.
Return type:: int

get_element_names()

Gets the names of all elements contained in the container.

Returns:: The names of all elements.
Return type:: tuple[str, …]

get_element_type()

Gets the type of the elements contained in the container.

Returns:: The type of the elements. None means that it is a multi-type container and you cannot determine the exact types with this interface.
Return type:: Any

get_parent()

Returns the parent of the object.

Return type:: XInterface

get_services()

Gets service names for the instance.

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

has_by_name(name)

Checks if the container has an element with the specified name.

Parameters:: name (str) – The name of the element.
Returns:: True if the container has an element with the specified name, otherwise False.
Return type:: bool

has_elements()

Determines whether the container has elements.

Return type:: bool

insert_by_index(index, element)

Inserts the given element at the specified index.

To append an element, use the index last index +1.

Parameters:

index (int) – The Zero-based index at which the element should be inserted.
element (T) – The element to insert.

Raises:

IllegalArgumentException – com.sun.star.lang.IllegalArgumentException
IndexOutOfBoundsException – com.sun.star.lang.IndexOutOfBoundsException
WrappedTargetException – com.sun.star.lang.WrappedTargetException

Return type:

None

insert_by_name(name, element)

Inserts the element with the specified name.

Parameters:

name (str) – The name of the element to be inserted.
element (T) – The new element.

Return type:

None

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_by_index(index)

Removes the element at the specified index.

Parameters:

index (int) – The Zero-based index of the element to remove.

Raises:

IndexOutOfBoundsException – com.sun.star.lang.IndexOutOfBoundsException
WrappedTargetException – com.sun.star.lang.WrappedTargetException

Return type:

None

remove_by_name(name)

Removes the element with the specified name.

Parameters:: name (str) – The name of the element to be removed.
Return type:: None

remove_container_listener(listener)

Removes the specified listener so it does not receive any events from this container.

Parameters:: listener (XContainerListener) – The listener to be removed.
Return type:: None

remove_event_listener(listener)

Removes an event listener from the component.

Parameters:: listener (XEventListener) – The event listener to be removed.
Return type:: None

replace_by_index(index, element)

Replaces the element at the specified index with the given element.

Parameters:

index (int) – The index of the element that is to be replaced.
element (Any) – The replacement element.

Return type:

None

replace_by_name(name, element)

Replaces the element with the specified name.

Parameters:

name (str) – The name of the element to be replaced.
element (T) – The new element.

Return type:

None

set_parent(parent)

Sets the parent of the object.

Return type:: None
Parameters:: parent (com.sun.star.uno.XInterface) –

support_service(*service)

Gets if instance supports a service.

Parameters:: *service (str) – Variable length argument list of UNO namespace strings such as com.sun.star.configuration.GroupAccess
Returns:: True if instance supports any passed in service; Otherwise, False
Return type:: bool

property calc_doc: CalcDoc

Calc Document.

Return type:: CalcDoc

property component: com.sun.star.form.Forms

Forms Component

Return type:: Forms

property extra_data: TheDict

Extra Data Key Value Pair Dictionary.

Properties can be assigned properties and access like a dictionary and with dot notation.

Note

This is a dictionary object that can be used to store key value pairs. Generally speaking this data is not part of the object’s main data structure and is not saved with the object (document).

This property is used to store data that is not part of the object’s main data structure and can be used however the developer sees fit.

Return type:: TheDict

property lo_inst: LoInst

Lo Instance

Return type:: LoInst

property office_doc: OfficeDocumentT

Office Document.

Return type:: OfficeDocumentT

property owner: SpreadsheetDrawPage

Returns: SpreadsheetDrawPage: Calc doc

Return type:: SpreadsheetDrawPage