# NAME

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

# DESCRIPTION

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

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

This module Should be used 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 OpenOffice.org format.

## Methods

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

Short Form: ooText(<parameters>)

See OpenOffice::OODoc::XPath->new

The XML member loaded by default is 'content.xml'. The most common
creation method is like this:

my $doc = OpenOffice::OODoc::Text->new (file => 'my_file.sxw'); 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 = OpenOffice::OODoc::Text->new
(
file            => 'filename.sxw',
paragraph_style => 'My Paragraphs',
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 headers, 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.

Creates a new header of any level and appends it to the end of the
document.

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

'text'              => <header text>
'level'             => header level, default is 1
'style'             => header style, default is 'Heading 1'

Examples:

$doc->appendHeader(text => 'Next section'); adds the text 'Next section' as 'Header 1'.$doc->appendHeader
(
text    => 'Chapter Conclusion',
level   => '2',
style   => 'Heading 2'
);

adds a level 2 header to the end of the text body.

You can give any XML attribute to the new header except for style or
header 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->appendHeader ( text => 'Attributes are important', level => '1', style => 'Chapter header', attribute => %attr ); If the 'text' option is empty, the header is created with an empty content. 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 getHeader 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]]) 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: ### appendItemList([type => list_type, [style => style [, options]]]) Creates a new (empty) list and appends it to the end of the document. An unordered list is the default. If the 'type' option is given with the value 'ordered', then an ordered list is created. 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. ### appendParagraph(<options>) Creates a new paragraph and appends it to the end of the document. Options: 'text' => <paragraph text> 'style' => <paragraph style> An 'attribute' option is also available under the same conditions as for the appendHeader method (see above) [19] . 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. 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 or replicateElement methods instead which are inherited from OODoc::XPath, or even appendText below. ### 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.

### 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 [20]  which defines
certain global properties for the table (width, background colour,
etc.).

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 OpenOffice.org, 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.

### appendText(element [, <options])

Appends a text element, by default to the end of a document.

Two type of usage are possible:

If the 'attachment' option is used, which indicates an element
reference, the new element is attached as a "child" element of the
given element. This allows you to place text in special zones, other
than in the document body, which is not appropriate in all
applications.

This method should be used to append unusual text elements (i.e. not
paragraphs or headers) or existing elements (in its second usage
type) of any type.

Remember that:

$doc->appendText('text:p', text => 'My text'); [21] is the same as:$doc->appendParagraph(text => 'My text');

### 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(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 OpenOffice.org 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 OpenOffice.org. Note 2: syntax and functionality of cell formulae differ greatly between the Writer and Calc applications. ### cellSpan(table, row, column [, span]) ### cellSpan(cell [, span]) 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. 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, optionnally, "text"): see updateCell(). ### cellValueType(table, row, column [, type]) ### cellValueType(cell [, type]) Get/set the data type of a table cell. 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.

### 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 OpenOffice.org document can be referenced in this
manner, as if it belonged to a single 3D table irrespective of the
rest of the document [22] .

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()), 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.

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. Any cellXXX() method in this module uses the same cell addressing logic as getCell(). Note about spreadsheets: 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 "managed area" (beginnning to the upper-left cell, and ending at a parametrizable position). If the 'expand_tables' property of the document is set to 'on', this managed area is automatically initialized when the sheet is targeted for the first time. So, the first access to a given sheet (whatever the row or the cell) can be significantly more costly than any subsequent access. 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);

### 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(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 text is
preceded and/or followed by a character string depending on the type
of element from which it was extracted. 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 [26] .

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-OpenOffice.org XML or a markup language other than
XML, generating code from text, etc..

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-feed ("\n") in addition to any delimiters.

If the element is a table cell, getText behaves like getCellValue.

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

### 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.

### insertHeader(path, position, options)

Same as appendHeader, but inserts the given header at the given
position.

Position is that of an existing element which can be another header
or a paragraph. Can be given by [path, position] or by element
reference.

Possible options are the same as for appendHeader, with the
additional option 'position' which determines if the header is
inserted before or after the element at the given position. Possible
values for this option are 'before' and 'after'. By default, the
element is inserted before the given element.

### 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(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(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.

### 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.

### insertTableRow(row_element [, options])

See insertRow.

### insertText(element, name, options)

