Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

OpenOffice::OODoc::Text
The text processing submodule of OpenOffice::OODoc

OpenOffice::OODoc::Text - The text processing submodule of OpenOffice::OODoc


NAME

OpenOffice::OODoc::Text - The text processing submodule of OpenOffice::OODoc


DESCRIPTION

This manual chapter describes the text-oriented methods of OpenOffice::OODoc, implemented by the OpenOffice::OODoc::Text class, and inherited by the OpenOffice::OODoc::Document class.

These methods are not essentially dedicated to string processing; they are more precisely focused on text containers. A text container is a document element which can (and must) be used in order to support a text and integrate it at the right place and according to the right presentation rules. The OpenDocument specification defines a lot of such containers, and the present API supports many of them, such as paragraphs, headings, tables (or spreadsheets), lists, sections, and draw pages. Some of these containers can host other containers: for example, a table contains rows, a row contains cells, a section can contain almost everything including other sections, etc.

These features are text-oriented, but can be used on documents of any class, such as spreadsheets or presentations as well as text documents. So, the 'Text' word doesn't mean that the features described in the present manual chapter are dedicated to OpenDocument Text (ODT) documents only. In the other hand, a few methods can't apply to any document class (ex: creating or retrieving draw pages makes sense with presentation and drawing documents only).

OODoc::Text should not be explicitly used in an ordinary application, because all its features are available through the OpenOffice::OODoc::Document class, in combination with other features. Practically, the present manual is provided to describe the text-oriented features of OpenOffice::OODoc::Document (knowing that these features are technically supported by the OpenOffice::OODoc::Text component of the API).

The OpenOffice::OODoc::Text class is a specialist derivative of OpenOffice::OODoc::XPath for XML elements which describe the text content of OOo/ODF documents. Here, ``text content'' means containers that can host text containers (i.e. tables, lists...) as well as flat text.

Knowing that the ``styles.xml'' member of an OpenDocument file can contain text (because some style definitions, such as page headers or footers, can contain text), the presently described features can be used against this member as well as the ``content.xml'' member.

This module should be used in combination with OpenOffice::OODoc::Styles, via the OpenOffice::OODoc::Document class, if the application has to handle detailed presentation parameters of text elements. This is because such parameters are held in styles elements and not in the text elements themselves, according to the principle of separation of content and presentation which is one of the foundations of the OpenDocument format.

Methods

Constructor : OpenOffice::OODoc::Text->new(<parameters>)


        Short Form: ooText(<parameters>)

        See OpenOffice::OODoc::XPath->new

        Returns an OODoc::XPath OpenDocument connector with additional

        features mainly focused on text containers.

        This constructor is generally not explicitly called, knowing that

        it's automatically triggered each time a Document object is created.

        The XML member loaded by default is 'content.xml'. The most common

        creation method is like this:

            my $doc = ooText(file => 'my_file.odt');

        This constructor should generally not be called directly, because it's

        inherited by ooDocument().

        Other parameters can be supplied as options (see the properties list

        at the end of the chapter).

        Example:

            my %delim =

                (

                'text:h'                =>

                        {

                        begin   => '\sect{',

                        end     => '}'

                        },

                'text:list-item'        =>

                        {

                        begin   => '\item'

                        }

                'text:footnote-body' =>

                        {

                        begin   => '\footnote{',

                        end     => '}'

                        }

                );

            my $doc = ooText

                        (

                        file            => 'filename.odt',

                        paragraph_style => 'My Paragraphs',

                        heading_style   => 'My Headings',

                        delimiters      => { %delim }

                        );

        This technique gives the default styles to be used when creating new

        text elements. It also gives the particular delimiters (in this case

        LaTeX style markers) to be used at the beginning or end of some

        elements (in this case headings, list elements, footers) where the

        text is to be exported "as is". See the getText method of

        OODoc::Text for information about exporting text.

appendBodyElement(element [, options])


        Copies an existing element of any type and appends it to the end of

        the document body. No new element is created.

appendDrawPage([options])


        In a presentation or drawing document, appends a new page at the en

        of the document.

        Possible options are:

                name            => page name (unique)

                id              => page numeric ID (unique)

                style           => page style name

                master          => master page name

        Returns the new draw page element if successful, undef if not.

appendHeading([options])


        Creates a new heading of any level and appends it to the end of the

        document.

        Options are given as a hash [key => value]:

            'text'              => <heading text>

            'level'             => heading level, default is 1

            'style'             => heading style, default is 'Heading 1'

        Examples:

            $doc->appendHeading(text => 'Next section');

        adds the text 'Next section' as a level 1 heading.

            $doc->appendHeading

                (

                text    => 'Chapter Conclusion',

                level   => '2',

                style   => 'Heading_20_2'

                );

        adds a level 2 heading to the end of the text body. 'Heading_20_n'

        styles, where 'n' is the level number, are presently available by

        default in OpenOffice.org.

        You can give any XML attribute to the new heading except for style or

        heading level. In this case, the program must construct a hash

        containing pairs of key-values for the attributes you want to create

        and pass it using the 'attribute' option. Example:

            my %attr    = ( 'att1' => 'value1', 'att2' => 'value2' );

            $doc->appendHeading

                (

                text    => 'Attributes are important',

                level   => '1',

                style   => 'Chapter heading',

                attribute => %attr

                );

        If the 'text' option is empty, the heading is created with an empty

        content.

        Caution, creating headings with level attributes is not always

        sufficient to produce the needed result. For example, in order to

        generate headings with appropriate levels of numbering, each one

        must be attached to the right position in a hierarchy of lists,

        in combination with appendItemList(), insertItemList(), and

        appendListItem().

        Note: this method can only be used with a new header i.e. it adds

        while it creates. To add an already available element using

        getHeading() from the same document or from another document, use

        the appendElement() method instead which is inherited from

        OODoc::XPath.

appendItem(list [, text => text ,style => style ,[other_options]])


        See appendListItem().

appendItemList([type => list_type, [style => style [, options]]])


        Creates a new (empty) list and appends it to the end of the

        document.

        In OpenOffice.org 1 documents, an unordered list is the default,

        and if the 'type' option is given with the value 'ordered', then an

        ordered list is created. In Open Documents, the 'type' option is

        ignored because there are generic lists only (a list is ordered or

        "bulleted" according to a style, and not natively).

        The 'style' options controls the list's style (as opposed to each

        item's style). If absent, the list takes the default paragraph style

        (see appendParagraph).

        Like appendParagraph, this method actually creates a new list

        element. To copy an existing list in the same document or in

        another, use appendElement or replicateElement instead.

appendListItem(list [, text => text ,style => style ,[other_options]])


        Adds a new item to a list (ordered or unordered).

        The first argument is the existing list element (created using

        getOrderedList or getUnorderedList, for example). Options are the

        same as for appendParagraph.

        If the 'style' option is absent, the element is inserted according

        to the following rule:

        - if the new item is not the first one of the list, it takes the

        same style as the first item;

        - otherwise, it takes the default paragraph style of the document.

        The new item is created as a paragraph container by default. A

        'type' option may be provided in order to require another type.

        Possible values are 'header', 'paragraph' or the XML name of any

        OpenDocument-compliant text container.

        If the type is provided and set to undef, the new item is created

        as an empty element, so it could/should receive a content later.

        An empty item could be used as the attachment point of another

        list, in order to create a hierarchy of lists.

appendParagraph(<options>)


        Creates a new paragraph and appends it to the document.

        Options:

            'text'              => <paragraph text>

            'style'             => <paragraph style>

        An 'attribute' option is also available under the same conditions as

        for the appendHeading method (see above).

        If the 'text' option is empty, calling this method is the equivalent

        of adding a line feed.

        If the 'style' option is empty, the style from the 'paragraph_style'

        property of the OODoc::Text instance is used.

        By default, the new paragraph takes place at the end of the document.

        But it's possible to attach it as the last child of an existing

        text container (ex: a table cell). To do so, the container must be

        provided through an 'attachment' option. For example, to append a new

        paragraph in a table cell, one can write

                my $cell = $doc->getCell("Table1", "B12");

                $doc->appendParagraph

                        (

                        text            => "The cell, reloaded",

                        attachment      => $cell

                        );

        Note: this method can only be used with a new paragraph i.e. it adds

        while it creates. To add an already existing paragraph using

        getParagraph from the same document or from another document, use

        the appendElement, insertElement or replicateElement methods instead

        which are inherited from OODoc::XPath.

        Note: The repeated spaces are not properly processed, so any sequence

        of spaces (whatever its length) in the 'text' string is replaced by a

        single space in the target document. See setText() and extendText().

appendRow(table [, options])


        Appends a row to the end of the given table either by reference, by

        logical name or by sequential number. By default, the new row is

        simply an exact copy of the preceding row (in terms of content and

        presentation). You can pass an options hash which will give certain

        attributes to the created row, under the same conditions as for the

        appendElement method of OODoc::XPath. The returned value is the

        created row element.

        Example:

            open SRC, '<', 'data.txt';

            my $table = $doc->getTable("Table1");

            my ($h, $l) = $doc->getTableSize($table);

            for (my $i = 0 ; my $record = <SRC> ; $i++)

                {

                last unless $record;

                chomp $record;

                my @data = split ';', $record;

                my $row = $i < $h ?

                        $doc->getRow($table, $i) :

                        $doc->appendRow($table);

                for (my $j = 0 ; $j < $l ; $j++)

                        {

                        $doc->cellValue($row, $j, $data[$j]);

                        }

                }

        The above program reads a CSV format data file sequentially (one

        record per line, comma-separated fields). Each record is split and

        put into a row in table Table1. On reading each new record, the

        reference for the following row is loaded by getRow, until the total

        number of rows is reached (total obtained previously using

        getTableSize). If the table is already full, it is lengthened by a

        row using appendRow. The internal loop loads the read data into the

        row's cells (pre-existing or newly created). See the sections on

        getTable, getRow, getTableSize and cellValue for a better

        understanding of this example.

        However, if good performance is what you are after, massive

        repetition of this method is not recommended (e.g. for lengthening a

        table dynamically, row by row, whilst loading external data into

        it). Rather than running dozens or hundreds of successive

        appendRows, it would be better for the application to read the total

        number of records to be loaded (using, for example, select count if

        from a relational database or otherwise preloading the data into an

        ordinary Perl table) and create a table of appropriate size in

        advance using insertTable or appendTable.

