A list is a structured object that contains an optional list header followed by any number of list items. The list header, if defined, contains one or more paragraphs that are displayed before the list. A list item can contain paragraphs, headings, or lists. Its properties are style, that is an appropriate list style, and continue numbering, a boolean value that, if true, means that if the numbering style of the preceding list is the same as the current list, the number of the first list item in the current list is the number of the last item in the preceding list incremented by one (default=false).
A list is created using odf_create_list(), then inserted using insert_element() as usual.
A list header is created “in place” with set_header(), called from a list element; this method returns an ODF element that can be used later as a context to append paragraphs in the header. Alternatively, it’s possible to call the list-based set_header() with one or more existing paragraphs as arguments, so these paragraphs are immediately incorporated in the new list header. Note that every use of set_header() replaces any existing header by a new one.
Regular list items are created in place (like the optional list header) using add_item() wich creates one or more new items and inserts them at a position which depends on optional parameters, according to the same kind of logic than the table-based add_row() method. Without any argument, a single item is appended at end of the list. An optional before named parameter may be provided; if defined, the value of this parameter must be an item number (in numeric, zero-based form) in the range of the list; the new items are inserted before the original item that existed at the given position. Alternatively, a after parameter may be provided instead of before; it produces a similar result, but the new items are inserted after the given position. If a additional number parameter is provided with a integer value, the corresponding number of identical items are inserted in place.
By default, a new item is created empty. However, as a shortcut for the most common case, it’s possible to directly create it with a text content. To do so, the text content must be provided through a text parameter; an optional style parameter, whose value is a regular paragraph style, may provided too. The new item is then created with a single paragraph as content (that is the most typical situation).
Another optional start value parameter may be set in order to restart the numbering of the current list at the given value. Of course, this start value apply to the first inserted item if add_item() is used to create many items in a single call.
add_item() returns the newly created list of item elements. In addition, an existing item may be selected in the list context using get_item() with its numeric position. A list item is an ODF element, so any content element may be attached to it using insert_element().
Note that, unlike headings, list items don’t have an explicit level property. All the items in an ODF list have the same level. Knowing that a list may be inside an item belonging to another list, the hierarchy is represented by the structural list imbrication, not by item attributes.
A list may be retrieved using the context-based get_list() method, whose optional parameters are the same as get_element(). A get_list_by_id() method selects a list according to its (optional) identifier. In addition, get_list_list() selects the item lists contained in the context according to the same rules as get_element_list().
A section is a named region in a text document. It’s a high level container that can include one or more content elements of any kind (including sections, that may be nested).
The purpose of a section is either to assign certain formatting properties to a document region, or to include an external content.
A section is created using odf_create_section() with a mandatory name as the first argument and the following optional parameters:
A new section may be inserted or appended somewhere using insert_element() or append_element(). (Of course, an existing section may be copied and pasted thanks to the common clone() method.)
A section may be retrieved using get_section() with the unique name of the needed section as argument, while get_section_list() returns all the sections (if any) of the context.
Draw pages are structured containers belonging to presentation or drawing documents. They shouldn’t appear in text or spreadsheet documents.
A draw page can contain forms, drawing shapes, frames, presentation animations, and/or presentation notes (§9.1.4 in the ODF specification). The present version of lpOD (level 1) supports frames and drawing shapes, as introduced in the “Graphic Content” chapter.
A draw page is created using odf_create_draw_page() and integrated through insert_element() or append_element(). Note that a draw page should be inserted at the document body level, knowing that it’s a top level content element.
A draw page must have an identifier (unique for the document) and may have the following parameters, to be set at creation time or later:
for the end-users); this parameter is strongly recommended knowing that some ODF applications don’t preserve the draw page identifier, so the name remains the only stable identifier;
style: the name of a drawing page style (existing or to be defined);
draw pages (beware, a master page defined for a text document don’t always fit for draw pages);
in §14.15 of the ODF specification (if such a layout is used); beware, such objects are neither similar nor related to general page layouts as defined in §14.3 (a general page layout may be used through a master page only, and should never be directly connected to a draw page) (sorry, this confusing vocabulary is not a choice of the lpOD team;-)
The following example creates a draw page with these usual parameters and integrates it as the last page of a presentation document:
dp = odf_create_draw_page('xyz1234',
name='Introduction',
style='DrawPageOneStyle',
master='DrawPageOneMaster',
layout='DrawPageOneLayout
)
document.append_element(dp)
All these parameters may retrieved or changed later using get_attributes() and set_attributes() with draw page objects.
An existing draw page may be retrieved in a given context (that should be the document body or root) through get_draw_page() with the identifier as argument. This methods attempts to retrieve a draw page whose identifier matches the argument, then, in case of failure, it looks for a draw page whose name matches. Alternatively, the user can explicitly select a draw page by name using get_draw_page_by_name() or according to its zero-based position in the document using get_draw_page_by_position(). The whole list of draw pages may be returned by get_draw_page_list().
Populating a draw page doesn’t require element-specific methods, knowing that:
associated style, master and layout;
using the regular insert_element() or append_element() method from the draw page object.