Class WriteForms

Introduction

The WriteForms class represents the collection of forms in a Writer 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 = WriteDoc(Write.create_doc())
>>> len(doc.draw_page.forms)
0
>>>doc.draw_page.forms.add_form()
>>> len(doc.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 = WriteDoc(Write.create_doc())
>>> if len(doc.draw_page.forms) == 0:
...   doc.draw_page.forms.add_form()
>>> form = doc.draw_page.forms[0]
<ooodev.write.WriteForm object at 0x7f8b1c0b4a90>

Get Form by Name.

>>> doc = WriteDoc(Write.create_doc())
>>> if len(doc.draw_page.forms) == 0:
...    doc.draw_page.forms.add_form("MyForm")
>>> form = doc.draw_page.forms["MyForm"]
<ooodev.write.WriteForm object at 0x7f8b1c0b4a90>

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

>>> doc = WriteDoc(Write.create_doc())
>>> if len(doc.draw_page.forms) == 0:
...    doc.draw_page.forms.add_form()
>>> form = doc.draw_page.forms[-1]
<ooodev.write.WriteForm object at 0x7f8b1c0b4a90>

Deleting a form

To delete a form, use the del keyword:

Delete by form index.

>>> del doc.draw_page.forms[1]

Delete by form name.

>>> del doc.draw_page.forms["MyForm"]

Iterating over forms

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

>>> for form in doc.draw_page.forms:
...     print(form.name)
MyForm

Other Examples

An example can be found on Live LibreOffice Python UNO Examples. Example: Build Forms.

Class Declaration

class ooodev.write.WriteForms(owner, forms, lo_inst=None)[source]

Bases: LoInstPropsPartial, FormsComp, WriteDocPropPartial, QiPartial

Class for managing Writer Forms.

This class is Enumerable and returns WriteForm instance on iteration.

__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__(key)[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.
Returns:: The form with the specified index or name.
Return type:: WriteForm

See also

get_by_index()
get_by_name()

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

Constructor

Parameters:

owner (WriteDrawPage) – Owner Component
forms (XForms) – Forms instance.
lo_inst (LoInst, optional) – Lo instance. Used when creating multiple documents. Defaults to 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:: WriteForm

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:

WriteForm

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

get_by_name(name)[source]

Gets the element with the specified name.

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

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

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) –

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

Forms Component

Return type:: Forms

property lo_inst: LoInst

Lo Instance

Return type:: LoInst

property office_doc: OfficeDocumentT

Office Document.

Return type:: OfficeDocumentT

property owner: WriteDrawPage

Returns: WriteDrawPage: Writer Draw Page

Return type:: WriteDrawPage

property write_doc: WriteDoc

Write Document.

Return type:: WriteDoc