appendSection(name [, options])


        Creates a new section with the given name, and appends it by default

        to the end of the document body. If the "attachment" option is

        provided, with an existing element as its value, the new section is

        appended in the context of this element. For example, if the value

        of "attachment" is an existing section, the new section is appended

        as the last sub-section of the existing one.

        A section may be used either to hold a local content or to insert

        a subdocument which can be reached through an external link.

        In order to insert a subdocument link instead of an ordinary section,

        the application must provide a "link" option whose value is either a

        local file path or an URL.

        Example:

            $doc->appendSection

                (

                "Article",

                link => "http://mycompany.com/doc/article.odt";

                );

        Other possible options:

            'style'     allows the application to explicitly select a style

                        for the new section

            'protected' write-protects the section when the document is

                        edited; "true" or "false", default "false"

            'key'       in combination with "protected" => "true", write-

                        protects the section by password (the value of

                        "key" is not the real password, but an encrypted

                        password, so the end-user will never remove the

                        protection by simply typing the key as it is

                        written in the program); see lockSection(),

                        unlockSection() and sectionProtectionKey()

appendTable(name, rows, columns [, options])


        Creates a new table with the given name, number of rows and number

        of columns, and appends it by default to the end of the document

        body. The name must be unique within the document (the call is

        rejected if the name already exists). Returns the created table

        element if successful.

        'rows' and/or 'columns', if omitted, are replaced by the 'max_rows'

        and 'max_cols' properties of the document (see the properties below).

        By default, the table is set to fit the entire width between the

        left and right margins with equal sized columns, cells of type

        string and without borders or background colour.

        Possible options:

            'table-style'       => table style

            'cell-type'         => default cell type

            'cell-style'        => default cell style

            'text-style'        => default cell text style

        The first option is the name of a table style which defines

        certain global properties for the table (width, background colour,

        etc.). See the OpenOffice::OODoc::Styles manual for information about

        styles.

        The second option is the cells' default data type. The main types

        available are string, float, currency, date, percentage. Caution: to

        be properly treated as having a numeric format in OOo/ODF, a

        cell needs more than to be just marked 'numeric'. If the cell really

        needs to be treated properly as a number, you must also give it a

        cell style which itself refers to a number style. The cell-style

        parameter can do this. However, even though the OODoc::Styles module

        is there to otherwise help you create and add styles from a program,

        this type of exercise can become very labour-intensive. We therefore

        recommend using basic tables created in advance from document

        templates or style libraries created from an office application,

        rather than creating complex number tables from code.

        The text-style option selects the paragraph style applicable to the

        text displayed in each cell.

        Once the table is created, you can obviously modify each cell's type

        and style individually.

        Example:

            my $table = $doc->appendTable

                                (

                                "Rate", 22, 5,

                                'table-style' => 'Table1',

                                'text-style' => 'Text body'

                                );

appendTableRow(table)


        See appendRow.