As appendText, but a new text element is inserted at the given
position.

The position is that of an existing element (of any type). It can be
given by [path, position] or by element reference.

Options are the same as for appendText, with the additional option
'position' which determines whether the element is inserted before
or after the element at the given position. Possible values for this
option are 'before' and 'after'. By default, the element is inserted
before the given element.

### is[Xxxx]

This module implements a set of accessors which can be used like
native text element methods as opposed to OODoc::Text methods, and
which allow you to determine what type a given element is [27] . For
an element $e of document$d, the syntax is $e->isXxx instead of$d-
>isXxx($e). Example: print "This is a list" if$element->isItemList;

Here is the list of element type indicators:

isFootnoteBody              footnote

isFootnoteCitation  footnote citation

isItemList          list (ordered or unordered)

isListItem          list item

isOrderedList               ordered list

isParagraph         paragraph

isSequenceDeclarations      set of sequence declarations

isTable                     table

isTableCell         table cell

isUnorderedList             unordered list

For a neater and more direct access to element types, see the
getName method of XML::XPath [28] .

### normalizeSheet(sheet [, rows [, columns]])

To be used with spreadsheets. This method preprocesses a given
sheet so its components (rows, cells) become available for all the
table-oriented methods described in this chapter.

This method is not needed for tables included in OpenOffice.org
Writer (sxw) documents, because these tables are "normalized" (i.e.
each component is mapped to an exclusive XML element). But in Calc
(sxc) documents, the XML mapping of rows, columns and cells 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 (sheet, row,
column). In order to allow the spreadsheets components to be addressed
with the same methods as the Writer table components, normalizeSheet()
reorganizes the XML mapping of the given sheet.

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 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.

Because a "normalized" sheet has the same XML structure as a Writer
table, it's generally possible to directly copy it from a spreadsheet
document to a text document. Example:

$doc1 = ooDocument(file => "spreadsheet.sxc");$doc2 = ooDocument(file => "text.sxw");
$sheet =$doc1->normalizeSheet("Sheet1", 6, 8);
$doc2->appendBodyElement($sheet);

In this last example, a new table, that is a copy of the A1:H7 area
of the "Sheet1" sheet of a Calc document, is attached at the end of
a Writer document.

Note: 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, so the effects of normalizeSheet()
disappear.

### 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.

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

Example:

$doc->removeHeader(4); removes the 5th header (whatever its level) counted from the beginning of the document. The header 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. ### 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. ### removeSpan(path, position) ### removeSpan(element) "Flattens" a text element, removing all presentation distinctions which may mark out some sections of its content. For example, the paragraph: I consider OpenOffice.org Writer to be my word processor of choice. becomes: I consider OpenOffice.org Writer to be my word processor of choice. when this method is applied. See also setSpan. ### 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. ### 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). 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 [29] . 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 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

### setSpan(element, [context,] expression, style)

Applies a "span" to part of the content of a text element.

In OpenOffice.org XML language, a "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 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).

The desired text element is normally indicated by [path, position]
or reference. 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. headers,
footers, unordered lists, etc.).

'expression' is the character string to be highlighted, and 'style'
is obviously the style describing the presentation characteristics
to give to it. See OODoc::Styles for how to construct styles from
code.

As a highlighted string can be quite long or not all known in
advance, you can represent it with a regular expression. Taking the
previous example again, you could use:

my @list = $doc->selectElementsByContent("OpenOffice"); foreach my$para (@list)
{
$doc->setSpan($para, "Open.*Writer", "Style1");
$doc->setSpan($para, "word.*ssor", "Style2");
}

This sequence selects all text elements (or, more simply,
paragraphs) which contain "OpenOffice". In each of them, the style
"Style1" is given to the string beginning with "Open" and ending
with "Writer" (if found) and the style "Style2" is given to the
string beginning with "word" and ending with "ssor". Defined
elsewhere, Style1 and Style2 would correspond to the required
presentation characteristics.

Caution: the current version of 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.

### 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 of 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.

For all other types of element, setText behaves normally as defined
in OODoc::XPath.

### 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.

### textStyle(element [, style])

Reads a text element's style or, if a 'style' argument is given,
changes it.

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 [31] .

### 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

## 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.

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.

# NOTES

See OpenOffice::OODoc::Notes(3) for the footnote citations ([n]) included in this page.