bibliographyEntryContent(id [, key1 => value1, key2 => value2, ...])


        Gets, and optionally sets, the properties of a given (existing)

        bibliographic entry. The optionally updated properties are provides

        as a hash. The returned description is a hash.

        The first argument can be either the logical identifier of the entry

        (as it appears for the end-user) or a previously found bibliography

        entry element (see getBibliographyElements()).

        Example:

                my %desc = $doc->bibliographyEntryContent

                                        (

                                        "GEN99",

                                        author  => 'Genicorp',

                                        pages   => 62

                                        );

        This sequence updates the "Author" and "Pages" values of the "GEN99"

        entry, then returns all the content of the entry in %desc.

        Caution: Several bibliography entries can have the same identifier.

        This method processes one element at a time. In the example above,

        only the first occurrence of the "GEN99" entries is updated. So, if

        the user needs to ensure that all the entries with the same identifier

        have the same content, the appropriate code should be something like:

                my @entries = $doc->getBibliographyElements("^GEN99$");

                foreach my $entry (@entries)

                        {

                        $doc->bibliographyEntryContent

                                (

                                $entry,

                                author  => 'Genicorp',

                                pages   => 62

                                )

                        }

        Caution: This method allows the user to create any new property and

        to put any value in any property, without control. For information

        about the legal and/or recommended properties, see the OpenDocument

        specification and the OpenOffice.org bibliographic project

        (http://bibliographic.openoffice.org).

bookmarkElement(element, name [, offset])


        See setBookmark().

cellCurrency(table, row, column [, currency])

cellCurrency(cell [, currency])


        Get/set the currency unit of a cell.

        If a currency is provided, the cell value type is automatically

        switched to 'currency'.

cellFormula(table, row, column [, formula])

cellFormula(cell [, formula])


        Accessor which returns the formula (or function) contained in the

        given table cell. Returns undef if no formula is found in the cell.

        The cell address is the same as for getCellValue().

        If a formula is given as the last argument, it is put into the cell,

        overwriting any existing formula. No check of the syntax is carried

        out on the inserted formula. It is up to the application to insert a

        formula which conforms to OOo/ODF syntax. Example:

            $doc->cellFormula(1,3,2, "sum <C2:C5>");

        Note 1: inserting or replacing a formula does not directly modify

        the value or text of the cell. Proper interpretation of a formula

        does not happen until the fields are updated when the document is

        reloaded into the office software.

        Note 2: syntax and functionality of cell formulae differ greatly

        between office applications.

cellSpan(table, row, column [, hspan [, vspan]])

cellSpan(cell [, hspan [, vspan]])


        In a spreadsheet document, get/set the span of a table cell,

        knowing that this span can be one or more columns. The cell addressing

        is the same as with getCell().

        Example:

                $doc->cellSpan($table, "B4", 3);

        creates a 3-cell span from B4 in a spreadsheet.

        With only one span argument, this method works for horizontal, left to

        right expansion. With an additional argument, the expansion is bi-

        directional, covering one or more rows below the given cell. The

        horizontal span should be set to 1 in order to get a vertical span

        only.

        The text of the covered cells (if any) is concatenated to the original

        content of the expanded cell (as in OOo Writer or Calc).

        The user should make sure that the cell expansion will not invade the

        span of another, previously expanded cell. Assuming A is a the target

        of cellSpan(), B is an existing expanded cell, and C is a covered cell

        in the span of B, the following rules apply:

        If B is to be covered by the span of A, the span of B is automatically

        reset to 1, so C becomes visible, then B is covered by A. But if C is

        in the target range of cellSpan() while B is not, the method produces

        an inconsistency in the table (this inconsistency doesn't prevent

        OpenOffice.org and KSpread from loading the file but the span of A is

        just ignored).

        In list context, the method returns the horizontal span, then the

        vertical span. In scalar context, it returns the horizontal span only.

        Caution: when related to table cells, "span" has not the same

        meaning as when related to flat text (see getSpan() and setSpan()).

cellStyle(table, row, column [, stylename])

cellStyle(cell [, stylename])


        Get or set the style of a table cell.

cellValue(table, row, column [, value [, text]])

cellValue(cell [, value [, text]])


        Without the "value" argument: see getCellValue().

        With "value" (and, optionally, "text"): see updateCell().

cellValueType(table, row, column [, type])

cellValueType(cell [, type])


        Get/set the data type of a table cell.

        Possible value types are 'string', 'float', 'percentage', 'currency',

        'date', 'time', 'boolean'.

        Note: If an application must convert a 'string' cell to a numeric

        one and fill it with a numeric value, cellValueType() must be called

        *before* cellValue(). Ex:

                my $cell = $doc->getCell('Sheet1', 4, 8);

                $doc->cellValueType($cell, 'float');

                $doc->cellValue($cell, 12.34);

columnStyle(column_element [, style])

columnStyle(table, column [, style])


        Returns the style name of the given column or replaces it with a new

        one. A column can be indicated either directly by reference or by

        the pair [table, column number]. The table itself can be indicated

        either by a table element, its number or its logical name. If the

        'style' argument is given, it replaces the old column style.

        Giving a column a style is actually the only way to control the

        width of a column in a table.

        Example:

            $doc->columnStyle('Table1', 2, 'NewStyle');

        Caution: columns are numbered beginning at 0.

copyRowToHeader(table, rownum)

copyRowToHeader(row)


        This method appends a copy of a given table row to the header of the

        table. It may be called repeatedly, allowing multi-row header

        creation.

        A table header is a row, or a sequence of rows, that is displayed at

        the top of a table and repeated at the top of every page if the table

        is spanned across more than one page.

        The given row remains in place unchanged; it's used as a template for

        the new header row.

        

=head3  createParagraph([text [, style]])

        Creates a free paragraph for later use. Unlike appendParagraph() or

        insertParagraph(), this method doesn't attach the new paragraph to

        the document.

        

        Without arguments, the paragraph is created empty. The first argument,

        if any, provides the text content of the paragraph. The second one,

        if any, is regarded as the style name; the default style is

        "Standard".

createTextBox(options)


        Creates a new text box. Can apply to any document class, but mostly

        used in presentations or drawings (where text boxes are required to

        host text content).

        

        Text boxes are implemented through frame element, so you should see

        createFrame() in the OpenOffice::OODoc::XPath manual chapter in order

        to understand the meaning of every option.

        

        The following options are allowed (and generally required in order

        to make a text box really visible and properly rendered):

        

        page: the page where the box must be attached; in presentations or

        drawings, this option should be set with the page name;

        

        name: the (unique) name of the text box;

        

        size: the size of the box;

        

        position: the page-relative position;

        

        style: the graphic style of the box; like an image box, a text box

        often requires a style to be properly displayed;

        

        content: the content to be displayed in the box; if this option is

        set to a literal, the given content is inserted as a paragraph in

        the box; if the given value is the reference of an element, this

        element is attached as is in the box (so it's possible to insert

        any complex object, such as a table, an item list, etc).

        

        The method returns the reference of the new text box element.

        

        The example below creates an graphic style ("TB"), then a text box

        ("The Box") which uses the new style. See O::O::Styles for comments

        about createStyle(). The text box is attached in a presentation page

        identified by its name ("AnyPageName"). The size (width then height)

        and position (x, y) options are provided in centimeters (other units

        are allowed), each one in a single string.

                $doc->createStyle

                        (

                        "TB",

                        family          => "graphic",

                        parent          => "objectwithshadow",

                        properties      =>

                                {

                                'style:vertical-pos'    => 'from-top',

                                'style:horizontal-pos'  => 'from-left',

                                'style:vertical-rel'    => 'page',

                                'style:horizontal-rel'  => 'page'

                                }

                        );

                $doc->createTextBox

                        (

                        page            => "AnyPageName",

                        name            => "The Box",

                        size            => '12cm, 4cm',

                        position        => '8cm, 14cm',

                        style           => 'TB',

                        content         => "The text in the box"

                        );

                        

        In this example, the content option is set to a flat text, so

        it will be inserted as a standard paragraph. If we want to insert

        a paragraph with a non-default style, this option must be set to

        the reference of an existing paragraph (which may have been created

        using createParagraph() or copied from another place).

defaultOutputTerminator([chars])


        Get or set the default terminator character for text export.

        Example:

                $doc->defaultOutputTerminator("\n");

        After this instruction, a line-break will be appended at the end of

        every paragraph or header exported by getText(), selectTextContent()

        or other text extracting methods.

        To reverse this behaviour, the user can call this method with an

        empty string.

        Without argument, returns the currently selected terminator, if any.

deleteBookmark(name)


        Deletes the given bookmark (if defined).

        Works with position bookmarks only.

deleteColumn(table, col_num)

deleteColumn(col_elt)


        Deletes a given column in a given table.

        Caution: Before using this method, the application should ensure that

        the whole area from the beginning of the table to the last cell of the

        column to be deleted is "normalized". See normalizeSheet() for details

        about table normalization.

deleteHeading()


        See removeHeading().

deleteRow(table, row_num)

deleteRow(row_elt)


        Deletes a given row in a table.

drawPageId(page [, new_id])


        Returns the internal identifier of a presentation page, and changes

        it if a second argument is provided. The page id is a positive

        integer.

        The first argument must comply to the same rules as with getDrawPage.

drawPageName(page [, newname])


        Returns the visible name of a presentation or drawing page.

        The first argument can be a page order number, a page element or the

        present page name (see getDrawPage). The page is renamed if a

        second argument is provided. Example:

                $doc->drawPageName("oldname", "newname");

deleteTableColumn(table, col_num)


        See deleteColumn().

deleteTableRow(table, row_num)


        See deleteRow().

extendText(element, text [, style [, offset]])


        Inserts the text provided as the second argument into the element

        specified by the first argument. The second argument may be either a

        flat string or another existing text element.

        

        If the 'text' argument is a paragraph or heading element, the text

        content (and not the element itself) is inserted. But if 'text' is

        any other element (for example: a variable text field or a sequence

        of spaces), its inserted as is.

        This method is an improvement of the general extendText() method

        which is documented in the OpenOffice::OODoc::XPath manual page.

        If a third argument is provided and is neither 0 nor an empty string,

        it's regarded as the desired style of the new text, which is inserted

        as a "styled span" (see setSpan() for details about text "spans").

        By default, the text is inserted without any special style (i.e. with

        the same style as the containing element).

        The new text is, by default, appended to the existing content of the

        element. However, if a valid numeric value is provided as the fourth

        argument, the new text is inserted within the existing content, at the

        given offset. If the offset is negative, it's counted backwards from

        the end of the string. If it's set to 0, the insertion takes place at

        the beginning.

                $doc->createStyle

                        (

                        "BlueYellow",

                        family          => "text",

                        properties      =>

                            {

                            "fo:color"                  => odfColor("blue"),

                            "fo:background-color"       => odfColor("yellow")

                            }

                        );

                my $p = $doc->getParagraph(4);

                $doc->extendText($p, "New text", "BlueYellow", 5);

        In the example above, "New text" is inserted at the offset 5 within

        the 5th paragraph, in blue letters on a yellow background.

        Of course, the offset argument can't be passed unless the style one is

        present. However, in order to pass an offset without setting a style,

        the application has just to provide a 0 or an empty string as the

        third argument. Example:

                $doc->extendText($p, "New text", "", 5);

        Every string inserted through this method looks like it had always

        been a part of the original string when edited using OOo. However,

        each one remains stored in a separate space, like a "styled text

        span" (see setSpan()). So, given the following example:

                $doc->setText($para, "Old");

                $doc->extendText($para, "New");

        After this sequence, the displayable content of $para is "OldNew",

        but "OldNew" is not retrievable by selectElementsByContent(),

        setSpan(), or other text-searching methods, because "Old" and "New"

        are physically stored in separate containers (each one can have a

        distinct style). In addition, a subsequent call of extendText()

        with an offset on the same target will not properly work if the

        offset value is greater than the initial length (3 in the example).

        However, all the internal text span borders may be removed by an

        explicit call of flatten(). So, a third instruction could be

        appended to the example:

                $doc->flatten($para);

        After this last instruction, the whole content of $para is stored

        as a single string, and there is no internal separation between the

        original content and the extension(s). In the other hand, flatten()

        removes any previous formatting markup as well. For details about

        flatten(), see OpenOffice::OODoc::XPath.

getBibliographyElements([id])


        Returns the list of the bibliographic entry elements contained in the

        document.

        If an argument is provided, the returned list is restricted to the

        bibliographic entries matching it (this argument can be a regexp).

        Example:

                my @biblio = $doc->getBibliographyElements("^W3C");

        returns the bibliographic entries where the identifier begins with

        "W3C".

getBookmark(name)


        Returns the bookmark element (if defined) corresponding to the given

        bookmark name.

        If the bookmark covers a range of text (i.e. if it's not a position),

        the returned element is the "bookmark start" one.

getCell(table, row, column)

getCell(table, coord)

getCell(row, column)


        Returns the element which represents the given cell. Possible

        arguments are respectively: the table number or its reference in the

        document, row number and column number. Each table cell contained in

        the body of an OOo/ODF document can be referenced in this

        manner, as if it belonged to a single 3D table irrespective of the

        rest of the document.

        If the cell is defined in the spreadsheet but covered (because of a

        cell merge), the return value is undef. In other words, this method

        doesn't provide access to a covered cell.

        The first argument can be either the sequential number of the table

        (starting at 0), the logical name of the table, or a 'table' object

        (which can be retrieved in advance using getTable). If it's a number

        or a name, getTable() is automatically called by getCell() in order

        to convert it in a 'table' object. However, if the first argument is

        a row object (previously obtained via getRow() or getHeaderRow()),

        the second one is processed as the column number. Before using several

        cells in the same row, it's a good idea to get the row object and then

        to use it in every cell selection, in order to minimize the

        coordinates calculation.

        In tables including one or more header rows, the best way to get a

        header cell is to use a header row (previously obtained using

        getHeaderRow()) as the first argument. If the first argument is a

        table, getCell() looks in the table body only.

        Alternatively, the user can provide the cell coordinates in a single

        alphanumeric argument, beginning with one or two letters and ending

        with one or more decimal digits, according to the same logic as in a

        spreadsheet. So, for example

                $doc->getCell($table, 'B12');

        is equivalent to

                $doc->getCell($table, 11, 1);

        (Remember that, with the numeric coordinates, the row number is the

        first argument, while with the alphanumeric, spreadsheet-like ones,

        the column letter(s) come first.)

        Numbers can also be negative, where position -1 is the last. For

        example:

            $cell = $doc->getCell(-1, -1, -1);

        returns the very bottom right cell of the very last table in the

        document $doc.

        Returns a null value if the given cell does not exist or if it's

        covered by the span of another cell.

        Any cellXXX() method in this module uses the same cell addressing

        logic as getCell().

        CAUTION: Remember that OODoc works with the XML representation of

        the tables, and not with the tables themselves. The [x,y] direct

        addressing feature works as long as there is a continuous, one-to-one

        mapping between the logical view and the physical XML storage of the

        table. But, according to the OpenDocument specification, several

        contiguous objects (cells or rows) are allowed to be mapped to a

        single XML object when they have the same content and the same

        style, in order to save some storage space. This optimization is

        systematically used, for example, by OpenOffice.org Calc.

        Addressing cells in spreadsheets is considerably more complex

        than in text document tables. However, the same addressing scheme

        in allowed in the "Calc" documents than in the "Writer" ones,

        provided the targeted cells belong to a preprocessed workspace

        (beginning at the upper-left cell, and ending at a parametrizable

        position). It's possible to use normalizeSheet() or getTable() in

        order to make this workspace available.

        See normalizeSheet() for more explanations.

        Remember that the table addressing is zero-based and

        the row comes before the column in OpenOffice::OODoc, so, for

        example:

                $cell1 = $doc->getCell($table, 0, 0);

                $cell2 = $doc->getCell($table, 31, 25);

        returns respectively the A1 and Z32 cells.

        Note: in a spreadsheet, (0,0) are the coordinates of the "A1" cell,

        and, for example, (16, 25) are the coordinates of the "Z17" cell.

getCellParagraph(table, row, column)

getCellParagraph(cell)


        Returns the paragraph element contained in a given table cell, if

        the cell contains a paragraph. If the cell contains more than one

        paragraph, returns the first one.

getCellParagraphs(table, row, column)

getCellParagraphs(cell)


        Returns the list of the paragraph elements contained in a given

        table cell (knowing that a single cell can contain one or more

        paragraphs).

getCellValue(table, row, column)

getCellValue(cell)


        Returns the value of a table cell, if the cell is defined and

        uncovered. Caution, in order to get the cell element itself for

        further processing, use getCell() instead.

        The first form indicates a cell by its 3D coordinates, as with

        getCell().

        The second form (quicker) takes a cell element as its only argument

        (e.g. as returned by a previous getCell call).

        This method behaves in two different ways depending on the cell

        type. The displayable text of the cell is regarded as the cell value

        if the cell type is 'string'. If the cell type is one of the possible

        numeric types ('float', 'currency', 'date'), the returned value is the

        internal, numeric value.

        This difference in handling is designed to allow programs to use

        returned numeric values directly in calculations.

        See also cellValueType().

        Note: To get information about a cell other than its value or value

        type (numeric, etc.), the best way is first to get its element

        reference with getCell() and then use it with getAttribute.

getChapterContent(heading [, options])


        This method returns the list of the elements depending (from the

        end-user's point of view) on a given heading element, not including

        the heading element itself. The argument and the options are the

        same as with getHeading().

        Examples:

                my @list = $doc->getChapterContent(2, level => 3);

                foreach my $element (@list)

                        {

                        my $text = $doc->getText($element);

                        print "$text\n";

                        }

        The code above selects and prints all the text elements below the

        third level 3 heading of the document (not including the content of

        the header itself. The following example creates a new section whose

        content is made of a heading and the content of the depending chapter

        (the heading text is used as the section name):

        

                my $heading = $doc->getHeading(2, level => 3);

                my $heading_text = $doc->getFlatText($heading);

                my $section = $doc->appendSection($heading_text);

                my @content = $doc->getChapterBodyElements($heading);

                $doc->moveElementsToSection($section, $heading, @content);

        (See appendSection(), getHeading(), moveElementsToSection() in the

        present manual chapter, and getFlatText() in OpenOffice::OODoc::XPath)

                

        Caution, this method returns a list of elements and not an element.

        Chapters, unlike sections, are not defined in OpenDocument. So,

        getChapterContent() should be used as a possible workaround in order

        to isolate a logical set of content elements which is not packaged in

        a section.

getColumn(table, column)


        Returns the element reference of the given column in the given

        table. The first argument is either the table's sequential number in

        the document, logical name or element reference. The second argument

        is the column's number in the table. Synonym: getTableColumn.

        Caution: The application should ensure that the area including the

        needed column is "normalized". See normalizeSheet() for details about

        table normalization.

getDrawPage(pos/name)


        For presentation and drawing documents.

        Returns the element reference of the given page name or position.

        If the argument contains an integer, the page is selected according to

        its zero-based position. If the value is negative, the position is

        counted backwards from the end.

        If the argument is alphanumeric, it's regarded as a page name, and the

        page is selected accordingly.

        Caution: This method can't retrieve a page by name if the name

        contains numeric characters only; selectDrawPageByName() should be

        preferred to do so.

getEndnoteCitationList()


        Returns the list of all the endnote citations (i.e. references to

        footnotes included in the text) contained in the document.

getEndnoteList()


        Returns the list of all the endnote body elements contained in the

        document. Should be replaced by getNoteList() with the "class" option

        set to "endnote".

getFootnoteCitationList()


        Returns the list of all the footnote citations (i.e. references to

        footnotes included in the text) contained in the document.

getFootnoteList()


        Returns the list of all the footnote body elements contained in the

        document. Should be replaced by getNoteList() with the "class" option

        set to "footnote".

getHeading(n [, options])


        Returns the nth+1 heading element.

        If n is negative, headings are counted backwards from the last.

        getHeader(-1) returns the last heading element of the document.

        The only one possible option is "level". It allows the application

        to select the nth+1 heading element for a given level.

        Example:

                my $heading = $doc->getHeading(2, level => 3);

        selects the third level 3 heading in the whole document.

        See also getChapterContent().

        Caution: without the "level" option, this method counts sequentially

        through all headings along a single plane, irrespective of their

        level. E.g. if you have a level 1 heading then two level 2 headings

        then a level 1 heading, the call getHeading(3) returns the last

        level 1 heading.

getHeadingList([level => value])


        Returns a list of heading elements (i.e. elements called 'text:h' in

        the document body).

        If the "level" option is provided, the list is restricted to the

        headings having the given level.

getHeaderRow(table [, row_number])


        See getTableHeaderRow().

getHeadingText(n)


        Returns the text of the nth+1 heading element. Elements are counted

        in the same way as for getHeading().

getHeadingTextList()


        Returns a list of document heading texts.

        In a list context, the result is returned in the form of a list of

        character strings. In a scalar context, the result is a single

        string in which the headings are separated by a line-break character

        ("\n").

        Note: This list is "flat". It contains no information about the

        headings' hierarchy. To get a hierarchical contents list, you must

        start with the list of headings obtained using getHeadingList and

        check each element's level attribute ('text:level').

getItemElementList(list)


        Returns a list of elements which represent items of an ordered or

        unordered list. The argument is a "list" element (obtained

        previously e.g. using getItemList, getOrderedList or

        getUnorderedList). Each element in this list can be used with item

        handling methods.

getItemList(n)


        Returns the element which represents the nth+1 list in a document

        if found.

        WARNING: In the OpenOffice.org 1 documents, only "ordered lists" and

        "unordered lists" can be present. In the Open Document format, there

        are generic list objects only, and each one is made "ordered" or

        "unordered" by its style. So, this method will never return anything

        from an OOo 1 document.

getLevel(element)


        See getOutlineLevel().

getList(n)


        See getItemList().

getListItem(list, n)


        Returns the nth+1 item in a given list if found.

        The list (1st argument) may be given either by its order number in

        the document, or directly as an element reference.

getNoteCitationList()


        For OpenDocument only (doesn't work on old OpenOffice.org documents).

        Returns the list of all the note citation elements (whatever their

        note class, i.e. "endnote" or "footnote").

getNoteClass(note_element)


        Returns the class of the given note element. Possible values are

        presently "endnote" and "footnote". Returns undef unless the given

        element is a note.

getNoteElement(class => $note_class, citation => $note_citation)


        Returns the first note element matching the given class and citation,

        if any. Returns undef if the target note element doesn't exist.

        The "class" parameter is either "endnote" or "footnote".

        The "citation" parameter is the numeric or literal which refers to

        the note, as it's visible for the end user.

        Caution: The uniqueness of a note citation in a given note class is

        not a general rule. The citation is an identifier when it belongs to

        an ordered sequence (such as 1, 2, 3... or "i", "ii", "iii"...). But

        the author is allowed to use the same citation (ex: an asterisk) for

        more than one footnote or endnote. In such a situation, the method

        returns the first note matching the given citation and the given

        class. As a consequence, the note identifier, if known, is a better

        option (see the second form of getNoteElement()).

getNoteElement(id => $note_identifier)


        Returns the note element matching the given internal note identifier

        (which is a "text:id" attribute according to the ODF specification).

        This internal identifier is unique, whatever the note class, so the

        "class" parameter is not needed. However, "class" may be provided as

        an additional filter; if so, the method will return undef if the

        element matching the identifier doesn't match the class.

getNoteElementList()


        Returns the list of the endnote and footnote main elements.

getNoteList()


        Returns the list of the endnote and footnote body elements.

getOrderedList(n)


        Returns the element which represents the nth+1 ordered list in a

        document if found.

        WARNING: Ordered lists are possible in the OpenOffice.org 1 format

        only. Don't use it against OpenDocument.

getOutlineLevel(element)


        Returns the level number of a text element, or undef if the given

        element don't have a level number. Every heading element should have

        a level, while ordinary text body elements should not. Example:

                my $level = $doc->getOutlineLevel($element);

                if ($level)

                        {

                        print "There is a level $level heading\n";

                        }

                else

                        {

                        print "Non-heading element\n";

                        }

getParagraph(n)


        Returns the nth+1 paragraph in the document body, or undef if the

        given number is greater than or equal to the total number of

        paragraphs in the document.

        You can also pass a negative argument, in which case paragraphs are

        counted backwards from the end (-1 being the last paragraph).

        By paragraphs we mean 'text:p' elements, which excludes headers but

        includes non-empty table cells, contents of list items and

        footnotes.

        Returned value is an element and not the text of the paragraph. All

        read/write operations involving attributes and content can use this

        element.

getParagraphList()


        Returns a list of paragraph elements (i.e. 'text:p' elements in the

        document body).

getParagraphText(n)


        Returns the text of the nth+1 paragraph, counted using the same

        rules as for getParagraph.

getParagraphTextList([filter])


        Returns a list of texts contained in the paragraphs of a document

        ('text:p' elements).

        A filter can be passed as an optional argument (literal or regular

        expression). In this case, only paragraph texts whose content match

        the filter are returned.

        In a list context, the result is returned in the form of a list of

        character strings. In a scalar context, the result is a single

        string in which the paragraphs are separated by a line-feed

        character ("\n").

getRow(table, row_num)


        Returns the element reference which corresponds to a row in a table.

        The first argument is either the table's sequential number in the

        document, logical name or element reference. The second argument is

        the row number in the table. Synonym: getTableRow.

        This methods ignores the table header (if any). It can retrieve a

        row in the table body only. See getTableHeaderRow().

getRowCells(table, row)

getRowCells(row)


        Returns the list of the uncovered cell elements corresponding to a

        given table row. The row can be provided either by table ID and row

        number or by direct row object.

getSection(name/number)


        If the first argument is a number, returns the nth+1 section in a

        document (section numbers are zero-based; if the argument is negative,

        the sections are counted from the end).

        The second form allows you to select a section by its logical name (as

        it would appear to the end user when editing the section's

        properties). This name is obviously easier to use than a number.

        Moreover, this type of selection means the application will still

        work even if a section changes position within a document.

        The returned object is a "handle" that can be used for subsequent

        element creations or retrievals in the selected section.

getSpanList([context])


        Returns a list of elements, in the given context, which correspond

        to texts which "stand out" from the regular flat text, i.e. which have

        been given a style which makes them stand out from the rest of the

        paragraph containing them. The context may be a paragraph, a section,

        or any other text container. The context argument is optional; the

        default context is the whole document.

        For example, a word in italics or in font size 12 in a paragraph of

        mostly standard characters in font size 10 is a 'span' element and

        would therefore appear in a list returned by getSpanList.

getSpanTextList([filter])


        Gets a list of texts which "stand out" in the same way as

        getSpanList and returns it under the same conditions as

        getParagraphTextList or getHeadingTextList, with optional filter.

getStyle(path, position)

getStyle(element)


        Obsolete. See textStyle.

getTable(number [, length, width])

getTable(name [, length, width])


        Returns the reference of a table, selected by name or number.

        If the first argument is a number, returns the nth+1 table in a

        document (table numbers are zero-based; if the argument is negative,

        the tables are counted from the end).

        The second form allows you to select a table by its logical name (as

        it would appear to the end user when editing the table's

        properties). This name is obviously easier to use than a number.

        Moreover, this type of selection means the application will still

        work even if a table changes position within a document. But the

        retrieval by name works with two restrictions:

        - if a table name is made of digits only, or if if represents a

        numeric expression, it's automatically regarded as a table number;

        - getTable() can't retrieve a table by name if the name contains

        one or more "$", "{" or "}" characters; these characters are allowed

        in the table names in text documents (ODT), but not allowed

        in spreadsheets (ODS).

        The returned object is a "handle" that can be used for subsequent

        accesses to its components (rows, cells).

        The additional size arguments are required with "open" tables, i.e.

        tables whose size is not really fixed, such as spreadsheets. If the

        length and width arguments are provided, the corresponding area

        becomes safely addressable. With OpenOffice.org Writer documents,

        the size declaration is presently not required, because every table

        has a fixed size and a continuous addressing scheme. See

        normalizeSheet() for details about the table size declarations. And

        use the size arguments each time you experience an addressing problem

        with a table.

        A getTable() call with the optional length, width arguments produces

        the same effect as an explicit call of normalizeSheet() with the same

        arguments.

getTableColumn(table, column)


        See getColumn.

getTableHeaderRow(table [, row_num])


        Returns the element reference which corresponds to a row in a table

        header, or undef if the given table has no header row.

        The arguments are processes in the same way as with getRow(), but

        the second argument is optional; it's required only if the table

        has more than one header row (the 1st header row is returned by

        default).

        The returned elements can be used with subsequent cell access methods

        in order to process header cells (see getCell()).

getTableList()


        Returns a list of table elements in a document.

getTableRow(table, row)


        See getRow.

getTableRows(table)


        Returns the list of the rows contained in the given table.

        When the user needs to process every row in large tables, this method

        allows some performance improvements, because it's less costly than

        a lot of successive getRow() calls.

getTableSize(table)


        Returns the size of a table as a pair of values which represent the

        number of rows and columns. The table can be specified either by

        number, logical name or reference.

        Example:

            my ($rows, $columns) = $doc->getTableSize("Table1");

        Caution: This method provides meaningful results with well delimited

        tables whose the XML storage is "normalized". It should not be used

        with "open" spreadsheets (such as OpenOffice.org Calc documents),

        where the physical length and width of a table don't really make

        sense. In the present OpenOffice.org Writer (text) documents, the

        tables are delimited and every row and cell is mapped to an exclusive

        XML element, so getTableSize() is workable (up to now) with this kind

        of documents. However, the OpenDocument specification allows an

        optimization strategy which, when implemented, prevents getTableSize()

        from returning workable results. In such a situation, the applications

        must assume the length and width of the table and, before using it,

        prepare a normalized addressing workspace. See normalizeSheet() for

        more details.

getTableText(n)


        Returns the content of a table, if found, whose number or reference

        is given as an argument. If not found, returns undef.

        The content of each cell is extracted according to the rules of

        getCellValue.

        In a list context, the returned value is a 2D table with each

        element containing the corresponding cell in the document.

        In a scalar context, the content is returned as a single string in

        CSV format. In this case, the rows are separated by a delimiter set

        by the instance variable 'line_separator' and the fields by the

        variable 'field_separator' in the OODoc::Text object. (These

        delimiters are by default "\n" and ";" respectively.)

getText(path, position)

getText(element)


        Exports the text contained in the given element according to the

        means appropriate to that type of element.

        If the 'use_delimiters' flag is set to 'on' (default), the content

        of each element (others than ordinary paragraphs, table cell,

        headers) is preceded and/or followed by a character string depending

        on the type of the element. This also depends on the settings given

        to the delimiter values 'begin' and 'end' by the 'delimiters' hash.

        In a default configuration where the application has not provided

        any specific delimiters, the following delimiters are used:

            - '<<' before and '>>' after sections of text highlighted within

            an element (e.g. words in bold or underlined within a paragraph

            of 'standard' font characters).

        footnote citations (in text body) are placed between square

        brackets.

        '{NOTE:' and '}' for the content of footnotes.

        (Footnotes are physically inserted into the text at the place

        where they are called, just after the link element indicating the

        footnote's number. Its display at the foot of the page or elsewhere

        is a trick of the graphical interface.)

        An application can change these delimiters, add more for other types

        of elements (e.g. paragraphs, headers, tables cells, etc.), or

        deactivate them using outputDelimitersOff. This depends on where the

        text is exported to e.g. display in editable "flat" format,

        conversion to non-OpenDocument XML or a markup language other than

        XML, generating code from text, etc..

        A default export (ex: "\n") terminator can be set for any element that

        is not listed in the 'delimiters' hash (see defaultOutputTerminator()

        above).

        If the element is an ordered or unordered list, the text produced is

        a concatenation of all the lines in the list, each separated by a

        line-break in addition to any delimiters. The default line break

        character is "\n", but it can be set to any other string (including

        an empty string) through the 'line_separator' property of the document

        object.

        If the element is a string table cell, getText behaves like

        getCellValue. If the cell contains more than one paragraph, the text

        produced is a concatenation of all the paragraph contents, each

        separated in the same way as list items.

        If the element is a table, getText behaves like getTableText.

getTextBoxElement(name/number)


        Retrieves a text box element by its unique name or by its order

        number in the document (or in the current context).

        

=head3  getTextContent()

        Returns the text of a document, as "flat" editable text.

        In a list context, the content is returned as a table with one text

        element (header or paragraph) per element.

        In a scalar context, the content is returned as a single character

        string with each text unit (header or paragraph) separated by a

        line-feed ("\n").

        The returned text contains no style or level information, so there

        is nothing to distinguish a header from a paragraph.

        Same as selectTextContent('.*').

getTextElementList()


        Returns the list of all the text elements, including headers,

        paragraphs and item lists.

getTopParagraph(n)


        Same as getParagraph but only considers top level paragraphs. The

        contents of lists, tables and footnotes are excluded.

getUnorderedList(n)


        Returns the element which represents the nth+1 unordered list in a

        document, if found.

        WARNING: Ordered lists are possible in the OpenOffice.org 1 format

        only. Don't use it against OpenDocument.

getUserFieldElement(name)


        Returns the element (if defined) representing a user-defined field,

        and corresponding to the given name. See also userFieldValue().

getVariableElement(name)


        Returns the user-defined variable identified by the given name.

        [Contribution by Andrew Layton]

hyperlinkURL(hyperlink [, url])


        Get/set the URL of an hyperlink element. The first argument may be

        a previously retrieved hyperlink element (see selectHyperlinkElement

        below), or the URL of an existing hyperlink. If a second argument is

        provided, it replaces the URL of the hyperlink element.

        With only one argument, just returns the existing URL of the link,

        or undef if the first argument doesn't match an existing hyperlink

        element.

inputTextConversion(text)


        Returns the UTF8 conversion of the given text, supposed to be in

        the local character set of the document (see the 'local_encoding'

        property).

insertColumn(table, col_num [, options])


        Inserts a new column in an existing table at a given position.

        The second argument must be the number of an existing column.

        Caution: this argument must be a column number, and not a column

        element.

        The new column is created as a copy of the column a the given

        position. It's inserted before or after the existing one, according

        to an optional "position" parameter (default 'before').

        Caution: before using insertColumn() against a spreadsheet, the

        application should ensure that the whole rectangular area from the top

        left cell ("A1") to the last used cell of the column at the target

        position is "normalized" (see normalizeSheet() for details about the

        table normalization).

insertDrawPage(page/pos [, options])


        In a presentation or drawing document, inserts a new page before

        or after an existing page.

        Possible options are the same as for appendDrawPage(), with an

        additional one:

                position        => 'before' or 'after' (default 'before')

        The new page is inserted before or after the reference page, according

        to the 'position' option.

        The first argument can be a draw page element reference (recommended)

        previously returned, for example, by a previous page retrieval or

        creation method call. Alternatively, it can be a page position or

        visible name, so it's regarded in the same way as in getDrawPage().

        Returns the new page element, or undef in case of failure.

insertHeading(path, position, options)

insertHeading(element, options)


        Same as appendHeading, but inserts the new heading before or after

        another element.

        Position is that of an existing element which can be another heading

        or a paragraph. Can be given by [path, position] or by element

        reference.

        Possible options are the same as for appendHeading, with the

        additional option 'position' which determines if the heading is

        inserted before or after the element at the given position. Possible

        values for this option are 'before' and 'after'. By default, the new

        element is inserted before the given element.

insertItemList(path, position [, options])

insertItemList(element [, options])


        Same as appendItemList, but a new list is inserted at the given

        position. The point of insertion can be given either by the pair

        [path, position] or by element reference. Options are the same as

        for insertParagraph.

insertParagraph(path, position [, options])

insertParagraph(element [, options])


        Same as appendParagraph, but a new paragraph is inserted at the

        given position.

        Position is that of an existing element which can be another

        paragraph or a header. Can be given by [path, position] or by

        element reference.

        Options are the same as for appendParagraph, with the additional

        option 'position' which determines whether the paragraph is inserted

        before or after the element at the given position. Possible values

        for this options are 'before' and 'after'. By default, the element

        is inserted before the given element.

insertRow(table, row [, options])

insertRow(row_element [, options])


        Inserts a new row into a table. In its first form, pass the table

        (reference, logical name or number) and the position number in the

        table. In its second form, pass the element reference of the

        existing row which is directly before or after the position where

        you want to make the insertion.

        By default, the new row is inserted at the position of the

        referenced row, which displaces it and the rest of the table down by

        one row position. However, you can insert it after by using the

        'position => after' option. By default, the new row is an exact copy

        of the referenced row, but you can assign particular attributes to

        it in the same manner as the insertElement method of OODoc::XPath.

insertSection(path, position, name [, options])

insertSection(element, name [, options])


        Creates a new section and inserts it immediately before or after

        an existing element (paragraph, header, table). The referenced element

        can be indicated as in insertParagraph.

        There is a "position" option which works in the same way as with

        insertParagraph() or insertRow().

        For other options, see appendSection(). For example, insertSection()

        may be used in order to insert a subdocument in a master document.

insertString(path, position, text, offset)

insertString(element, text, offset)


        Inserts a flat character string in a given element (whatever the type

        of element) at the given offset. If the offset is not defined, the

        text is appended to the end of the element (however, if the offset is

        provided and set to zero, the string is inserted at the beginning).

insertTable(path, position, name, rows, columns [, options])

insertTable(element, name, rows, columns [, options])


        Creates a new table and inserts it immediately before or after

        another element (paragraph, header, table). The referenced element

        can be indicated as in insertParagraph. The other arguments and

        options are the same as for appendTable with the additional option

        'position' as in insertParagraph.

insertTableColumn(table, col_num [, options])


        See insertColumn().

insertTableRow(table, row [, options])

insertTableRow(row_element [, options])


        See insertRow().

lockSection(section [, key])


        Installs a write protection on the given section.

        If a second argument is provided, it's stored as an encrypted key

        which is associated to the write protection. Caution, it's not the

        key as it should be typed by the OOo end-user.

        Such a write protection works only when the document is edited through

        an OpenOffice.org-compatible desktop software. It doesn't prevent the

        programs using OpenOffice::OODoc from deleting or updating the

        protected sections.

makeHeading([options])


        Creates a new heading element, or marks as a heading an existing

        element.

        Options:

                element         => an arbitrary existing element

        If this option is provided, the given element is converted in place

        to a heading, whatever its original type and position. No element

        is created.

        Without the 'element' option, a new heading element is created and

        returned for later use. This element is free; it's not automatically

        attached somewhere in the document. For direct heading creation and

        attachment, you should prefer appendHeading() or insertHeading().

                level           => a numeric, positive integer value

        Sets the hierarchical level of the heading (remember 1 is the top

        heading level). Caution: no default value.

                style           => the name of a convenient heading style

        While it's not mandatory, the 'style' option and a properly defined

        heading style are generally required in order to allow the office

        software to really process and display the element as a heading with

        the right hierarchical level. Of course, any previously existing

        hierarchical style is reusable here.

        The main purpose of this method is to allow quick heading hierarchy

        creation in a "flat" document. For exemple, an application can select

        a set of flat paragraphs matching a given condition and convert each

        one in place to a heading with a given level.

        

=head3  moveElementsToSection(section, list)

        Moves a list of elements from any place to a section.

        

        The section may be passed by name or by element reference; it must be

        an existing one (no new section is created).

        

        The list is a set of arbitrary elements (including sections). Each one

        is cut from its previous place and appended to the section in the

        order of the list, without document consistency check.

normalizeSheet(sheet, rows, columns)


        This method preprocesses a given sheet so its components (rows,

        cells) become available for all the table-oriented methods described

        in this chapter. The 2nd and 3rd arguments control the size of a

        rectangular area, beginning at the first cell ([0, 0] or "A1"), to

        be processed. The processed area becomes a workspace which is safely

        addressable by any cell/row/column processing method. This

        preprocessing is sometimes required, sometimes not. Simply speaking,

        it's required on present OpenOffice.org Calc spreadsheets, and

        useless on present OpenOffice.org Text tables.

        It's automatically executed when getTable() is called

        with size arguments; therefore it's not always explicitly invoked by

        the applications. However, it's useful to know its purpose.

        The object addressing logic (which, for example, allows a program to

        directly reach a cell using its coordinates) relies on a continuous,

        regular mapping between the user's view and the physical XML storage

        of the tables. However, the OpenDocument specification allows any

        conforming application to map more than one table element to a

        single XML element. When two or more contiguous objects contain

        the same value and have the same style and the same data type, they

        *may* be mapped to a single XML element with a repetition attribute.

        As a consequence, the position of the appropriate XML element can't be

        directly calculated from the logical coordinates of the object, and

        OODoc needs to scan the table in order to get all the repetition

        attributes and calculate the real mapping. In addition, updating an

        object whose the XML corresponding element has a repetition attribute

        would automatically update all the objects mapped to the same element,

        producing unpredictable and generally wrong results.

        OpenOffice.org Calc systematically uses this storage optimization in

        spreadsheets, while OpenOffice.org Writer doesn't use it for tables in

        text documents. In Calc (sxc/ods) documents, the XML mapping of the

        whole content is "denormalized" in order to save memory: several table

        components can be mapped to a single XML element, so the XML address

        of each one can't be simply calculated from its logical coordinates.

        In order to allow the spreadsheet components to be addressed with the

        same methods as the Writer table components, normalizeSheet()

        reorganizes the XML mapping of the given sheet.

        Caution: The OpenDocument specification doesn't make any difference

        about this point between tables included in text documents and tables

        in spreadsheet-only documents. So any ODF-compliant application

        *could* denormalize the XML storage of any table and use the

        repetition attributes. As a consequence, normalizeSheet() *could* be

        required in the future for other documents than OOo Calc ones.

        This method is not (presently) always needed for tables included

        in OpenOffice.org Writer (odt/sxw) documents, because their storage is

        "normalized" (i.e. each component is mapped to an exclusive XML

        element), with the exception of the column objects. So,

        normalizeSheet() is required with these tables when the application

        needs to use a column-focused method such as getColumn(),

        insertColumn() or deleteColumn().

        In the other hand, normalizeSheet() is not required to address a sheet

        which has been created through the OODoc methods (provided that the

        document has not been edited with OpenOffice.org in the meantime).

        These methods, i.e. appendTable() and insertTable(), create normalized

        tables, whatever the document class.

        Because this method is very time and memory consuming, it should never

        be used to reorganize the largest possible area of a sheet (meaning

        thousands of rows and hundreds of columns that will probably never be

        used). So it's action is limited to a given area, controlled by the

        rows, columns arguments. When these arguments are not provided, the

        method uses the 'max_rows' and 'max_cols' properties instead (see the

        Properties section for other explanations). The processed area should

        be sized in order to cover all the cells to be reached by the program,

        and nothing more.

        The first argument can be either the logical name of the sheet (as

        it's shown in the bottom tab by OOo Calc), the sheet number, or a

        table object reference, previously returned by getTable(). The return

        value is the table object (or undef in case of failure).

        Example:

                $doc = ooDocument(file => 'report.sxc');

                my $sheet = $doc->normalizeSheet('Sheet1', 7, 9);

                my $result = $doc->cellValue($sheet, 5, 6);

        In the sequence above, a top left area of 7 rows by 8 columns is

        pre-processed, so the cells from A1 to H6 of this sheet can be

        reached according to the same addressing scheme as in Writer tables.

        The last instruction gets the content of G6.

        The transformed sheets, of course, are readable by OOo Calc.

        They simply take some more disk space when the processed spreadsheet

        is saved. If the document is later read then written by OOo Calc,

        the storage is optimized again, so the effects of normalizeSheet()

        disappear.

        normalizeSheet() can be used safely against Writer document tables,

        with two possible results. If the table size is greater than the given

        size, the method is neutral. Otherwise, the length and/or the width is

        increased according to the given arguments (however, the new rows and

        columns appear with default styles, so the extended table may be badly

        presented).

        An explicit call to this method can be replaced by getTable() with the

        additional length and width parameters.

normalizeTable(table [, rows [, columns]])


        See normalizeSheet().

outputDelimitersOn()

outputDelimitersOff()


        Turns delimiters on or off. Used to mark up text exported by certain

        methods like getText or selectTextContent.

        The delimiters actually used depends on the table loaded into the

        OODoc::Text instance via the 'delimiters' property.

outputTextConversion(text)


        Returns the conversion in local character set of the given text,

        supposed to be in UTF8. The local character set of the document

        is used (see the 'local_encoding' property).

removeBookmark(id)


        See deleteBookmark().

removeHeading(position [, level => level_no])

removeHeading(element)


        Removes the given heading element.

        Example:

            $doc->removeHeading(4);

        removes the 5th heading (whatever its level) counted from the

        beginning of the document.

        See getHeading() for the argument and option.

        If the argument is an element reference (second form), the type is

        not checked and this method becomes the equivalent of removeElement()

        (which is documented with OpenOffice::OODoc::XPath generic methods).

removeHyperlink(path, position)

removeHyperlink(element)


        Removes any hyperlink contained in the given element, leaving

        in place the previously hyperlinked text.

removeParagraph(position)

removeParagraph(element)


        Removes the paragraph at the given position (first form).

        The paragraph to be removed can be indicated by element reference

        (second form). In this case, the type of element is not checked and

        this method becomes the equivalent of removeElement.

removeCellSpan($cell)


        Removes the multi-column, multi-row span of a table cell. The width

        and height of the cell are reduced to one column and one row.The

        uncovered cells take the same style and data type as the reduced cell.

        

        Caution: This method works with cells that heve been expanded using

        the "number-rows-spanned" and "number-columns-spanned" OpenDocument

        attributes. The cell expansion is done this way by the cellSpan()

        method, as well as with the present version of OpenOffice.org Calc.

        But other applications (including the present version of

        OpenOffice.org Writer) can implement the cell merge using subtables

        instead of span attributes.

        

=head3  removeSpan(path, position)

removeSpan(element)


        "Flattens" a text element, removing all presentation distinctions

        which may mark out some substrings of its content.

        For a more drastic result, see flatten() in OpenOffice::OODoc::XPath.

        See also setSpan().

renameSection(section, newname)


        Renames an existing section using the second argument.

renameTable(table, newname)


        Renames an existing table using the second argument.

rowStyle(row_element [, style])

rowStyle(table, row [, style])


        Reads or modifies a table row's style, in the same way as

        columnStyle does for columns.

sectionProtectionKey(section)


        Returns the encrypted key which is associated to the given section,

        if the section is write-protected by key.

        This method can't provide the real key (as it should be typed by

        the end-user to unlock the section), but the returned value may be

        reused in order to protect more than one section with the same

        password.

        See also unlockSection().

sectionStyle(section, [newstylename])


        Without argument, returns the current style of a given section.

        If an argument is provided, it becomes the new style of the section.

selectDrawPageByName(name)


        In a presentation or drawing document, returns the page element

        identified by the given name, or undef if the name is unknown.

        The names to be used correspond to the displayed page names in

        OpenOffice.org Impress.

selectElementByBookmark(name)


        Returns the element containing the given bookmark.

        Caution: this method works with position bookmarks only, not with

        range bookmarks (a range bookmark can be spread over several text

        elements).

selectElementByContent(filter, [...])


        Returns the first text element whose content matches the 'filter'

        (which can be an exact string or a regular expression), or undef

        if no matching content is found.

        With more than one argument, this method can be used for replacement

        operations, or user-defined function triggering, in the same

        conditions as selectElementsByContent().

selectElementsByContent(filter)

selectElementsByContent(filter, replacement)

selectElementsByContent(filter, action [, other_arguments])


        This method returns a list of text elements such as paragraphs,

        headers or ordered/unordered lists whose content matches the search

        criteria contained in 'filter' (which can be an exact string or a

        regular expression).

        This method is context-sensitive (see currentContext() and

        resetCurrentContext() in OpenOffice::OODoc::XPath for details about

        the context). Its search space is restrained to the children of the

        context element (so the default search space is the whole document

        body). Be careful: if the search is successful, the returned elements

        are not always the direct containers of the string which matches the

        filter; they are the elements whose any child element contains the

        string. For example, if a table cell contains a matching string, the

        containing table, and not the cell, is returned. If a paragraph

        containing the matching string belongs to a section, the section,

        not the paragraph, is returned. However, if the current context is

        the table, selectElementsByContent() will return the matching rows.

        And if the context is the section, it will return the matching

        objects included in the section (knowing that a section can contain

        other sections and any other structured containers).

        The first form simply returns the given list without modifying the

        text.

        The second form returns the same list, but replaces all strings

        which match the search criteria with the 'replacement' string as it

        goes.

        The third form, where the 'action' argument is a program function

        reference, launches the given function each time the filter string

        is matched. If defined, the value returned by the function is used

        as the replacement value. If the function returns a null value

        (undef) then no replacement is made. If it returns an empty string,

        the retrieved text is deleted. The called function receives the rest

        of the arguments, in this order:

        1) all remaining arguments after 'action' ('other_arguments'), if any.

        2) the element containing the retrieved text.

        3) the string actually selected. If the filter is an exact string,

        it is equal to the filter. If the filter is a regular expression,

        it matches the "real" text retrieved.

        The returned text (if any) must be encoded in UTF8.

        The returned list is the same one returned by the first two forms.

        Example:

            sub action

                {

                my ($d, $element, $value) = @_;

                if ($value < 100)

                        {

                        $d->removeElement($element);

                        return undef;

                        }

                else

                        {

                        return $value * 2;

                        }

                }

                        @list =

             $doc->selectElementsByContent("[0-9]+", \&action, $doc);

        In the above code, the subroutine "action" is called each time an

        integer (one or more digits) is found. The subroutine receives the

        document reference itself as its first argument (an OODoc::Text

        object given by the application). Next, it automatically receives

        the reference of the element in which the search string was found

        (i.e. an integer) and, finally, it receives the exact number found

        as its second-last and last arguments respectively. If this number

        is less than 100, the element is removed. This is why the subroutine

        needed the $doc object, used to invoke the removeElement method. If

        more than 100, the number is multiplied by two and the result

        replaces the original value in the element. The list returned by

        selectElementsByContent contains all elements which contain the

        search string, including any which might have been removed by the

        called function while it was running.

        It is the "main" elements containing strings which matched the

        filter which are returned and not any of their sub-elements. For

        example, if the returned string is found in one of the items in an

        unordered list, the list element is selected and not the item.

        Similarly, the table is selected when one of its cells matches the

        filter, and the paragraph which is selected when the search string

        is found in an attached footnote.

        However, a character string cannot be considered to match the filter

        unless it is entirely within the same sub-element and all its

        characters have the same style. For example, if you were searching

        for the string "OpenOffice" using selectElementsByContent, the

        string, if present, can't be found if, say, "Open" and "Office" are

        not represented with the same font, the same color and/or the same

        font size.

        Note: This method can be used with a "non-filtering" regular

        expression (".*") for unconditional movement through all text

        elements.

selectElementByTextId(id)


        Returns the element (if any) identified by the given value of text

        identifier. The text identifier (i.e. "text:id") is an optional

        attribute for text containers. It *should* be unique in a document.

        However, this identifier is presently used in a few elements only

        by OpenOffice.org.

selectHyperlinkElement(url_filter)


        Retrieves the first hyperlink element (if any) whose the URL matches

        the argument. Example:

                my $e = $doc->selectHyperlinkElement("cpan");

        could return an hyperlink element containing "www.cpan.org" as

        well as "search.cpan.org", etc. The URL filter is processed as

        a regexp.

        Note: In order to get the text container (ex: paragraph) where the

        hyperlink is located, the application can use the parent() element

        method. Example:

                 my $e = $doc->selectHyperlinkElement("www.cpan.org");

                 my $p = $e->parent if $e;

selectHyperlinkElements(url_filter)


        Returns the list of the hyperlink elements whose the URL matches

        the argument (and not only the first one).

selectParagraphByStyle(stylename)


        Returns the first paragraph (if any) using the given style.

selectParagraphsByStyle(stylename)


        Returns the list of the paragraphs using the given style.

selectTextContent(filter)

selectTextContent(filter, replacement)

selectTextContent(filter, action [, other_arguments])


        Returns a list of header texts and/or paragraphs (in the document's

        own order) which match the given search criteria.

        The filter can be an exact string or a regular expression. A filter

        set to ".*" (no selection) will result in an export of the entire

        text.

        In all three forms, this method behaves like

        selectElementsByContent, except that it returns text instead of a

        list of elements.

        Depending on the context (list or scalar), the result is returned in

        the form of a list of rows or in the form of a single character

        string where the elements are separated by a line-feed ("\n").

        Note: called with a "non-filtering" regular expression, this method

        will result in a "flat" export of the document:

            print $doc->selectTextContent('.*');

setBibliographyMark(element, offset, identifier => id [, options])


        Creates a new bibliography mark within a given text element at a

        given offset. The hosting element, the offset (relative to the content

        of the element) and the "identifier" parameter are mandatory. The other

        options are all the possible attributes of an OpenDocument-compliant

        bibliography entry, such as author, editor, isbn, title, year, and

        many others. Example:

                $para = $doc->selectElementByContent("ODF-related book");

                $doc->setBibliographyMark

                        (

                        $para, 0,

                        identifier      => "JDE",

                        title           => "OASIS OpenDocument Essentials",

                        author          => "J. David Eisenberg",

                        year            => 2005,

                        isbn            => "1-4116-6832-4"

                        );

        This sequences puts a bibliography mark at the beginning (position=0)

        of a previously selected text element. This mark will be displayed by

        default as "[JDE]" with OpenOffice.org Writer.

setBookmark(element, name [, offset])


        Puts a bookmark in a text element.

        Example:

                my $paragraph = $doc->selectElementByContent

                                                ("Eragon and Saphira");

                $doc->setBookmark($paragraph, "The Heroes");

        puts a bookmark identified by "The Heroes" in a paragraph where a

        given text has been found (of course, the bookmark will remain even

        if the text of the paragraph is changed later).

        By default, the bookmark is put at the beginning of the text. But,

        thanks to the optional offset, it can be put at any position within

        the text of the bookmarked element.

        Note: This method puts a position bookmark, and not a range bookmark.

        The OpenDocument specification allows both range and position

        bookmarks. However, a range bookmark is not an element; it's a pair

        of elements ("bookmark-start" and "bookmark-end").

setHyperlink(path, position, [context,] expression, url)

setHyperlink(element, [context,] expression, url [, options])


        Puts an hyperlink on a text area in a given text element.

        Example:

            $doc->setHyperlink($para, "CPAN", "http://www.cpan.org";);

        This method works in the same was as setSpan(), described below,

        but the text span is hyperlinked, and not only presented according

        a particular style. So, the third argument must be an URL instead

        of a style. 

        

        A set of hyperlink attributes may be optionally provided as a hash.

        For example, the application can provide a 'style-name' and a

        'visited-style-name' options:

        

            $doc->setHyperlink

                        (

                        $para, "CPAN", "http://www.cpan.org";,

                        'style-name' => "ToBeVisited",

                        'visited-style-name' => "Visited"

                        );

                        

        'style-name' selects the style which applies to the text of the

        hyperlink, as long as the URL is not visited, while

        'visited-style-name' indicates, of course, the style in use if the

        link location was already visited. These styles must belong to the

        'text' family. 

        

        Other allowed hyperlink attributes are listed in the 5.1.4 of the

        OASIS OpenDocument 1.0 specification.

        Note: The hyperlink is not always a remote URL, such as in the

        example above. Internal references ere allowed as well. An

        internal reference is prefixed by "#". If an internal reference

        is a heading, it's prefixed by "#" and suffixed by "|outline".

        An hyperlink may be aimed at a location inside another document;

        such a link is the concatenation of a file path, a "#", and a local

        name that makes sense in the target document (bookmark, heading...).

setSpan(path, position, [context,] expression, style)

setSpan(element, [context,] expression, style)


        Applies a special text style to one or more parts of the content

        of a text element.

        In OpenDocument XML language, a "text span" is a substring whose

        presentation style differs from the style of the text element to

        which it belongs. For example, a given "span" could be in italics

        while the rest of the paragraph is in normal characters.

        Caution: the same word has a different meaning when it's used

        about table cells (see cellSpan()).

        A "span" is therefore a way to use several styles within the same

        element, bearing in mind that the paragraph's global style can be

        modified by setStyle().

        The properties of a text span can be related to any kind of character

        string presentation, such as font, font size, font weight, font

        style, and colors (background and foreground). Whatever these

        properties, they apply through a style.

        The desired text element is normally indicated by [path, position]

        or reference (recommended). The optional argument 'context' which

        consists of an element reference, allows you (when using [path,

        position]) to limit a search to child elements of a particular

        element (e.g. page header, page footer, item list, section, etc.).

        'expression' represents a filter; every substring contained

        in the target element and matching the filter is attributed using the

        given style. This filter is processed, up to some extent, as a regular

        expression, but there is no full perl regexp support here.

        'style' is obviously the style describing the presentation

        characteristics to give to it. See OODoc::Styles for how to construct

        styles by program or to replicate existing styles. Remember that a

        style must belong to the 'text' family in order to be used in this

        context (for example, a paragraph style would not work).

        As a highlighted string can be quite long or not all known in

        advance, you can represent it with a regular expression. Taking the

        following paragraph as an example:

        "OpenOffice.org includes Writer, Calc, Draw and Impress"

        Assuming this text is contained in a $p element, the following

        instruction gives the "Highlight" style to the "OpenOffice.org",

        "Writer", "Calc", "Draw", and "Impress" substrings:

                $doc->setSpan

                    (

                    $p,

                    'OpenOffice\.org|Writer|Draw|Calc|Impress',

                    "Highlight"

                    );

        The style referred to by setSpan() may be an existing style as well

        as a style to be defined by the program (see createStyle() in

        OpenOffice::OODoc::Styles).

        

        setSpan() works on any kind of text container, whatever its

        hierarchical level. For example, if the given element is a table,

        the span style attribution applies to every cell of the table. And

        the same change can be done in all the displayable content not

        including page headers, page footers, and page backgrounds through

        a single setSpan() call, if the given element is the document body

        itself (see getBody() in OpenOffice::OODoc::XPath).

        

        Caution: this method can neither recognise nor handle a string

        located partly in a "span" and partly outside it. It can, however,

        create a "span" inside another.

        See also removeSpan() and setHyperlink().

setStyle(path, position, style_name)

setStyle(element, style_name)


        Obsolete. See textStyle.

setText(element, text ,[text, ...])


        Alters the setText method of OODoc::XPath, so that it can handle

        complex text elements.

        If the element is a paragraph, a header or a list item (ordered or

        unordered), its content is replaced by the 'text' argument. Caution:

        setText() deletes and replaces the previous content of the paragraph.

        If the element is a table cell, this method is the same as

        updateCell.

        If the element is a list (ordered or unordered), the content of each

        'text' argument (however many) forces the creation of a new item

        which is appended to the list (existing items remain unchanged).

        Example:

            $doc->setText($element, "Peter", "Paul", "John")

        adds three items to the list if $element is a list. If $element is,

        for example, a paragraph, then the second argument ("Peter") becomes

        the content of the paragraph and the other arguments are ignored.

        If the element is a note element or a note body, the given text

        becomes the content of the note body.

        If the element is a section, the whole content of the section is

        deleted and replaced by a single paragraph containing the given text.

        For all other types of $element, setText() behaves normally as defined

        in OODoc::XPath.

        Note: setText(), as any other text input method, can't properly

        process repeated spaces. So, a sequence of spaces, whatever its

        length, is replaced by a single space. See setText() and extendText()

        in OpenOffice::OODoc::XPath.

        

=head3  setTextBoxContent(text_box, content)

        Fills the given text box according to the given content.

        

        The first argument may be the unique name, the order number or the

        reference of a text box. The content is processed in the same way

        as the content option in createTextBox().

setTextField(element, [context,] expression, field-type [, options])


        Replaces one or more substrings of a given text element by a variable

        text field. See textField() in the present manual chapter for some

        information about text fields.

        

        This method works the same way as setSpan() to retrieve the strings

        to be replaced. However, each matching string becomes invisible and

        is replaced by the variable field.

        

        Optional field attributes are allowed after the field type in the same

        conditions as for textField().

        

        The following example replaces every occurrence of "TIMESTAMP" in a

        given section by a variable field displaying a time which is 2 hours

        later than the current time:

        

                $section = $doc->getSection("Variables");

                $doc->setTextField

                        (

                        $section, "TIMESTAMP", 'time',

                        'time-adjust' => 'PT02H'

                        );

tableName(table [, newname])


        Returns the current name of a given table, or replaces it with a new

        name given as the second argument. The table can be indicated

        by number, logical name or reference.

        Returns undef unless the given table is defined.

        If the new name is the name of an existing table, the table is not

        renamed and an error message is produced.

textBoxCoordinates(text_box [, new_coord])


        Gets or sets the position of a text box. The new coordinates, if

        any, must be provided using the same syntax and units as with

        the "position" option in createTextBox().

        

=head3  textBoxDescription(text_box, [, new_desc])

        Gets or sets the optional description (long label) of the given

        text box.

        

=head3  textBoxName(text_box [, new_name])

        Allows the applications to get the name of the given text box

        (which makes sense if the name is unknown, i.e. if the first

        argument is the element reference or the order number and not

        the name itself, of course). If a literal is passed as a second

        argument, the text box is renamed accordingly.

        

=head3  textId(element [, text_id])

        This accessor gets or sets the "text identifier", an optional

        attribute of any text container. This attribute is presently used

        for a few elements by OpenOffice.org (ex: the notes).

        With one argument only, returns the existing identifier of the given

        element, or undef if the element doesn't own a text identifier.

        If a second argument is provided, its value replaces any previous

        value of the identifier, and the text identifier is created if needed.

        The new value is not checked, so the application should take care of

        its uniqueness.

        The text identifier can be used as a bookmark, knowing that, unlike a

        bookmark, this attribute is not visible for the end user.

        See also selectElementByTextId().

        Caution: The text identifiers created or changed by other applications

        are presently *not* preserved when the document is edited through

        OpenOffice.org.

tableStyle(table [, style])


        Returns the current style of a given table, or replaces it with a

        new style given as the second argument. The table can be indicated

        by number, logical name or reference.

textField(type [, options])


        Creates and returns a variable field to be inserted within a text

        element.

        

        Such a field doesn't contain any static text by itself. When

        included in a text container, it tells the editing/printing software

        to display dynamic context data, such as date, time, file name,

        page number, page count, author, etc. Variable text fields are mainly

        used in page headers or footers, but they are allowed in the page

        bodies as well. Remember that a text field must be attached as a child

        element of a text container (paragraph or heading) in order to be

        displayed. However, the text container itself may be attached to

        anything anywhere (ex: a page header, a table cell, a list item, etc).

        

        The first argument (mandatory) is the field type. Many field types

        are allowed, so they are not all listed here. For some of them,

        options are allowed or required.

        

        To get the full list of field types, and their possible options,

        look at the chapter 6 "Text fields" in the OpenDocument 1.0

        specification. However, a few ones are presented below as examples.

        The field type, as well as each field option, must be provided as it

        appears in the OpenDocument specification, without the "text:" prefix

        (this prefix is automatically added). However, the application can

        force any arbitrary field name and/or field option such as 'xxx:yyy'

        (any name or option including a ':' is accepted as is).

        

        Caution: textField() allows the user to create any kind of field,

        without OpenDocument compliance check. So it can be used to insert

        application-specific markup in any place. This feature could prove

        useful in some situations, but remember that a typo in a field type

        or option will not be automatically detected. In the other hand, every

        non-OpenDocument field is silently removed if the document is later

        edited and saved through OpenOffice.org.

        

        Knowing that the created element is not attached to a text container,

        it must be inserted or appended through another method. For example,

        the following sequence creates a paragraph displaying "This document

        contains <page-count> pages and we are in the page <page-number>":

        

                $para = $doc->appendParagraph

                        (

                        text => "This document contains ",

                        style => "Standard"

                        );

                $pg = $doc->textField('page-count');

                $doc->appendElement($para, $pg);

                $doc->extendText($para, " pages and we are in the page ");

                $pg = $doc->textField('page-number');

                $doc->appendElement($para, $pg);        

                

        The 'page-number' field type, introduced above, could be adjusted in

        order to display the page number of any following or preceding page.

        To do so, a 'page-adjust' option, set with a positive or negative

        integer value, should be provided to createField():

        

                $pg = $doc->textField

                        ('page-number', 'page-adjust' => -2);

                        

        Note that, if the arithmetic sum of the real page number and the

        'page-adjust' value doesn't match an existing page, the editing

        application should display nothing.

                        

        As another example, a 'chapter' field displays the current chapter

        number or title. It requires 2 options: 'outline-level', an integer

        which selects the hierarchical heading level to be regarded as the

        chapter level, and 'display' which controls the value to display

        (chapter number, chapter name or both). The following instruction

        creates a field displaying the number and the name of the current

        level 1 heading:

        

                $chapter_field = $doc->textField

                        (

                        'chapter',

                        'outline-level' => 1,

                        'display'       => 'number-and-name'

                        );

                        

        Other possible fields display the current date or time (see the

        setTextField() example about a time field with an optional ajustment),

        the author's name, the file path or name, and many other variable or

        fixed values, according to many options.

textStyle(path, position [, style])

textStyle(element [, style])


        Reads a text element's style or, if a 'style' argument is given,

        changes it. The text element may be a section, paragraph, a header,

        or a span included in a paragraph or a header.

        The element can be indicated by the pair [path, position] or by

        reference.

        Note: the returned value is a literal style identifier or the value

        of the element's 'text:style-name' attribute.

        Note: this method allows you to attribute a non-existent style to a

        paragraph or header. Such a style can be created later (e.g. using

        createStyle) or not at all. The actual existence of the style is

        only relevant to the needs of the application. Obviously,

        opening a document which contains references to non-existent styles

        in OpenOffice.org will give unpredictable results as to the viewing

        of the given paragraphs or headers.

unlockSection(section)


        Removes the write protection (if any) of the given section. If the

        section was key-protected, the key is removed and provides the return

        value of the method.

        Example:

                my $key = $doc->unlockSection("Section1");

                $doc->lockSection("Section2", $key);

        The two lines above remove the protection of "Section1" and protect

        "Section2" with the password which previously protected "Section1".

unlockSections()


        Removes the write protection of every section in the document.

updateCell(table, row, column, value [, text])

updateCell(element, value [, text])


        Modifies the content of a table cell.

        In its first form, indicates a cell by its 3D coordinates, as with

        getCell(). In its second form, indicates a cell by its element

        reference.

        If the cell is set to literal, its content is limited to its text.

        In this case, the optional argument "text" is of no use (the text

        equals the value).

        If the cell is set to numeric (float, currency, date, etc.), you

        should generally pass a literal argument as well as the value.

        This method can be replaced by the accessor cellValue which allows

        reads and writes.

userFieldValue(user_field [, value])


        Reads the stored value of a given user field or changes it if a

        value is provided. The 1st argument can be either the name of the

        field (as it appears for the end-user) or a previously loaded

        user field element. See also getUserFieldElement().

        This method doesn't create any new user field. It can only read or

        update an existing one.

        If the given user field is numeric (ex: date, currency) the returned

        and/or provided value is the internally stored value, and not the

        displayed one. The user field is displayed according to a data style

        by OpenOffice.org. For example, 'Tuesday, March 1, 2005' is a possible

        displayed value for 38412.

variableValue(name/element [, newvalue])


        Returns the current value of the given user-defined variable or, if

        a new value is provided as the second argument, updates the variable

        accordingly.

        [Contribution by Andrew Layton]

OpenOffice::OODoc::Element methods


        While all the methods above belong to the document object, some

        additional methods are defined for individual text containers. These

        methods belong to the OpenOffice::OODoc::Element class. The most

        general of them are described in the OpenOffice::OODoc::XPath manual.

        Some of them (listed below) are simple read-only accessors allowing

        the user to check the type of any element.

isXXX() methods


        A set of "isXXX" methods, returning true or false, allow to check

        the type of a given element. Caution, this methods belong to the

        elements, not to the document.

        Example:

            print "This is a list" if $element->isItemList;

        Here is the list of element type indicators:

            isBibliographyMark          bibliography mark (in the doc. body)

            isCovered                   covered (invisible) table cell

            isDrawPage                  presentation or drawing page

            isEndnote                   endnote main element

            isEndnoteBody               endnote body element

            isEndnoteCitation           endnote citation element

            isFootnote                  footnote main element

            isFootnoteBody              footnote body element

            isFootnoteCitation          footnote citation element

            isHeading                   heading

            isItemList                  list (ordered or unordered)

            isListItem                  list item

            isNote                      main note element (end- or footnote)

            isNoteBody                  note body (in end- or footnote)

            isOrderedList               ordered list (OOo only)

            isParagraph                 paragraph

            isSection                   section

            isSequenceDeclarations      set of sequence declarations

            isSpan                      span element (see setSpan)

            isTable                     table

            isTableCell                 table cell

            isTableRow                  table row

            isUnorderedList             unordered list (OOo only)

Other element methods


        For a neater and more direct access to element types, see the

        getName method of XML::Twig::Elt. A call to $element->getName

        returns the element's XML name including its namespace prefix

        e.g. 'text:p' for a paragraph or 'table:table-row' for a table

        row. Remember that all the features of XML::Twig::Elt are

        available for any text container.

Properties


        No class variables are exported.

        Instance properties are the same as for OODoc::XPath, plus:

            'delimiters'        => delimiter table

        hash giving the relation between element types and the delimiters to

        use when exporting text (see getText).

            'use_delimiters'    => delimiter usage (see getText)

        indicates whether delimiters are to be used by getText or not when

        exporting text. Set to 'on' by default. Can be set to 'off' or

        another value to stop or limit use of delimiters.

            'heading_style'     => default header style

        indicates the default header style to be used by element creation

        methods when no style is specified. Set to 'Heading 1' by default.

            'paragraph_style'   => default paragraph style

        indicates the default paragraph style to be used by element creation

        methods when no style is specified. Set to 'Standard' by default.

            'field_separator'   => field separator

        contains the character string to be used as the field separator when

        exporting tables. By default it is ";".

            'line_separator'    => line separator

        contains the string to be used to separate lines when exporting

        "flat" text. By default, it is a line-feed ("\n").

            'max_rows'          => max table length (default 32)

            'max_cols'          => max table width (default 26)

        these 2 properties control the size of the "managed area" in a

        spreadsheet; the default "managed area" is the A1:Z31 rectangle,

        corresponding to the (0,0)-(31,25) coordinates; see getTable() and

        getCell() and normalizeSheet() for more explanations.

            'expand_tables'     => table transformation usage

        indicates whether the XML representation of the spreadsheets are to

        be expanded in order to allow the same cell/row addressing scheme

        as with the tables belonging to text documents; by default, this

        property is not set. If this property is set to 'on', the first

        access to any sheet will automatically trigger this transformation,

        so the explicit normalizeSheet() method will not be needed.

        However, this automatic (but costly) transformation has a drawback:

        it uses the same 'max_rows' and 'max_cols' values for every targeted

        sheet, whatever the really needed managed area for each one.


AUTHOR/COPYRIGHT

Developer/Maintainer: Jean-Marie Gouarne http://jean.marie.gouarne.online.fr

Contact: jmgdoc@cpan.org

Copyright 2004-2006 by Genicorp, S.A. http://www.genicorp.com

Initial English version of the reference manual by Graeme A. Hunter (graeme.hunter@zen.co.uk)

License:


        - Licence Publique Generale Genicorp v1.0

        - GNU Lesser General Public License v2.1
Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy